@amxts/core 0.1.0 → 0.2.1

package/README.md

@@ -25,13 +25,13 @@ plugin.
   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")`,
+  `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
+- **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
+- **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
@@ -40,9 +40,8 @@ plugin.
   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.
+- **Machine code.** Plugins are compiled to machine code before the server
+  loads them ([performance](docs/en/2.core/05.performance.md)).
 - **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.
@@ -55,9 +54,11 @@ On the server:
   `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.
+- **ReHLDS with ReGameDLL and ReAPI** - recommended. amxts is tested on it and
+  on plain HLDS, where the entity fields work through AMX Mod X's own modules
+  and the game events come through Ham Sandwich, the game's log and its
+  messages: most of them after the game has acted, and a few of ReGameDLL's
+  not at all.
 - **AMX Mod X 1.9** or later.
 
 To write plugins: [Node.js](https://nodejs.org) 20.12+. The build runs on
@@ -73,14 +74,6 @@ 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
@@ -95,8 +88,8 @@ 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", sayHp);
-server.addEventListener("putinserver", (event) => {
+server.addCommand("/hp", ({ player }) => sayHp(player));
+server.addEventListener("putInServer", (event) => {
 	print(0, `${event.player.name} joined`);
 });
 
@@ -118,8 +111,9 @@ official modules, kept by the amxts authors:
 | [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 |
+| [ftp](https://github.com/amxts/ftp) | FTP, FTPS and SFTP: upload, download and list files on another server, every call a promise |
 
-`fetch` over easy_http comes with the core (`~/modules/http`). More modules
+Web requests come with the core: `useFetch<T>(url)` and `fetch`, as in the browser. More modules
 are in the [catalog](https://amxts.github.io/modules), and
 `npx amxts init --module` starts your own.
 
@@ -133,8 +127,10 @@ register as you type them. TypeScript itself needs nothing extra: a project's
 ## 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).
+modules, testing and what amxts cannot do yet, in English and Russian. It
+describes the latest release; the next one, which this branch builds, is at
+[amxts.github.io/docs/next](https://amxts.github.io/docs/next). The sources
+are in [`docs`](docs).
 
 ## Building from source
 
@@ -157,6 +153,6 @@ 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
+[MIT](LICENSE). The server module built from this code, with the host plugin
+it carries, uses AMX Mod X's SDK, so it is distributed under GPL-3.0-or-later. Third-party
 licenses: [`runtime/licenses`](runtime/licenses/README.md).

package/README.ru.md

@@ -25,13 +25,13 @@ Mod X рядом с Pawn-плагинами. Они вызывают друг д
   интерфейсы с необязательными полями, замыкания, `async`/`await` с
   `AbortSignal`.
 - **Игроки и сущности — объекты.** `player.health = 100`,
-  `player.team == "CT"`, `player.hideHud.push("Money")`,
+  `player.team == "CT"`, `player.hideHud.push("money")`,
   `entity.renderMode = "additive"`.
-- **События как в DOM.** `server.addEventListener("putinserver", ...)`,
+- **События как в DOM.** `server.addEventListener("putInServer", ...)`,
   `game.addEventListener("takeDamage", ...)` для событий игры (хукчейнов
-  reapi и функций Ham Sandwich), с
+  ReAPI и функций Ham Sandwich), с
   `event.preventDefault()` и ответом через `return`.
-- **Редактор знает игру.** Каждый натив, поле reapi и хукчейн — с типом и
+- **Редактор знает игру.** Каждый натив, поле ReAPI и хукчейн — с типом и
   подсказкой на русском или английском; опечатка — красная строка, а не
   ошибка на сервере.
 - **Без строк импорта.** `Player`, `server`, `print` и имена модулей
@@ -41,9 +41,8 @@ Mod X рядом с Pawn-плагинами. Они вызывают друг д
   перезагружает работающий сервер — без смены карты, никого не выкидывает.
 - **Тесты без сервера.** Плагин работает на поддельном сервере под
   `bun test`, и тест ведёт его, как вели бы игроки.
-- **Быстрее Pawn.** К загрузке на сервер плагин уже машинный код; на горячем
-  пути настоящего плагина это примерно в три раза быстрее той же логики на
-  Pawn.
+- **Машинный код.** Плагин компилируется в машинный код до того, как сервер
+  его загрузит ([производительность](docs/ru/2.core/05.performance.md)).
 - **Модули — по одному на сервер.** `amxts.config.ts` их перечисляет,
   `amxts module add` ставит, и каждый работает на сервере в одном экземпляре
   для всех плагинов, которые им пользуются; модуль, которым не пользуется
@@ -57,9 +56,11 @@ Mod X рядом с Pawn-плагинами. Они вызывают друг д
   `amxts_amxx_i386.so`, оба проверены на настоящем сервере. Плагин
   компилируется под систему своего сервера, которую сборка узнаёт по папке
   сервера (или по `--os`).
-- **ReHLDS с ReGameDLL и reapi** — рекомендуется, на этом amxts и
-  проверяется. Полям сущностей нужен reapi, как и событиям игры, которые
-  приходят от него; на обычном HLDS не запускали.
+- **ReHLDS с ReGameDLL и ReAPI** — рекомендуется. amxts проверяется на нём и
+  на обычном HLDS, где поля сущностей работают через собственные модули AMX
+  Mod X, а события игры приходят через Ham Sandwich, лог игры и её сообщения:
+  большинство — когда игра уже сделала своё, а некоторые события ReGameDLL не
+  приходят вовсе.
 - **AMX Mod X 1.9** или новее.
 
 Для разработки плагинов: [Node.js](https://nodejs.org) 20.12+. Сборка работает
@@ -74,13 +75,6 @@ npm create amxts@latest    # or: pnpm create amxts, yarn create amxts, bun creat
 Команда спрашивает менеджер пакетов, папку, модули, линт и папку сервера,
 пишет проект с первым плагином и его тестом и всё устанавливает.
 
-> [!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
@@ -95,8 +89,8 @@ 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", sayHp);
-server.addEventListener("putinserver", (event) => {
+server.addCommand("/hp", ({ player }) => sayHp(player));
+server.addEventListener("putInServer", (event) => {
 	print(0, `${event.player.name} joined`);
 });
 
@@ -118,8 +112,9 @@ 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 |
+| [ftp](https://github.com/amxts/ftp) | FTP, FTPS и SFTP: загрузка, скачивание и список файлов на другом сервере, каждый вызов — промис |
 
-`fetch` поверх easy_http идёт с ядром (`~/modules/http`). Другие модули — в
+Веб-запросы идут с ядром: `useFetch<T>(url)` и `fetch`, как в браузере. Другие модули — в
 [каталоге](https://amxts.github.io/ru/modules), а `npx amxts init --module`
 начинает свой.
 
@@ -133,8 +128,10 @@ amxts:
 ## Документация
 
 [amxts.github.io](https://amxts.github.io/ru/) — начало работы, API, модули,
-тесты и то, чего amxts пока не умеет, на русском и английском. Исходники — в
-[`docs`](docs).
+тесты и то, чего amxts пока не умеет, на русском и английском. Она описывает
+последний релиз; следующий, который собирает эта ветка, — на
+[amxts.github.io/ru/docs/next](https://amxts.github.io/ru/docs/next).
+Исходники — в [`docs`](docs).
 
 ## Сборка из исходников
 
@@ -157,6 +154,7 @@ bun run test
 
 ## Лицензия
 
-[MIT](LICENSE). Модуль сервера и host-плагин, собранные из этого кода,
-используют SDK AMX Mod X, поэтому распространяются под GPL-3.0-or-later.
+[MIT](LICENSE). Модуль сервера, собранный из этого кода, вместе с
+плагином-хостом, который он несёт в себе, использует SDK AMX Mod X, поэтому
+распространяется под GPL-3.0-or-later.
 Лицензии сторонних проектов: [`runtime/licenses`](runtime/licenses/README.md).

package/as/amxts.d.ts

@@ -5,7 +5,7 @@
 // Only the editor reads this file. The build reads a module's definition from
 // its source and evaluates amxts.config.ts with a defineConfig of its own
 // (scripts/project.ts); asc never compiles either call.
-import type { ModuleOptions, Player, PlayerChangeEvent } from "./facade";
+import type { CommandOptions, ModuleOptions, Player, PlayerChangeEvent } from "./facade";
 
 declare global {
 	/** A module's name and config key. */
@@ -128,6 +128,21 @@ type PlayerFieldValue<F extends string> = F extends `${infer O}.${infer M}`
 	? O extends keyof Player ? (M extends keyof Player[O] ? Player[O][M] : never) : never
 	: F extends keyof Player ? Player[F] : never;
 
+// A command's arguments, typed. The build reads the type argument and the
+// usage the same way (scripts/typed-commands.ts); the editor reads them here.
+
+/** The names a usage requires: `<target>` in `"/kick <target> [reason]"`. */
+type RequiredNames<U extends string> = U extends `${string}<${infer N}>${infer R}` ? N | RequiredNames<R> : never;
+
+/** The names a usage may leave out: `[reason]`. */
+type OptionalNames<U extends string> = U extends `${string}[${infer N}]${infer R}` ? N | OptionalNames<R> : never;
+
+/** A usage's arguments, each text; any name for a usage made at run time, which the build reads. */
+type UsageArgs<U extends string> = string extends U ? Record<string, string | undefined> : { [K in RequiredNames<U>]: string } & { [K in OptionalNames<U>]?: string };
+
+/** A command's arguments: the type argument's, or else the usage's, as text. */
+type CommandArgsOf<T, U extends string> = [T] extends [never] ? UsageArgs<U> : T;
+
 declare module "./facade" {
 	interface PlayerChangeEvent<F extends string = string> {
 		/** The field's value after the change; with `{ field }`, of the field's type. */
@@ -143,10 +158,55 @@ declare module "./facade" {
 		 * and `event.previous` have the field's type.
 		 */
 		// oxlint-disable-next-line typescript/method-signature-style -- an overload, merged into the class's method
-		addEventListener<F extends PlayerFieldName>(type: "playerchange", listener: (event: PlayerChangeEvent<F>) => void, options: { field: F }): void;
+		addEventListener<F extends PlayerFieldName>(type: "playerChange", listener: (event: PlayerChangeEvent<F>) => void, options: { field: F }): void;
 		/** Stops calling a listener added with `addEventListener` - the same function and the same field. */
 		// oxlint-disable-next-line typescript/method-signature-style -- an overload, merged into the class's method
-		removeEventListener<F extends PlayerFieldName>(type: "playerchange", listener: (event: PlayerChangeEvent<F>) => void, options: { field: F }): void;
+		removeEventListener<F extends PlayerFieldName>(type: "playerChange", listener: (event: PlayerChangeEvent<F>) => void, options: { field: F }): void;
+		/**
+		 * Adds a command players type, by its usage: the name, then the
+		 * arguments, `<name>` required and `[name]` optional. Their types are an
+		 * interface, the type argument; without it each is text.
+		 *
+		 * ```ts
+		 * interface KickArgs {
+		 *   target: Player;
+		 *   reason?: string;
+		 * }
+		 *
+		 * server.addCommand<KickArgs>("/kick <target> [reason]", ({ player, target, reason }) => {
+		 *   target.kick(reason ?? `Kicked by ${player.name}`);
+		 * }, { access: "kick" });
+		 * server.addCommand("/hp", ({ player }) => print(player, `${player.health} HP`));
+		 * ```
+		 *
+		 * A name with `/` is a chat command, one without a console command, and
+		 * `"say <phrase>"` a phrase written in chat. A `number` argument is
+		 * parsed, a `Player` found by `#userid`, the whole name or a part of it,
+		 * a `string` taken as it is - the last one takes the rest of the line. A
+		 * word that is not what the command takes answers the player with the
+		 * usage, and the handler does not run.
+		 *
+		 * Pawn: `register_clcmd`
+		 */
+		// oxlint-disable-next-line typescript/method-signature-style -- the editor's signature of the class's method, which the build writes per call
+		addCommand<T extends object = never, const U extends string = string>(usage: U, handler: (args: CommandArgsOf<T, U> & { player: Player }) => void, options?: CommandOptions): void;
+		/**
+		 * Adds a command of the server console - typed there, sent over rcon or
+		 * run by another plugin - by its usage, its arguments read as a player's
+		 * command's are. No player types it.
+		 *
+		 * ```ts
+		 * interface ResetArgs {
+		 *   what?: "scores" | "all";
+		 * }
+		 *
+		 * server.addServerCommand<ResetArgs>("myplugin_reset [what]", ({ what }) => reset(what ?? "all"));
+		 * ```
+		 *
+		 * Pawn: `register_srvcmd`
+		 */
+		// oxlint-disable-next-line typescript/method-signature-style -- the editor's signature of the class's method, which the build writes per call
+		addServerCommand<T extends object = never, const U extends string = string>(usage: U, handler: (args: CommandArgsOf<T, U>) => void): void;
 	}
 }