Health and damage
Read and change health
Section titled “Read and change health”Peds, players, vehicles and objects expose health. Server peds and players also
expose maxHealth and armour. These are GTA health values. A newly created
server ped or player has 200 health and 200 maximum health.
On the server, health and armour accept values from 0 to 100000.
maxHealth must be greater than 0 and at most 100000. Lowering maxHealth
also lowers current health if it exceeds the new maximum. Raising the maximum
leaves current health unchanged. Set both when applying a higher-health character.
This example heals a living player and applies a fixed amount of hunger damage when your server gameplay logic calls the corresponding function:
// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
/** @param {revo.Player} player */export function healPlayer(player) { if (!player.valid || player.dead) return; player.health = player.maxHealth;}
/** @param {revo.Player} player */export function applyHungerDamage(player) { if (!player.valid || player.dead) return; player.health = Math.max(0, player.health - 5);}
revo.on('healthChanged', (entity, oldHealth, newHealth, source) => { if (!entity.valid || !(entity instanceof revo.Player)) return; revo.log(`Player ${entity.id}: health ${oldHealth} -> ${newHealth}, source ${source}`);});Direct health changes apply the value you assign. The hunger example subtracts
health while leaving armour unchanged. Put armour handling in that function if
the damage should consume armour. A direct assignment does not invoke
beforeDamage.
Use server properties for shared state. On the client, health setters operate
on loaded local entities created by that resource. The client armour property
is spelled armor, while the server property is armour.
Observe changes
Section titled “Observe changes”Server state events provide the previous and new values:
| Event | Target |
|---|---|
healthChanged(entity, oldHealth, newHealth, source) |
A physical entity. |
armourChanged(ped, oldArmour, newArmour, source) |
An NPC or player. |
maxHealthChanged(ped, oldMaxHealth, newMaxHealth, source) |
An NPC or player. |
StateChangeSource.Server identifies server state changes.
StateChangeSource.Sync identifies state received from simulation. These notifications are queued, so check valid
before reading the entity. Use the event’s old/new values for that transition,
since the entity may already have changed again.
On the client, entityHit(victim, attacker, weaponHash, damage) reports damage
after GTA applies it. The attacker can be null. Use it for local feedback.
Server damage rules belong in beforeDamage for accepted weapon hits,
explosions and fire. Its headshot example and cancellation rules are covered in
Weapons and ammunition.
Death and recovery
Section titled “Death and recovery”playerDied(player, source) fires when the server marks a player dead.
Use player.dead for the current state. Once dead, a positive health assignment
is rejected. Call player.spawn(position, heading) to revive the player.
See Spawning and respawning for delayed respawns
and disconnect cleanup.
NPCs do not emit playerDied. Use the health notifications for health-based
NPC rules. On a client with the ped loaded, ped.dead reports its GTA death
state. When the mod replaces an NPC, destroy the old server ped and create a
new one with the desired properties and behavior.
Vehicle health, broken parts and repair have their own behavior. See
Damage, doors and repairs. Objects expose health,
but the visible damage and destruction depend on their model’s physics and
damage setup. Use destroy() when the mod intends to remove an object completely.