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,cstrikeandfun. 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 saystarget: "hlds"inamxts.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 withhasModule("reapi").
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.dllamxts 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 itssteam_legacybranch; - the game rules' fields
teamBalancedandskipShowMenu: they read0and write nothing, said once;neededPlayersandescapeRatioare read from the game's counts and not written;timeLimitandgameStartTimeare counted frommp_timelimit; - ReAPI's own natives (
get_entvar,get_member,rg_*): a call does nothing and answers0, said once for each native.
The server kit
The kit is one archive per system, with everything that goes on the server:
| system | archive | the module |
|---|---|---|
| Windows | amxts-server-windows-x64.zip | amxts_amxx.dll |
| Linux | amxts-server-linux-x64.tar.gz | amxts_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
- Copy the kit's
addons/over the game folder'saddons/. - Add the module to
addons/amxmodx/configs/modules.ini, on its first line, abovereapiand the others:amxts_amxx
AMX Mod X findsamxts_amxx.dlloramxts_amxx_i386.soby that name. A module listed above it does not hand its forwards to amxts (forwards). AMX Mod X'splugins.inineeds no line: amxts is the module alone (The module in AMX Mod X). - 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
pnpm amxts upgrade
yarn amxts upgrade
bunx 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_amxxtakes 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 pluginslists Pawn plugins alone -amxts_pluginslists the amxts ones (Server commands);amxx cmdsandamx_helpdo not list the plugins' commands, andamxx cvarsnames 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
pluginsLoadedon.
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
.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 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
| command | what it does |
|---|---|
amxts_plugins | lists 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_reload | reads 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_trace | logs 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.
CLI
amxts is the command a project runs: it creates projects and modules, adds modules, builds, deploys, type-checks and tests. It is the package @amxts/cli, which @amxts/core depends on, so every project has it and runs it through its package manager:
A server in Docker
ghcr.io/amxts/server is a Docker image of a Linux Counter-Strike 1.6 server that runs amxts: HLDS with ReHLDS, ReGameDLL, Metamod-R, AMX Mod X 1.10 and ReAPI, the amxts module and its compiler. Your project is mounted into it, and the server runs your plugins with your configs and files - on Windows, macOS or Linux, with nothing to install but Docker.