Getting started

Installing on a server

A game server runs amxts plugins with two things: the amxts_amxx module and the addons/amxts folder with the plugins. The plugins are built on your machine, in a project (npx amxts build), and the server loads the .aot files a build makes - as AMX Mod X loads the .amxx compiled from a .sma. This page puts the module on a server of your own. The other way is the server in Docker, which has all of it inside.

What the server needs

  • Counter-Strike 1.6 on HLDS, Windows or Linux. ReHLDS is recommended.
  • Metamod and AMX Mod X 1.9 or later, with AMX Mod X's own modules engine, fakemeta, hamsandwich, cstrike and fun. amxts is tested on AMX Mod X 1.10 with Metamod-R.
  • ReGameDLL for every game event of its own as the game raises it, and ReHLDS for the engine's: amxts hooks their hookchains itself. Without them the plugin is written the same: the entity properties (players and entities) and the player actions (give, respawn, …) are the game's own functions, which amxts calls itself, and most game events are heard through the game's other hooks, some with less (a server without ReGameDLL). A project for such a server says target: "hlds" in amxts.config.ts (the server's includes), and a listener for an event nothing there hears does not build.
  • ReAPI is not needed: amxts hooks the game, reads the game rules and runs a player's actions itself - on ReGameDLL through ReGameDLL's own API. Its natives (get_member, rg_*) are there for a plugin that calls them directly; a plugin asks with hasModule("reapi").
Plain HLDS
On Valve's own HLDS - Metamod and AMX Mod X, no ReHLDS, ReGameDLL or ReAPI; checked with metamod-p - the events of ReGameDLL's and ReHLDS's own are heard through the game's own functions, which amxts hooks itself, and through AMX Mod X's own modules, as a Pawn plugin hears them there. What is not there:
  • the events nothing there hears - the player's movement (jumpMovement, airMove, …), the engine's own (printf, addResource, …) and the grenades' explosions: a listener for one is never called, and the server console says so once, when it is added;
  • what some of the heard ones cannot give - most come after the game has acted, so preventDefault() and a changed field do nothing there, and a few lack a field: the game events page lists them, and asking for it is one line in the console;
  • on Windows with an mp.dll amxts does not know, the game rules' functions as ReGameDLL has them: amxts hooks them in the builds of Valve's game it knows - the one steam installs and its steam_legacy branch;
  • the game rules' fields teamBalanced and skipShowMenu: they read 0 and write nothing, said once; neededPlayers and escapeRatio are read from the game's counts and not written; timeLimit and gameStartTime are counted from mp_timelimit;
  • ReAPI's own natives (get_entvar, get_member, rg_*): a call does nothing and answers 0, said once for each native.

The server kit

The kit is one archive per system, with everything that goes on the server:

systemarchivethe module
Windowsamxts-server-windows-x64.zipamxts_amxx.dll
Linuxamxts-server-linux-x64.tar.gzamxts_amxx_i386.so

Download it from the releases: the one of the same version as @amxts/core in your projects.

What is inside, laid out as it goes into the game folder (cstrike/):

addons/
├── amxmodx/
│   ├── modules/amxts_amxx.dll          amxts_amxx_i386.so on Linux
│   └── scripting/include/amxts.inc     for Pawn plugins: the fields plugins add to Player
└── amxts/
    ├── plugins.ini                     the amxts plugin list: hello.aot
    ├── plugins/hello.aot               an example plugin, built for the kit's system
    └── licenses/                       the licenses of what the module and the example are built from
README.txt

Installing

  1. Copy the kit's addons/ over the game folder's addons/.
  2. Add the module to addons/amxmodx/configs/modules.ini, on its first line, above reapi and the others:
    amxts_amxx
    

    AMX Mod X finds amxts_amxx.dll or amxts_amxx_i386.so by that name. A module listed above it does not hand its forwards to amxts (forwards). AMX Mod X's plugins.ini needs no line: amxts is the module alone (The module in AMX Mod X).
  3. Start the server, or restart it if it runs.

The first start loads the example. The console shows:

[amxts] loaded hello.aot

amxts_plugins in the server's console lists the plugins and what each is doing:

[amxts] 1 plugin(s): 1 running, 0 unloaded, 0 refused
  hello.aot  running   Hello 1.0.0  by you - An example to edit

Join the server and say /hp in chat to see the example answer.

Updating since v0.2

A server a project deploys to is updated from the project:

npx amxts upgrade

Along with the project's packages and code (upgrade), it puts the module of the new release into addons/amxmodx/modules/, keeping the old one beside it with its version (amxts_amxx.dll.0.1.0). Restart the server to load the new module. A server without a project takes the new release's kit, as when installing.

What the module writes

On every start the module makes the addons/amxts/plugins folder, and writes addons/amxts/plugins.ini - naming no plugin - when it is not there. It leaves the list alone after that: it is yours. So a server with only the module runs the plugins you put there.

The module in AMX Mod X since v0.3

amxts is one AMX Mod X module, amxts_amxx, and nothing else of AMX Mod X's: no plugin in addons/amxmodx/plugins/, no line in a plugins.ini. The module hears the game itself, through Metamod, and calls a native of AMX Mod X, of another module or of a Pawn plugin by its name. AMX Mod X keeps it loaded from the server's start to its end; each map, the module starts the amxts plugins again.

What that means on a server:

  • A new amxts_amxx takes a restart of the server: a map change keeps the module that is loaded. The plugins reload without one (Reloading).
  • AMX Mod X's own lists do not show amxts: amxx plugins lists Pawn plugins alone - amxts_plugins lists the amxts ones (Server commands); amxx cmds and amx_help do not list the plugins' commands, and amxx cvars names no plugin for a cvar one of them makes.
  • On the first map the plugins load before AMX Mod X loads the Pawn plugins, so the natives they export are there for every Pawn plugin; a native of a module AMX Mod X loads for a Pawn plugin is not there yet for a plugin's top level - call it from pluginsLoaded on.
Pawn plugins hear an event first
AMX Mod X loads the module into Metamod after every plugin of Metamod's own plugins.ini. Where AMX Mod X and the module hear the same thing at the same moment - a command, a client's event, a message - Pawn plugins hear it first, and the module knows when one of them handled it. On Metamod-R a server can place the module elsewhere by naming amxts_amxx in Metamod's plugins.ini.

The plugins

addons/amxts/plugins.ini lists the plugins the server runs, one file of addons/amxts/plugins/ per line, in the order they load. A line that starts with ; or # is left out. The plugin of a shared module loads before the plugins that use it wherever its line is since v0.3.3.

; One plugin per line: a .aot in plugins/, built with npx amxts build.
myplugin.aot
hello.aot

A .aot is a plugin built in a project, loaded as it is. It is built for the server's system: one built for Windows does not load on Linux (the server's system). A line myplugin.ts loads myplugin.aot beside it.

::: warning A server does not build .ts A server loads .aot files only: a .ts put on the server is not built. A line that names one with no .aot of its name beside it loads nothing, and the console says so as the plugins load:

[amxts] myplugin.ts is source: the server loads only .aot - build it on your machine with npx amxts build and upload the .aot

:::

A plugin is built for one line of amxts
A .aot carries the amxts it was built with and what of its API it uses, and the module loads the plugins built by any release of its own line since v0.3: a plugin built with 0.3.0 loads on the module of 0.3.2, and one built with 0.3.2 on the module of 0.3.0 - unless it uses something a later release added. Such a plugin is not loaded, the others are, and the console says what to do: [amxts] myplugin.aot needs amxts 0.3.2 or later (it uses player_glow): npx amxts upgrade. A plugin built with a core that is not released yet - from its repository - may use what no release has; the server's module then says [amxts] myplugin.aot needs a newer amxts than 0.3.2 (it uses player_glow): the server needs the module of the core it was built withsince v0.3.3. To know before an upload, check the plugins against the server's module: build --against. A plugin of another line - 0.2.x under 0.3.1 - would call into the module in ways it does not take, and the console says which one to build again: [amxts] myplugin.aot was built for amxts 0.2, this is 0.3 - build it again (or was built for an older amxts). Updating the module to another line, build the project again and deploy it (npx amxts build --deploy). A plugin keeps the code it was built with: rebuild it to take a fix the newer release made in the API.

From a project

A project deploys to the server's addons/amxts folder, which AMXTS_SERVER names in the project's .env:

AMXTS_SERVER=D:/hlds/cstrike/addons/amxts

The server's own folder (D:/hlds), its cstrike or cstrike/addons will do too: the build takes cstrike/addons/amxts under it and names the folder it uses on the Server line of its header. A folder that is none of them stops the build with one line saying where it looked.

npx amxts build --deploy copies the built .aot files into addons/amxts/plugins/ and writes addons/amxts/plugins.ini: the modules first, then the project's plugins, and every line the build does not know after them. A plugin that exports natives also gets its include copied into addons/amxmodx/scripting/include/, for Pawn plugins compiled on the server. npx amxts dev does it on every save and reloads the server over rcon (hot reload).

Reloading

The module looks at the plugins ten times a second. A .aot written again since it loaded restarts that plugin from disk, and after it the plugins that use its shared module - no map change and no command; the other plugins run on. The new file, and the files of the plugins that use its module, are read and prepared while the game runs, so the server waits only while they start. amxts_reload restarts every amxts plugin by hand, and reads plugins.ini again. Each plugin hears "end" before it stops and the map's start after it (the order).

plugins.ini is looked at the same way since v0.3.3: a line added loads its plugin, prepared while the game runs as an upload is, and a line taken out unloads it; a line that only moved changes nothing. The console says what it did:

[amxts] addons/amxts/plugins.ini changed: loading shop.aot; unloading arena.aot

A plugin whose module others use stays while they run, and says so.

A .aot or plugins.ini that is still being written - an upload over FTP or SFTP comes in pieces - is loaded once two looks in a row find its time and size alike. One read before its end anyway is refused, [amxts] myplugin.aot is incomplete or unreadable - it is loaded again once it changes, and the rest of the upload loads it.

One plugin since v0.2

amxts_unload shop       // stops shop.aot
amxts_load shop         // starts it again
amxts_reload shop       // starts it over from disk
amxts_load arena.aot    // a file of plugins/ the list does not name, until the map changes

A plugin is named by its line in plugins.ini, with or without .aot. amxts_unload stops it and takes back everything it registered - its timers, commands, game events, menus' callbacks and message listeners - and the plugin stays stopped until amxts_load or the next map; a reload of every plugin leaves it stopped too. amxts_reload <plugin> restarts that plugin alone, and the others run on.

A plugin whose shared module other plugins use holds what they made through it - a menu, a function they handed it. So amxts_unload refuses it while one of them runs and names them: unload those first. amxts_reload of it restarts them after it.

amxts_plugins shows each plugin as running with its memory in MiB, unloaded, refused with the reason - it is a .ts with no .aot, it was built for another amxts or another system, its top level failed - or stopped since v0.3.3 with the reason: it ran out of memory, or it uses the module of one that did. amxts_reload of it starts it again.

A plugin starts over
A plugin loaded again starts from its top level: what it kept in its variables is gone. What has to outlive it goes into shared player fields or Storage.

Server commands

commandwhat it does
amxts_pluginslists the plugins: file, state (running and its memory, unloaded, refused or stopped and why), name, version, author; and how many callback slots are in use
amxts_reloadreads plugins.ini again and restarts every amxts plugin from disk
amxts_reload <plugin>restarts one plugin from disk, and the plugins that use its module
amxts_unload <plugin>stops a plugin and what it registered, until amxts_load or the next map
amxts_load <plugin>starts a stopped plugin, or one of plugins/ the list does not name
amxts_tracelogs every call into a plugin, for finding what crashes the server; again to turn it off

Another plugin list

+localinfo amxts_plugins <file> on the server's command line gives the module another list, as a path from the game folder. Its plugins are the files in plugins/ beside that list:

hlds.exe -game cstrike +localinfo amxts_plugins addons/amxts/myserver/plugins.ini +map de_dust2

With a list of its own the module does not lay out addons/amxts: it runs that list and leaves the rest of the install as it is. The server in Docker runs a project's dist/ this way.