Начало работы

Установка на сервер

Чтобы игровой сервер запускал плагины amxts, на нём нужны две вещи: модуль amxts_amxx и папка addons/amxts с плагинами. Плагины собираются на вашей машине, в проекте (npx amxts build), а сервер загружает файлы .aot, которые делает сборка, — так же, как AMX Mod X загружает .amxx, скомпилированный из .sma. На этой странице — как поставить модуль на свой сервер. Другой путь — сервер в Docker, в котором всё это уже есть.

Что нужно серверу

  • Counter-Strike 1.6 на HLDS, Windows или Linux. Рекомендуем ReHLDS.
  • Metamod и AMX Mod X 1.9 или новее с модулями самого AMX Mod X engine, fakemeta, hamsandwich, cstrike и fun. amxts проверяется на AMX Mod X 1.10 с Metamod-R.
  • ReGameDLL — для всех его собственных событий игры в том виде, в каком их поднимает игра, и ReHLDS — для событий движка: amxts перехватывает их хукчейны сам. Без них плагин пишется так же: свойства сущностей (игроки и сущности) и действия с игроком (give, respawn, …) — собственные функции игры, которые amxts вызывает сам, и большинство событий игры слышно через другие хуки игры, некоторые — не целиком (сервер без ReGameDLL). Проект для такого сервера пишет target: "hlds" в amxts.config.ts (include сервера), и обработчик события, которое там никто не слышит, не собирается.
  • ReAPI не нужен: amxts сам перехватывает игру, читает правила игры и выполняет действия с игроком — на ReGameDLL через собственный API ReGameDLL. Его нативы (get_member, rg_*) есть для плагина, который вызывает их напрямую; плагин спрашивает об этом через hasModule("reapi").
Оригинальный HLDS
На HLDS от Valve — Metamod и AMX Mod X, без ReHLDS, ReGameDLL и ReAPI; проверено с metamod-p — события, которые есть только у ReGameDLL и ReHLDS, слышны через собственные функции игры, которые amxts перехватывает сам, и через собственные модули AMX Mod X, так, как их слышит там плагин на Pawn. Чего нет:
  • событий, которые там никто не слышит, — движения игрока (jumpMovement, airMove, …), собственных событий движка (printf, addResource, …) и взрывов гранат: обработчик такого события не вызывается никогда, и консоль сервера говорит об этом один раз, когда его добавляют;
  • того, чего не могут дать некоторые из слышных, — большинство приходит, когда игра уже сделала своё, и preventDefault() и запись поля там ничего не делают, а у некоторых нет какого-то поля: это перечислено в событиях игры, и просьба об этом — одна строка в консоли;
  • на Windows с mp.dll, которую amxts не знает, — функций правил игры так, как их даёт ReGameDLL: amxts перехватывает их в сборках игры Valve, которые знает, — той, что ставит steam, и её ветке steam_legacy;
  • полей правил игры teamBalanced и skipShowMenu: они читаются как 0 и не записываются, о чём сказано один раз; neededPlayers и escapeRatio читаются из счётчиков игры и не записываются; timeLimit и gameStartTime считаются из mp_timelimit;
  • собственных нативов ReAPI (get_entvar, get_member, rg_*): вызов ничего не делает и отвечает 0, о чём сказано один раз для каждого натива.

Серверный набор

Набор — один архив на систему, в нём всё, что ставится на сервер:

системаархивмодуль
Windowsamxts-server-windows-x64.zipamxts_amxx.dll
Linuxamxts-server-linux-x64.tar.gzamxts_amxx_i386.so

Скачайте его из выпусков: той же версии, что @amxts/core в ваших проектах.

Что внутри — так, как оно ложится в папку игры (cstrike/):

addons/
├── amxmodx/
│   ├── modules/amxts_amxx.dll          на Linux — amxts_amxx_i386.so
│   └── scripting/include/amxts.inc     для плагинов на Pawn: поля, которые плагины добавляют Player
└── amxts/
    ├── plugins.ini                     список плагинов amxts: hello.aot
    ├── plugins/hello.aot               плагин-пример, собранный для системы набора
    └── licenses/                       лицензии того, из чего собраны модуль и пример
README.txt

Установка

  1. Скопируйте addons/ из набора поверх addons/ в папке игры.
  2. Добавьте модуль первой строкой addons/amxmodx/configs/modules.ini, выше reapi и остальных:
    amxts_amxx
    

    AMX Mod X находит amxts_amxx.dll или amxts_amxx_i386.so по этому имени. Модуль, который стоит выше, не передаёт amxts свои форварды (форварды). В plugins.ini AMX Mod X строка не нужна: amxts — это один модуль (Модуль в AMX Mod X).
  3. Запустите сервер или перезапустите, если он работает.

При первом запуске сервер загружает пример. В консоли:

[amxts] loaded hello.aot

amxts_plugins в консоли сервера показывает плагины и что с каждым из них:

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

Зайдите на сервер и напишите в чат /hp — пример ответит.

Обновление с v0.2

Сервер, на который выкладывает проект, обновляется из проекта:

npx amxts upgrade

Вместе с пакетами и кодом проекта (upgrade) команда кладёт модуль нового выпуска в addons/amxmodx/modules/, оставляя старый рядом с его версией (amxts_amxx.dll.0.1.0). Перезапустите сервер, чтобы загрузить новый модуль. Сервер без проекта берёт набор нового выпуска, как при установке.

Что пишет модуль

При каждом запуске модуль создаёт папку addons/amxts/plugins и пишет addons/amxts/plugins.ini — без плагинов, — если его нет. Дальше список он не трогает: он ваш. Поэтому сервер, где есть только модуль, запускает плагины, которые вы туда положите.

Модуль в AMX Mod X с v0.3

amxts — это один модуль AMX Mod X, amxts_amxx, и больше ничего в AMX Mod X: ни плагина в addons/amxmodx/plugins/, ни строки в каком-либо plugins.ini. Модуль сам слышит игру — через Metamod — и вызывает натив AMX Mod X, другого модуля или плагина на Pawn по его имени. AMX Mod X держит модуль загруженным от запуска сервера до остановки; на каждой карте модуль заново запускает плагины amxts.

Что это значит на сервере:

  • Новый amxts_amxx требует перезапуска сервера: смена карты оставляет загруженный модуль. Плагины перезагружаются и без него (Перезагрузка).
  • Собственные списки AMX Mod X не показывают amxts: amxx plugins показывает только плагины на Pawn — плагины amxts показывает amxts_plugins (Команды сервера); amxx cmds и amx_help не показывают команд плагинов, а amxx cvars не называет плагина у квара, который создал один из них.
  • На первой карте плагины загружаются раньше, чем AMX Mod X загружает плагины на Pawn, поэтому нативы, которые они экспортируют, есть у каждого плагина на Pawn; натива модуля, которого AMX Mod X загружает ради плагина на Pawn, на верхнем уровне файла плагина ещё нет — вызывайте его начиная с pluginsLoaded.
Плагины на Pawn слышат событие первыми
AMX Mod X загружает модуль в Metamod после всех плагинов из собственного plugins.ini Metamod. Там, где AMX Mod X и модуль слышат одно и то же в один момент, — команду, событие клиента, сообщение, — плагины на Pawn слышат его первыми, и модуль знает, если кто-то из них его обработал. На Metamod-R сервер может поставить модуль в другое место, назвав amxts_amxx в plugins.ini Metamod.

Плагины

addons/amxts/plugins.ini перечисляет плагины, которые запускает сервер, — по одному файлу из addons/amxts/plugins/ на строку, в порядке загрузки. Строка, которая начинается с ; или #, пропускается. Плагин общего модуля загружается раньше плагинов, которые им пользуются, где бы ни стояла его строка с v0.3.3.

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

.aot — плагин, собранный в проекте; загружается как есть. Он собран под систему сервера: собранный для Windows на Linux не загрузится (система сервера). Строка myplugin.ts загружает myplugin.aot, лежащий рядом.

::: warning Сервер не собирает .ts Сервер загружает только файлы .aot: положенный на сервер .ts не собирается. Строка, которая называет .ts без .aot с тем же именем рядом, ничего не загружает, а консоль говорит об этом, когда загружаются плагины:

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

:::

Плагин собран под одну линейку amxts
.aot помнит, какой версией amxts он собран и чем из её API пользуется, и модуль загружает плагины, собранные любым выпуском его линейки с v0.3: плагин, собранный 0.3.0, загружается модулем 0.3.2, а собранный 0.3.2 — модулем 0.3.0, если не пользуется тем, что добавил более поздний выпуск. Такой плагин не загружается, остальные загружаются, а консоль говорит, что делать: [amxts] myplugin.aot needs amxts 0.3.2 or later (it uses player_glow): npx amxts upgrade. Плагин, собранный ещё не выпущенным ядром — из его репозитория, — может пользоваться тем, чего нет ни в одном выпуске; тогда модуль сервера говорит [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 withс v0.3.3. Чтобы узнать это до выкладки, проверьте плагины по модулю сервера: build --against. Плагин другой линейки — 0.2.x под 0.3.1 — обращался бы к модулю так, как тот не принимает, и консоль говорит, какой собрать заново: [amxts] myplugin.aot was built for amxts 0.2, this is 0.3 - build it again (или was built for an older amxts). Обновив модуль до другой линейки, соберите проект заново и выложите его (npx amxts build --deploy). Плагин сохраняет код, с которым собран: чтобы получить исправление API из более нового выпуска, соберите его заново.

Из проекта

Проект выкладывается в папку addons/amxts сервера, которую называет AMXTS_SERVER в .env проекта:

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

Подойдёт и папка самого сервера (D:/hlds), его cstrike или cstrike/addons: сборка берёт cstrike/addons/amxts внутри неё и называет выбранную папку в строке Server своего заголовка. Папка, которая не подходит ни под один вариант, останавливает сборку одной строкой о том, где она искала.

npx amxts build --deploy копирует собранные .aot в addons/amxts/plugins/ и пишет addons/amxts/plugins.ini: сначала модули, потом плагины проекта, а после них — все строки, которых сборка не знает. Include плагина, который экспортирует нативы, тоже копируется — в addons/amxmodx/scripting/include/, для плагинов на Pawn, которые компилируются на сервере. npx amxts dev делает это при каждом сохранении и перезагружает сервер через rcon (горячая перезагрузка).

Перезагрузка

Модуль проверяет плагины десять раз в секунду. .aot, записанный заново после загрузки, перезапускает с диска этот плагин, а после него — плагины, которые пользуются его общим модулем, — без смены карты и без команды; остальные плагины работают дальше. Новый файл и файлы плагинов, которые пользуются его модулем, читаются и готовятся, пока игра идёт, так что сервер ждёт только их запуска. amxts_reload вручную перезапускает все плагины amxts и заново читает plugins.ini. Каждый плагин слышит "end" перед остановкой и старт карты после (порядок).

Так же проверяется и plugins.ini с v0.3.3: добавленная строка загружает свой плагин — он готовится, пока игра идёт, как при загрузке файла, — а убранная выгружает его; строка, которая только переехала, ничего не меняет. Консоль говорит, что сделано:

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

Плагин, модулем которого пользуются другие, остаётся, пока они работают, и говорит об этом.

.aot или plugins.ini, который ещё записывается, — загрузка по FTP или SFTP идёт по частям, — загружается, когда две проверки подряд видят у него одно время и один размер. Прочитанный всё же до конца отвергается, [amxts] myplugin.aot is incomplete or unreadable - it is loaded again once it changes, а остаток загрузки загружает его.

Один плагин с v0.2

amxts_unload shop       // останавливает shop.aot
amxts_load shop         // запускает его снова
amxts_reload shop       // перезапускает с диска
amxts_load arena.aot    // файл из plugins/, которого нет в списке, — до смены карты

Плагин называют его строкой в plugins.ini, с .aot или без. amxts_unload останавливает его и забирает всё, что он зарегистрировал, — таймеры, команды, события игры, обработчики меню и слушателей сообщений, — и плагин остаётся остановленным до amxts_load или следующей карты; перезапуск всех плагинов тоже его не запускает. amxts_reload <плагин> перезапускает только этот плагин, остальные работают дальше.

Плагин, чьим общим модулем пользуются другие плагины, держит то, что они через него сделали, — меню, функцию, которую ему передали. Поэтому amxts_unload отказывает, пока работает хоть один из них, и называет их: сначала выгрузите их. amxts_reload такого плагина перезапускает их после него.

amxts_plugins показывает каждый плагин как running (работает) с его памятью в MiB, unloaded (выгружен), refused (отвергнут) с причиной — это .ts без .aot, собран для другой версии amxts или другой системы, его верхний уровень упал — или stopped (остановлен) с v0.3.3 с причиной: ему не хватило памяти или он пользуется модулем плагина, которому не хватило. amxts_reload такого плагина запускает его снова.

Плагин начинает заново
Загруженный снова плагин начинает со своего верхнего уровня: то, что он держал в переменных, пропадает. То, что должно его пережить, кладите в общие поля игрока или в Storage.

Команды сервера

командачто делает
amxts_pluginsсписок плагинов: файл, состояние (running и его память, unloaded, refused или stopped и почему), имя, версия, автор; и сколько слотов обработчиков занято
amxts_reloadзаново читает plugins.ini и перезапускает все плагины amxts с диска
amxts_reload <плагин>перезапускает один плагин с диска и плагины, которые пользуются его модулем
amxts_unload <плагин>останавливает плагин и то, что он зарегистрировал, до amxts_load или следующей карты
amxts_load <плагин>запускает остановленный плагин или плагин из plugins/, которого нет в списке
amxts_traceпишет в лог каждый вызов плагина — чтобы найти, что роняет сервер; повторный вызов выключает

Другой список плагинов

+localinfo amxts_plugins <файл> в командной строке сервера даёт модулю другой список — путь от папки игры. Его плагины — файлы в plugins/ рядом с этим списком:

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

Со своим списком модуль не раскладывает addons/amxts: он запускает этот список, а остальную установку оставляет как есть. Так сервер в Docker запускает dist/ проекта.