Messages
The server tells each client what to draw and play through messages: a chat line, a HUD icon, the round clock, a death notice. A plugin hears a message before it leaves, reads it, changes it or stops it:
server.addMessageListener("death", (event) => {
if (event.headshot) server.print(`${event.killer?.name} - headshot - ${event.victim?.name}`);
});
server.addMessageListener("text", (event) => {
if (event.text == "#Round_Draw") event.preventDefault(); // the client does not get it
});
server.addMessageListener("team", (event) => {
if (event.team == "SPECTATOR") console.log(`${event.target?.name} watches`);
});
server.addMessageListener("roundTime", (event) => {
event.seconds = 90; // the clock shows 90
});
server.removeMessageListener("death", listener) stops it: pass the same name
and the same function that were added. Only the messages listened for reach
the plugin.
A message's name is written out as a string, and the editor lists the names,
each with what the game uses the message for and the game's own name of it:
death is the game's DeathMsg, chat its SayText. The table at the end
of the page has them all.
A few of the game's messages are one thing to a plugin, and one name hears
them all: progressBar is BarTime and BarTime2, which only adds where
the bar starts. The event has the fields of every one of them, and
event.name says which one came; a field the message that came does not
carry reads as 0, null or empty, and assigning it changes nothing -
startPercent is 0 on a BarTime.
server.addMessageListener("progressBar", (event) => {
console.log(`${event.name}: ${event.seconds} s from ${event.startPercent}%`);
});
The event
event.player is the player the message goes to, null for one sent to
everyone, so a player the message is about is a field of its own: target,
or its role - killer, victim, sender. preventDefault() stops the
message. event.name is the game's name of the message, "DeathMsg" for
death.
The game writes each message in a layout of its own, and a message whose
layout is known - almost every one Counter-Strike sends - has a field for
each of its arguments, named and typed: a player is a Player (null for
none), a flag a boolean, a team a Team, a weapon a WeaponKind, a mask
an array of names, a time in seconds. The editor lists them. Assigning a
field changes what the client gets: event.team = "CT".
server.addMessageListener("hideWeapon", (event) => {
event.flags = event.flags.concat(["money"]); // the money is hidden too
});
A message whose layout is not known - a bot's progress, the tutor's texts -
is read by the place of its arguments, through event.args, which every
message has for what its fields leave out:
server.addMessageListener("botProgress", (event) => {
console.log(`${event.args.length} ${event.args.number(0)}`);
});
event.args.number(i) and event.args.text(i) read the argument at i,
0 for the first; isText(i) tells which it is; setNumber(i, value) and
setText(i, value) change it.
An argument the message did not write - statusIcon's colour when it hides
the icon, the params of a text that takes none - reads as 0 or empty, and
assigning it changes nothing. A name the game has no message for is a build
error.
message_begin does not reach the listeners:
they hear what goes through the engine's functions, as AMX Mod X's
register_message does. One sent with emessage_begin does, and so do the
ones player.screen sends and the one player.money sends when it is
written.A Pawn plugin's
register_message or set_msg_block on a message hears it
first, and AMX Mod X sends the message as that plugin leaves it. The
listeners then hear it as the game wrote it, and what they change or block
of it is not sent; the server's console says so once for the message.menu is every text menu a player is shown - the game's, and a plugin's
too: a Menu, menu-core's, a Pawn plugin's show_menu. Blocking one by a
word of its text hides a plugin's menu that has the word. The game's own
menus come as its keys - #Team_Select, #CT_Select, #Terrorist_Select,
#RadioA - so compare event.text with those. A menu or a vguiMenu
that is blocked never reaches the player, and the menu already on his
screen keeps its keys.Sending a message since v0.3
What a plugin often sends has a method of its own - player.screen.fade(),
player.money, player.showMotd(). Any other message of the table below
that has fields is sent by its name, with the same fields its listeners read:
player.send("team", { target: other, team: "CT" }); // to one player
server.send("score", { target: player, frags: 10, deaths: 2, team: "CT" });
server.send("bombDrop", { origin: [0, 0, 64] }, { near: player.origin }); // to the players who see the point
The editor lists the names send takes and each one's fields. A field left
out goes as 0 or empty text, so a message is given whole; listeners hear it
on its way, as the game's own. player.send reaches the player reliably;
server.send everyone, and with near only the players who can see that
point - not reliably, as effects go. A name of several messages sends the one
with all their fields: progressBar sends BarTime2.
The client draws what a message says: a
team message paints a player's
name in another colour without moving him to another team, a money
message shows a sum he does not have. To change the game, change the player
(player.team, player.money); send a message to show something the game
does not.A message of the plugin's own since v0.3.3
A client-side mod - a HUD of its own, a speedometer - reads the messages it
knows by their names. A plugin gives it one with UserMessage: made at the
top level, the message is registered as the server starts, and its values
are written one after another, then sent to one player or to everyone:
const jump = new UserMessage("KzJump");
server.addCommand("/jump", ({ player }) => {
jump.byte(1).coord(player.origin.z).text(player.name).send(player);
});
server.addEventListener("putInServer", () => jump.byte(0).sendAll());
The client reads the values in the order they were written, each as it was written:
| Method | Writes | Bytes |
|---|---|---|
byte(value) | a number, 0 to 255 | 1 |
char(value) | a number, -128 to 127 | 1 |
short(value) | a number, -32768 to 32767 | 2 |
long(value) | a whole number | 4 |
angle(value) | an angle in degrees, to the nearest 1.4 | 1 |
coord(value) | a coordinate, to an eighth of a unit, -4096 to 4096 | 2 |
text(value) | a text: its UTF-8 bytes and a zero | its bytes + 1 |
entity(value) | an entity or a player, as its id; 0 for null | 2 |
send and sendAll send what was written since the last send. Every
plugin's message hooks hear it on its way, and a Pawn plugin finds it by its
name: get_user_msgid("KzJump") answers its id, and message_begin takes
it. One name is one message - for every plugin, and on every map.
A UserMessage of a name the game registers itself is the game's message
since v0.3.5: new UserMessage("BuyClose").send(player) closes the player's
buy menu. One the game registered with a fixed size is sent only with
exactly that many bytes written - BuyClose with none - and the server's
console says so when the size differs.
A message's name is at most 11 characters, and a message carries at most 192 bytes. The engine has room for 192 messages, the game's among them - a Counter-Strike server registers about a hundred. A message whose name is too long is not registered, one larger than that is not sent, and the server's console says why. A
message_begin with an id of a name that
was not registered is refused with a plugin error. A bot's game gets no
message: the engine drops what is sent to a bot.A
UserMessage made at the top level is registered as the plugin starts,
before the players come. One made later is registered at once, and the
engine tells the players already in about it; Valve's HLDS does that in the
next frame, so a message sent in the frame it is made in is lost there.Shots and other played events since v0.3
A shot's sound and flash, a knife's swing, a grenade's bounce are not
messages: the engine plays them to the players near as events. The
"playbackEvent" server event hears each one; preventDefault() stops it
for everyone, and recipients plays it only to the players chosen of those
it would reach:
const hidden = new Set<number>(); // the ids of players who hide others
server.addEventListener("playbackEvent", (event) => {
if (event.entity < 1 || event.entity > server.maxPlayers) return;
event.recipients = server.players.filter(player => !hidden.has(player.id));
});
event.entity is what plays it - for a shot, the player who fired.
recipients chooses among the other players: the one who plays the event
is not left out by it, as his game shows his own shots itself. An event
with no entity plays to everyone.Temporary effects since v0.3.3
A decal on a wall, a spray, sparks, a beam: the game sends each as a
temporary effect, the tempEntity message, and its listeners hear it before
it leaves. event.type is the effect's number, one of the TE_* constants;
the rest of its arguments are read by place, through event.args, the first
after the type at 1. event.source is what made it.
event.recipients = players sends a message only to those of the chosen
players it would reach, and to nobody else - any message, not only an
effect. Here a hidden player's sprays are kept from the players who hide
others:
import { TE_DECAL, TE_PLAYERDECAL, TE_WORLDDECAL } from "@amxts/core/constants";
const hidden = new Set<number>(); // the ids of hidden players
const hidesOthers = new Set<number>(); // the ids of players who hide them
server.addMessageListener("tempEntity", (event) => {
if (event.type != TE_DECAL && event.type != TE_WORLDDECAL && event.type != TE_PLAYERDECAL) return;
const maker = event.source?.owner ?? 0; // a spray can's player
if (hidden.has(maker)) event.recipients = server.players.filter(player => !hidesOthers.has(player.id));
});
A message to everyone reaches every player in the game; one to the players who see or hear a point reaches only those of the chosen who do; one to a single player reaches him if he is chosen. Each chosen player gets a copy of his own.
The game's temporary effect carries no player:
event.source is the entity
whose think made it, else the player whose command made it, and null when
neither. A spray is the spray can's think, an entity without a classname
whose owner is the player; an effect made while a player's move runs is
that player's. A knife's mark on a wall is no message at all - the game
leaves it to the client of the one who swung - and the knife's sounds come
from the player, heard by the "startSound" game event.Every message
| Name | The game's name | What it is | Fields |
|---|---|---|---|
adStop | ADStop | A player's HUD stops showing the round's advertisement. | - |
allowSpectate | AllowSpec | Whether a player may pick Spectate in the team menu. | allowed |
ammo | AmmoX | A player's reserve ammo of one kind on his HUD changes. | ammo, amount |
ammoPickup | AmmoPickup | A player picks up ammo: the notice at the side of his screen. | ammo, amount |
armor | Battery | A player's armour on his HUD changes. | armor |
armorType | ArmorType | The armour icon on a player's HUD: a vest, or a vest and a helmet. | helmet |
bombDrop | BombDrop | The bomb on the terrorists' radar: dropped or planted. | origin, planted |
bombPickup | BombPickup | The bomb is picked up: it leaves the terrorists' radar. | - |
botProgress | BotProgress | The progress bar a player's client shows while the bots learn a new map. | args |
botVoice | BotVoice | The voice icon over a bot who talks on the radio. | talking, target |
chat | SayText | A chat line. | sender, text, params |
closeBuyMenu | BuyClose | A player's buy menu is closed. | - |
corpse | ClCorpse | A dead player's body is left on the ground for the clients to draw. | model, team, target |
crosshair | Crosshair | Counter-Strike's own crosshair on a player's screen is shown or hidden. | shown |
currentWeapon | CurWeapon | The weapon in a player's hands and its clip on his HUD. | active, weapon, clip |
czCareer | CZCareer | A step of Condition Zero's career, its single-player campaign. | args |
czCareerHud | CZCareerHUD | Condition Zero's career on a player's HUD. | args |
damage | Damage | A player is shown the damage he took: the red marks at the side of his screen. | armor, damage, damageType, origin |
death | DeathMsg | A kill in the top right corner of every screen. | killer, victim, headshot, weapon |
flashlight | Flashlight | The flashlight icon on a player's HUD: on or off, and its battery. | on, battery |
flashlightBattery | FlashBat | The flashlight's battery on a player's HUD changes. | battery |
fog | Fog | The fog on a player's screen: its colour and density. | args |
forceCamera | ForceCam | The views a dead player may watch the game in, as mp_forcecamera and mp_forcechasecam allow. | args |
fov | SetFOV | A player's field of view is set. | fov |
gameMode | GameMode | Whether the game is played in teams, for a player's client. | args |
gameTitle | GameTitle | The game's title on a player's screen when he enters the game. | args |
geiger | Geiger | The Geiger counter's clicks a player hears near radiation. | range |
health | Health | A player's health on his HUD changes. | health |
hideWeapon | HideWeapon | The parts of a player's HUD that are hidden change. | flags |
hint | HudText, HudTextArgs, HudTextPro | A hint in the middle of a player's screen. | text, params |
hltv | HLTV | A note to the HLTV proxies, such as a new round's start. | args |
hostageKilled | HostageK | A hostage is killed: it leaves the counter-terrorists' radar. | hostage |
hostagePosition | HostagePos | A hostage on the counter-terrorists' radar. | hostage, origin |
initHud | InitHUD | A player's HUD is set up, when he enters the game. | - |
itemPickup | ItemPickup | A player picks up an item: the notice at the side of his screen. | item |
itemStatus | ItemStatus | The night vision and the defuse kit a player has, for his HUD. | nightVision, defuseKit |
location | Location | The place on the map a player is in, as the radio names it. | target, place |
menu | ShowMenu | A text menu on a player's screen - the team menu without VGUI, the radio, a plugin's menu. | more, text |
money | Money | A player's money on his HUD changes. | amount, flash |
moneyBlink | BlinkAcct | A player's money on his HUD blinks: he cannot afford what he tried to buy. | blinks |
motd | MOTD | A part of the message of the day, the window a joining player sees. | last, text |
nightVision | NVGToggle | A player's night vision is turned on or off. | on |
progressBar | BarTime, BarTime2 | The progress bar in the middle of a player's screen is shown or hidden, from empty or part of the way full. | seconds, startPercent |
radar | Radar | A teammate on a player's radar. | target, origin |
reloadSound | ReloadSound | The sound of a weapon reloaded nearby, for a player's client. | args |
requestState | ReqState | The game asks a player's client for its state, for the voice. | - |
resetHud | ResetHUD | A player's HUD is reset, at his spawn. | - |
roundTime | RoundTime | The round clock at the top of a player's HUD is set. | seconds |
scenarioIcon | Scenario | The scenario icon on a player's HUD, such as the bomb's or a hostage's. | active, sprite, alpha |
score | ScoreInfo | A player's row on the scoreboard. | target, frags, deaths, team |
scoreAttribute | ScoreAttrib | The marks the scoreboard shows beside a player: dead, the bomb, the VIP. | target, flags |
screenFade | ScreenFade | A player's screen is coloured, fading in or out - a flashbang, a fade to black. | duration, hold, direction, modulate, stay, color |
screenShake | ScreenShake | A player's view shakes - an explosion nearby. | amplitude, duration, frequency |
serverName | ServerName | The server's name a player's client shows. | serverName |
shadow | ShadowIdx | The sprite a player's client draws the players' shadows with. | args |
shellCasing | Brass | A spent shell a weapon throws out, for the clients to draw. | args |
showTimer | ShowTimer | The round clock appears on a player's HUD. | - |
sound | SendAudio | A sound played to a player, such as a radio line. | sender, sound, pitch |
spectatedHealth | SpecHealth, SpecHealth2 | The health of the player a spectator watches. | health, target |
spectator | Spectator | A player becomes a spectator, or stops being one, on the scoreboard. | target, spectator |
statusIcon | StatusIcon | A status icon on a player's HUD - the buy zone, the bomb - is shown, flashed or hidden. | state, sprite, color |
statusText | StatusText | The status line at the bottom of a player's screen, such as the name of the player he aims at. | line, text |
statusValue | StatusValue | A value the status line shows, such as the player a player aims at. | slot, value |
taskTime | TaskTime | The countdown of a task on a player's HUD, such as rescuing the hostages in a career. | seconds, active, fade |
team | TeamInfo | A player's team on the scoreboard. | target, team |
teamScore | TeamScore | A team's score on the scoreboard. | team, score |
tempEntity | SVC_TEMPENTITY | A temporary effect - a decal on a wall, a spray, a spark, a beam. The engine's message. | type, source, args |
text | TextMsg | A text from the game - an announcement, a hint - in chat, the console or the middle of the screen. | destination, text, params |
train | Train | The speed of the train a player drives, on his HUD. | speed |
tutorClose | TutorClose | A tutor's message on a player's screen closes. | - |
tutorLine | TutorLine | A tutor's pointer on a player's screen, at a thing in the world. | args |
tutorState | TutorState | The tutor's state on a player's client. | args |
tutorText | TutorText | A tutor's message on a player's screen. | args |
vguiMenu | VGUIMenu | A VGUI menu of the game opens on a player's screen: the team menu, the class menu, the buy menu. | menu |
viewMode | ViewMode | A player's view goes back to first person. | - |
voiceMask | VoiceMask | The players a player hears on the voice chat, and the ones he has muted. | args |
weaponList | WeaponList | A weapon's description for a player's client: its ammo, its slot, its place in the slot. | classname, ammo, maxAmmo, ammo2, maxAmmo2, slot, position, weapon |
weaponPickup | WeapPickup | A player picks up a weapon: the notice at the side of his screen. | weapon |
weather | ReceiveW | The weather on the map, rain or snow, for a player's client. | args |
Cvars
A cvar is a server setting with a name: mp_freezetime, sv_gravity, or one of your plugin's own. A Cvar object reads and writes one:
Storage
Storage keeps values by key, like a Map, but on disk: what a plugin stores survives a map change and a server restart. It is the place for a player's saved points, his last visit, a preference.