@amxts/menu-core 0.1.0 → 0.2.0

package/PAWN.md

@@ -2,7 +2,9 @@
 
 [English](PAWN.md) | [Русский](PAWN.ru.md)
 
-Menu Core serves the 30 natives of `menu_core.inc` (`mc_register_action`, `mc_show_menu`, `mc_add_menu_item` and the rest) with their signatures, so compiled `.amxx` plugins work unchanged. It takes the place of `menu_core.amxx`: comment that one out in `plugins.ini`, since two plugins cannot give the same natives.
+Menu Core serves the 30 natives of `menu_core.inc` (`mc_register_action`, `mc_show_menu`, `mc_add_menu_item` and the rest) with their signatures, so compiled `.amxx` plugins work unchanged.
+
+Pawn plugins write `#include <menu_core>`; the package ships `include/menu_core.inc`. Only one plugin on a server can give these natives: if another Pawn plugin in `plugins.ini` registers `mc_*` natives too, comment it out.
 
 Callbacks are named by their public function, and Menu Core calls them in the plugin that registered them.
 
@@ -16,7 +18,7 @@ A plugin compiled against it gets a tag warning for a bare number where `MenuPro
 
 ### How the natives behave
 
-- No Pawn limits: names, titles and placeholders are as long as they are written, a menu keeps every item, the way back is as long as it gets, and a menu longer than 500 bytes is sent whole.
+- No length limits: names, titles and placeholders are as long as they are written, a menu keeps every item, the way back is as long as it gets, and a menu longer than 500 bytes is sent whole.
 - `mc_get_menu_property_string(idx, MP_SECTION)` gives the menu's section.
 - A condition filter applies wherever the condition is asked.
 - A restriction's `message` is shown beside an item it greys out when the item has no message of its own.

package/PAWN.ru.md

@@ -2,7 +2,9 @@
 
 [English](PAWN.md) | [Русский](PAWN.ru.md)
 
-Menu Core отдаёт 30 нативов из `menu_core.inc` (`mc_register_action`, `mc_show_menu`, `mc_add_menu_item` и остальные) с их сигнатурами, так что собранные `.amxx`-плагины работают без изменений. Он встаёт на место `menu_core.amxx`: тот закомментируйте в `plugins.ini` — два плагина не могут отдавать одни и те же нативы.
+Menu Core отдаёт 30 нативов из `menu_core.inc` (`mc_register_action`, `mc_show_menu`, `mc_add_menu_item` и остальные) с их сигнатурами, так что собранные `.amxx`-плагины работают без изменений.
+
+Pawn-плагины пишут `#include <menu_core>`; в пакете лежит `include/menu_core.inc`. Отдавать эти нативы на сервере может только один плагин: если в `plugins.ini` есть другой Pawn-плагин с нативами `mc_*`, закомментируйте его.
 
 Колбэки задаются именем публичной функции, и Menu Core вызывает их в том плагине, который их зарегистрировал.
 
@@ -16,7 +18,7 @@ Menu Core отдаёт 30 нативов из `menu_core.inc` (`mc_register_acti
 
 ### Как работают нативы
 
-- Нет ограничений Pawn: названия, заголовки и подстановки любой длины, меню хранит все пункты, путь назад любой длины, меню длиннее 500 байт отправляется целиком.
+- Нет ограничений длины: названия, заголовки и подстановки любой длины, меню хранит все пункты, путь назад любой длины, меню длиннее 500 байт отправляется целиком.
 - `mc_get_menu_property_string(idx, MP_SECTION)` отдаёт секцию меню.
 - Фильтр условия применяется везде, где спрашивают условие.
 - `message` ограничения показывается рядом с посеревшим пунктом, если у пункта нет своего сообщения.

package/README.md

@@ -17,20 +17,17 @@
 
 Describe a menu once, in a file — INI, YAML or JSON — or in code, and Menu Core handles the rest: pages, keys, the way back, countdowns, and items that appear, disappear or grey out depending on who is looking.
 
-> [!WARNING]
-> **In progress.** Menu Core has been tried in game only a few times, and its API may still change.
-
 ## Features
 
 - **Menus from a file or from code.** Admins edit `menu.ini`, `menu.yaml` or `menu.json` without touching a plugin; plugins add their own items at run time.
 - **Mistakes said where they are.** An unknown key, a value of the wrong kind, a condition or an action nobody registered: the server console says so, with the file and the line.
 - **Shown, and chosen.** An item says when it is shown at all (`visible`) and when it can be chosen (`enabled`): greyed out, with the message of the first requirement that fails beside it.
-- **Text that follows the player.** A title, an item or a message can be a function — ``(player) => `Heal (${player.health} HP)` `` — read each time the menu is drawn; in `menu.ini`, `%hp%`-style placeholders do the same.
+- **Text that follows the player.** A title, an item or a message can be a function — ``({ player }) => `Heal (${player.health} HP)` `` — read each time the menu is drawn; in `menu.ini`, `%hp%`-style placeholders do the same.
 - **List menus.** A row per player or per item of your own list, with filters and a message when nothing is left.
 - **Variants.** One item, several faces: the first variant whose `when` holds is shown.
 - **Countdowns and locks.** Timed menus, one timer per player or one for everyone, and menus that cannot be closed or replaced.
 - **One instance per server.** Every plugin, TypeScript or Pawn, fills and opens the same menus.
-- **No Pawn limits.** Long names, many items, Cyrillic menus over 500 bytes.
+- **No length limits.** Long names, many items, Cyrillic menus over 500 bytes.
 
 ## Installation
 
@@ -65,38 +62,72 @@ The build loads Config Core first. A config that lists only Menu Core builds the
 A plugin uses the module as `menus`, without an import line: the build adds the import to the plugins that use it, and builds the module only when some plugin does.
 
 ```ts
-const shop = menus.create("SHOP", { title: (player) => `Shop for ${player.name}` });
+const shop = menus.create("SHOP", { title: ({ player }) => `Shop for ${player.name}` });
 
-shop.addItem((player) => `Heal (${player.health} HP)`, {
-	visible: (player) => player.health < 100,
-	onSelect: (player) => {
+shop.addItem({
+	title: ({ player }) => `Heal (${player.health} HP)`,
+	visible: ({ player }) => player.health < 100,
+	onSelect: ({ player }) => {
 		player.health = 100;
 	},
 });
-shop.addItem("Buy AWP", {
+shop.addItem({
+	title: "Buy AWP",
 	// Greyed out while one says no: the first that does gives its message.
 	enabled: [
-		{ when: (player) => player.isAlive, message: "Only while alive" },
-		{ when: (player) => player.account >= 4750, message: (player) => `Need $${4750 - player.account} more` },
+		{ when: ({ player }) => player.isAlive, message: "Only while alive" },
+		{ when: ({ player }) => player.money >= 4750, message: ({ player }) => `Need $${4750 - player.money} more` },
 	],
-	onSelect: (player) => {
-		player.account = player.account - 4750;
+	onSelect: ({ player }) => {
+		player.money = player.money - 4750;
 		player.give("weapon_awp");
 	},
 });
-shop.addItem("Reset score", {
-	enabled: (player) => player.frags != 0,
+shop.addItem({
+	title: "Reset score",
+	enabled: ({ player }) => player.frags != 0,
 	message: "(already 0)",
-	onSelect: (player) => {
+	onSelect: ({ player }) => {
 		player.frags = 0;
 	},
 });
-shop.addItem("Close", { action: "CLOSE_MENU", spaceBefore: 1 });
+shop.addItem({ title: "Close", action: "CLOSE_MENU", spaceBefore: 1 });
+
+server.addCommand("/shop", ({ player }) => shop.show(player));
+```
+
+Every function of a menu — a title, `visible`, `enabled`, `onSelect` — gets one object, the menu's context:
+
+- `player` — the player the menu is shown to: who looks at it, and who chooses;
+- `target` — the player the menu is about: the row's in a list menu, the one `show(player, { target })` was given otherwise, and `player` himself when there is none;
+- `row` — the row's number in a list menu, as `listRow()` gave it: an entity, an index of your own list — or a player's `id` in a list of players;
+- `menu` — the menu.
+
+A list menu (its name starts with `LIST_`) has a row per player, drawn with its first item:
+
+```ts
+const kick = menus.create("LIST_KICK", { title: "Kick a player" });
+kick.addFilter(({ player, target }) => target.id != player.id, "Nobody to kick");
+kick.addItem({
+	title: ({ target }) => target.name,
+	onSelect: ({ player, target }) => target.kick(`Kicked by ${player.name}`),
+});
+```
+
+Or a row per item of a list of your own, `menu.setListSource(rows)`:
 
-server.addCommand("/shop", (player) => shop.show(player));
+```ts
+const maps = ["de_dust2", "de_inferno", "de_nuke"];
+
+const vote = menus.create("LIST_MAPS", { title: "Next map" });
+vote.setListSource(() => maps.map((map, index) => menus.listRow(index, map)));
+vote.addItem({
+	title: ({ row }) => maps[row],
+	onSelect: ({ player, row }) => print(0, `${player.name} votes for ${maps[row]}`),
+});
 ```
 
-Text — a title, an item, a message — is the text itself or a function that gives it for the player who looks. A plain string that is a lang key is translated for him.
+Text — a title, an item, a message — is the text itself or a function that gives it for the context. A plain string that is a lang key is translated for the player.
 
 An item says when it is shown and when it can be chosen:
 
@@ -115,13 +146,14 @@ A menu is an object: `menus.create()` makes one, and its methods fill and open i
 
 | Method | What it does |
 | --- | --- |
-| `menu.addItem(text, options?)` | Adds an item: its text, or `(player, target) => text` — `target` is the row's in a list menu. Options: `onSelect`, `visible` (left out while it says no), `enabled` (greyed out while it says no — a test, or a list of `{ when, message }`), `message`, `at`, `spaceBefore`, `spaceAfter`; and for menus that name what plugins register, `action` and `placeholder`. |
-| `menu.addFixedItem(slot, text, options?)` | An item that keeps slot 1–7 on every page. |
-| `menu.addFilter(test, message?)` | A list menu leaves out the rows `test` says no to. |
-| `menu.setListSource(rows)` | A list menu's own rows: `listRow(target, text)`, `textRow(text)`. |
+| `menu.addItem(item)` | Adds an item: `title` — the text, or a function of the context — and `onSelect`, `visible` (left out while it says no), `enabled` (greyed out while it says no — a test, or a list of `{ when, message }`), `message`, `at`, `spaceBefore`, `spaceAfter`; and for menus that name what plugins register, `action` and `placeholder`. |
+| `menu.addFixedItem(slot, item)` | An item that keeps slot 1–7 on every page. |
+| `menu.addFilter(test, message?)` | A list menu leaves out the rows `test` says no to; `target` is the row's player. |
+| `menu.setListSource(rows)` | A list menu's own rows: `listRow(row, text)`, `textRow(text)`. |
 | `menu.addEventListener("open" \| "close" \| "show", listener)` | This menu's events; `"show"` comes before it opens, `event.preventDefault()` stops it. |
 | `menu.show(player, options?)` | Opens the menu; `false` when it does not open. Options: `time`, `target`, `resetHistory`, `force`, `skipHistory`. |
 | `menu.refresh()` · `menu.close()` · `menu.clearItems()` | Redraw it or close it for whoever looks at it; remove its items. |
+| `menu.runActions(player, line, target?)` | Runs an action line — `"GIVE_HP CLOSE_MENU"` — as a choice in the menu does. |
 | `menu.setTimer(seconds)` · `menu.cancelTimer()` | The countdown everyone looking at it shares. |
 
 Its fields — `title`, `time`, `hideBack`, `hideExit`, `locked`, `sharedTimer` — are set directly; `name`, `kind` and `countdown` are read.
@@ -131,7 +163,7 @@ Its fields — `title`, `time`, `hideBack`, `hideExit`, `locked`, `sharedTimer`
 | `create(name, options?)` | A menu in code, or the existing one with that name. A name starting with `LIST_` makes a list menu. Options: `title` (text or a function), `time`, `hideBack`, `hideExit`, `locked`, `activeWhen`. |
 | `find(name)` · `register(name)` | A menu by its name; `register` reads it from the file ahead of time. |
 | `show(player, name, options?)` · `close(player)` · `activeMenu(player)` · `lock(player)` | The player's menu, whichever it is. |
-| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | What menu files and Pawn plugins name, answered by functions — `%name%` in their text is a placeholder. A restriction's `message` is said beside an item it greys out, unless the item or the requirement has its own. `menu.addPlaceholder(name, value)` gives one to a single menu. |
+| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | What menu files and Pawn plugins name, answered by functions — `%name%` in their text is a placeholder. An action, a placeholder and a restriction get the menu's context and the `name` they are asked by; a condition, `(player, viewer, name)`, is asked of the row's player in a list menu. A restriction's `message` is said beside an item it greys out, unless the item or the requirement has its own. `menu.addPlaceholder(name, value)` gives one to a single menu. |
 | `setListSource(name, rows)` · `refresh("A B")` · `conditionChanged(name)` · `addEventListener(type, listener)` | The same for menus by name, and every menu's events. |
 
 ## Menus in a file
@@ -333,14 +365,24 @@ What does not fit a menu file is said in the server console with the file and th
 
 ### In the editor
 
-The amxts extension for VS Code checks a menu file as you type — the same checks, in the same words — and completes the keys and the names your plugins register (TypeScript, Pawn and installed modules), with hover and go to definition to the registration. A name added in a plugin is offered in the menu file at once, before the plugin is saved. It is not on the Marketplace yet: install its `.vsix` with `code --install-extension amxts-vscode-<version>.vsix`.
+The amxts extension for VS Code checks a menu file as you type — the same checks, in the same words — and completes the keys and the names your plugins register (TypeScript, Pawn and installed modules), with hover and go to definition to the registration. A name added in a plugin is offered in the menu file at once, before the plugin is saved. It is installed from its `.vsix`, with `code --install-extension amxts-vscode-<version>.vsix`.
 
 > [!WARNING]
 > The extension knows only names written as a string in the workspace: `menus.addAction(name, ...)` with the name in a variable, and a name only a Pawn plugin on the server registers, are a warning in the editor. The server's check on its first frame is the one that counts.
 
 ## Pawn plugins
 
-Pawn plugins use Menu Core through the 30 `mc_*` natives of `menu_core.inc`, which the package ships in `include/`; compiled `.amxx` plugins work unchanged. In `plugins.ini` it takes the place of `menu_core.amxx`. When no TypeScript plugin of the project uses the module, `pawn: ["@amxts/menu-core"]` in `amxts.config.ts` keeps it in the build for them. The details: [PAWN.md](PAWN.md).
+A Pawn plugin makes, fills and shows menus through Menu Core too, with its 30 natives whose names start with `mc_`: `mc_register_action`, `mc_show_menu`, `mc_add_menu_item` and the rest. The package ships their include in `include/`:
+
+```pawn
+#include <menu_core>
+```
+
+A Pawn plugin already compiled against this include works as it is, with nothing to rebuild.
+
+Only one plugin on a server can give these natives: if another Pawn plugin in `plugins.ini` registers `mc_*` natives too, comment it out.
+
+Menu Core runs on the server as one of the project's plugins. When no TypeScript plugin of the project uses it, keep it in the build for the Pawn plugins: `pawn: ["@amxts/menu-core"]` in `amxts.config.ts`. Every native with its signature: [PAWN.md](PAWN.md).
 
 ## Testing
 

package/README.ru.md

@@ -17,20 +17,17 @@
 
 Опишите меню один раз — в файле INI, YAML или JSON или в коде, — а остальное Menu Core сделает сам: страницы, клавиши, возврат назад, обратный отсчёт и пункты, которые появляются, скрываются или становятся серыми в зависимости от того, кто смотрит.
 
-> [!WARNING]
-> **В работе.** В игре Menu Core пробовали всего несколько раз, и API ещё может измениться.
-
 ## Возможности
 
 - **Меню из файла или из кода.** Админ правит `menu.ini`, `menu.yaml` или `menu.json`, не трогая плагин; плагины добавляют свои пункты на ходу.
 - **Ошибки — с местом.** Незнакомый ключ, значение не того вида, условие или действие, которое никто не зарегистрировал: консоль сервера говорит об этом, с файлом и строкой.
 - **Виден и доступен.** Пункт говорит, когда он вообще показан (`visible`) и когда его можно выбрать (`enabled`): иначе он серый, а рядом — сообщение первого требования, которое не выполнено.
-- **Текст, который зависит от игрока.** Заголовок, пункт или сообщение могут быть функцией — ``(player) => `Лечение (${player.health} HP)` `` — она читается при каждой отрисовке; в `menu.ini` то же делают плейсхолдеры вроде `%hp%`.
+- **Текст, который зависит от игрока.** Заголовок, пункт или сообщение могут быть функцией — ``({ player }) => `Лечение (${player.health} HP)` `` — она читается при каждой отрисовке; в `menu.ini` то же делают плейсхолдеры вроде `%hp%`.
 - **Меню-списки.** Строка на каждого игрока или на каждый элемент своего списка, с фильтрами и сообщением, если никого не осталось.
 - **Варианты.** Один пункт, несколько видов: показывается первый вариант, чьё `when` выполняется.
 - **Отсчёт и блокировка.** Меню с таймером — свой у каждого игрока или один на всех — и меню, которое нельзя закрыть или заменить.
 - **Один экземпляр на сервер.** Все плагины, на TypeScript и на Pawn, наполняют и открывают одни и те же меню.
-- **Без ограничений Pawn.** Длинные названия, сколько угодно пунктов, меню на кириллице длиннее 500 байт.
+- **Без ограничений длины.** Длинные названия, сколько угодно пунктов, меню на кириллице длиннее 500 байт.
 
 ## Установка
 
@@ -65,38 +62,72 @@ export default defineConfig({
 Плагин пользуется модулем как `menus`, без строки импорта: сборка добавляет импорт в те плагины, которые им пользуются, и собирает модуль, только когда им пользуется хоть один.
 
 ```ts
-const shop = menus.create("SHOP", { title: (player) => `Магазин для ${player.name}` });
+const shop = menus.create("SHOP", { title: ({ player }) => `Магазин для ${player.name}` });
 
-shop.addItem((player) => `Лечение (${player.health} HP)`, {
-	visible: (player) => player.health < 100,
-	onSelect: (player) => {
+shop.addItem({
+	title: ({ player }) => `Лечение (${player.health} HP)`,
+	visible: ({ player }) => player.health < 100,
+	onSelect: ({ player }) => {
 		player.health = 100;
 	},
 });
-shop.addItem("Купить AWP", {
+shop.addItem({
+	title: "Купить AWP",
 	// Серый, пока одно отвечает «нет»: первое такое даёт своё сообщение.
 	enabled: [
-		{ when: (player) => player.isAlive, message: "Только живым" },
-		{ when: (player) => player.account >= 4750, message: (player) => `Не хватает $${4750 - player.account}` },
+		{ when: ({ player }) => player.isAlive, message: "Только живым" },
+		{ when: ({ player }) => player.money >= 4750, message: ({ player }) => `Не хватает $${4750 - player.money}` },
 	],
-	onSelect: (player) => {
-		player.account = player.account - 4750;
+	onSelect: ({ player }) => {
+		player.money = player.money - 4750;
 		player.give("weapon_awp");
 	},
 });
-shop.addItem("Сбросить счёт", {
-	enabled: (player) => player.frags != 0,
+shop.addItem({
+	title: "Сбросить счёт",
+	enabled: ({ player }) => player.frags != 0,
 	message: "(уже 0)",
-	onSelect: (player) => {
+	onSelect: ({ player }) => {
 		player.frags = 0;
 	},
 });
-shop.addItem("Закрыть", { action: "CLOSE_MENU", spaceBefore: 1 });
+shop.addItem({ title: "Закрыть", action: "CLOSE_MENU", spaceBefore: 1 });
+
+server.addCommand("/shop", ({ player }) => shop.show(player));
+```
+
+Каждая функция меню — заголовок, `visible`, `enabled`, `onSelect` — получает один объект, контекст меню:
+
+- `player` — игрок, которому показано меню: тот, кто его смотрит и выбирает;
+- `target` — игрок, о котором меню: игрок строки в меню-списке, иначе тот, кого передали `show(player, { target })`, а если такого нет — сам `player`;
+- `row` — номер строки в меню-списке, как его дал `listRow()`: сущность, индекс в своём списке — или `id` игрока в списке игроков;
+- `menu` — само меню.
+
+Меню-список (его имя начинается с `LIST_`) — строка на каждого игрока, нарисованная по его первому пункту:
+
+```ts
+const kick = menus.create("LIST_KICK", { title: "Кикнуть игрока" });
+kick.addFilter(({ player, target }) => target.id != player.id, "Кикать некого");
+kick.addItem({
+	title: ({ target }) => target.name,
+	onSelect: ({ player, target }) => target.kick(`Кикнул ${player.name}`),
+});
+```
+
+Или строка на каждый элемент своего списка — `menu.setListSource(rows)`:
 
-server.addCommand("/shop", (player) => shop.show(player));
+```ts
+const maps = ["de_dust2", "de_inferno", "de_nuke"];
+
+const vote = menus.create("LIST_MAPS", { title: "Следующая карта" });
+vote.setListSource(() => maps.map((map, index) => menus.listRow(index, map)));
+vote.addItem({
+	title: ({ row }) => maps[row],
+	onSelect: ({ player, row }) => print(0, `${player.name} голосует за ${maps[row]}`),
+});
 ```
 
-Текст — заголовок, пункт, сообщение — это сам текст или функция, которая даёт его для игрока, который смотрит. Обычная строка, если это ключ словаря, переводится для него.
+Текст — заголовок, пункт, сообщение — это сам текст или функция, которая даёт его по контексту. Обычная строка, если это ключ словаря, переводится для игрока.
 
 Пункт говорит, когда он показан и когда его можно выбрать:
 
@@ -115,13 +146,14 @@ server.addCommand("/shop", (player) => shop.show(player));
 
 | Метод | Что делает |
 | --- | --- |
-| `menu.addItem(text, options?)` | Добавляет пункт: его текст или `(player, target) => текст` — `target` — цель строки в меню-списке. Опции: `onSelect`, `visible` (пункта нет, пока отвечает «нет»), `enabled` (пункт серый, пока отвечает «нет», — проверка или список `{ when, message }`), `message`, `at`, `spaceBefore`, `spaceAfter`; а для меню, которые называют зарегистрированное плагинами, — `action` и `placeholder`. |
-| `menu.addFixedItem(slot, text, options?)` | Пункт, который на каждой странице занимает слот 1–7. |
-| `menu.addFilter(test, message?)` | Меню-список пропускает строки, на которые `test` отвечает «нет». |
-| `menu.setListSource(rows)` | Свои строки меню-списка: `listRow(target, text)`, `textRow(text)`. |
+| `menu.addItem(item)` | Добавляет пункт: `title` — текст или функция контекста — и `onSelect`, `visible` (пункта нет, пока отвечает «нет»), `enabled` (пункт серый, пока отвечает «нет», — проверка или список `{ when, message }`), `message`, `at`, `spaceBefore`, `spaceAfter`; а для меню, которые называют зарегистрированное плагинами, — `action` и `placeholder`. |
+| `menu.addFixedItem(slot, item)` | Пункт, который на каждой странице занимает слот 1–7. |
+| `menu.addFilter(test, message?)` | Меню-список пропускает строки, на которые `test` отвечает «нет»; `target` — игрок строки. |
+| `menu.setListSource(rows)` | Свои строки меню-списка: `listRow(row, text)`, `textRow(text)`. |
 | `menu.addEventListener("open" \| "close" \| "show", listener)` | События этого меню; `"show"` приходит до открытия, `event.preventDefault()` его отменяет. |
 | `menu.show(player, options?)` | Открывает меню; `false`, если оно не открылось. Опции: `time`, `target`, `resetHistory`, `force`, `skipHistory`. |
 | `menu.refresh()` · `menu.close()` · `menu.clearItems()` | Перерисовать или закрыть у всех, кто его смотрит; убрать пункты. |
+| `menu.runActions(player, line, target?)` | Выполняет строку действий — `"GIVE_HP CLOSE_MENU"` — как её выполняет выбор в меню. |
 | `menu.setTimer(seconds)` · `menu.cancelTimer()` | Общий отсчёт для всех, кто его смотрит. |
 
 Его поля — `title`, `time`, `hideBack`, `hideExit`, `locked`, `sharedTimer` — задаются напрямую; `name`, `kind` и `countdown` читаются.
@@ -131,7 +163,7 @@ server.addCommand("/shop", (player) => shop.show(player));
 | `create(name, options?)` | Меню в коде или уже существующее с таким именем. Имя с `LIST_` делает меню-список. Опции: `title` (текст или функция), `time`, `hideBack`, `hideExit`, `locked`, `activeWhen`. |
 | `find(name)` · `register(name)` | Меню по имени; `register` заранее читает его из файла. |
 | `show(player, name, options?)` · `close(player)` · `activeMenu(player)` · `lock(player)` | Меню игрока, какое бы оно ни было. |
-| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | То, что называют файлы меню и Pawn-плагины, — ответы функциями; `%name%` в их тексте — плейсхолдер. `message` ограничения пишется рядом с пунктом, который оно гасит, если у пункта или требования нет своего. `menu.addPlaceholder(name, value)` задаёт его одному меню. |
+| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | То, что называют файлы меню и Pawn-плагины, — ответы функциями; `%name%` в их тексте — плейсхолдер. Действие, плейсхолдер и ограничение получают контекст меню и имя `name`, по которому их спросили; условие, `(player, viewer, name)`, в меню-списке спрашивается об игроке строки. `message` ограничения пишется рядом с пунктом, который оно гасит, если у пункта или требования нет своего. `menu.addPlaceholder(name, value)` задаёт его одному меню. |
 | `setListSource(name, rows)` · `refresh("A B")` · `conditionChanged(name)` · `addEventListener(type, listener)` | То же для меню по имени и события всех меню. |
 
 ## Меню в файле
@@ -252,7 +284,7 @@ VIEW = {
 | `labels`: `exit`, `back`, `next`, `number`, `disabled`, `page`, `time` | `[MAIN]` `KEY = { ... }` | Слова кнопок, страницы и отсчёта. |
 | `menus`: `{ NAME: меню }` | `[NAME]` | Меню; имя на `LIST_` — меню-список. |
 | `title` | `TITLE` | Заголовок; он у меню обязателен. |
-| `activeOn` | `ACTIVE_ON` | Условия, при которых меню открывается. |
+| `activeOn` | `ACTIVE_ON` | Условия, только при которых меню открывается. |
 | `hideBack` · `hideExit` | `HIDE_BACK` · `HIDE_EXIT` | `true` (INI: `YES`) убирает кнопку. |
 | `time` · `onTimeout` | `TIME` · `ON_TIMEOUT` | Отсчёт в секундах и действия, когда он закончился. |
 | `locked` · `sharedTimer` | `LOCKED` · `GLOBAL` | Пункты нельзя выбрать; один отсчёт на всех. |
@@ -333,14 +365,24 @@ INI — формат, который читают и Pawn-плагины, поэ
 
 ### В редакторе
 
-Расширение amxts для VS Code проверяет файл меню прямо при наборе — теми же проверками и теми же словами — и подсказывает ключи и имена, которые регистрируют ваши плагины (TypeScript, Pawn и установленные модули), с подсказкой при наведении и переходом к регистрации. Имя, добавленное в плагине, сразу появляется в подсказках файла меню, ещё до сохранения плагина. В Marketplace его пока нет: установите `.vsix` командой `code --install-extension amxts-vscode-<версия>.vsix`.
+Расширение amxts для VS Code проверяет файл меню прямо при наборе — теми же проверками и теми же словами — и подсказывает ключи и имена, которые регистрируют ваши плагины (TypeScript, Pawn и установленные модули), с подсказкой при наведении и переходом к регистрации. Имя, добавленное в плагине, сразу появляется в подсказках файла меню, ещё до сохранения плагина. Оно ставится из своего `.vsix` — командой `code --install-extension amxts-vscode-<версия>.vsix`.
 
 > [!WARNING]
 > Расширение знает только имена, записанные строкой в рабочей области: `menus.addAction(name, ...)` с именем в переменной и имя, которое регистрирует только плагин на Pawn на сервере, — предупреждение в редакторе. В счёт идёт проверка сервера на его первом кадре.
 
 ## Pawn-плагины
 
-Pawn-плагины работают с Menu Core через 30 нативов `mc_*` из `menu_core.inc`, который лежит в пакете в `include/`; собранные `.amxx`-плагины работают без изменений. В `plugins.ini` он встаёт на место `menu_core.amxx`. Когда модулем не пользуется ни один плагин проекта на TypeScript, `pawn: ["@amxts/menu-core"]` в `amxts.config.ts` оставляет его в сборке для них. Подробности — в [PAWN.ru.md](PAWN.ru.md).
+Pawn-плагин тоже создаёт, наполняет и показывает меню через Menu Core — 30 нативами, имена которых начинаются с `mc_`: `mc_register_action`, `mc_show_menu`, `mc_add_menu_item` и остальные. Их include лежит в пакете в `include/`:
+
+```pawn
+#include <menu_core>
+```
+
+Pawn-плагин, уже собранный с этим include, работает как есть — пересобирать ничего не нужно.
+
+Отдавать эти нативы на сервере может только один плагин: если в `plugins.ini` есть другой Pawn-плагин с нативами `mc_*`, закомментируйте его.
+
+Menu Core работает на сервере как один из плагинов проекта. Если им не пользуется ни один плагин проекта на TypeScript, оставьте его в сборке для Pawn-плагинов: `pawn: ["@amxts/menu-core"]` в `amxts.config.ts`. Все нативы с сигнатурами — в [PAWN.ru.md](PAWN.ru.md).
 
 ## Тесты
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@amxts/menu-core",
 	"type": "module",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Menus for amxts plugins, from ini files or code: conditions, placeholders, lists - and the mc_* natives for Pawn plugins.",
 	"author": {
 		"name": "kukson777",
@@ -49,8 +49,8 @@
 		"lint:fix": "oxfmt && oxlint --fix --silent || oxlint --fix --silent || oxlint --fix"
 	},
 	"peerDependencies": {
-		"@amxts/config-core": "^0.1.0",
-		"@amxts/core": "^0.1.0"
+		"@amxts/config-core": "^0.1.1",
+		"@amxts/core": "^0.2.0"
 	},
 	"devDependencies": {
 		"@e18e/eslint-plugin": "^0.8.1",