@amxts/core 0.2.3 → 0.3.0

package/README.md

@@ -34,7 +34,7 @@ plugin.
 - **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
+- **No import lines.** `Player`, `server`, `game` 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.
@@ -90,11 +90,11 @@ plugin({ name: "Hello", version: "1.0.0", author: "you", description: "An exampl
 
 server.addCommand("/hp", ({ player }) => sayHp(player));
 server.addEventListener("putInServer", (event) => {
-	print(0, `${event.player.name} joined`);
+	server.print(`${event.player.name} joined`);
 });
 
 function sayHp(player: Player) {
-	print(player, `${player.name}, your HP: ${player.health}`);
+	player.print(`${player.name}, your HP: ${player.health}`);
 
 	if (player.health < 50) player.health = 100;
 }
@@ -153,6 +153,6 @@ send a change.
 
 ## License
 
-[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
+[MIT](LICENSE). The server module built from this code, with the natives'
+image 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

@@ -34,7 +34,7 @@ Mod X рядом с Pawn-плагинами. Они вызывают друг д
 - **Редактор знает игру.** Каждый натив, поле ReAPI и хукчейн — с типом и
   подсказкой на русском или английском; опечатка — красная строка, а не
   ошибка на сервере.
-- **Без строк импорта.** `Player`, `server`, `print` и имена модулей
+- **Без строк импорта.** `Player`, `server`, `game` и имена модулей
   импортируются сами: сборка добавляет то, чем плагин пользуется, и ничего
   больше.
 - **Сохранил — играешь.** `amxts dev` пересобирает сохранённое, выкладывает и
@@ -91,11 +91,11 @@ plugin({ name: "Hello", version: "1.0.0", author: "you", description: "An exampl
 
 server.addCommand("/hp", ({ player }) => sayHp(player));
 server.addEventListener("putInServer", (event) => {
-	print(0, `${event.player.name} joined`);
+	server.print(`${event.player.name} joined`);
 });
 
 function sayHp(player: Player) {
-	print(player, `${player.name}, your HP: ${player.health}`);
+	player.print(`${player.name}, your HP: ${player.health}`);
 
 	if (player.health < 50) player.health = 100;
 }
@@ -154,7 +154,7 @@ bun run test
 
 ## Лицензия
 
-[MIT](LICENSE). Модуль сервера, собранный из этого кода, вместе с
-плагином-хостом, который он несёт в себе, использует SDK AMX Mod X, поэтому
+[MIT](LICENSE). Модуль сервера, собранный из этого кода, вместе с образом
+нативов, который он несёт в себе, использует SDK AMX Mod X, поэтому
 распространяется под GPL-3.0-or-later.
 Лицензии сторонних проектов: [`runtime/licenses`](runtime/licenses/README.md).

package/as/amxts.d.ts

@@ -143,6 +143,13 @@ type UsageArgs<U extends string> = string extends U ? Record<string, string | un
 /** 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;
 
+/**
+ * What a command's handler takes: its arguments and `player` - `({ player,
+ * target }) =>`; for a command without arguments, the player himself too -
+ * `(player) =>`, which the compiler hands `player` (`Context & Player`).
+ */
+type CommandHandlerArgs<T, U extends string> = CommandArgsOf<T, U> & { player: Player } & ([T] extends [never] ? ([RequiredNames<U> | OptionalNames<U>] extends [never] ? Player : unknown) : unknown);
+
 declare module "./facade" {
 	interface PlayerChangeEvent<F extends string = string> {
 		/** The field's value after the change; with `{ field }`, of the field's type. */
@@ -176,11 +183,14 @@ declare module "./facade" {
 		 * 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`));
+		 * server.addCommand("/hp", ({ player }) => player.print(`${player.health} HP`));
+		 * server.addCommand(["/cp", "cp"], checkpoint);   // several names; a handler of the player
 		 * ```
 		 *
 		 * A name with `/` is a chat command, one without a console command, and
-		 * `"say <phrase>"` a phrase written in chat. A `number` argument is
+		 * `"say <phrase>"` a phrase written in chat. Several names - the usage
+		 * first, then other names - are one command. A command without
+		 * arguments takes a handler of the player, `(player) => ...`. 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
@@ -189,7 +199,7 @@ declare module "./facade" {
 		 * 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;
+		addCommand<T extends object = never, const U extends string = string>(usage: U | readonly [U, ...string[]], handler: (args: CommandHandlerArgs<T, U>) => 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