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:
const freezeTime = new Cvar("mp_freezetime");
const speed = new Cvar("myplugin_speed", "250"); // created with "250" if the server has no such cvar
speed.addEventListener("change", (event) => {
console.log(`${event.cvar.name}: ${event.oldValue} -> ${event.value}`);
});
function startWarmup() {
freezeTime.number = 0;
console.log(`speed ${speed.number}, text "${speed.value}", on: ${speed.boolean}`);
}
Like an input's value, a cvar is text underneath, and it can be read and
written three ways:
| Property | Reads | Writes |
|---|---|---|
value | the text: "250" | the text |
number | a number: 250 | a number; a whole one is written without a fraction ("5", not "5.000000") |
boolean | true for anything but 0 | true as 1, false as 0 |
The second argument of new Cvar is the default. When the server has no cvar
by that name, it is created with that value - the way a plugin adds its own
settings. Without a default, a missing cvar stays missing: exists is
false, reading gives "", 0 and false, and writing does nothing.
Make a Cvar once, at the top of the file, and use it from there. A Cvar
made at the top of the file finds its cvar once the server has loaded every
plugin, so the game's own cvars and those of other plugins are there by the
time your code reads them.
Hearing a change
addEventListener("change", listener) calls the listener on every change -
from the console, from a config, from amx_cvar, from another plugin or from
this one - once, after the change, with event.cvar, event.oldValue and
event.value (both as text). A value set again as it was is no change.
removeEventListener("change", listener) with the same function stops it.
hook_cvar_change hears a change before the listeners. On a
server without ReHLDS whose AMX Mod X gamedata has no signature of the
engine's Cvar_DirectSet, a change is heard on the frame after it is made.A plugin that reads its settings once can do it in the "configsExecuted" event, after
the server has run its config files (Plugin):
const reward = new Cvar("myplugin_reward", "300");
let rewardMoney = 0;
server.addEventListener("configsExecuted", () => {
rewardMoney = reward.number;
});
For settings richer than a few numbers - lists, nested sections, per-map values - a config file is often the better place (Configs).
Secrets and server settings: env() since v0.3
A token, a password or a key in a URL does not belong in a plugin's code:
anything compiled into a .aot can be read out of it. Put it in the server's
addons/amxts/.env instead, and read it with env():
# addons/amxts/.env
MYPLUGIN_TOKEN=abc123
MYPLUGIN_MAX_RECORDS=500
MYPLUGIN_DEBUG=on
const token = env("MYPLUGIN_TOKEN"); // text, required
const maxRecords = env("MYPLUGIN_MAX_RECORDS", 100); // a number, 100 when there is none
const debug = env("MYPLUGIN_DEBUG", false); // an on/off switch
const mirror = env("MYPLUGIN_MIRROR", "https://example.com/maps"); // text, with a default
Every plugin on the server reads the same file. A line is NAME=value, #
starts a comment, and a value in quotes is kept as it is, # and spaces
included. A variable of the server process's environment - one a game panel or
Docker sets - wins over the file's line of the same name.
The default says what the value is:
| Call | Gives | The value in .env |
|---|---|---|
env("NAME") | text | anything; the variable is required |
env("NAME", "text") | text | anything |
env("NAME", 100) | a number | a decimal number: 500, -1.5, 2e3 |
env("NAME", false) | true or false | 1/0, true/false, yes/no, on/off, in any case |
The name and the default are written out in the call - env(name) or
env("NAME", limit) does not build: the build reads from the call what each
plugin needs. A plugin does not start while a variable it reads without a
default is nowhere, or while a value is not of its default's kind. The console
says so in one line:
[amxts] myplugin needs MYPLUGIN_TOKEN in addons/amxts/.env
[amxts] myplugin needs MYPLUGIN_MAX_RECORDS as a number in addons/amxts/.env
and amxts_plugins lists the plugin as refused for the same reason. Fix the
line in .env, and amxts_reload myplugin reads the file again and starts
it. amxts dev and amxts build --deploy warn when the server's .env lacks
what a plugin needs; they never copy .env itself.
.env is a file in the game folder: anyone with FTP access to the server can
read it. No console command prints a value, so rcon cannot. Every plugin on the
server can read every variable.Flags
Some game data is a set of on/off flags: which buttons a player holds, which parts of the HUD are hidden, whether an entity is on the ground. In a plugin such a set is an array of names:
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: