amxts - плагины AMX Mod X на TypeScript 0.3.1

amxts 0.3.1 — база данных MySQL прямо в плагине, и ничего больше не держит кадр сервера.

Плагины, собранные под 0.3.0, работают на модуле 0.3.1 как есть. Для нового нужен модуль 0.3.1 — npx amxts upgrade ставит его на сервер.

MySQL в amxts
Модуль сам говорит с MySQL и MariaDB — без сторонних библиотек, с TLS — и каждый запрос идёт в своём потоке: сервер никогда не ждёт базу. Таблицы описываются на TypeScript, как в Drizzle, строки приходят с типами:

JavaScript:

import { asc, double, eq, int, table, varchar } from "@amxts/core/database";

export const records = table("records", {
    id: int().primaryKey().autoincrement(),
    steamId: varchar(32).notNull(),
    map: varchar(64).notNull(),
    time: double().notNull(),
});

const db = new Database(env("MYPLUGIN_DB"));   // mysql://… или jdbc:mysql://… прямо из панели хостинга
await db.create(records);

const top = await db.select().from(records)
    .where(eq(records.map, server.map))
    .orderBy(asc(records.time))
    .limit(10);

Опечатка в имени колонки видна в редакторе, значения уходят параметрами, а не текстом SQL. Есть транзакции, сырой SQL рядом (db.query), файлы в BLOB-колонках как Uint8Array. Другие базы подключаются провайдерами.

Ничего не держит кадр
Распаковка скачанной карты больше не даёт лаг: await fs.extract(bytes) работает в потоке модуля. Так же запись и чтение байтов и новое сжатие — @amxts/core/zlib как в Node: gzip, gunzip, deflate, inflate.

Новое в API

• Своё движение игрока: player.movement.airAccelerate = 100, friction, stopSpeed и другие — сервер двигает его с ними, а игра предсказывает их, на любом сервере
• Свои поля на сущностях, как у игрока: door.doorSpeed — общие для плагинов, исчезают вместе с сущностью
• Кто что слышит: звук и выстрел можно отдать только части игроков — event.recipients = [...]; звук одному игроку — door.emitSound(sample, { to: player })
• HUD без мигания: new HudLine({ priority: 1 }) — строка важнее держит свой канал
• entity.touch(other), entity.restart(), player.resetMaxSpeed(), player.jumpSlowdown, server.intermission(), fs.existsSync(path, { game: true })
• На обычном HLDS теперь слышно событие move

Каждый новый вызов проверяется против того же действия на Pawn — и быстрее него.

Исправления

• Storage.get терял последний символ у значения длиннее 1 КБ
• amxclient_cmd из Pawn-плагина доходит до команд на TypeScript
• Плагин можно назвать как файл ядра (hooks.ts, facade.ts)
• Infinity | 0 и большие числа считаются как в JavaScript
• Модуль показывает свою версию в amxx modules

Что поменять в коде

• fs.extract(bytes) теперь промис: await fs.extract(bytes) или синхронный fs.extractSync(bytes) — npx amxts upgrade перепишет сам
• В событии startSound event.recipients — список игроков, а не число — upgrade покажет такие места

Как обновиться
Нужен Node.js 24 или новее: на Node 22 npm 10 на Linux не может поставить тестовый раннер нового проекта.

C-подобный:

npm install -D @amxts/cli@latest
npx amxts upgrade

Полный список изменений: релиз v0.3.1 на GitHub
Документация: amxts.github.io/docs

amxts 0.3.0 — большое обновление: модуль стал один, ReAPI больше не нужен, а плагины на TypeScript работают не медленнее Pawn.

Главное

amxts — теперь один модуль
В 0.2 было две части: модуль amxts_amxx и плагин-хост amxts_host.amxx в plugins.ini, через который события игры шли в TypeScript. В 0.3 хоста нет: модуль сам слушает игру — команды игроков, сообщения, квары, лог, меню и хуки ReGameDLL/ReHLDS. Между игрой и вашим кодом больше нет Pawn.
Заодно amxts стал быстрее: на каждом замере тестового набора плагин на TypeScript работает как минимум так же быстро, как его двойник на Pawn, а на большинстве — быстрее.

ReAPI не нужен
То, что делали натив ReAPI rg_*, модуль делает сам — через API ReGameDLL, а на чистом HLDS через функции игры. Выдача и отбор оружия, смена команды, возрождение, модели, HUD, текстовые меню, game.restartRound() работают одинаково на:

• ReHLDS + ReGameDLL, с ReAPI и без;
• обычном HLDS от Valve с metamod-p.

Сервер только загружает, собирает ваш компьютер
Сервер больше ничего не компилирует: он загружает готовые .aot. Собираете npx amxts build и заливаете — или amxts dev / build --deploy делают это сами, как .sma компилируют дома и заливают .amxx. Комплект для сервера стал в разы меньше.

Одна линия — один ABI
Плагин, собранный под 0.3.0, загружается на любом модуле 0.3: 0.3.1, 0.3.2 и дальше. Патч ядра не заставляет ничего пересобирать.

Что нового

Секреты через env() — токен или ключ не попадают в код и в .aot, а читаются на сервере из addons/amxts/.env или окружения:

JavaScript:

const token = env("MYPLUGIN_TOKEN");          // обязательный: текст
const maxRecords = env("MYPLUGIN_MAX", 100);  // число
const debug = env("MYPLUGIN_DEBUG", false);   // вкл/выкл

player.print и server.print

JavaScript:

player.print(`С возвращением, ${player.name}!`);
player.print("Раунд перезапущен", "center");
server.print("Смена карты через 30 секунд");

Команды с несколькими именами, обработчик получает игрока:

JavaScript:

server.addCommand(["/cp", "cp"], (player) => player.print("Чекпоинт сохранён"));

А каждая команда игрока доходит до события "command", где preventDefault() её останавливает.

Что видит каждый игрок — событие "entityState": меняете то, что сервер шлёт одному игроку про одну сущность, и изменение видит только он.

Плагины, управляющие плагинами — server.plugins: список всех плагинов (TypeScript и Pawn), остановка, запуск, перезагрузка, вызов публичной функции Pawn-плагина.

Storage с типами — new Storage<T>(name) хранит любой интерфейс в JSON и один раз забирает nVault-файл с тем же именем, так что при переносе с Pawn ничего не теряется.

Файлы, загрузки и архивы — файлы читаются и пишутся байтами, fs.extract распаковывает zip: плагин может скачать карту и положить её на место.

Движение игрока — у событий движения есть event.touchCount и event.frameTime: хватает для jump stats без get_pmove из ReAPI.

И ещё

• трассировки: trace.line, player.aim (куда смотрит игрок), canSee;
• сообщения по имени: player.send и server.send;
• игрок: player.model, player.info, player.country, player.showMotd;
• экран: player.screen.hint и HudLine.showAll;
• выстрелы: остановить выстрел или показать его только части игроков;
• у amxts dev панель: карта, игроки, FPS, состояние плагинов, клавиши пересборки, смены карты и рестарта раунда; amxts rcon шлёт команду серверу.

Как обновиться
Сначала обновите команду пакетным менеджером проекта:

C-подобный:

npm install -D @amxts/cli@latest

Потом:

C-подобный:

npx amxts upgrade

Он переведёт @amxts/core на 0.3.0 и модули на их версии, перепишет код под изменения API, соберёт проект и поставит модуль 0.3.0 на сервер из AMXTS_SERVER. Что нужно проверить руками, он перечислит в конце. Плагин amxts_host.amxx и папки addons/amxts/tools/ и build/ старого комплекта больше не нужны.

Полный список изменений и таблица несовместимостей: релиз v0.3.0 на GitHub
Документация: amxts.github.io/docs