Health

Hurting, healing and killing players, and explosions. A shot or a fall takes no health by itself: the mod hears it and decides, with hurt or set_health. At 0 health a player is dead until the mod brings them back.

Each hurt shows as it happens. The attacker sees a hit mark. The one hurt sees a red bar pointing at the attacker. Everyone sees a death, with the weapon, as a kill feed needs. A shot at a player shows its shooter a mark only once the mod hurts for it; one at an NPC shows it as it lands. The dead neither move nor fire, and no one sees them.

Fields

What a player, p, or an entity, e, reads beside the mod’s state. A field of the other side’s fails.

Name	Type	Side	What it is
p.health	number?	On both sides	Their health; on a client, the shown player's alone.
p.max_health	number?	On both sides	The health they have at most; on a client, the shown player's alone.

explode

On the server explode(at, options)

Sets off an explosion at a point, hurting the players and NPCs around it as a grenade's does.

It plays no effect and no sound: play those with play_effect and play_sound. It goes off on the next tick, and what stops shots shields from it. It hurts by too, if near. 16 go off a tick and the rest wait their turn; past 256 waiting, more are dropped.

Name	Type	What it is
at	vector	Needed.
options	table	A table of the options below. Those marked needed may not be left out.
radius	number0 to 50	How far it reaches, in metres, over 0. Needed.
damage	number0 or more	The damage at its middle. Needed.
min_damage	number0 or more, default 0	The damage at its edge, radius away; in between it falls in a straight line from damage.
by	(Player | number)?	Who set it off, a player or an NPC, as its hurts and kills name them.

Fails

• a value of the wrong type
• an option it does not have
• a key it needs left out
• a value outside its range

To drop a mortar where a player stands

local at = p.position
explode(at, { radius = 6, damage = 150, min_damage = 10 })
play_effect("explosion", { at = at })
play_sound("explosion_boom", { at = at, range = 200 })

To blow up the charge a player planted, so its kills are theirs

local charge = model("grenade", { at = p.position })
wait(3)
explode(charge.position, { radius = 8, damage = 300, by = p })
charge:remove()

hurt

On the server p:hurt(damage, by?, weapon?, { kind?, location? }?)

Hurts a player, as a hit would, taking damage from their health; at 0 they die.

by is who did it, a player or an NPC, and weapon what with: any weapon’s name, a file of weapons/ or not. The player hurt sees a red bar pointing at by, and by sees a hit mark, as do those watching either through their eyes; a by not in play counts as no one. A death it causes is shown to everyone with who did it, the weapon, the kind and the limb, as a kill feed needs. The dead stay dead. An NPC has no health of the engine’s, so hurt on one fails: the mod keeps its own.

Name	Type	What it is
damage	number0 or more	Needed.
by	(Player | number)?	May be left out.
weapon	string?	May be left out.
how	table?	A table of the options below. It, and each option, may be left out.
kind	"bullet" | "melee" | "explosion" | "fall" | "mod"default "mod"	How it was done, as the kill feed and the damaged and killed events' means name it.
location	("head" | "neck" | "chest" | "stomach" | "upper_arm" | "lower_arm" | "hand" | "upper_leg" | "lower_leg" | "foot")?	The limb it hit, one of a weapon's locations; none, a hurt of the whole body, without one.

Fails

• a value of the wrong type
• an option it does not have
• a value outside its range

To hurt a player standing in fire

p:hurt(5)

To deal a zombie’s claw, so the kill feed names it

local zombie = spawn()
p:hurt(40, zombie, "zombie_claw", { kind = "melee", location = "chest" })

heal

On the server p:heal(amount)

Gives a living player back amount health, up to their maximum.

Name	Type	What it is
amount	number0 or more	Needed.

Fails

• a value of the wrong type
• a value outside its range

To heal a player a little each second, for five seconds

for _ = 1, 5 do
    p:heal(5)
    wait(1)
end

set_health

On the server p:set_health(health)

Sets a living player's health, no higher than their maximum; at 0 they die, as by a hurt.

Name	Type	What it is
health	number0 to 10000	Needed.

Fails

• a value of the wrong type
• a value outside its range

To give a player full health

p:set_health(p.max_health)

set_max_health

On the server p:set_max_health(max)

Sets a player's maximum health; everyone starts at 100.

It is kept through death, and a respawn brings the player back at it. Health over it comes down to it.

Name	Type	What it is
max	number1 to 10000	Needed.

Fails

• a value of the wrong type
• a value outside its range

To give a player the Juggernog perk

p:set_max_health(250)
p:set_health(250)

respawn

On the server p:respawn()

Brings a dead player back at the next marker whose name starts with spawn, at full health, with the loadout.

Followed at once by p:set_position and p:set_angles on the same player, in the same handler, timer or tick, it brings anyone back there instead, dead or alive, and leaves that spawn for the next. A player alive is left as they are otherwise. A push, turn or move not yet carried out goes with the life before; tune, hold and limit_view outlast it.

To bring every dead player back at the start of a round

for _, p in players do
    if not p.npc and p.health == 0 then
        p:respawn()
    end
end

To bring a player back at a point of your choosing

local at = vector.create(4, 0, 2)
p:respawn()
p:set_position(at)
p:set_angles({ yaw = math.pi })

on("hit")

On the server on("hit", fn)

Something struck a player or an NPC, once for each pellet that hits. It takes no health itself: the mod hurts them, as with p:hurt.

Name	Type	What it is
e.victim	Player	Who was struck.
e.attacker	Player?	Who struck them; nil for no one, or one no longer here.
e.amount	number	The damage it would do.
e.means	string	How: bullet, melee, explosion, fall or mod, the mod's own.
e.location	string?	The limb it struck, as head; nil for an explosion or a fall.
e.weapon	string?	The weapon it was done with; nil for none.
e.point	{x: number, y: number, z: number}	Where it struck.
e.dir	{x: number, y: number, z: number}	Which way it was going, a unit vector.

on("fell")

On the server on("fell", fn)

A player landed from over 6.5 m, a fall that would hurt, all their health from 12.2 m. It takes no health itself: the mod hurts them.

Name	Type	What it is
e.player	Player	Who landed.
e.amount	number	The damage the fall would do.
e.height	number	How far they fell, in metres.

on("killed")

On both sides on("killed", fn)

A player or an NPC died, heard on the next mod tick.

Name	Type	What it is
e.victim	Player	Who died: a player or an NPC.
e.killer	Player?	Who killed them; nil for no one, or one no longer here.
e.weapon	string?	The weapon it was done with; nil for none.
e.means	string	How: bullet, melee, explosion, fall or mod, the mod's own.
e.location	string?	The limb it struck, as head; nil for an explosion or a fall.

on("damaged")

On both sides on("damaged", fn)

A player or an NPC lost health.

Name	Type	What it is
e.victim	Player	Who was hurt: a player or an NPC.
e.attacker	Player?	Who hurt them; nil for no one, or one no longer here.
e.amount	number	The health it took.
e.weapon	string?	The weapon it was done with; nil for none.
e.means	string	How: bullet, melee, explosion, fall or mod, the mod's own.
e.location	string?	The limb it struck, as head; nil for an explosion or a fall.

on("hit_too_late")

On a client on("hit_too_late", fn)

A shot of this player's reached its victim as they died or left, so it did nothing.

Name	Type	What it is
e.victim	Player	Who the shot reached.