Плагин: команды, события, таймеры, чат, переводы
Плагин — это один файл .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-плагинов сервера раньше, чем до плагинов 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();
});
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-битный процесс: игра, её модули и все плагины делят несколько ГиБ адресов. Память плагина растёт удвоением, так что плагину, который держит около 1 ГиБ, может не найтись места на следующий шаг. Плагин, который хранит всё, что когда-либо случилось, в конце концов упирается в потолок: то, что должно жить долго, держите в
Storage или в базе данных, остальное
отпускайте.Меню с v0.2
Настоящие меню — магазин, меню админа, голосование — это то, для чего есть официальный модуль 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, — поэтому плагин может остановить сам себя или того, кто его
вызвал.
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}`. Место, на которое аргумента не хватило, остаётся как
написано, а ключ, которого нет ни в одном словаре, возвращается как есть.
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" не обрывает никогда |
volume | 1 | от 0 до 1 |
attenuation | 0.8 | как быстро затихает с расстоянием: 0 слышен по всей карте, 2 — только вблизи |
pitch | 100 | в процентах: 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.
Ограничения
Чего amxts пока не умеет — и что писать вместо этого. Почти о каждом пункте ниже скажут сборка, редактор или консоль сервера; здесь можно посмотреть, что это значит.
События игры
То, что происходит в игре, — игрок получает урон, возрождается, умирает, покупает оружие, бросает гранату, раунд заканчивается, — это события на game. Обработчик слышит событие до того, как игра что-то сделает, и может пропустить его, изменить, остановить или ответить вместо игры: