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 are the game's own functions, which amxts hooks itself:
ReGameDLL's and ReHLDS's hookchains, and an entity's functions in its class
(Ham Sandwich's). Neither ReAPI nor the Ham Sandwich module is needed for
them. 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
| To | Write |
|---|---|
| let the game go on | return nothing |
| stop the game's action | event.preventDefault() |
| change what the game gets | assign a field: event.damage = 10 |
| answer in the game's place | return the answer: return true |
| stop the game and every listener after this one | event.stopImmediatePropagation() |
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.
A function either returns a value on every path or on none. A listener that should answer only sometimes returns nothing and calls
event.preventDefault() where it has to stop the game - or always answers,
repeating the game's own rule for the other cases.With ReAPI, a Pawn plugin's handler of the same hookchain runs before the listeners of amxts before the game, and after them after it: what a Pawn plugin blocks before the game reaches no amxts listener, and the Pawn handlers after the game hear what a listener blocked. A Pawn plugin's Ham Sandwich hook of an entity's function and amxts' hook of it run one inside the other: the one made later runs first before the game and last after it.
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.
A Pawn plugin's
register_touch and pfn_touch hear a touch after the
listeners of amxts, and one a listener blocked as well.What each player sees since v0.3
game.addEventListener("entityState", (event) => {
if (event.player.team != "CT") {
event.preventDefault(); // a marker only the CTs see
return;
}
event.renderFx = "glowShell"; // and it glows for them
event.renderColor = [0, 160, 255];
event.renderAmount = 10;
}, { classname: "myplugin_marker" });
"entityState" is what the server sends one player of one entity he can
see, every frame: event.player gets it, event.entity is what it is about.
Its fields - origin, angles, renderMode, renderAmount, renderColor,
renderFx, effects, modelIndex, body, skin, and the model's
animation: sequence since v0.3.3, gaitSequence since v0.3.3, frame since v0.3.3,
frameRate since v0.3.3, animTime since v0.3.3, ducking since v0.3.3, solid since v0.3.3 - are what that
player sees, and writing one changes it for him alone; the entity stays as it
is.
event.preventDefault() hides the entity from him.
It happens for every entity every player sees, every frame, so the third
argument names the class it is about - { classname: "player" } - and only
those reach the plugin. A server with no entityState listener pays nothing
for it.
The client plays an animation on by itself: from frame at animTime, at
frameRate. A frameRate of 0 holds the model in the pose frame names, so
a pose kept and sent again freezes the model for one player while the others
see it move:
interface Pose { sequence: number; gaitSequence: number; frame: number; }
let watcher = 0; // the player who froze the others, by id
const poses = new Map<number, Pose>(); // the pose each one froze in, by id
game.addEventListener("entityState", (event) => {
if (event.player.id != watcher) return;
const id = event.entity.id;
let pose = poses.get(id);
if (pose == null) {
pose = { sequence: event.sequence, gaitSequence: event.gaitSequence, frame: event.frame };
poses.set(id, pose);
}
event.sequence = pose.sequence; // the pose he froze them in
event.gaitSequence = pose.gaitSequence;
event.frame = pose.frame;
event.frameRate = 0; // held there, not played on
}, { classname: "player" });
What a listener writes lasts one frame for one player: the next frame the entity is sent as it is, and the listener runs again. A listener that hides an entity hides it every frame it runs.
What a player is sent of himself since v0.3.3
game.addEventListener("clientData", (event) => {
if (event.player.flags.includes("onGround")) return;
event.maxSpeed = 200; // his client predicts him slower in the air
});
"clientData" is what the server sends a player's own client of the player
himself, every frame: event.player gets it. Its fields - nextAttack,
fov, weaponAnim, maxSpeed, origin, velocity, punchAngle,
viewOffset, flags - are what his client predicts his movement and his
weapon with and draws his view from, and writing one changes it for his client alone; the
player stays as he is. nextAttack is the seconds until his next attack, as
his client counts them down: the client runs his weapon - its shots and its
animations - only at 0 or less.
His view is drawn from these fields too: his eyes at origin plus
viewOffset, turned by punchAngle - the kick of a shot or a hit - and
bobbing by velocity's speed along the ground. flags are the names
player.flags has; "ducking" among them is a crouch.
It happens for every player every frame. A server with no clientData
listener pays nothing for it.
A spectator watching a player through his eyes is sent that player's data: his view sways and kicks as the player's does. A listener can hold it still:
let paused = false; // the replay myplugin plays is on pause
game.addEventListener("clientData", (event) => {
if (!paused || event.player.observerMode != "inEye") return;
event.velocity = [0, 0, 0]; // no bob from the watched player's movement
event.punchAngle = [0, 0, 0]; // nor a kick from his shots
});
A weapon's look in his hands
One view model can hold several looks of a weapon as body groups - a knife
with several finishes. weapon.viewBody picks the one his hands show:
game.addEventListener("defaultDeploy", (event) => {
if (event.weapon.classname != "weapon_knife") return;
event.viewModel = "models/myplugin/v_knife.mdl";
event.weapon.viewBody = 2; // the third finish of the model
});
While the weapon is in his hands, every animation of it - the draw, the idle,
the swing - comes from the server drawn with that body, and his client does
not predict them: a client predicts its weapon's animations itself, and
draws them without the body. Set viewBody on every draw, as the
defaultDeploy listener above does; 0 is a body of the model like any
other and holds the weapon the same way. When the weapon leaves his hands -
holstered, dropped, taken away - the module lets the body go.
His client is kept in step as well: a client plays the animation it is told
the weapon holds again, with a body of its own, when that is not the last one
it played itself - so the module tells it the draw's, and sends the draw once
more with the body right after his client's own. A clientData listener runs
after that and can change weaponAnim.
A spectator watching him through his eyes sees the weapon with the same body: the module sends the spectator each animation of it and keeps the spectator's client in step the same way.
With a
viewBody the animations of the weapon in his hands come from the
server, late by his ping. A weapon whose shots the client draws itself loses
them for its holder: the sound and the flash of his own shots are left to
his client, which no longer runs the weapon. viewBody is for a weapon such
as a knife.Where a player sees from since v0.3.3
const replays = new Map<number, number[]>(); // where myplugin's replay each player watches is, by id
game.addEventListener("visibility", (event) => {
const point = replays.get(event.player.id);
if (point != null) event.addOrigin(point); // he is sent what is seen from there too
});
"visibility" is where the server looks from for a player every frame: it
sends him the entities that can be seen from event.origin, and the
entityState listeners run for those. event.origin is his eyes, the eyes of
the player he watches as a spectator, or of his view.
A plugin that shows a player a place his own eyes are far from - a replay, a
camera drawn by his client - adds that place with event.addOrigin(point):
he is sent what can be seen from either, so the walls, doors and platforms
around it reach him. His own eyes stay: a spectator is sent the player he
watches only while that player can be seen - without them, the watched
player's model is gone in third person and his view breaks in first person.
Writing event.origin moves the first point instead - he is no longer sent
what only his eyes see. Both last for this frame alone; his view and the
player stay as they are. Up to 15 points can be added per player per frame;
past that, addOrigin leaves the point out.
It happens for every player every frame. A server with no visibility
listener pays nothing for it, and each point added costs the server about
what working out the player's own point does.
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.
An entity's function is hooked one class of entity at a time: a listener of an event about one class alone without
classname is not added, and the
console says so. stopImmediatePropagation() there blocks the game's
function and the listeners of amxts after this one; a Pawn plugin's Ham
Sandwich hook of the function still runs.On a server without ReGameDLL - plain HLDS - a player's event is hooked in the player's class too, and a weapon's event without
classname in every
weapon's class: the listener is written the same and hears the same, and what
the note above says holds for it. The events of ReGameDLL's and ReHLDS's own
come there from other hooks, some with less
(a server without ReGameDLL).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);
trap.touch(player); // the trap's teleport or damage, on him
| Method | On |
|---|---|
spawn, activate, think, use, blocked, heal, killed, restart, touch since v0.3.1 | any entity |
addFrags, addTeamScore, addItem, removeItem, giveAmmo, jump, duck | a player |
deploy, holster, drop, primaryAttack, secondaryAttack, reload, weaponIdle, retireWeapon, addToPlayer, attachToPlayer, extractAmmo, extractClipAmmo, resetEmptySound, sendWeaponAnim | a weapon |
entity.touch(toucher) runs the entity's touch on toucher, as the game
runs it when toucher moves into it: the touch event and
Ham Sandwich's listeners hear it, a Pawn plugin's register_touch does not.
The player's movement since v0.3
game.addEventListener("airMove", (event) => {
if (event.touchCount > 0) console.log(`${event.player.name} hit something in the air`);
});
The events of a player's movement - move, airMove, jumpMovement,
duckMovement, ladderMove and the rest - have two more fields:
event.touchCount, how many things the player has touched in this movement
so far (the floor, a wall, another player), and event.frameTime, the
movement frame's length in seconds.
move, the whole of a player's movement, is heard on plain HLDS too
since v0.3.1, with its fields and preventDefault(); the rest of the
movement events need ReGameDLL.
What an event has
- Fields are the event's data, typed:
event.damageis anumber,event.damageTypeaDamage[](flags), a text astring. 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 aWeapon, anything else anEntity.event.attacker.team,event.player.health. event.playeris 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` ).
A field is read from the game's call when you read it, and the next call of the same event hands out the same object. Keep what you need, not the event:
const victim = event.player before an await or a setTimeout.Events you will use first
| Event | When | Answer |
|---|---|---|
takeDamage | a player is about to take damage: player, attacker, inflictor, damage, damageType; to change how much, assign event.damage | number |
traceAttack | a shot hits a player, before the damage | - |
playerKilled¹ | a player was killed: victim, killer, inflictor | - |
playerSpawn¹ | a player spawned | - |
giveDefaultItems¹ | the game gives a spawned player his default weapons | - |
newRound¹ | a new round starts | - |
roundStart¹ | the freeze time at the round's start is over | - |
roundEnd¹ | the round is ending: winner, reason, delay | boolean |
buyWeapon¹ | a player buys a weapon: weapon | Entity: the weapon bought |
itemRestricted¹ | the game asks whether an item is forbidden to a player | boolean: true forbids |
canPlayerHearPlayer¹ | the game asks whether listener hears sender on voice chat | boolean |
fallDamage¹ | the game works out a fall's damage | number |
addMoney¹ | a player's money changes: amount, reason | - |
chooseTeam¹ | a player picks a team in the menu: choice | number |
throwHeGrenade¹ | a player throws an HE grenade | Entity |
playerBlind¹ | a flashbang blinds a player: fadeTime, fadeHold, alpha | - |
¹ Heard with less on a server without ReGameDLL: a server without ReGameDLL.
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");
});
| Event | Field | Names |
|---|---|---|
roundEnd | winner | RoundWinner: "TERRORIST", "CT", "draw", "none" |
roundEnd | reason | RoundEndReason: "ctsWin", "terroristsWin", "targetSaved", "targetBomb", "bombDefused", "endDraw", "gameRestart", "none", … |
roundEnd | delay | seconds until the next round |
canSwitchTeam | team | Team |
chooseTeam | choice | TeamChoice: "TERRORIST", "CT", "VIP", "auto", "SPECTATOR" |
buyWeapon | weapon | WeaponKind, as weapon.kind names them: "ak47", "awp", … |
addMoney | reason | RewardReason: "roundBonus", "enemyKilled", … |
itemRestricted | restriction | ItemRestriction: "buying", "touched", "equipped" |
itemRestricted | item | ItemKind: a weapon by its kind ("awp", "hegrenade", …) or "kevlar", "assault", "defusekit", "nvg", … |
pain | lastHitGroup | HitGroup: "head", "chest", "stomach", "leftArm", … - as player.lastHitGroup names them |
setAnimation | animation | PlayerAnimation: "idle", "walk", "jump", "attack1", "reload", … |
addResource | resourceType | ResourceType: "sound", "model", "decal", "generic", "eventscript", … |
gameEvent | gameEvent | BotEvent: "playerDied", "bombPlanted", … |
showVguiMenu | menu | VguiMenu: "team", "classT", "classCT", "buy", … |
sendDeathMessage | flags | DeathMessageFlag[]: "position", "assistant", "killRarity" |
sendDeathMessage | rarity | KillRarity[]: "headshot", "noScope", "penetrated", "inAir", … |
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 ReGameDLL 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 amxts hears
through their hookchains. 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 the player's
functions, money through the
Money message, a purchase through cstrike. The plugin is written the same;
amxts picks the way once, when the server starts.
The game rules' functions - fallDamage, canHaveItem, canRespawn
and the rest of their questions, and playerSpawn, playerKilled,
newRound, deathNotice and the rest the table below names so - are heard
there since v0.3.2 as with ReGameDLL: their listeners are called before
the game acts, and their answers, fields and preventDefault() count. So are
addMoney and giveDefaultItems since v0.3.2. amxts hooks the game's
own function for them: on Linux always, on Windows in the builds of Valve's
game it knows - the one steam installs and its steam_legacy branch.
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.
| Event | On a server without ReGameDLL |
|---|---|
addMoney | reason reads as "none"; heard as with ReGameDLL where AMX Mod X's gamedata finds the game's function; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing; amount is how much his money moved since the game last sent it to him |
becomeBomber | Heard after the game has acted, so preventDefault() and changing a field do nothing; returning an answer does nothing |
becomeVip | Heard after the game has acted, so preventDefault() and changing a field do nothing |
buyAmmo | Heard as the game checks the purchase, for an item a buy command or a buy menu names: preventDefault() stops it; weapon reads as the world, blinkMoney as true; returning an answer does nothing |
buyItem | Heard as the game checks the purchase, for an item a buy command or a buy menu names: preventDefault() stops it; heard for the equipment menu's items; returning an answer does nothing |
buyWeapon | Heard as the game checks the purchase, for an item a buy command or a buy menu names: preventDefault() stops it; event.result reads as null; returning an answer does nothing |
canHaveItem | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
canPlayerHearPlayer | Asked as the game tells the engine who hears whom, with sv_alltalk on too, and for a player who muted the other: the answer overrides both |
canRespawn | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
canTakeDamage | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
changeLevel | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere preventDefault() does nothing |
changeName | Heard after the game has acted, so preventDefault() and changing a field do nothing; info reads as ""; returning an answer does nothing |
checkWinConditions | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
chooseAppearance | Heard from the player's command: preventDefault() stops it; a model the game picks itself is not heard |
chooseTeam | Heard from the player's command: preventDefault() stops it; returning an answer does nothing, and a team the game picks itself is not heard |
clientConnected | Heard after the game has acted, so preventDefault() and changing a field do nothing |
connectClient | Heard after the game has acted, so preventDefault() and changing a field do nothing; heard once the player is let in |
deathNotice | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere it is heard as its death message is sent: preventDefault() does nothing, and inflictor reads as the world |
defuseBombEnd | Heard after the game has acted, so preventDefault() and changing a field do nothing; heard only when the bomb is defused, not when a defuse stops halfway |
defuseBombStart | Heard after the game has acted, so preventDefault() and changing a field do nothing |
disconnectClient | Heard after the game has acted, so preventDefault() and changing a field do nothing; crash reads as false, and reason is the one AMX Mod X was told |
dropPlayerItem | Heard from the player's drop command: preventDefault() stops it; event.result reads as null, and a drop the game makes itself is not heard |
dropWeaponsOnDeath | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
explodeBomb | Heard after the game has acted, so preventDefault() and changing a field do nothing; trace and damageType read as 0 |
fallDamage | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
gameThink | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
getNextBestWeapon | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
gibSpawn | Heard after the game has acted, so preventDefault() and changing a field do nothing |
giveBomb | Returning an answer does nothing; heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
giveDefaultItems | Heard as with ReGameDLL where AMX Mod X's gamedata finds the game's function; elsewhere nothing hears it |
intermission | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
itemRestricted | Asked only for "buying", as a player asks to buy: answering true forbids the purchase, false lets the game go on |
mapReset | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
newRound | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere it is heard as the round restarts - the listeners before the game when it announces the round, the ones after it once its players have respawned - but preventDefault() does nothing |
plantBomb | Heard after the game has acted, so preventDefault() and changing a field do nothing; it is heard as the bomb gets its model; returning an answer does nothing |
playerBlind | Heard after the game has acted, so preventDefault() and changing a field do nothing; inflictor and attacker read as the world, color as zero |
playerGotWeapon | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
playerKilled | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
playerSpawn | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing |
precacheFile | preventDefault() skips the precache, which answers 0; returning an answer or changing file does nothing |
precacheModel | preventDefault() skips the precache, which answers 0; returning an answer or changing file does nothing |
precacheSound | preventDefault() skips the precache, which answers 0; returning an answer or changing file does nothing |
removeGuns | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
roundEnd | Heard after the game has acted, so preventDefault() and changing a field do nothing; returning an answer does nothing; delay is the original game's 5 seconds, 3 for "gameCommence", unless game.endRound set it |
roundStart | Heard after the game has acted, so preventDefault() and changing a field do nothing |
sendDeathMessage | preventDefault() stops the message; assister and inflictor read as the world, flags as empty, rarity has "headshot" alone; changing a field does nothing |
sendUserInfo | Heard as with ReHLDS on Linux, and on Windows with a build of HLDS amxts knows; elsewhere nothing hears it. receiver is null when the engine sends to every client at once |
setModel | preventDefault() keeps the model off; changing modelName does nothing |
shouldSwitchWeapon | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
showVguiMenu | Heard as the menu is sent, to a player with VGUI menus on (not a bot): preventDefault() stops it; oldMenu reads as "", and changing a field does nothing |
spawnSpot | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere nothing hears it |
startSound | Heard for the sounds the game plays through the engine's EmitSound: preventDefault() stops it and recipients chooses its players; changing a field does nothing |
throwFlashbang | Heard after the game has acted, so preventDefault() and changing a field do nothing; it is heard as the grenade gets its model |
throwGrenade | Heard after the game has acted, so preventDefault() and changing a field do nothing; it is heard as the grenade gets its model, and eventIndex reads as 0 |
throwHeGrenade | Heard after the game has acted, so preventDefault() and changing a field do nothing; it is heard as the grenade gets its model, and eventIndex reads as 0 |
throwSmokeGrenade | Heard after the game has acted, so preventDefault() and changing a field do nothing; it is heard as the grenade gets its model, and eventIndex reads as 0 |
userInfoChange | Heard as with ReGameDLL on Linux, and on Windows with a build of Valve's game amxts knows; elsewhere heard after the game has acted, so preventDefault() and changing a field do nothing; info reads as "" |
With an
mp.dll amxts does not know - a build of Valve's game it was not
checked against - amxts does not hook the game rules' functions: the
server's console says so once, and their events are heard as the table
says for that case.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.
The rest of ReGameDLL's and ReHLDS's events - the game rules' questions the original game asks inside its own code (
teamFull, teamStacked,
balanceTeams) or only as the map starts (checkMapConditions), the
player's movement (jumpMovement, airMove, …), the engine's own
(printf, addResource, …) and the grenades' explosions - nothing on
plain HLDS hears. A listener for one is never called: the console says
so once, when it is added, the editor's tooltip of the event says so, and a
project with target: "hlds" does not build it. Listen for one that is
heard there - chooseTeam for a
side's place.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", message: "" }); // nobody scores, no message
| Option | Meaning |
|---|---|
winner | "TERRORIST", "CT", "draw" or "none" - who scores, and the game's usual message and sound for that end |
delay | seconds until the next round; 5 by default |
message | the message in the middle of the screen, or a game text such as "#Terrorists_Win", instead of the usual one; "" for none |
sound | the radio sound, such as "terwin", instead of the usual one; "" for none |
dispatch | true tells the roundEnd listeners of every plugin as when the game ends a round itself: amxts plugins' listeners, every plugin's message hooks (the message and the sound) and Pawn plugins' logevents (the log lines of a round's end). false by default: a roundEnd listener that ends the round would otherwise call itself |
Restarting the round since v0.3
game.completeReset = true; // the score from zero too, as after sv_restart
game.restartRound(); // the round starts over at once
game.checkWinConditions(); // after moving players by hand: is the round won?
game.swapTeams(); // the sides swapped, their scores too
game.balanceTeams(); // the sides evened, as mp_autoteambalance does
if (game.timeLeft < 60) server.command("say One minute left");
game.restartRound() starts the round over at once, as the game does when it
restarts one: everyone back at a spawn point with the round's money and
weapons, the map cleaned up; the score stays unless game.completeReset is
set first. The newRound listeners of every plugin hear it.
game.checkWinConditions() has the game check whether the round is won and
end it if it is, as it checks after a death: for after a plugin moved players
between sides or killed them. Both work the same on every server, plain HLDS
included.
game.swapTeams() swaps the sides and their scores, as the game does halfway
through a match. game.balanceTeams() evens them as the game does at a
round's start with mp_autoteambalance: from the bigger side the players who
came last, four at most. game.timeLeft is the seconds until the map ends by
its time limit, Infinity without one.
server.addEventListener("log", (event) => {
// World triggered "Round_Draw" (CT "3") (T "3")
if (event.args[0] == "World triggered") console.log(`the world: ${event.args[1]}`);
});
The "log" server event hears every line the game writes to its log -
a round's start and end, a kill, a bomb planted - event.text whole, without
the date, and event.args in parts, as AMX Mod X splits it: a quoted text, a
text in parentheses and the words between, each one part.
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.
gameName is the game's name in the server list, and writing it changes it
there.
ReGameDLL adds fields to the game rules, which a server without it keeps elsewhere or not at all.
timeLimit and gameStartTime are counted from
mp_timelimit and AMX Mod X's time left, which starts when a restart is
announced, and writing timeLimit sets mp_timelimit. neededPlayers and
escapeRatiosince v0.3.2 are read from the counts the game keeps -
spawnableTerrorists and spawnableCts, haveEscaped and numEscapers -
and writing them does nothing. teamBalanced and skipShowMenu are
ReGameDLL's own, true only while its balancing moves a player and while a
player joins by its mp_auto_join_team: without it they read 0 and write
nothing. The console says so once.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
Plugin
A plugin is one .ts file in the project's plugins folder. It does its work at the top level of the file: it names itself, adds commands and listens to events. What it uses from the core - plugin, server, Player - needs no import line (auto-imports).
Forwards
A forward is an event one plugin raises and other plugins hear - TypeScript and Pawn alike. It is how a plugin tells the rest of the server that a round of its game mode started, that a player bought something, that a setting changed.