Skip to content

Health and damage

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:

Server
// @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.

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.

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.