@amxts/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kukson777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="amxts" width="96" height="96">
+
+# amxts
+
+*Counter-Strike 1.6 plugins in TypeScript*
+
+[Documentation](https://amxts.github.io/) • [Getting started](https://amxts.github.io/docs/getting-started/quick-start) • [Modules](https://amxts.github.io/modules) • [Building from source](#building-from-source)
+
+**English** | [Русский](README.ru.md)
+
+</div>
+
+amxts is a framework for writing AMX Mod X plugins in TypeScript. A plugin is
+an ordinary `.ts` file - classes, closures, `async`/`await`, events you
+listen to - compiled ahead of time to native code and run inside AMX Mod X,
+next to your Pawn plugins. The two call each other: a TypeScript plugin
+exports natives and forwards for Pawn, and calls any native of any module or
+plugin.
+
+## Features
+
+- **TypeScript you already know.** `number`, `string`, arrays, `Map`,
+  classes, interfaces with optional fields, closures, `async`/`await` with
+  `AbortSignal`.
+- **Players and entities are objects.** `player.health = 100`,
+  `player.team == "CT"`, `player.hideHud.push("Money")`,
+  `entity.renderMode = "additive"`.
+- **Events as in the DOM.** `server.addEventListener("putinserver", ...)`,
+  `game.addEventListener("takeDamage", ...)` for the game's events (reapi's
+  hookchains and Ham Sandwich's functions), with
+  `event.preventDefault()` and an answer by `return`.
+- **The editor knows the game.** Every native, reapi field and hookchain
+  comes with its type and a tooltip in English or Russian; a typo is a red
+  line, not a runtime error.
+- **No import lines.** `Player`, `server`, `print` and the modules' names are
+  auto-imported: the build adds what a plugin uses, and nothing else.
+- **Save and play.** `amxts dev` rebuilds what you saved, deploys it and
+  reloads the running server - no map change, nobody disconnected.
+- **Tests without a server.** Your plugin runs on a fake server under
+  `bun test`, driven as players would drive it.
+- **Faster than Pawn.** Plugins are machine code by the time the server loads
+  them; on the hot path of a real plugin that is about three times faster
+  than the same logic in Pawn.
+- **Modules, one per server.** `amxts.config.ts` lists them, `amxts module add`
+  installs them, and each runs once per server for every plugin that
+  uses it; a module no plugin uses is not built.
+
+## Requirements
+
+On the server:
+
+- **Windows or Linux** - the `amxts_amxx` module is `amxts_amxx.dll` or
+  `amxts_amxx_i386.so`, both tested on a real server. A plugin is compiled
+  for its server's system, which the build reads off the server's folder
+  (or `--os`).
+- **ReHLDS with ReGameDLL and reapi** - recommended, and what amxts is tested
+  on. Entity fields and the game events reapi delivers need it; plain HLDS
+  has not been tried.
+- **AMX Mod X 1.9** or later.
+
+To write plugins: [Node.js](https://nodejs.org) 20.12+. The build runs on
+[Bun](https://bun.sh), which the core installs itself - nothing to set up.
+
+## Getting started
+
+```sh
+npm create amxts@latest    # or: pnpm create amxts, yarn create amxts, bun create amxts
+```
+
+It asks for the package manager, the folder, the modules, lint and the
+server's folder, writes a project with a first plugin and its test, and
+installs everything.
+
+> [!WARNING]
+> The packages are not on npm yet. Until they are, create a project from a
+> clone of this repository, with [amxts-cli](https://github.com/amxts/amxts-cli)
+> (the `amxts` command) and the official modules cloned beside it; it links
+> the core and the modules instead of installing them:
+> `node <core>/bin/amxts.mjs init my-server --local`.
+> See [getting started](https://amxts.github.io/docs/getting-started/quick-start#a-project).
+
+Then, in the project:
+
+```sh
+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
+```
+
+## A plugin
+
+```ts
+// plugins/hello.ts
+plugin({ name: "Hello", version: "1.0.0", author: "you", description: "An example" });
+
+server.addCommand("/hp", sayHp);
+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;
+}
+```
+
+## Modules
+
+The core includes no modules: a project lists the ones it uses in
+`amxts.config.ts`, and `npx amxts module add <name>` installs one. The
+official modules, kept by the amxts authors:
+
+| module | what |
+| --- | --- |
+| [menu-core](https://github.com/amxts/menu-core) | menus from INI, YAML or JSON files or from code: conditions, lists, countdowns - and the `mc_*` natives for Pawn plugins |
+| [config-core](https://github.com/amxts/config-core) | configs in INI, YAML or JSON, read into typed objects and written back - and the `cfg_*` natives for Pawn plugins |
+| [resemiclip](https://github.com/amxts/resemiclip) | who walks through whom, as a rule over two players, over the ReSemiclip module |
+
+`fetch` over easy_http comes with the core (`~/modules/http`). More modules
+are in the [catalog](https://amxts.github.io/modules), and
+`npx amxts init --module` starts your own.
+
+## Editor support
+
+[amxts for VS Code](https://github.com/amxts/amxts-vscode) gives menu and
+config files completion, checks and navigation, from the names your plugins
+register as you type them. TypeScript itself needs nothing extra: a project's
+`tsconfig.json` is ready for any editor.
+
+## Documentation
+
+[amxts.github.io](https://amxts.github.io/) - getting started, the API,
+modules, testing and what amxts cannot do yet, in English and Russian. The
+sources are in [`docs`](docs).
+
+## Building from source
+
+Working on amxts itself takes Bun, an AMX Mod X 1.10 distribution
+(`bun run setup:amxmodx`), for the Windows module Windows with CMake and
+Visual Studio (32-bit) and LLVM 18 for `wamrc`, for the Linux one Docker
+(`bun run build:linux`, `bun run test:server --linux`), and the official
+modules and the `amxts` command ([amxts-cli](https://github.com/amxts/amxts-cli))
+checked out beside the core. The compilers are patched - AssemblyScript
+0.28.20 and WAMR 2.4.5 - and the generated API is not committed:
+
+```sh
+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.md`](CONTRIBUTING.md) has every step, the checks and how to
+send a change.
+
+## License
+
+[MIT](LICENSE). The server module and the host plugin built from this code use
+AMX Mod X's SDK, so they are distributed under GPL-3.0-or-later. Third-party
+licenses: [`runtime/licenses`](runtime/licenses/README.md).

package/README.ru.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="amxts" width="96" height="96">
+
+# amxts
+
+*Плагины для Counter-Strike 1.6 на TypeScript*
+
+[Документация](https://amxts.github.io/ru/) • [Начало работы](https://amxts.github.io/ru/docs/getting-started/quick-start) • [Модули](https://amxts.github.io/ru/modules) • [Сборка из исходников](#сборка-из-исходников)
+
+[English](README.md) | **Русский**
+
+</div>
+
+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`, и тест ведёт его, как вели бы игроки.
+- **Быстрее Pawn.** К загрузке на сервер плагин уже машинный код; на горячем
+  пути настоящего плагина это примерно в три раза быстрее той же логики на
+  Pawn.
+- **Модули — по одному на сервер.** `amxts.config.ts` их перечисляет,
+  `amxts module add` ставит, и каждый работает на сервере в одном экземпляре
+  для всех плагинов, которые им пользуются; модуль, которым не пользуется
+  никто, не собирается.
+
+## Требования
+
+На сервере:
+
+- **Windows или Linux** — модуль `amxts_amxx` — это `amxts_amxx.dll` или
+  `amxts_amxx_i386.so`, оба проверены на настоящем сервере. Плагин
+  компилируется под систему своего сервера, которую сборка узнаёт по папке
+  сервера (или по `--os`).
+- **ReHLDS с ReGameDLL и reapi** — рекомендуется, на этом amxts и
+  проверяется. Полям сущностей нужен reapi, как и событиям игры, которые
+  приходят от него; на обычном HLDS не запускали.
+- **AMX Mod X 1.9** или новее.
+
+Для разработки плагинов: [Node.js](https://nodejs.org) 20.12+. Сборка работает
+на [Bun](https://bun.sh), которого ядро ставит само — настраивать ничего не нужно.
+
+## Начало работы
+
+```sh
+npm create amxts@latest    # or: pnpm create amxts, yarn create amxts, bun create amxts
+```
+
+Команда спрашивает менеджер пакетов, папку, модули, линт и папку сервера,
+пишет проект с первым плагином и его тестом и всё устанавливает.
+
+> [!WARNING]
+> Пакетов в npm пока нет. До тех пор проект создаётся из клона этого
+> репозитория, рядом с которым склонированы [amxts-cli](https://github.com/amxts/amxts-cli)
+> (команда `amxts`) и официальные модули; он подключает ядро и модули
+> ссылками, а не ставит их: `node <core>/bin/amxts.mjs init my-server --local`.
+> Подробнее — в [начале работы](https://amxts.github.io/ru/docs/getting-started/quick-start#проект).
+
+Дальше, в проекте:
+
+```sh
+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
+```
+
+## Плагин
+
+```ts
+// plugins/hello.ts
+plugin({ name: "Hello", version: "1.0.0", author: "you", description: "An example" });
+
+server.addCommand("/hp", sayHp);
+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](https://github.com/amxts/menu-core) | меню из файлов INI, YAML или JSON или из кода: условия, списки, отсчёты — и нативы `mc_*` для Pawn-плагинов |
+| [config-core](https://github.com/amxts/config-core) | конфиги в INI, YAML или JSON, прочитанные в типизированные объекты и записанные обратно, — и нативы `cfg_*` для Pawn-плагинов |
+| [resemiclip](https://github.com/amxts/resemiclip) | кто сквозь кого проходит, правилом над двумя игроками, поверх модуля ReSemiclip |
+
+`fetch` поверх easy_http идёт с ядром (`~/modules/http`). Другие модули — в
+[каталоге](https://amxts.github.io/ru/modules), а `npx amxts init --module`
+начинает свой.
+
+## Поддержка в редакторе
+
+[amxts для VS Code](https://github.com/amxts/amxts-vscode) даёт файлам меню и
+конфигов подсказки, проверки и навигацию — по именам, которые регистрируют
+плагины, прямо при наборе. Самому TypeScript ничего дополнительно не нужно:
+`tsconfig.json` проекта готов для любого редактора.
+
+## Документация
+
+[amxts.github.io](https://amxts.github.io/ru/) — начало работы, API, модули,
+тесты и то, чего amxts пока не умеет, на русском и английском. Исходники — в
+[`docs`](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](https://github.com/amxts/amxts-cli))
+рядом с ядром. Компиляторы заплатаны — AssemblyScript 0.28.20 и WAMR 2.4.5, —
+а сгенерированный API не коммитится:
+
+```sh
+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`](CONTRIBUTING.ru.md) — все шаги, проверки и то, как
+прислать изменение.
+
+## Лицензия
+
+[MIT](LICENSE). Модуль сервера и host-плагин, собранные из этого кода,
+используют SDK AMX Mod X, поэтому распространяются под GPL-3.0-or-later.
+Лицензии сторонних проектов: [`runtime/licenses`](runtime/licenses/README.md).