amxts

Плагины для Counter-Strike 1.6 на TypeScript

Документация • Начало работы • Модули • Сборка из исходников

English | Русский

amxts — фреймворк для плагинов AMX Mod X на TypeScript. Плагин — обычный файл .ts: классы, замыкания, async/await, события, на которые подписываешься, — заранее компилируется в машинный код и работает внутри AMX Mod X рядом с Pawn-плагинами. Они вызывают друг друга: TypeScript-плагин отдаёт Pawn нативы и форварды и вызывает любой натив любого модуля или плагина.

Возможности

• Знакомый TypeScript. number, string, массивы, Map, классы, интерфейсы с необязательными полями, замыкания, async/await с AbortSignal.
• Игроки и сущности — объекты. player.health = 100, player.team == "CT", player.hideHud.push("money"), entity.renderMode = "additive".
• События как в DOM. server.addEventListener("putInServer", ...), game.addEventListener("takeDamage", ...) для событий игры (хукчейнов ReAPI и функций Ham Sandwich), с event.preventDefault() и ответом через return.
• Редактор знает игру. Каждый натив, поле ReAPI и хукчейн — с типом и подсказкой на русском или английском; опечатка — красная строка, а не ошибка на сервере.
• Без строк импорта. Player, server, print и имена модулей импортируются сами: сборка добавляет то, чем плагин пользуется, и ничего больше.
• Сохранил — играешь. amxts dev пересобирает сохранённое, выкладывает и перезагружает работающий сервер — без смены карты, никого не выкидывает.
• Тесты без сервера. Плагин работает на поддельном сервере под bun test, и тест ведёт его, как вели бы игроки.
• Машинный код. Плагин компилируется в машинный код до того, как сервер его загрузит (производительность).
• Модули — по одному на сервер. amxts.config.ts их перечисляет, amxts module add ставит, и каждый работает на сервере в одном экземпляре для всех плагинов, которые им пользуются; модуль, которым не пользуется никто, не собирается.

Требования

На сервере:

• Windows или Linux — модуль amxts_amxx — это amxts_amxx.dll или amxts_amxx_i386.so, оба проверены на настоящем сервере. Плагин компилируется под систему своего сервера, которую сборка узнаёт по папке сервера (или по --os).
• ReHLDS с ReGameDLL и ReAPI — рекомендуется. amxts проверяется на нём и на обычном HLDS, где поля сущностей работают через собственные модули AMX Mod X, а события игры приходят через Ham Sandwich, лог игры и её сообщения: большинство — когда игра уже сделала своё, а некоторые события ReGameDLL не приходят вовсе.
• AMX Mod X 1.9 или новее.

Для разработки плагинов: Node.js 20.12+. Сборка работает на Bun, которого ядро ставит само — настраивать ничего не нужно.

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

npm create amxts@latest    # or: pnpm create amxts, yarn create amxts, bun create amxts

Команда спрашивает менеджер пакетов, папку, модули, линт и папку сервера, пишет проект с первым плагином и его тестом и всё устанавливает.

Дальше, в проекте:

npx amxts dev              # build, deploy to the server in AMXTS_SERVER, again on every save
npx amxts build --deploy   # build once and deploy
npx amxts test             # the tests, on a fake server

Плагин

// plugins/hello.ts
plugin({ name: "Hello", version: "1.0.0", author: "you", description: "An example" });

server.addCommand("/hp", ({ player }) => sayHp(player));
server.addEventListener("putInServer", (event) => {
	print(0, `${event.player.name} joined`);
});

function sayHp(player: Player) {
	print(player, `${player.name}, your HP: ${player.health}`);

	if (player.health < 50) player.health = 100;
}

Модули

Ядро не включает модулей: проект перечисляет нужные в amxts.config.ts, а npx amxts module add <name> ставит модуль. Официальные модули от авторов amxts:

| модуль | что | | --- | --- | | menu-core | меню из файлов INI, YAML или JSON или из кода: условия, списки, отсчёты — и нативы mc_* для Pawn-плагинов | | config-core | конфиги в INI, YAML или JSON, прочитанные в типизированные объекты и записанные обратно, — и нативы cfg_* для Pawn-плагинов | | resemiclip | кто сквозь кого проходит, правилом над двумя игроками, поверх модуля ReSemiclip | | ftp | FTP, FTPS и SFTP: загрузка, скачивание и список файлов на другом сервере, каждый вызов — промис |

Веб-запросы идут с ядром: useFetch<T>(url) и fetch, как в браузере. Другие модули — в каталоге, а npx amxts init --module начинает свой.

Поддержка в редакторе

amxts для VS Code даёт файлам меню и конфигов подсказки, проверки и навигацию — по именам, которые регистрируют плагины, прямо при наборе. Самому TypeScript ничего дополнительно не нужно: tsconfig.json проекта готов для любого редактора.

Документация

amxts.github.io — начало работы, API, модули, тесты и то, чего amxts пока не умеет, на русском и английском. Она описывает последний релиз; следующий, который собирает эта ветка, — на amxts.github.io/ru/docs/next. Исходники — в docs.

Сборка из исходников

Для работы над самим amxts нужны Bun, дистрибутив AMX Mod X 1.10 (bun run setup:amxmodx), для модуля под Windows — Windows с CMake и Visual Studio (32-битная сборка) и LLVM 18 для wamrc, для модуля под Linux — Docker (bun run build:linux, bun run test:server --linux), а также официальные модули и команда amxts (amxts-cli) рядом с ядром. Компиляторы заплатаны — AssemblyScript 0.28.20 и WAMR 2.4.5, — а сгенерированный API не коммитится:

npm install --no-package-lock   # npm, not bun: it links the file: folders
bun run generate    # after the compilers are built and patched
bun run test

CONTRIBUTING.ru.md — все шаги, проверки и то, как прислать изменение.

Лицензия

MIT. Модуль сервера, собранный из этого кода, вместе с плагином-хостом, который он несёт в себе, использует SDK AMX Mod X, поэтому распространяется под GPL-3.0-or-later. Лицензии сторонних проектов: runtime/licenses.