Combat & Health¶

Deal damage, heal, kill, and read health — for both destructible objects (a barrel, crate, or vehicle with a Health component) and players. Combat is server-authoritative: the server owns every health value, so scripts can't be tricked into cheating.

That authority splits the API in two:

Combat.* writes are server-only. They change health, so they run only in the server-side world logic. A player's own client build can't call them — a script can't self-heal on the client. Damage comes from server-side sources — a script, a trap, an NPC, or a player firing a Weapon once you enable PvP.
Health.* reads work anywhere — server logic, client scripts, or the play-mode test harness.

Dealing damage¶

All of these run server-side. targetId is either a player id (see Player API) or an object's network id — routing is automatic (the engine checks the object store first, then the player store). attackerId is a player id, or "" for world/environment damage (a trap, lava, a fall).

Call	What it does
`Combat.ApplyDamage(targetId, amount, attackerId)`	Subtract `amount` health from the target.
`Combat.ApplyRadiusDamage(x, y, z, radius, amount, attackerId)`	Area damage around a world point, linear falloff to the edge — grenades / explosives. Hits objects always; players only when PvP is on.
`Combat.Heal(targetId, amount)`	Add `amount` health (clamped to max).
`Combat.SetHealth(targetId, value)`	Set health to an exact value.
`Combat.Kill(targetId, attackerId)`	Drop the target to 0 (destroy the object / kill the player).
`Combat.SetInvulnerable(playerId, invulnerable)`	Turn damage immunity on/off for a player.
`Combat.Revive(playerId)`	Bring a dead player back at their checkpoint.
`Combat.Respawn(playerId)`	Send a player to their checkpoint (see below).
`Combat.DamageSelf(amount)`	Damage the Health object this script is attached to.
`Combat.KillSelf()`	Kill the Health object this script is attached to.

DamageSelf / KillSelf act on the attached object

Combat.DamageSelf and Combat.KillSelf take no target — they act on the SSHealth object the script lives on. Use them inside an object's own logic (for example, a barrel that hurts itself when it's set on fire).

Player-vs-player (PvP)¶

Player-vs-player weapon damage is off by default — a placed Weapon can shoot world objects but not other players until you turn PvP on for the world:

Call	What it does
`Combat.SetPvpEnabled(enabled)`	Enable/disable player-vs-player weapon damage for this world. Off by default (also settable with the World Descriptor's Allow Pvp checkbox).
`Combat.IsPvpEnabled()`	`true` if PvP is currently enabled.

Toggle it live for a match round, an arena, or a timed event. It gates only the weapon path — a creator script calling Combat.ApplyDamage / Kill / ApplyRadiusDamage on a player is authoritative and works regardless.

Reading health¶

These reads work anywhere. targetId follows the same rule — a player id or an object network id.

Call	Returns
`Health.GetHealth(targetId)`	Current health (a `float`).
`Health.GetMaxHealth(targetId)`	Maximum health.
`Health.GetPercent(targetId)`	Health as a fraction, `0..1`.
`Health.IsDead(targetId)`	`true` once health has hit 0.
`Health.GetSelfHealth()`	Current health of the object this script is attached to.

if (Health.GetPercent(id) < 0.25f)
    Combat.Heal(id, 50f);   // top up a player below a quarter health

Reacting to combat¶

The engine calls these methods by name on your NexusBehaviour, server-side, whenever the matching event happens — there's no wiring or subscription. Just declare the ones you care about.

Callback	When it fires
`OnDamage(victimId, amount, attackerId)`	After a target takes damage.
`OnDeath(victimId, attackerId)`	When a target reaches 0 health.
`OnRespawn(playerId)`	After a player respawns at their checkpoint.

public void OnDamage(string victimId, float amount, string attackerId)
{
    // attackerId is "" for world/environment damage (a fall, a trap)
    if (attackerId != "")
        Debug.Log(attackerId + " hit " + victimId + " for " + amount);
}

Respawn & checkpoints¶

Every player has a respawn point (checkpoint), defaulting to where they spawned, and it's server-authoritative. Death, a safe fall, and a manual reset all send the player there. These Player.* calls act on the local player; placement is still enforced by the server.

Call	What it does
`Player.Respawn()`	Send the local player to their checkpoint.
`Player.SetRespawnPoint(x, y, z)`	Move the checkpoint to a world position.
`Player.GetRespawnPoint()`	Read the current checkpoint (`Vector3`).
`Player.SetHeightRespawn(mode)`	What happens when the player falls below the world's respawn height (an always-on net — this only picks reset-vs-death, it can't disable it): `0`/`1` safe reset to checkpoint (no death), `2` death (ragdoll, then respawn). To let players fall further, lower the World Descriptor's `respawnHeight` instead.

Players don't use a Health component

Player health is built in — default 100, server-authoritative. At 0 a player ragdolls, the camera pulls back, and they auto-respawn at their checkpoint after about 4 seconds. Player-vs-player weapon damage is off by default — enable it with Combat.SetPvpEnabled(true) or the World Descriptor's Allow Pvp — until then only self, fall, script, trap, and NPC damage apply.

You can do the same three things with no scripting — the Respawn, Set Respawn Point, and Set Height-Respawn actions on World Triggers and the Health component share this exact behavior.

Examples¶

A barrel that awards a point when destroyed. Put a Health component on the barrel, add an On Death entry, and point it at this script method:

public class ScoreBarrel : NexusBehaviour
{
    int _score;

    // Called by the barrel's On Death entry (server-side).
    public void AwardPoint()
    {
        _score++;
        Debug.Log("Barrels destroyed: " + _score);
    }
}

Respawn a player as soon as they die — react to the death callback, then send the victim to their checkpoint:

public class RespawnOnDeath : NexusBehaviour
{
    public void OnDeath(string victimId, string attackerId)
    {
        Combat.Respawn(victimId);   // server-authoritative respawn at their checkpoint
    }
}

Quick reference¶

Group	Calls
Damage (server-only)	`Combat.ApplyDamage · ApplyRadiusDamage · Heal · SetHealth · Kill · SetInvulnerable · Revive · Respawn · DamageSelf · KillSelf`
PvP (server-only)	`Combat.SetPvpEnabled · IsPvpEnabled`
Read	`Health.GetHealth · GetMaxHealth · GetPercent · IsDead · GetSelfHealth`
Callbacks	`OnDamage(victimId, amount, attackerId)` · `OnDeath(victimId, attackerId)` · `OnRespawn(playerId)`
Respawn (local player)	`Player.Respawn · SetRespawnPoint · GetRespawnPoint · SetHeightRespawn`

→ See the Combat & Respawn feature page for the no-code Health component and World-Trigger actions, and Player API for finding and reading players.