Основы

Плагин: команды, события, таймеры, чат, переводы

Плагин — это один файл .ts в папке плагинов проекта. Работу он делает на верхнем уровне файла: называет себя, добавляет команды и подписывается на события. То, чем он пользуется из ядра, — plugin, server, Player — строки импорта не требует (автоимпорты).

plugin
({
name
: "Welcome",
version
: "1.0.0",
author
: "you" });
server
.
addCommand
("/hp", ({
player
}) => showHp(
player
));
server
.
addEventListener
("putInServer", (
event
) => {
event
.
player
.
print
("Добро пожаловать на сервер!");
}); function showHp(
player
: Player) {
player
.
print
(`${
player
.
name
}, у тебя ${
player
.
health
} HP`);
}

Всё, что есть на этой странице, — API ядра, @amxts/core, и оно импортируется само.

Плагины в папках с v0.3.6

Каждый файл .ts на верхнем уровне папки плагинов — плагин; файл в подпапке — код, который плагины импортируют. Чтобы держать плагины и в папках, перечислите папки в amxts.config.ts:

export default 
defineConfig
({
plugins
: ["modules", {
path
: "games",
prefix
: "minigame_" }],
});
plugins/
├── core.ts        # плагин → core.aot
├── core/          # код core.ts, не плагины
├── games/
│   └── hns.ts     # плагин → minigame_hns.aot
└── modules/
    ├── duel.ts    # плагин → duel.aot
    └── duel/      # код duel.ts, не плагины

Имя плагина на сервере — имя его файла, а перед ним prefix его папки. Если два файла из двух папок получают одно имя, сборка останавливается.

Автоимпорты

Плагин пользуется API ядра и тем, что дают модули проекта, не импортируя их. Сборка находит имена, которые файл использует, но не объявляет, и добавляет импорт каждого, которое знает:

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
(`Ваша команда: ${
names
.
join
(", ")}`);
}

server и Player — ядра; semiclip даёт @amxts/semiclip в проекте, где amxts.config.ts его перечисляет. Импорты встают после последней строки файла, поэтому ошибка по-прежнему указывает на строку, которую вы написали.

  • Что импортируется само: всё, что @amxts/core экспортирует для плагинов, — Player, Entity, server, game, lang, effects, Cvar, Forward, Storage, таймеры, типы событий (TakeDamageEvent), имена полей и флагов (Team, HideHud) — и имя каждого модуля (menus, configs, semiclip). Не нативы и константы (@amxts/core/natives, @amxts/core/constants), не файлы (@amxts/core/fs), не ваши собственные файлы: плагин, которому они нужны, говорит об этом импортом.
  • Своё имя важнее. Переменная, параметр или функция с именем server — ваши там, где они видны; автоимпорт — только для мест, где их не видно.
  • Явный импорт тоже работает: import { Player } from "@amxts/core", import * as menus from "@amxts/menu-core". Его пишет плагин, которому модуль нужен под другим именем, и для того, что само не импортируется.
  • Что называет импорт. API ядра — по имени пакета: @amxts/core, @amxts/core/natives, @amxts/core/constants, @amxts/core/fs, @amxts/core/os; модуль — по имени его пакета; ваши собственные файлы — через ~/, это папка плагинов: import { twice } from "~/lib/math" — это plugins/lib/math.ts, из любой подпапки. ~/ называет только ваши файлы: импорт API ядра через него не собирается.
  • Редактор знает те же имена: npx amxts prepare — его первым шагом запускают dev, build, typecheck и npm install — пишет .amxts/imports.d.ts, где они глобальные, поэтому автодополнение, переход к определению и проверка типов работают без импорта. Файл пишется заново, когда после изменения модулей в amxts.config.ts запускается команда.
  • Как выключить: imports: { autoImport: false } в amxts.config.ts; тогда каждый плагин импортирует то, чем пользуется, сам.
// amxts.config.ts
export default 
defineConfig
({
modules
: ["@amxts/menu-core"],
imports
: {
autoImport
: false },
});

Модуль говорит, что даёт, в своём defineModule, — себя пространством имён, imports: [{ from: "@amxts/menu-core", as: "menus" }], или один из своих экспортов под его именем, [{ from: "@amxts/semiclip", name: "semiclip" }] (свой модуль). Два источника одного имени останавливают сборку, и она называет оба.

Собирается только то, чем пользуются

Плагин получает импорт только того, чем пользуется, поэтому модуль, которым не пользуется ни один плагин, не попадает ни в один из них. Сборка идёт дальше: собственный плагин модуля она собирает и пишет в plugins.ini, только когда модулем пользуется хоть один плагин проекта — через автоимпорт или явный импорт, сам или через файл, который он импортирует. Модуль из amxts.config.ts, которым не пользуется никто, в сборку не попадает, и сборка об этом говорит:

i module "menu-core" is installed but no plugin uses it - left out

Модулем, чьи нативы вызывают Pawn-плагины, — mc_* у menu-core, cfg_* у config-core — пользуются плагины, которых сборка не видит. Его оставляет pawn:

// amxts.config.ts
export default 
defineConfig
({
modules
: ["@amxts/config-core", "@amxts/menu-core"],
pawn
: ["@amxts/menu-core"], // Pawn-плагины вызывают mc_*: собирается, даже если им не пользуется ни один плагин
});

Модуль, который работает сам, — semiclip, чьё правило действует на всех игроков без вызовов из плагинов, — говорит об этом в своём описании (standalone) и собирается всякий раз, когда его перечисляет amxts.config.ts с v0.3.4.

То, что модуль требует, идёт вместе с ним. В amxts dev сохранение, после которого плагин начал пользоваться модулем, собирает модуль вместе с плагином; модуль, которым больше не пользуется ни один плагин, уходит из plugins.ini.

Описание плагина

plugin
({
name
: "Welcome",
version
: "1.0.0",
author
: "you",
description
: "Приветствует игроков" });

Имя, версия и автор, под которыми сервер показывает плагин: их выводит amxts_plugins в консоли сервера. description можно не писать. plugin вызывается один раз, в начале файла.

Команды с v0.2

interface KickArgs {
    
target
: Player;
reason
?: string;
}
server
.
addCommand
<KickArgs>("/kick <target> [reason]", ({
player
,
target
,
reason
}) => {
server
.
print
(`${
player
.
name
} кикает ${
target
.
name
}`);
target
.
kick
(
reason
?? "Кикнут админом");
}, {
access
: "kick",
description
: "Кикнуть игрока" });
server
.
addCommand
("/hp", ({
player
}) =>
player
.
print
(`${
player
.
health
} HP`));
server
.
addCommand
("myplugin_heal <amount>", ({
player
,
amount
}) =>
player
.
print
(`лечение ${
amount
}`)); // без слэша - команда консоли
server
.
addCommand
("say rules", ({
player
}) => showRules(
player
)); // строка чата без слэша

Первый аргумент — использование команды: её имя, затем аргументы, <name> — тот, что игрок должен набрать, [name] — тот, что может пропустить. Обработчик получает их под этими именами, вместе с player — игроком, который набрал команду.

Типы аргументов — интерфейс, с именем, переданный первым, как addCommand<KickArgs> (тип, написанный на месте, <{ ... }>, читается хуже и не годится второй раз). Поле говорит, как читается его слово:

типсловонапример
stringкак есть; последний аргумент забирает остаток строкиreason в /kick bob being rude — "being rude"
numberчисло/give 5
Player#userid, имя целиком или его часть, в любом регистре/kick bo, /kick #12
"on" | "off"одно из этих слов/mode on

[name] в использовании — это name?: в интерфейсе, а <name> — поле без ?. Имя, которое есть в использовании, но нет в интерфейсе, — или наоборот, — не собирается, и ошибка говорит какое. Без интерфейса каждый аргумент — string: ({ amount }) выше — текст.

Если слово не то, что команда принимает, — число, которое не число, игрок, чьё имя ни с чем не совпало, — игрок получает в чат использование команды, и обработчик не запускается. На часть имени, которая есть у нескольких игроков, он получает их имена, чтобы набрать побольше. Лишнее слово получает тот же ответ, если только последний аргумент не текст: текст забирает остаток строки.

Слова разделяются пробелами, а слово в двойных кавычках — одно слово: /kick "Bob Smith" spam. SteamID или слово с :, ,, ' или скобками приходит целым с v0.3.3 — amx_ban STEAM_0:1:123 5 даёт STEAM_0:1:123, — и в консоли, и в чате, как и event.args события "command".

  • Имя со / — команда чата. Её запускают и say /hp, и say_team /hp, а сама строка в чате не появляется; с chat: "say" в параметрах — только say, с chat: "team" — только say_team с v0.3.
  • Имя без / — команда консоли: игрок набирает myplugin_heal 50 у себя в консоли.
  • "say <фраза>" срабатывает, когда игрок пишет в чат ровно эту фразу: "say rules" — на rules, но не на rules please. Аргументов у неё нет.

Регистр в имени команды не важен: /HP запускает /hp.

Несколько имён, обработчик игрока с v0.3

function checkpoint(
player
: Player) {
player
.
print
("Чекпоинт сохранён");
}
server
.
addCommand
(["/cp", "cp"], checkpoint); // в чате и в консоли
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
));

Массив имён — одна команда: сначала использование с аргументами, затем другие имена, без них. У команды один обработчик, один access и один description; server.commands перечисляет её один раз, другие имена — в aliases.

Команда без аргументов принимает обработчик игрока: функция, параметр которой — имя, (player) => ..., или объявленная с player: Player, получает игрока, который ввёл команду. Та, что разбирает аргумент, ({ player }) => ..., получает объект команды, как у команды с аргументами.

access — право админа, которое нужно игроку, как его даёт users.ini: "kick", "ban", "slay", "map", "cvar", "rcon", "levelA" … "levelH" и остальные — редактор их подсказывает. У кого права нет, для того команда ничего не делает, а его строка уходит в чат обычным сообщением. description — для server.commands, о нём ниже; amx_help из AMX Mod X показывает только команды Pawn-плагинов.

Права самого игрока — player.access, массив тех же имён: player.access.includes("ban").

Pawn-плагины слышат команду первыми
Команда игрока доходит до Pawn-плагинов сервера раньше, чем до плагинов amxts. Pawn-плагин, который её забрал, — PLUGIN_HANDLED из client_command или из своего register_clcmd с тем же именем, — забирает её и у этих обработчиков. Команда, которую Pawn-плагин шлёт за игрока через amxclient_cmd, доходит до них так же, как набранная (на HLDS от Valve под Windows — только до Pawn-плагинов и игры); отправленная через engclient_cmd идёт только игре, мимо всех плагинов. Из TypeScript бот шлёт команду так же, как игрок: bot.command("say /hp") (фейковые клиенты).

Команда помощи

server.commands перечисляет команды, которые добавил плагин, — у каждой usage, description и access, — это и печатает /help:

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
}`);
} });

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

interface ResetArgs {
    
what
?: "scores" | "all";
}
server
.
addServerCommand
<ResetArgs>("myplugin_reset [what]", ({
what
}) => {
console
.
log
(`сброс: ${
what
?? "all"}`);
});

Команда консоли сервера: её набирают там, присылают по rcon или запускает другой плагин через server_cmd. Её использование и аргументы читаются так же, как у команды игрока; игрок её не набирает, поэтому player у обработчика нет. То, что он печатает через console.log, уходит тому, кто прислал команду, — по rcon это ответ rcon.

События сервера

server
.
addEventListener
("putInServer", (
event
) => {
event
.
player
.
print
("Добро пожаловать!");
});
server
.
addEventListener
("disconnected", (
event
) => {
console
.
log
(`${
event
.
player
.
name
} вышел: ${
event
.reason}`);
});
server
.
addEventListener
("configsExecuted", loadSettings); // сервер выполнил свои конфиги

server.addEventListener работает как addEventListener в браузере: первый аргумент — имя события, второй — функция, которую сервер вызывает каждый раз, когда событие случается. От имени зависит тип event, поэтому (event) => ... пишется без аннотации, а редактор дополняет имена и подчёркивает опечатку. Поля типизированы: игрок — Player, текст — string, да/нет — boolean (event.dropped).

СобытиеКогда
"init"плагин запускается, когда загружены все плагины
"pluginsLoaded"все плагины запустились: время создать форвард, который услышат другие плагины
"configsExecuted"карта загрузилась, и сервер выполнил свои конфиги — server.cfg, amxx.cfg, конфиг карты: время читать квары
"precache"грузится карта: время прекешировать модели и звуки
"changeLevel"карта вот-вот сменится
"end"плагин останавливается: смена карты, выключение сервера, перезагрузка или выгрузка плагина
"connect"игрок подключается и ещё не в игре
"authorized"стал известен Steam ID игрока (event.steamId)
"putInServer"игрок вошёл в игру
"disconnected"игрок ушёл (event.dropped, event.reason)
"playerChange"изменилось поле, которое плагины добавили в Player (общие поля игрока)
"command"игрок отправил команду консоли: event.command — её имя, event.args — её слова (у say и say_team — слова строки чата), event.text — строка после имени с v0.3
"impulse"игрок отправил импульс: 100 — фонарик, 201 — спрей
"cmdStart"пришла команда движения игрока: каждый кадр его игры, каждый bot.move бота
"suicide"игрок набрал kill в консоли, после того как игра это обработала
"frame"каждый кадр сервера
"log"строка, которую игра пишет в свой лог: event.text целиком, event.args по частям с v0.3

event.preventDefault() с v0.3 в слушателе "command" останавливает команду: игра её не выполняет — строка чата не уходит в чат, — и её не слышит ни один server.addCommand плагинов. Остальные слушатели "command" её слышат.

server
.
addEventListener
("command", (
event
) => {
if (
event
.command == "chooseteam" && !
event
.
player
.
isAlive
)
event
.preventDefault();
});
AMX Mod X слышит команду игрока раньше amxts: обработчики client_command и register_clcmd Pawn-плагинов выполняются первыми, и тот, что вернул PLUGIN_HANDLED, останавливает команду до того, как её услышит "command".

Слушатель "cmdStart" читает и меняет команду движения игрока до того, как игра подвинет его по ней: event.forward, event.side и event.up — скорости в юнитах в секунду, как их принимает bot.move, — event.angles, куда он смотрит, event.buttons, зажатые кнопки, event.msec, длина команды в миллисекундах, и event.impulse с v0.3.3. Записанное поле меняет движение. Пока выполняется его команда, game.time — его собственные часы, а не часы кадра (Часы).

server
.
addEventListener
("cmdStart", (
event
) => {
// Скорость вбок, которую не дали клавиши стрейфа, отменяется. if (
event
.side != 0 && !
event
.buttons.includes("moveLeft") && !
event
.buttons.includes("moveRight"))
event
.side = 0;
});
Команда каждый кадр
Игра выполняет команду на каждый кадр каждого игрока — сотни в секунду на полном сервере, — так что слушатель должен быть крошечным. Поле читается из команды, когда слушатель его читает: тот, что не читает ни одного, ничего лишнего не стоит. Поле, записанное после await, меняет событие, а не команду: игра уже подвинула игрока.

Перезагрузка — amxts_reload или заново записанный .aot плагина — останавливает плагин и запускает его на идущей карте. Старый слышит "end"; новый — "init", "pluginsLoaded", "configsQueued" и, когда конфиги карты уже выполнены, "configsExecuted", в том порядке, что и при старте карты. "precache" не приходит снова: для precache нужна смена карты. Поэтому то, что плагин сохраняет в "end" и настраивает в "pluginsLoaded", переживает перезагрузку. amxts_unload поднимает "end", а amxts_load — старт.

Перезагрузка запускает плагин с новой памятью: то, что он делал в этот момент, — записываемый забег, голосование — пропадает. server.keep(key, value) с v0.3.3 отдаёт серверу значение для следующего запуска плагина, который читает его через server.kept<T>(key):

let 
run
=
server
.
kept
<Uint8Array>("run") ?? new
Uint8Array
(0); // забег прошлого запуска, если он его сохранил
server
.
addEventListener
("end", () =>
server
.
keep
("run",
run
));

Текст сохраняется как есть, Uint8Array — как байты, остальное — как JSON, так же как его сохраняет Storage. kept даёт undefined, если под ключом ничего не сохранено.

Сохраняется на один запуск, в памяти
Сохранённое ждёт в памяти сервера следующего запуска плагина: перезагрузки, нового .aot, amxts dev или amxts_load после amxts_unload на той же карте. Новый плагин читает его от верхнего уровня до событий своего запуска ("init", "pluginsLoaded", ...); потом оно удаляется, прочитано или нет. Смена карты его удаляет, а перезапуск сервера теряет: то, что должно жить дольше, — в Storage или в файл. Плагину, который что-то сохраняет, нужен модуль amxts версии 0.3.3 или новее.
Почему игрок ушёл
event.dropped и event.reason в "disconnected" берутся из того места, где движок сам отключает игрока. Сервер, где amxts до него не достаёт, — без ReHLDS и без его сигнатуры в gamedata AMX Mod X, — отдаёт любой уход как выход самого игрока: dropped — false, reason пустой, и один раз пишет об этом в консоль.

В "connect", "authorized" и "putInServer" игрок ещё не появился на карте, поэтому event.player — это Client: у него есть id, name, ip, steamId, access, team, muted, print и command, но нет здоровья и оружия. У Player есть всё, что есть у Client, поэтому функция, которой нужно только это, принимает Client и работает с обоими.

Весь список показывает редактор; его подсказка называет форвард AMX Mod X, который под событием (client_putinserver). То, что происходит с игроком в игре, — он «думает» каждый кадр, меняет свои данные, касается чего-то, — это игровые события: game.addEventListener("preThink", ...), "userInfoChange", "touch".

Обработчик, написанный отдельной функцией, указывает тип события — это имя форварда словами: ClientPutinserverEvent, ClientDisconnectedEvent, ClientImpulseEvent.

server
.
addEventListener
("impulse", onImpulse);
function onImpulse(
event
: ClientImpulseEvent) {
if (
event
.
impulse
== 100)
event
.
player
.
print
("Фонарик!");
}

server.removeEventListener("impulse", onImpulse) отписывает обработчик: передайте ту же функцию, что добавляли.

Имя пишется строкой прямо в вызове: server.addEventListener(name, ...) с именем в переменной — ошибка сборки, потому что по имени выбирается тип события.

Обработчик — замыкание, как в JavaScript: он видит переменные функции, в которой написан, и они живут, пока живёт он.

server
.
addEventListener
("putInServer", (
event
) => {
const
player
=
event
.
player
;
setTimeout
(() =>
player
.
print
(`Рады видеть, ${
player
.
name
}!`), 2000);
});
Сохраняйте значения, а не событие
Поле читается из вызова сервера в тот момент, когда его читают, а следующий вызов того же события отдаёт тот же объект. async-обработчик сохраняет своё событие каким оно было: после await он читает тот вызов, который получил. Ссылка, сохранённая в переменной или в функции таймера, — нет: сохраняйте значения, как const player = event.player выше.

Сообщения клиентам с v0.2

server
.
addMessageListener
("death", (
event
) => {
if (
event
.
headshot
)
server
.
print
(`${
event
.
killer
?.
name
} - headshot - ${
event
.
victim
?.
name
}`);
});

Любое сообщение, которое сервер шлёт клиенту, — строка чата, значок HUD, часы раунда, сообщение об убийстве, — слышно через server.addMessageListener до того, как оно ушло, с аргументами в типизированных полях. Подробности и имена всех сообщений — на странице Сообщения.

События игры

game
.
addEventListener
("newRound", () =>
console
.
log
("новый раунд"));
game
.
addEventListener
("takeDamage", (
event
) => {
if (
event
.
attacker
.
team
==
event
.
player
.
team
)
event
.
preventDefault
();
});

То, что происходит в игре, — урон, возрождения, смерти, конец раунда, покупки — это события на game, так же как события сервера — на server. Обработчик может остановить действие игры или ответить вместо неё. Это собственные функции игры, которые amxts перехватывает сам, и большинство слышно и на обычном HLDS; подробно — в Событиях игры.

Таймеры

const 
handle
=
setTimeout
(() => player.print("Вперёд!"), 2000); // один раз, через 2 с
clearTimeout
(
handle
); // отменить до срабатывания
function countdown(
player
: Player) {
let
left
= 3;
const
ticking
=
setInterval
(() => {
player
.
print
(`${
left
}`);
left
--;
if (
left
== 0)
clearInterval
(
ticking
);
}, 1000); }

Как в браузере: setTimeout вызывает функцию один раз через заданное число миллисекунд, setInterval — раз в столько-то миллисекунд, и оба возвращают дескриптор, который принимают clearTimeout и clearInterval. Функция может читать и менять переменные вокруг себя. Функция без параметров передаётся как есть: setTimeout(startVote, 3000).

Внутри async-функции так же ждёт await sleep(1000) (async).

На кадре сервера
Таймер срабатывает на кадре сервера — первом, который наступил в его время или позже: он опаздывает не больше чем на кадр, а setTimeout(f) выполнится на следующем кадре.

Время и случайность

Date
.
now
(); // миллисекунды с 1970 года
new
Date
().
getHours
(); // час по часам сервера
new
Date
().
getUTCHours
(); // час по UTC
const
start
= performance.now(); // миллисекунды с точностью до микросекунды, для замеров
Math
.
random
(); // 0 <= x < 1, при каждом запуске новая последовательность
game
.
time
; // часы игры: секунды с начала карты

Date работает как в JavaScript: new Date() — сейчас, геттеры UTC (getUTCHours, ...) и местные (getHours, getDate, getMonth, getFullYear, getTimezoneOffset, ...) — местные по часовому поясу сервера. Дата становится текстом так, как её пишет JavaScript, по часовому поясу сервера:

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 и toLocaleTimeString принимают язык: en-US, если он не назван, en-GB, de, fr, ru и языки, которые пишутся как ru (uk, be, kk); другой пишется как en-US.

game.time — часы, по которым идут поля сущностей, хранящие момент: grenade.damageTime = game.time + 1. Таймеры атаки — nextPrimaryAttack оружия, nextAttack игрока — считаются от текущего момента: weapon.nextPrimaryAttack = 1 — это через секунду.

Часы

  • game.time — часы игры: секунды с начала карты; каждый кадр они прибавляют длину кадра и стоят, пока сервер на паузе. По ним считают поля сущностей, а также setTimeout, setInterval и sleep. Это 32-битное число: через несколько часов на одной карте оно шагает по миллисекунде.
  • performance.now() — миллисекунды с запуска сервера по часам компьютера, с точностью до микросекунды: чтобы измерить, сколько работает код.
  • Date.now() и new Date() — часы компьютера, для момента, который читает человек; они прыгают, когда часы компьютера переводят.

На отрезке из многих кадров все трое идут в одном темпе. В слушателе "frame" и в таймере game.time — момент кадра.

Движение игрока идёт по его собственным часам
Игра двигает каждого игрока по часам его команд. Пока выполняется одна из них — хуки его движения: preThink, postThink, касание, прыжок, — game.time — момент этой команды: клиент шлёт команды пачками, каждая длиной msec, и игра раскладывает пачку так, чтобы она кончалась через кадр после момента кадра, поэтому первая команда пачки отстаёт от кадра, а последняя на кадр впереди. В "cmdStart" это ещё часы, оставленные предыдущим движением, или часы кадра. До следующего кадра игра их не возвращает: всё, что выполняется после движения, — его строка в чат или консольная команда, команда следующего игрока, слушатель "frame" после bot.move, таймеры этого кадра — видит часы, оставленные движением, до кадра вперёд. Чтобы отмерять время по кадрам сервера, запоминайте game.time в начале слушателя "frame".

Чат и консоль

player
.
print
("Это видишь только ты");
server
.
print
("Это видят все");
player
.
print
("Здоровье восстановлено!", "center"); // "chat" (по умолчанию), "center", "console", "notify"
server
.
print
("Вперёд!", "center"); // всем, посреди экрана
console
.
log
("в консоль сервера");

player.print пишет одному игроку, server.print — всем; у Client — игрока, который ещё подключается, — print тоже есть. Второй аргумент — где показать текст: "chat", "center" (посреди экрана), "console" (консоль игрока) или "notify" (тоже консоль; на экране игра показывает его только с developer 1).

console.log пишет строку в консоль сервера, после [amxts]; console.warn и console.error помечают свои строки как предупреждение и ошибку. Каждый принимает строку или Error — его он пишет со стеком (ошибки).

Цвета

Цвет в тексте — метка: ! и буква.

player
.
print
("!g[Магазин]!y Ты купил !rброню");
МеткаЦветЧатМеню
!yжёлтый, обычный цвет чатадада
!rкрасныйдада
!dсерыйдада
!gзелёныйданет
!bсинийданет
!tцвет команды читающегоданет
!wбелыйнетда
!Rостаток строки — к правому краюнетда

Буква означает один и тот же цвет в чате и в меню. Строка чата до первой метки жёлтая: "KZ !gGG" — это "!yKZ !gGG".

Где рисуются метки
Каждое место рисует свои метки, а чужие убирает из текста, и никто об этом не предупреждает: !w и !R — для меню, !g, !b и !t — для чата. У "center", "console" и "notify" цветов нет: там текст показывается как написан, вместе с метками. Регистр в метках важен: !R — не красный.
Один цвет команды на сообщение
Красный, синий, серый и !t рисуются цветом команды, а он у сообщения в чате один: побеждает первый из них в строке, остальные показываются им же. "!rКрасный !bСиний" выводит оба слова красным.

Ошибки с v0.2

Вызов, который падает, — throw, который никто не поймал, x! на null, индекс за границей, переполнение стека, — заканчивает этот вызов, а не плагин: следующее событие, команда или таймер выполняются как обычно. Консоль сервера называет ошибку и место, где она случилась, а лог AMX Mod X (addons/amxmodx/logs) хранит строку ошибки с v0.3.3: панель хостинга часто не хранит консоль.

Слушатель — отдельный вызов, откуда бы он ни начался. Когда ваш код выполняет команду через server_exec, вызывает форвард или кикает игрока, ваши слушатели, до которых это доходит, выполняются сразу, и ошибка в одном из них заканчивает только этот слушатель: консоль называет её, а ваш код продолжается после вызова. try вокруг вызова её не ловит — как в JavaScript её не ловит try вокруг dispatchEvent.

function price(
item
: Item | null): number {
return
item
!.price;
} function onSelect(): number { return price(null); }

Плагин, который компилирует amxts dev, ведёт запись своих вызовов: консоль называет каждый вызов, который привёл к ошибке, — с файлом, строкой и столбцом в твоём TypeScript — и под первым вызовом твоего собственного кода показывает саму строку:

[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)

Плагин, который компилирует amxts build, такой записи не ведёт: она замедляла бы нагруженный плагин (производительность). Консоль называет ошибку, а для throw, x! или неудавшейся проверки — место выражения, которое упало; переполнение стека говорит только своё сообщение:

[amxts] myplugin.aot: TypeError: Unexpected 'null' (not assigned or failed cast) (plugins/myplugin/shop.ts:26:9)

У пойманной ошибки тот же стек: error.stack — этот текст, от места, где ошибку создали, а console.error(error) его пишет. В плагине, который компилирует amxts build, error.stack — первая строка ошибки.

try {
    buy(
player
, item);
} catch (
error
) {
console
.
error
(
error
); // "Error: ..." и, в сборке для разработки, вызовы под ней
}

Строка под первым вызовом показывается, когда сервер может прочитать твой .ts, как с amxts dev. Вызовы внутри собственной библиотеки AssemblyScript — методы массива, String — показывают имя без места.

Нехватка памяти с v0.3.3

Память плагина растёт, когда он держит больше, и не уменьшается, пока он работает: amxts_plugins показывает память каждого работающего плагина в MiB. Когда ей некуда расти — у сервера не осталось для неё места, — вызов, которому она понадобилась, падает, и плагин не может работать дальше: всё, что он запустил бы после, падало бы внутри его менеджера памяти, вызов за вызовом. Поэтому модуль останавливает его на следующем кадре, как amxts_unload, а вместе с ним — плагины, которые пользуются его общим модулем. Одна строка в консоли и в логе AMX Mod X говорит почему:

[amxts] myplugin.aot stopped: out of memory, its memory 1280.0 MiB - amxts_reload myplugin.aot starts it again

amxts_plugins показывает его как stopped с причиной. amxts_reload myplugin, новый .aot или следующая карта запускают его снова, и плагины, остановленные вместе с ним. Любая другая ошибка завершает только свой вызов.

32-битный сервер
Игровой сервер — 32-битный процесс: игра, её модули и все плагины делят несколько ГиБ адресов. Память плагина растёт удвоением, так что плагину, который держит около 1 ГиБ, может не найтись места на следующий шаг. Плагин, который хранит всё, что когда-либо случилось, в конце концов упирается в потолок: то, что должно жить долго, держите в Storage или в базе данных, остальное отпускайте.

Меню с v0.2

Меню для сервера: menu-core
Настоящие меню — магазин, меню админа, голосование — это то, для чего есть официальный модуль menu-core: меню в файлах INI, YAML или JSON, которые владелец сервера правит без сборки, пункты, которые показываются и доступны по условиям, %плейсхолдеры%, списки игроков и своих строк, меню, в которые добавляют пункты Pawn-плагины, и редактор, который проверяет файл меню прямо при наборе. Добавьте его командой npx amxts module add menu-core и прочитайте Меню.

Быстрое меню в коде

Menu — меню как объект: заголовок, пункты и show(player). Оно выглядит и листается так же, как собственные меню AMX Mod X, входит в ядро и не требует модуля — для одного-двух меню, которые плагин собирает в коде.

interface ShopData {
    
category
: string;
} const
shop
= new
Menu
<ShopData>(({
data
}) => `!yМагазин: ${
data
.
category
}`);
shop
.
addItem
({
title
: "Броня - !y$1000",
enabled
: ({
player
}) =>
player
.
armor
< 100,
onSelect
: ({
player
}) => {
player
.
armor
= 100;
}, });
shop
.
addItem
({
title
: ({
player
}) => `Лечение !d(${
player
.
health
} HP)`,
visible
: ({
player
}) =>
player
.
isAlive
,
enabled
: ({
player
}) =>
player
.
health
< 100,
onSelect
: ({
player
,
menu
,
data
}) => {
player
.
health
= 100;
menu
.
show
(
player
,
data
); // остаётся открытым
}, });
server
.
addCommand
("/shop", ({
player
}) =>
shop
.
show
(
player
, {
category
: "all" }));
  • Пункт — объект: его title, visible — показан ли он, enabled — можно ли его выбрать, и onSelect — что делает выбор. Без visible и enabled они true; скрытый пункт не занимает места, недоступный рисуется серым и ничего не делает.
  • Каждая функция получает контекст: player — тот, кому показано меню; menu — само меню; data — то, что получил show. Data, аргумент типа, говорит, что это, — меню, показанное без данных, его не передаёт.
  • Заголовок, visible и enabled могут быть функцией или просто значением: они вычисляются при каждом show, для этого игрока.
  • После выбора меню закрывается. onSelect, который показывает его снова, оставляет его открытым.
  • Страницы, «Назад», «Дальше» и «Выход» рисуются так же, как у AMX Mod X: семь пунктов на странице, остальные на следующих.
  • Меню, показанное поверх, забирает его клавиши: другой Menu, меню Pawn-плагина, собственное меню игры (меню радио). Menu, показанный поверх меню Pawn-плагина, закрывает его, как меню AMX Mod X закрывают друг друга, — его обработчик получает MENU_EXIT. amxts_reload или amxts_unload плагина закрывает его меню: нажатая в нём клавиша ничего не делает.
  • Цветовые теги — те же, что в чате и меню: !y жёлтый, !r красный, !d серый, !w белый, !R — к правому краю.
  • Строка без номера с v0.3: addText(text) ставит строку текста под последним добавленным пунктом — до первого под заголовком, — а addBlank() — пустую строку; они показываются и скрываются вместе с этим пунктом.

Создайте меню один раз, на верхнем уровне файла, и показывайте сколько угодно раз. Настройки — второй аргумент:

const 
vote
= new
Menu
("!yСледующая карта?", {
perPage
: 0, // все пункты на одной странице, без «Назад» и «Дальше» (до 10)
exit
: false, // без пункта «Выход»
numberColor
: "!y", // номера пунктов жёлтые, а не красные
backText
: "Назад",
nextText
: "Дальше",
exitText
: "Закрыть",
});

Меню AMX Mod X

Меню старого вида — текст и клавиши, на которые оно отвечает, — это showMenu из @amxts/core/kit с register_menucmd для клавиш: его обработчик передаётся именем public-функции, которое для функции делает publicFor из того же набора (нативы напрямую). Собственные меню AMX Mod X (menu_create) ищут вызвавший их плагин на Pawn и недоступны (ограничения).

Плагины сервера с 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
(); // выгружен (плагин на Pawn - на паузе) до start() или смены карты
shop
?.
start
();
shop
?.
reload
(); // заново из файла; плагин на Pawn перезагрузить нельзя
server
.
loadPlugin
("event.aot"); // файл из plugins/, которого нет в списке
const
ranks
=
server
.
plugins
.
find
(
plugin
=>
plugin
.
file
== "ranks.amxx");
ranks
?.
call
("show_rank",
player
); // публичная функция плагина на Pawn

server.plugins перечисляет все плагины сервера, на TypeScript и на Pawn: его файл, имя, версию и автора, которые он сам указал, его language и running — работает ли он. stop(), start(), reload() и server.loadPlugin(file) действуют на следующем кадре — как консольные amxts_unload, amxts_load и amxts_reload, — поэтому плагин может остановить сам себя или того, кто его вызвал.

Плагин на Pawn ставится на паузу, а не выгружается
AMX Mod X загружает плагины раз за карту: stop() ставит плагин на Pawn на паузу, а start() снимает её, сохраняя его состояние; reload() бросает ошибку. Плагин на TypeScript выгружается и загружается заново, и его состояние начинается сначала.

Переводы

Текст на языке читающего берётся из словаря: файла в data/lang, где у каждого языка своя секция, а у каждого ключа — своя строка.

[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) отдаёт строку ключа на языке игрока — его setinfo lang, — а null вместо игрока даёт язык сервера (amx_language). Языка, которого нет в словаре, заменяет язык сервера. %s, %d и %f (%.1f, %02d) заполняются из args, а это строки: число передаётся текстом, `${seconds}`. Место, на которое аргумента не хватило, остаётся как написано, а ключ, которого нет ни в одном словаре, возвращается как есть.

511 байт на строку
AMX Mod X читает строку словаря до 511 байт — это около 255 букв кириллицы; остаток более длинной строки обрезается.

player.language — этот самый язык, для того, чего нет в словаре, — звука, картинки: player.language == "ru". Это его setinfo lang или язык сервера, если своего у него нет или amx_client_languages равен 0.

lang.languages() с v0.3 перечисляет языки словарей, которые загрузил плагин, по их кодам, в порядке файлов: ["en", "ru"] — для меню, где игрок выбирает свой. lang.languages("myplugin") перечисляет языки одного словаря. Ни то ни другое не перечисляет языки собственных словарей AMX Mod X, которые есть у сервера для его сообщений.

Словарь пишет цвета так, как AMX Mod X, — \y в меню, ^4 в чате, — а lang.translate возвращает их метками: \y — это !y, \r — !r, \d — !d, \w — !w, \R — !R, ^1 — !y, ^3 — !t, ^4 — !g. Поэтому одна строка работает и в меню, и в чате; каждое место убирает метки, которых не рисует (!w в чате). ^n — перенос строки.

Словарь, записанный на работающий сервер, перечитывается, как только его загрузка закончена с v0.3.3, — вместе с перезагрузкой его плагина или после неё, что бы ни пришло первым.

Убранный ключ остаётся
Перечитанный словарь меняет и добавляет строки; ключ, убранный из файла, сохраняет старую строку до смены карты.

HUD-сообщения

player
.
showHud
("Раунд 3", {
color
: [255, 40, 40],
y
: 0.3,
hold
: 2 });
server
.
showHud
("Для всех");

Текст на экране вне чата. Настройки, крупные буквы и HudLine — на странице Игроки.

Звуки и прекэш

server
.
precache
("myplugin/hit.wav");
server
.
precache
("models/myplugin/box.mdl");
function hit(
player
: Player) {
player
.
emitSound
("myplugin/hit.wav"); // слышат все рядом
player
.
emitSound
("myplugin/hit.wav", {
volume
: 0.5,
pitch
: 120,
channel
: "voice" });
player
.
playSound
("vox/one.wav"); // слышит только он, как рацию
}

Модель, спрайт или звук, которым пользуется игра, прекэшируется, пока грузится карта: server.precache(path) на верхнем уровне файла прекэширует его тогда, а в событии "precache" — сразу. К тому же он заставляет игроков скачать файл. Звук пишется так, как его играет игра, — внутри sound/ ("myplugin/hit.wav"); модель или спрайт — со своей папкой ("models/myplugin/box.mdl"). Возвращает файл как Resource — его эффект принимает вместо спрайта или модели.

entity.emitSound(sample, options) проигрывает звук от сущности — и от игрока тоже: его слышат все рядом, и он затихает с расстоянием. У каждой настройки есть значение по умолчанию:

НастройкаПо умолчаниюЗначение
channel"auto"канал сущности: "auto", "weapon", "voice", "item", "body", "stream", "static"; новый звук на канале обрывает тот, что играет на нём, "auto" не обрывает никогда
volume1от 0 до 1
attenuation0.8как быстро затихает с расстоянием: 0 слышен по всей карте, 2 — только вблизи
pitch100в процентах: 50 — октавой ниже, до 255
to с v0.3.1все рядомединственный игрок, который его слышит, — оттуда, где сущность: door.emitSound("myplugin/creak.wav", { to: player })

player.playSound(sample) проигрывает звук одному игроку — он слышит его одинаково, где бы ни стоял, как рацию.

Звук, который проигрывает игра, — шаг, прыжок, перезарядка, — это игровое событие "startSound": preventDefault() его заглушает, а recipients с v0.3.1 проигрывает его только выбранным из тех игроков, до кого он дошёл бы:

const 
deaf
= new
Set
<number>(); // id игроков, которые никого не слышат
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
));
});
Свои шаги игроку проигрывает его игра
Свои шаги и прыжки игрок слышит из своей игры, а не с сервера: recipients выбирает среди остальных игроков.
Прекэшировать можно только пока грузится карта, а модель, которую игре дали без прекэша, останавливает сервер. Плагин, перезагруженный посреди карты, события "precache" не получает; его верхний уровень выполняется снова, и Resource, запрошенный там, находит индекс, который карта дала файлу. Файл, который никто из плагинов не прекэшировал, пока грузилась карта, ждёт следующей карты.

server.precached с v0.3.3 говорит, сколько места движка заняла карта, — models (вместе со спрайтами и моделями самой карты), sounds и прочие файлы files, — по всем прекэшам: игры и всех плагинов, на Pawn тоже:

server
.
addEventListener
("pluginsLoaded", () => {
console
.
log
(`models: ${
server
.
precached
.
models
} of 512`);
});
Место для прекэшированных файлов
У движка место для 512 моделей, 512 звуков и 512 прочих файлов на карту, и прекэш сверх него останавливает сервер. Когда вид доходит до 461 — девяти десятых, — и ещё раз, когда он заполнен, консоль и лог AMX Mod X говорят об этом, с последним прекэшированным файлом и плагином, который его прекэшировал (плагин amxts — по имени; плагин на Pawn или игра — так и названы). Карта со множеством своих моделей оставляет плагинам меньше места: её модели считаются прекэшированными.

Сервер

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"); // выполнится в консоли сервера

server.command выполняет строку в консоли сервера, как будто её набрали там. Выполнить её в консоли игрока — player.command("say hi").

server
.
game
; // "cstrike"
server
.
versions
.
reGameDll
; // "5.28", null в оригинальной игре
server
.
mapExists
("de_nuke"); // true, если карта на сервере есть
server
.
changeLevel
("de_nuke"); // переходит туда сейчас; false, если карты нет
server
.
lightStyle
= "b"; // темнее, от "a" до "z", "m" — свет самой карты, до смены карты
server
.
intermission
(); // таблица счёта всем, взгляд замер, до смены карты
server
.
print
("Round 3"); // в чат всем игрокам; "center", "console" — как в print

server.game с v0.3, server.versions с v0.3 — версии amxts, AMX Mod X и Metamod, API ReHLDS и ReGameDLL или null, — server.mapExists с v0.3, server.changeLevel с v0.3, server.lightStyle с v0.3, server.logsDir с v0.3, server.print с v0.3 и server.intermission с v0.3.1 — антракт, как его показывает игра в конце карты; карту меняйте через несколько секунд server.changeLevel.