Game events

What happens in the game - a player takes damage, spawns, dies, buys a weapon, throws a grenade, a round ends - are events on game. A listener hears the event before the game acts, and can let it go on, change it, stop it, or answer in the game's place:

// no damage between teammates
game
.
addEventListener
("takeDamage", (
event
) => {
    if (
event
.
attacker
.
team
 == 
event
.
player
.
team
) 
event
.
preventDefault
();
});

// double damage from the knife
game
.
addEventListener
("takeDamage", onTakeDamage);

function onTakeDamage(
event
: TakeDamageEvent) {
    const 
weapon
 = 
event
.
attacker
.
activeItem
;
    if (
weapon
 && 
weapon
.
kind
 == "knife") 
event
.
damage
 = 
event
.
damage
 * 2;
}

// the game asks, the plugin answers: players hear only their own team
game
.
addEventListener
("canPlayerHearPlayer", (
event
) => 
event
.
listener
.
team
 == 
event
.
sender
.
team
);

The game events come from the ReAPI and Ham Sandwich modules. game.addEventListener works like server.addEventListener (Plugin): the name picks the type of event, the editor completes the names and marks a misspelt one, and game.removeEventListener with the same function takes a listener off. With its last listener off, the event stops coming to the plugin until a listener is added again.

What a listener can do

Changing a field changes what the game and the listeners after this one get; reading the field afterwards gives the new value.

Returning a value answers the game's question - "can this player hear that one?", "how much fall damage?", "may he buy this?" - and the game does not run its own code. The answer has the event's type (boolean, number, Player, Entity): returning another type is an error in the editor and in the build. An event whose game function answers nothing takes no answer.

preventDefault() stops the game's action without an answer: the damage is not dealt, the default weapons are not given. Where the game expects an answer, it gets 0 or false.

After the game has acted

game
.
addEventListener
("fallDamage", (
event
) => 
event
.
result
 / 2, true);   // half the fall damage

game
.
addEventListener
("playerSpawn", (
event
) => {
    
event
.
player
.
give
("weapon_deagle");
}, true);

With true as the third argument - or { post: true }, which is the same - the listener runs after the game's function. event.result is what the game answered, and a returned value replaces it. Changing a field there changes nothing: the game has already used it. To take such a listener off, pass true to removeEventListener as well.

Touches

game
.
addEventListener
("touch", onTouch, { 
toucher
: "player", 
touched
: "player" });

function onTouch(
event
: TouchEvent) {
    const 
player
 = new 
Player
(
event
.
toucher
.
id
);
    const 
below
 = new 
Player
(
event
.
touched
.
id
);
    if (
player
.
groundEntity
 == 
below
.
id
) 
console
.
log
(`${
player
.
name
} stands on ${
below
.
name
}`);
}

"touch" is two entities touching: event.toucher moved into event.touched, both Entity. A touch happens every frame for every player standing on something, so the third argument names the classes a listener is about - toucher, touched, or both - and only those touches reach the plugin: the server filters them before it. A class left out is any class. event.preventDefault() blocks the touch. Two players touching are two touches, one each way.

One class of entity

game
.
addEventListener
("primaryAttack", onSlash, { 
classname
: "weapon_knife" });

function onSlash(
event
: PrimaryAttackEvent) {
    const 
knife
 = 
event
.
weapon
;
    
knife
.
secondaryAttack
();         // the right click instead; every plugin's listeners run on it
    
event
.
preventDefault
();          // and not the left one
}

game
.
addEventListener
("takeDamage", (
event
) => {
    
console
.
log
(`${
event
.
entity
.
classname
} took ${
event
.
damage
}`);
}, { 
classname
: "func_breakable" });

A weapon's attack, a door's use, an entity's think are events of one class of entity: classname in the third argument names it, and only its entities reach the plugin - the server filters them before it. { classname, post: true } listens after the game has acted.

An event about a player - takeDamage, killed, spawn - is a player's without classname, and another class's with it: event.player is the player, event.entity the entity of the class named. An event about a weapon - canDeploy, itemPostFrame - is every weapon's without classname, one class's with it. An event about one class of entity alone - primaryAttack, deploy, think, use - needs classname. A field such an event has is writable where the game takes it back, an entity or a vector too.

The same functions are an entity's methods - the game runs them as when it does so itself, and every plugin's listeners hear it:

knife.deploy();                          // drawn again: the model and the animation
knife.deploy({ 
hooks
: false });          // the game's function alone, no listeners
player
.
jump
();
door.use(
player
, 
player
, "toggle", 0);

What an event has

• Fields are the event's data, typed: event.damage is a number, event.damageType a Damage[] (flags), a text a string. A field is named in words: event.trace, event.info, event.direction, event.start; the tooltip names the parameter as ReAPI has it.
• Entities are objects: a player is a Player, a weapon a Weapon, anything else an Entity. event.attacker.team, event.player.health.
• event.player is the player the event is about: the one taking damage, spawning, jumping, being blinded.
• event.result, in a listener that runs after the game, is the game's answer.

Hover over an event's name for what it is, and over a field for what it holds. The last line of each tooltip names it as ReAPI and Ham Sandwich do (Pawn: `RG_CBasePlayer_TakeDamage`, `Ham_TakeDamage` ).

Events you will use first

¹ Heard with less on a server without ReAPI, ² not heard there: a server without ReAPI.

The editor lists all of them, about 250.

An event is named after what the game does, in camelCase, whichever module hears it: RG_CBasePlayer_TakeDamage and Ham_TakeDamage are both "takeDamage", RG_CSGameRules_PlayerSpawn is "playerSpawn" (the round's spawn of a player) and RG_CBasePlayer_Spawn "spawn", Ham_Weapon_PrimaryAttack is "primaryAttack". The event's type is the name in PascalCase with Event: TakeDamageEvent, PrimaryAttackEvent.

canPlayerHearPlayer is asked only while sv_alltalk is 0: with alltalk on the game asks nobody. To silence a player whatever alltalk says, use player.muted (Players).

Enums and flags — names

A field that holds one of a fixed set of values is a name, and a field of bit flags is an array of names:

game
.
addEventListener
("roundEnd", (
event
) => {
    if (
event
.
reason
 == "targetSaved") 
console
.
log
("the bomb site was saved");
    if (
event
.
winner
 == "CT") 
console
.
log
("counter-terrorists win");
});

game
.
addEventListener
("showVguiMenu", (
event
) => {
    if (
event
.
menu
 == "team") 
event
.
preventDefault
();
});

game
.
addEventListener
("sendDeathMessage", (
event
) => {
    if (
event
.
rarity
.
includes
("headshot")) 
console
.
log
("a headshot");
});

Assigning a name changes the value the game gets: event.reason = "terroristsWin". A value no name stands for - another plugin or a mod passed it - reads as "unknown" ("none" for RoundWinner and WeaponKind, "UNASSIGNED" for Team), and assigning "unknown" leaves the field as the game passed it. Flags that have no name are kept when a flag array is assigned.

A server without ReAPI since v0.2

ReGameDLL and ReHLDS have events of their own - a player's spawn into the round, the round's start and end, money, purchases - which ReAPI delivers. On a server without them - Valve's own HLDS with AMX Mod X - most of them are heard the way a Pawn plugin hears them there: a new round through the HLTV message, the end of the freeze time and of the round through the game's log, a spawn and a death through Ham Sandwich, money through the Money message, a purchase through cstrike. The plugin is written the same; amxts picks the way once, when the server starts.

What such an event cannot give there is in the table below and in the editor's tooltip of the event. A listener that asks for it anyway - preventDefault(), an answer, a field written - is one line in the server console, once for the event; a field the event cannot fill reads as 0, "", null or the world.

The order of a round is the game's: newRound before the players respawn, their playerSpawn, newRound after the game once they are alive, roundStart, roundEnd.

Ending the round

game
.
endRound
({ 
winner
: "TERRORIST" });                      // the terrorists win; next round in 5 s
game
.
endRound
({ 
winner
: "CT", 
delay
: 3 });
game
.
endRound
({ 
winner
: "draw", 
message
: "Nobody won" });
game
.
endRound
({ 
winner
: "none", 
delay
: 0.1, 
message
: "" });  // a quiet restart

The game rules

if (
game
.
isFreezeTime
) 
console
.
log
("the round has not begun");
game
.
isFreezeTime
 = false;               // over, for the game's own checks
game
.
ctWins
 = 0;                         // the score, on the scoreboard at once
if (
game
.
roundWinner
 == "CT") 
console
.
log
("the counter-terrorists took the last round");

The game's own state - the freeze time, the score, the round's times, what the map has - is a field of game, typed as a player's fields are: a number, a boolean, a text, the round's winner as a name. The names are a player's words for the member: m_bFreezePeriod is isFreezeTime, m_iNumCTWins is ctWins, m_iRoundWinStatus is roundWinner, and the editor lists the rest with their meaning and the member's name. A team's score written - ctWins, terroristWins - is on the scoreboard at once, as when the game counts a round.

Async listeners

A listener may be async and await inside (async). What it returns before its first await is its answer to the game. After an await the game has moved on: the listener can still act - print, give an item - but what it returns no longer reaches the game.

Limits

• A vector field is written whole. event.direction = new Vector(0, 0, 1) turns traceAttack's shot; event.direction.z = 1 changes a copy and the game never sees it.
• Messages to clients are heard through server.addMessageListener (Messages); temporary effects are effects.