Plugin: commands, events, timers, chat, translations
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).
plugin({ name: "Welcome", version: "1.0.0", author: "you" });
server.addCommand("/hp", ({ player }) => showHp(player));
server.addEventListener("putInServer", (event) => {
event.player.print("Welcome to the server!");
});
function showHp(player: Player) {
player.print(`${player.name}, your HP: ${player.health}`);
}
Everything on this page is the core's API, @amxts/core, and is auto-imported.
Plugins in folders since v0.3.6
Every .ts file at the top of the plugins folder is a plugin; a file in a
subfolder is code the plugins import. To keep plugins in folders too, list
the folders in amxts.config.ts:
export default defineConfig({
plugins: ["modules", { path: "games", prefix: "minigame_" }],
});
plugins/
├── core.ts # plugin → core.aot
├── core/ # core.ts's code, not plugins
├── games/
│ └── hns.ts # plugin → minigame_hns.aot
└── modules/
├── duel.ts # plugin → duel.aot
└── duel/ # duel.ts's code, not plugins
A plugin's name on the server is its file's, after its folder's prefix.
Two files that come to one name, in two folders, stop the build.
Auto-imports
A plugin uses the core's API and what the project's modules give without importing it. The build finds the names a file uses and does not declare, and adds an import for each one it knows:
semiclip.rule = (player, target) => player.team == target.team;
server.addCommand("/team", ({ player }) => showTeam(player));
function showTeam(player: Player) {
const names = server.players.filter(other => other.team == player.team).map(other => other.name);
player.print(`Your team: ${names.join(", ")}`);
}
server and Player are the core's; semiclip is what
@amxts/semiclip gives, in a project whose amxts.config.ts lists it. The imports go after the
file's last line, so an error still points at the line you wrote.
- What is auto-imported: everything
@amxts/coreexports for plugins -Player,Entity,server,game,lang,effects,Cvar,Forward,Storage, the timers, the events' types (TakeDamageEvent), the names of fields and flags (Team,HideHud) - and each module's name (menus,configs,semiclip). Not the natives and constants (@amxts/core/natives,@amxts/core/constants), not files (@amxts/core/fs), not your own files: a plugin that uses them says so with an import. - A name of your own wins. A variable, a parameter or a function named
serveris yours where it is visible; the auto-import is only for the places that do not see one. - An explicit import works too:
import { Player } from "@amxts/core",import * as menus from "@amxts/menu-core". It is what a plugin writes for a module under another name, and for what is not auto-imported. - What an import names. The core's API by the package's name -
@amxts/core,@amxts/core/natives,@amxts/core/constants,@amxts/core/fs,@amxts/core/os- a module by its package's name, and your own files by~/, which is the plugins folder:import { twice } from "~/lib/math"isplugins/lib/math.ts, from any subfolder.~/names only your files: an import of the core's API by it does not build. - The editor knows the same names:
npx amxts prepare- whichdev,build,typecheckandnpm installrun first - writes.amxts/imports.d.ts, where they are globals, so completion, go to definition and the type check work without an import. It is written again when a command runs after the modules inamxts.config.tschange. - Turning it off:
imports: { autoImport: false }inamxts.config.ts; every plugin then imports what it uses.
// amxts.config.ts
export default defineConfig({
modules: ["@amxts/menu-core"],
imports: { autoImport: false },
});
A module says what it gives in its defineModule - itself as a namespace,
imports: [{ from: "@amxts/menu-core", as: "menus" }], or one of its
exports by its own name, [{ from: "@amxts/semiclip", name: "semiclip" }]
(creating a module). Two sources of one name stop
the build, which names both.
Only what is used is built
A plugin gets an import only for what it uses, so a module no plugin uses is
compiled into none of them. The build goes further: it builds a module's own
plugin, and lists it in plugins.ini, only when some plugin of the project
uses the module - through an auto-import or an explicit one, itself or through
a file it imports. A module amxts.config.ts lists and no plugin uses is left
out, and the build says so:
i module "menu-core" is installed but no plugin uses it - left out
A module whose natives Pawn plugins call - menu-core's mc_*, config-core's
cfg_* - is used by plugins the build does not see. pawn keeps it:
// amxts.config.ts
export default defineConfig({
modules: ["@amxts/config-core", "@amxts/menu-core"],
pawn: ["@amxts/menu-core"], // Pawn plugins call mc_*: built even when no plugin uses it
});
A module that does its work on its own - semiclip, whose rule covers every
player with no plugin calling it - says so in its definition (standalone),
and is built whenever amxts.config.ts lists it since v0.3.4.
What a module requires comes with it. In amxts dev a save that starts using
a module builds the module with the plugin; a module no plugin uses any more
leaves plugins.ini.
Plugin info
plugin({ name: "Welcome", version: "1.0.0", author: "you", description: "Greets players" });
The name, version and author the server lists for the plugin: amxts_plugins
in the server console shows them. description is optional. Call plugin
once, at the top of the file.
Commands since v0.2
interface KickArgs {
target: Player;
reason?: string;
}
server.addCommand<KickArgs>("/kick <target> [reason]", ({ player, target, reason }) => {
server.print(`${player.name} kicks ${target.name}`);
target.kick(reason ?? "Kicked by admin");
}, { access: "kick", description: "Kick a player" });
server.addCommand("/hp", ({ player }) => player.print(`${player.health} HP`));
server.addCommand("myplugin_heal <amount>", ({ player, amount }) => player.print(`heal ${amount}`)); // no slash: a console command
server.addCommand("say rules", ({ player }) => showRules(player)); // a chat line without a slash
The first argument is the command's usage: its name, then its arguments,
<name> one the player must type and [name] one he may leave out. The
handler gets them by those names, with player, the player who typed the
command.
The arguments' types are an interface, named and passed first, as
addCommand<KickArgs> (a type written in place, <{ ... }>, is harder to
read and cannot be used twice). Each field is how its word is read:
| type | the word | e.g. |
|---|---|---|
string | as it is; the last argument takes the rest of the line | reason in /kick bob being rude is "being rude" |
number | a number | /give 5 |
Player | #userid, the whole name or a part of it, any case | /kick bo, /kick #12 |
"on" | "off" | one of those words | /mode on |
[name] in the usage is name?: in the interface, and <name> a field
without ?. A name in the usage and not in the interface - or the other way
round - does not build, and the error says which. Without the interface every
argument is a string: ({ amount }) above is text.
When a word is not what the command takes - a number that is not one, a player nobody's name matches - the player gets the usage in chat, and the handler does not run. A part of a name several players have is answered with their names, so he can type more of it. A word too many is answered the same way, unless the last argument is text, which takes the rest of the line.
The words are apart at spaces, and a word in double quotes is one word:
/kick "Bob Smith" spam. A SteamID, or a word with :, ,, ' or
brackets, comes whole since v0.3.3 - amx_ban STEAM_0:1:123 5 gives
STEAM_0:1:123 - in the console as in chat, and so do event.args of the
"command" event.
- A name with
/is a chat command.say /hpandsay_team /hpboth run it, and the line does not show in chat; withchat: "say"among the options onlysaydoes, withchat: "team"onlysay_teamsince v0.3. - A name without
/is a console command: the player typesmyplugin_heal 50in his console. "say <phrase>"runs when a player writes exactly that phrase in chat:"say rules"runs onrules, not onrules please. It takes no arguments.
Command names are not case-sensitive: /HP runs /hp.
Several names, a handler of the player since v0.3
function checkpoint(player: Player) {
player.print("Checkpoint saved");
}
server.addCommand(["/cp", "cp"], checkpoint); // in chat and in the console
server.addCommand(["/kz", "chooseteam"], (player) => openMenu(player));
server.addCommand("/top", (player) => showTop(player));
server.addCommand(["/kick <target> [reason]", "/k"], ({ player, target, reason }) => kick(player, target, reason));
An array of names is one command: the usage first, with the arguments, then
the other names, without them. The command has one handler, one access and
one description; server.commands lists it once, with the other names in
aliases.
A command without arguments takes a handler of the player: a function whose
parameter is a name, (player) => ..., or one declared with player: Player,
gets the player who typed it. One that takes its argument apart,
({ player }) => ..., gets the command's object, as a command with arguments
does.
access is the admin right a player needs, as users.ini gives it: "kick",
"ban", "slay", "map", "cvar", "rcon", "levelA" … "levelH" and the
rest - the editor suggests them. For a player without the right the command
does nothing, and his chat line shows as a normal message. description is
for server.commands, below; AMX Mod X's amx_help lists Pawn plugins'
commands alone.
A player's own rights are player.access, an array of the same names:
player.access.includes("ban").
A player's command reaches the server's Pawn plugins before it reaches the amxts plugins. A Pawn plugin that takes it -
PLUGIN_HANDLED from
client_command or from its own register_clcmd of the same name - takes
it from these handlers too. A command a Pawn plugin sends for a player with
amxclient_cmd reaches them as a typed one does (on Valve's HLDS on
Windows, the Pawn plugins and the game alone); one sent with engclient_cmd
goes to the game alone, past every plugin. From TypeScript a
bot sends one as a player does: bot.command("say /hp")
(fake clients).A help command
server.commands lists the commands the plugin added - each one's usage,
description and access - which is what a /help prints:
server.addCommand("/help", ({ player }) => {
for (const command of server.commands) {
if (command.access == null || player.access.includes(command.access)) player.print(`${command.usage} - ${command.description}`);
}
});
Server commands
interface ResetArgs {
what?: "scores" | "all";
}
server.addServerCommand<ResetArgs>("myplugin_reset [what]", ({ what }) => {
console.log(`reset: ${what ?? "all"}`);
});
A command of the server console: typed there, sent over rcon, or run by
another plugin with server_cmd. Its usage and arguments are read as a
player's command's are; no player types it, so the handler has no player.
What it prints with console.log goes back to whoever sent the command -
over rcon, into the rcon reply.
Server events
server.addEventListener("putInServer", (event) => {
event.player.print("Welcome!");
});
server.addEventListener("disconnected", (event) => {
console.log(`${event.player.name} left: ${event.reason}`);
});
server.addEventListener("configsExecuted", loadSettings); // the server has run its configs
server.addEventListener works like addEventListener in the browser: the
first argument is the event's name, the second a function the server calls
every time the event happens. The event's name decides the type of event,
so (event) => ... needs no annotation, and the editor completes the names
and marks a misspelt one. The fields are typed: a player is a Player, a
text a string, a yes/no a boolean (event.dropped).
| Event | When |
|---|---|
"init" | the plugin starts, once all plugins are loaded |
"pluginsLoaded" | every plugin has started: the moment to make a forward other plugins hear |
"configsExecuted" | the map has loaded and the server has run its configs - server.cfg, amxx.cfg, the map's own: the moment to read cvars |
"precache" | the map loads: the moment to precache models and sounds |
"changeLevel" | the map is about to change |
"end" | the plugin stops: the map changes, the server shuts down, or the plugin is reloaded or unloaded |
"connect" | a player connects, before he is in the game |
"authorized" | a player's Steam ID is known (event.steamId) |
"putInServer" | a player is in the game |
"disconnected" | a player has left (event.dropped, event.reason) |
"playerChange" | a field plugins added to Player changed (shared player fields) |
"command" | a player sent a console command: event.command its name, event.args its words - for say and say_team the chat line's - and event.text the line after the name since v0.3 |
"impulse" | a player sent an impulse: 100 is the flashlight, 201 the spray |
"cmdStart" | a player's move command arrived: every frame of his game, every bot.move of a bot |
"suicide" | a player typed kill in the console, once the game has dealt with it |
"frame" | every server frame |
"log" | a line the game writes to its log: event.text whole, event.args its parts since v0.3 |
event.preventDefault() since v0.3 in a "command" listener stops the
command: the game does not run it - a chat line is not said - and no
plugin's server.addCommand hears it. The other "command" listeners still
do.
server.addEventListener("command", (event) => {
if (event.command == "chooseteam" && !event.player.isAlive) event.preventDefault();
});
client_command and register_clcmd handlers run first, and one that
returns PLUGIN_HANDLED stops the command before "command" hears it.A "cmdStart" listener reads and writes the player's move command before
the game moves him by it: event.forward, event.side and event.up - the
speeds in units a second, as bot.move takes them - event.angles, where he
looks, event.buttons, the buttons he holds, event.msec, the command's
length in milliseconds, and event.impulse since v0.3.3. A field
written changes the move. While his command runs, game.time is his own
clock, not the frame's (Clocks).
server.addEventListener("cmdStart", (event) => {
// A side speed the strafe keys did not give is taken away.
if (event.side != 0 && !event.buttons.includes("moveLeft") && !event.buttons.includes("moveRight")) event.side = 0;
});
The game runs a command for every frame of every player - hundreds a second on a full server - so keep the listener tiny. A field is read from the command when the listener reads it: one that reads none costs no more. A field written after an
await changes the event, not the command: the game
has moved the player by then.A reload - amxts_reload, or the plugin's .aot written again - stops the
plugin and starts it on a running map. The old one hears "end"; the new one
hears "init", "pluginsLoaded", "configsQueued" and, once the map's
configs have run, "configsExecuted", in the order a map's start has them.
"precache" does not come again: precaching needs a map change. So what a
plugin saves in "end" and sets up in "pluginsLoaded" holds across a
reload. amxts_unload raises "end", and amxts_load the start.
A reload starts the plugin with new memory: what it was in the middle of - a
run being recorded, a vote - is gone. server.keep(key, value) since v0.3.3
hands the server a value for the plugin's next start, which reads it back
with server.kept<T>(key):
let run = server.kept<Uint8Array>("run") ?? new Uint8Array(0); // the last run's, if it kept one
server.addEventListener("end", () => server.keep("run", run));
Text is kept as it is, a Uint8Array as its bytes, anything else as JSON, as
a Storage keeps it. kept gives undefined when
nothing was kept under the key.
What is kept waits in the server's memory for the plugin's next start: a reload, a new
.aot, amxts dev, or amxts_load after amxts_unload on
the same map. The new plugin reads it from its top level through its start's
events ("init", "pluginsLoaded", ...); then it is dropped, read or not. A
map change drops it, and a server restart loses it: what has to last longer
goes to a Storage or a file. A plugin that keeps something needs the amxts
module of 0.3.3 or later.event.dropped and event.reason of "disconnected" come from the
engine's own drop of the player. A server where amxts cannot reach it -
neither ReHLDS nor its signature in AMX Mod X's gamedata - gives every leave
as a quit, droppedfalse and reason empty, and says so once in the
console.In "connect", "authorized" and "putInServer" the player has not
spawned yet, so event.player is a Client: his id, name, ip,
steamId, access, team, muted, print and command, but no health or weapons.
A Player has everything a Client has, so a function that needs only these
takes a Client and works with both.
The editor lists every event; its tooltip names the AMX Mod X forward
under it (client_putinserver). What happens to a player in the game - he
thinks every frame, changes his info, touches something - is a
game event: game.addEventListener("preThink", ...),
"userInfoChange", "touch".
A listener written as a function of its own names the event's type, which is
the forward's name in words: ClientPutinserverEvent,
ClientDisconnectedEvent, ClientImpulseEvent.
server.addEventListener("impulse", onImpulse);
function onImpulse(event: ClientImpulseEvent) {
if (event.impulse == 100) event.player.print("Flashlight!");
}
server.removeEventListener("impulse", onImpulse) stops it: pass the same
function that was added.
The name is written out as a string: server.addEventListener(name, ...)
with the name in a variable is a build error, because the name picks the
event's type.
A listener is a closure, as in JavaScript: it may use the variables of the function it is written in, and they live as long as it does.
server.addEventListener("putInServer", (event) => {
const player = event.player;
setTimeout(() => player.print(`Glad to see you, ${player.name}!`), 2000);
});
A field is read from the server's call when you read it, and the next call of the same event hands out the same object. An
async listener keeps its
event as it was: after an await it reads the call it was given. A
reference kept in a variable or a timer's function does not: keep the
values, as const player = event.player above.Messages to clients since v0.2
server.addMessageListener("death", (event) => {
if (event.headshot) server.print(`${event.killer?.name} - headshot - ${event.victim?.name}`);
});
Every message the server sends a client - a chat line, a HUD icon, the round
clock, a death notice - is heard through server.addMessageListener, before
it leaves, with its arguments as typed fields. Messages
has the details and every message's name.
Game events
game.addEventListener("newRound", () => console.log("a new round"));
game.addEventListener("takeDamage", (event) => {
if (event.attacker.team == event.player.team) event.preventDefault();
});
What happens in the game - damage, spawns, deaths, round ends, buying - are
events on game, the way the server's are on server. A listener can stop
the game's action or answer in its place. They are the game's own
functions, which amxts hooks itself, and most are heard on plain HLDS too;
see Game events.
Timers
const handle = setTimeout(() => player.print("Go!"), 2000); // once, in 2 s
clearTimeout(handle); // stop it before it fires
function countdown(player: Player) {
let left = 3;
const ticking = setInterval(() => {
player.print(`${left}`);
left--;
if (left == 0) clearInterval(ticking);
}, 1000);
}
As in the browser: setTimeout runs a function once after a delay in
milliseconds, setInterval runs it every so many milliseconds, and each
returns a handle that clearTimeout or clearInterval takes. The function
may use and change the variables around it. A function without parameters
goes as itself: setTimeout(startVote, 3000).
Inside an async function, await sleep(1000) waits the same way
(async).
A timer fires on a server frame, the first one at or after its time: it is late by up to one frame, and
setTimeout(f) runs on the next frame.Time and randomness
Date.now(); // milliseconds since 1970
new Date().getHours(); // the hour on the server's clock
new Date().getUTCHours(); // the hour, UTC
const start = performance.now(); // milliseconds, to the microsecond, for measuring
Math.random(); // 0 <= x < 1, a new sequence every start
game.time; // the game's clock: seconds since the map started
Date works as in JavaScript: new Date() is now, the UTC getters
(getUTCHours, ...) and the local ones (getHours, getDate, getMonth,
getFullYear, getTimezoneOffset, ...) - local being the server's time
zone. A date becomes text as JavaScript writes it, in the server's time
zone:
const now = new Date();
now.toString(); // "Tue Sep 29 2026 14:05:09 GMT+0300"
now.toLocaleString(); // "9/29/2026, 2:05:09 PM"
now.toLocaleString("ru-RU"); // "29.09.2026, 14:05:09"
now.toLocaleDateString("de"); // "29.9.2026"
now.toLocaleTimeString("en-GB"); // "14:05:09"
toLocaleString, toLocaleDateString and toLocaleTimeString take the
language: en-US when none is named, en-GB, de, fr, ru and the
languages written as ru (uk, be, kk); another is written as en-US.
game.time is the clock
entity fields that hold a moment are on: grenade.damageTime = game.time + 1.
The attack timers - a weapon's nextPrimaryAttack, a player's nextAttack -
count from now instead: weapon.nextPrimaryAttack = 1 is a second away.
Clocks
game.timeis the game's clock: seconds since the map started, moving a frame's length each frame and standing while the server is paused. Entity fields count by it, and so dosetTimeout,setIntervalandsleep. It is a 32-bit number: a few hours into one map it steps by a millisecond.performance.now()is milliseconds since the server started, by the computer's clock, to the microsecond: for measuring how long code takes.Date.now()andnew Date()are the computer's clock, for a moment a person reads; they jump when the computer's clock is set.
Over a run of frames the three go at one pace. In a "frame" listener and
a timer, game.time is the frame's moment.
The game moves each player by the clock of his commands. While it runs one
- the hooks of his move:
preThink,postThink, a touch, a jump -game.timeis that command's moment: his client sends its commands in batches, eachmseclong, and the game lays a batch out to end one frame after the frame's moment, so the first of a batch is behind the frame and the last a frame ahead. In"cmdStart"it is still the clock the move before left, or the frame's. The game does not set it back until the next frame: what runs after a move - his chat line or console command, the next player's command, a"frame"listener after abot.move, that frame's timers - sees the clock the move left, up to a frame ahead. To time something by the server's frames, keepgame.timefrom the start of a"frame"listener.
Chat and console
player.print("Only you see this");
server.print("Everyone sees this");
player.print("Health restored!", "center"); // "chat" (the default), "center", "console", "notify"
server.print("Go!", "center"); // everyone, in the middle of the screen
console.log("to the server console");
player.print writes to one player, server.print to every player; a
Client - a player still connecting - has print too. The second argument
is where the text shows: "chat", "center"
(the middle of the screen), "console" (the player's console) or "notify"
(the console too; the game shows it on screen only with developer 1).
console.log writes a line to the server console, after [amxts];
console.warn and console.error mark theirs as a warning and an error.
Each takes a string, or an Error, which it writes with its stack
(errors).
Colours
A colour in text is a tag: ! and a letter.
player.print("!g[Shop]!y You bought !rarmor");
| Tag | Colour | Chat | Menu |
|---|---|---|---|
!y | yellow, the usual chat colour | yes | yes |
!r | red | yes | yes |
!d | grey | yes | yes |
!g | green | yes | no |
!b | blue | yes | no |
!t | the reader's team colour | yes | no |
!w | white | no | yes |
!R | aligns the rest of the line right | no | yes |
A letter means the same colour in chat and in menus.
A chat line is yellow up to its first tag: "KZ !gGG" is "!yKZ !gGG".
Each place draws the tags it has and drops the others from the text, and nothing warns:
!w and !R are for menus, !g, !b and !t for chat.
"center", "console" and "notify" have no colours: there the text shows
as written, tags included. Tags are case-sensitive: !R is not red.Red, blue, grey and
!t are drawn with a team's colour, and a chat message
has one: the first of them in the line wins, and the others show in it.
"!rRed !bBlue" shows both words red.Errors since v0.2
A call that fails - a throw nobody catches, x! on a null, an index
out of range, a stack overflow - ends that call, not the plugin: the next
event, command or timer runs as usual. The server console names the error
and where it happened, and AMX Mod X's log (addons/amxmodx/logs) keeps
the error's line since v0.3.3: a host's panel often keeps no console.
A listener is a call of its own wherever it starts from. When your code runs
a command with server_exec, emits a forward or kicks a player, the
listeners of yours that this reaches run at once, and an error in one of
them ends that listener alone: the console names it, and your code goes on
after the call. A try around the call does not catch it, as in JavaScript a
try around dispatchEvent does not.
function price(item: Item | null): number {
return item!.price;
}
function onSelect(): number {
return price(null);
}
A plugin amxts dev compiles keeps a record of its calls: the console names
each call that led to the error, with its file, line and column in your
TypeScript, and shows the line itself under the first call of your own code:
[amxts] myplugin.aot: TypeError: Unexpected 'null' (not assigned or failed cast)
at price (plugins/myplugin/shop.ts:26:9)
26 | return item!.price;
at onSelect (plugins/myplugin/shop.ts:30:15)
at timerFired (node_modules/@amxts/core/as/facade.ts:3772:2)
A plugin amxts build compiles keeps no such record, which would slow a
busy plugin down (performance). The
console names the error and, for a throw, an x! or a failed check, the
place of the statement that failed; a stack overflow says its message
alone:
[amxts] myplugin.aot: TypeError: Unexpected 'null' (not assigned or failed cast) (plugins/myplugin/shop.ts:26:9)
An error you catch has the same stack: error.stack is that text, from
where the error was made, and console.error(error) writes it. In a plugin
amxts build compiles, error.stack is the error's first line.
try {
buy(player, item);
} catch (error) {
console.error(error); // "Error: ..." and, in a dev build, the calls under it
}
The line under the first call shows when the server can read your .ts
file, as it can with amxts dev. Calls inside AssemblyScript's own library
- an array's methods,
String- show their name without a place.
Out of memory since v0.3.3
A plugin's memory grows as it keeps more, and never shrinks while it runs:
amxts_plugins shows each running plugin's memory in MiB. When it cannot
grow - the server has no room left for it - the call that needed it fails,
and the plugin cannot go on: what it ran next would fail inside its memory
manager, call after call. So the module stops it at the next frame, as
amxts_unload does, and the plugins that use its
shared module with it. One line in the
console and in AMX Mod X's log says why:
[amxts] myplugin.aot stopped: out of memory, its memory 1280.0 MiB - amxts_reload myplugin.aot starts it again
amxts_plugins lists it as stopped with the reason. amxts_reload myplugin,
a new .aot or the next map starts it again, and the plugins stopped with it.
Any other error ends only its call.
The game server is a 32-bit process: the game, its modules and every plugin share a few GiB of addresses. A plugin's memory grows by doubling, so one that holds about 1 GiB may find no room for the next step. A plugin that keeps a record of everything that ever happened runs out in the end: keep what has to last in
Storage or a database, and
let go of the rest.Menus since v0.2
Real menus - a shop, an admin menu, a vote - are what the official module menu-core is for: menus in INI, YAML or JSON files the server owner edits without a build, items shown and enabled by conditions,
%placeholders%,
lists of players and of your own rows, menus Pawn plugins add items to, and
the editor checking a menu file as it is typed. Add it with
npx amxts module add menu-core and read Menus.A quick menu in code
Menu is a menu as an object: a title, items, and show(player). It looks
and pages as AMX Mod X's own menus do, is part of the core and needs no
module - for a menu or two a plugin builds in code.
interface ShopData {
category: string;
}
const shop = new Menu<ShopData>(({ data }) => `!yShop: ${data.category}`);
shop.addItem({
title: "Armor - !y$1000",
enabled: ({ player }) => player.armor < 100,
onSelect: ({ player }) => {
player.armor = 100;
},
});
shop.addItem({
title: ({ player }) => `Heal !d(${player.health} HP)`,
visible: ({ player }) => player.isAlive,
enabled: ({ player }) => player.health < 100,
onSelect: ({ player, menu, data }) => {
player.health = 100;
menu.show(player, data); // stays open
},
});
server.addCommand("/shop", ({ player }) => shop.show(player, { category: "all" }));
- An item is an object: its
title,visible- whether it is shown,enabled- whether it can be chosen, andonSelect, what choosing it does.visibleandenabledaretruewhen left out; a hidden item takes no place, one that cannot be chosen is drawn grey and does nothing. - Each function gets the context:
player, the one the menu is shown to;menu, the menu itself;data, whatshowwas given.Data, the type argument, says what that is - a menu shown without data leaves it out. - A title,
visibleandenabledmay be a function, or a plain value: they are worked out at everyshow, for that player. - After a choice the menu closes.
onSelectthat shows it again keeps it open. - Pages, Back, More and Exit are drawn as AMX Mod X draws them: seven items to a page, the rest on the next ones.
- A menu shown over it takes its keys: another
Menu, a Pawn plugin's menu, the game's own (the radio menu). AMenushown over a Pawn plugin's menu closes that one, as AMX Mod X's menus close each other - its handler hearsMENU_EXIT.amxts_reloadoramxts_unloadof the plugin closes its menus: a key pressed on one does nothing. - Colour tags are the ones of chat and menus:
!yyellow,!rred,!dgrey,!wwhite,!Rto the right edge. - A line without a number since v0.3:
addText(text)puts a line of text under the last item added - under the title before the first - andaddBlank()an empty one; they are shown and hidden with that item.
Make a menu once, at the top level of the file, and show it as often as needed. The options are the second argument:
const vote = new Menu("!yNext map?", {
perPage: 0, // every item on one page, no Back and More (up to 10)
exit: false, // no Exit item
numberColor: "!y", // the item numbers in yellow, not red
backText: "Back",
nextText: "Next",
exitText: "Close",
});
AMX Mod X's menus
Old-style menus - text and the keys that answer - are showMenu of
@amxts/core/kit, with register_menucmd for the keys: its handler is
given by the name of a public, which publicFor of the same kit makes for a
function (calling natives directly).
AMX Mod X's own menus (menu_create) look for the Pawn plugin calling them
and are out of reach (limitations).
The server's plugins since v0.3
for (const plugin of server.plugins) {
console.log(`${plugin.file} ${plugin.language} ${plugin.version} ${plugin.running}`);
}
const shop = server.plugins.find(plugin => plugin.file == "shop.aot");
shop?.stop(); // unloaded - a Pawn plugin paused - until start() or the map changes
shop?.start();
shop?.reload(); // from its file again; a Pawn plugin cannot be reloaded
server.loadPlugin("event.aot"); // a file of plugins/ the list does not name
const ranks = server.plugins.find(plugin => plugin.file == "ranks.amxx");
ranks?.call("show_rank", player); // a public of a Pawn plugin
server.plugins lists every plugin on the server, TypeScript and Pawn: its
file, the name, version and author it gives itself, its language, and
whether it is running. stop(), start(), reload() and
server.loadPlugin(file) act at the next frame - as the console's
amxts_unload, amxts_load and amxts_reload would - so a plugin may stop
itself, or the one that called it.
AMX Mod X loads its plugins once a map:
stop() pauses a Pawn plugin and
start() lets it run on, its state kept; reload() throws. A TypeScript
plugin is unloaded and loaded again, its state started over.Translations
Text in the reader's language comes from a dictionary: a file in
data/lang, a section per language and a line per key.
[en]
MYPLUGIN_WELCOME = Welcome, ^4%s^1!
MYPLUGIN_ON = \d[\yOn\d]
[ru]
MYPLUGIN_WELCOME = Добро пожаловать, ^4%s^1!
MYPLUGIN_ON = \d[\yВкл\d]
lang.load("myplugin"); // data/lang/myplugin.txt
server.addEventListener("putInServer", (event) => {
event.player.print(lang.translate(event.player, "MYPLUGIN_WELCOME", [event.player.name]));
});
lang.translate(player, key, args) gives the key's line in the player's
language - his lang setinfo - and null for the player gives the server's
(amx_language). A language the dictionary lacks falls back to the server's.
%s, %d and %f (%.1f, %02d) are filled from args, which are
strings: a number goes in as text, `${seconds}`. A placeholder with no
argument left for it stays as written, and a key no dictionary has comes back
as the key itself.
AMX Mod X reads a dictionary line up to 511 bytes - about 255 Cyrillic letters; the rest of a longer line is cut.
player.language is that language, for what a dictionary does not hold - a
sound, a picture: player.language == "ru". It is his lang setinfo, or the
server's language when he has none or amx_client_languages is 0.
lang.languages() since v0.3 lists the languages of the dictionaries
the plugin loaded, by their codes, in the files' order: ["en", "ru"] - for
a menu where a player picks his. lang.languages("myplugin") lists one
dictionary's. Neither lists the languages of AMX Mod X's own dictionaries,
which the server has for its own messages.
A dictionary writes colours as AMX Mod X does - \y in a menu, ^4 in
chat - and lang.translate gives them back as tags: \y is !y,
\r !r, \d !d, \w !w, \R !R, ^1 !y, ^3 !t, ^4 !g.
So one line works in a menu and in chat; each place drops the tags it cannot
draw (!w in chat). ^n is a line break.
A dictionary written on a running server is read again as soon as its upload is over since v0.3.3 - with its plugin's reload or after it, whichever comes first.
A dictionary read again changes and adds lines; a key taken out of the file keeps its old line until the map changes.
HUD messages
player.showHud("Round 3", { color: [255, 40, 40], y: 0.3, hold: 2 });
server.showHud("For everyone");
Text on the screen outside chat. The options, the large director letters and
HudLine are on Players.
Sounds and precaching
server.precache("myplugin/hit.wav");
server.precache("models/myplugin/box.mdl");
function hit(player: Player) {
player.emitSound("myplugin/hit.wav"); // everyone near hears it
player.emitSound("myplugin/hit.wav", { volume: 0.5, pitch: 120, channel: "voice" });
player.playSound("vox/one.wav"); // he alone, as the radio
}
A model, a sprite or a sound the game uses is precached while the map loads:
server.precache(path) at the top level of the file precaches it then, and
in the "precache" event at once. It also makes players download the file. A
sound is written as the game plays it, under sound/ ("myplugin/hit.wav");
a model or a sprite with its folder ("models/myplugin/box.mdl"). It returns
the file as a Resource, which an effect takes for a sprite or
a model.
entity.emitSound(sample, options) plays a sound from an entity - a player
too - heard by everyone near and fading with distance. Every option has a
default:
| Option | Default | Meaning |
|---|---|---|
channel | "auto" | the entity's channel: "auto", "weapon", "voice", "item", "body", "stream", "static"; a new sound on a channel cuts the one playing there, "auto" never cuts |
volume | 1 | 0 to 1 |
attenuation | 0.8 | how fast it fades with distance: 0 is heard across the map, 2 only close by |
pitch | 100 | in percent: 50 is an octave lower, up to 255 |
to since v0.3.1 | everyone near | the one player who hears it, from where the entity is: door.emitSound("myplugin/creak.wav", { to: player }) |
player.playSound(sample) plays a sound to one player, heard as it is
wherever he stands, as the radio is.
A sound the game plays - a step, a jump, a reload - is the
game event "startSound": preventDefault() keeps it silent,
and recipients since v0.3.1 plays it only to the players chosen of
those it would reach:
const deaf = new Set<number>(); // the ids of players who hear no one else
game.addEventListener("startSound", (event) => {
const source = event.entity.id;
if (source < 1 || source > server.maxPlayers) return;
event.recipients = server.players.filter(player => !deaf.has(player.id));
});
A player hears his own steps and jumps from his own game, not from the server:
recipients chooses among the other players."precache" event; its top level runs again, and a Resource asked
for there finds the index the map gave the file. A file no plugin precached
while the map loaded waits for the next map.server.precached since v0.3.3 says how much of the engine's room the
map has taken - models (sprites among them, and the map's own), sounds
and other files - counted from every precache, the game's and every
plugin's, Pawn ones too:
server.addEventListener("pluginsLoaded", () => {
console.log(`models: ${server.precached.models} of 512`);
});
The engine has room for 512 models, 512 sounds and 512 other files a map, and a precache past it stops the server. Once a kind is at 461 - nine tenths of it - and again once it is full, the console and AMX Mod X's log say so, with the file precached last and the plugin that precached it (an amxts plugin by name; one of Pawn or the game as such). A map with many models of its own leaves the plugins less room: its models count as precached.
The server
server.map; // "de_dust2"
server.maxPlayers; // 32
server.configsDir; // "addons/amxmodx/configs"
server.dataDir; // "addons/amxmodx/data"
server.logsDir; // "addons/amxmodx/logs"
server.command("changelevel de_nuke"); // runs in the server console
server.command runs a line in the server console as if it were typed there.
To run one in a player's console: player.command("say hi").
server.game; // "cstrike"
server.versions.reGameDll; // "5.28", null on the original game
server.mapExists("de_nuke"); // true when the server has the map
server.changeLevel("de_nuke"); // goes there now; false for a map it does not have
server.lightStyle = "b"; // darker, "a" to "z", "m" the map's own, until the map changes
server.intermission(); // the scoreboard to everyone, their view still, until the map changes
server.print("Round 3"); // to every player's chat; "center", "console" as in print
server.game since v0.3, server.versions since v0.3 - amxts's,
AMX Mod X's and Metamod's versions, ReHLDS's and ReGameDLL's API or null -
server.mapExists since v0.3, server.changeLevel since v0.3,
server.lightStyle since v0.3, server.logsDir since v0.3,
server.print since v0.3 and server.intermission since v0.3.1 - the
intermission, as the game shows it at a map's end; change the map a few
seconds later with server.changeLevel.
Limitations
What amxts cannot do yet, each with what to write instead. The build, the editor or the server console says so for almost every item below; this page is where to look up what it means.
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: