Merge branch 'master' into feature/placeholders

Author: ArKaNeMaN

.opencode/plugin/amxb-skills.js

@@ -0,0 +1,28 @@
+// Bridge: exposes amxb (amxx-builder) skills to opencode from three sources:
+//   1. builder-bundled skills, via "amxb skills-dir"
+//   2. the current project's own "skills:" from amxbuild.yml
+//   3. deps/repos skills read from their manifests; missing ones are fetched
+//      from the network on demand ("amxb opencode-skills")
+// No machine-specific paths are stored in opencode.json: amxb resolves its own
+// install and cache directories at every opencode start, like the MCP entry does.
+import { execSync } from "node:child_process";
+
+export default async function amxbSkills() {
+  return {
+    config(cfg) {
+      cfg.skills = cfg.skills || {};
+      cfg.skills.paths = cfg.skills.paths || [];
+      const exe = process.platform === "win32" ? "amxb.cmd" : "amxb";
+      const add = (p) => {
+        if (p && !cfg.skills.paths.includes(p)) cfg.skills.paths.push(p);
+      };
+      try {
+        add(execSync(exe + " skills-dir", { encoding: "utf8" }).trim());
+      } catch {}
+      try {
+        const out = execSync(exe + " opencode-skills", { encoding: "utf8", timeout: 180000 });
+        for (const line of out.split("\n")) add(line.trim());
+      } catch {}
+    },
+  };
+}

amxbuild.yml

@@ -4,3 +4,44 @@ name: ParamsController
 
 amxmodx:
   version: "1.10.5428"
+
+skills:
+  - dir: skills/param-types
+    name: ParamsController param types
+    description: >-
+      Встроенные типы параметров ParamsController: допустимые JSON-значения,
+      что попадает в Trie, теги и геттер чтения для каждого типа. Только
+      специфика типов; общие механизмы контроллера здесь не описаны. Покрывает
+      Boolean, Integer, Float, ShortString, String, LongString, RGB, Model,
+      PlayerModel, Sound, Resource, File, Dir, ChatMessage, Flags, Time,
+      TimeInterval, WeekDay, Regexp.
+  - dir: skills/param-types-authoring
+    name: Plugin param types skill authoring
+    description: >-
+      Мета-скилл: как агенту описать скилл с типами параметров, которые плагин
+      регистрирует сам через ParamsController (ParamsController_OnRegisterTypes,
+      ParamsController_RegSimpleType, ParamsController_ParamType_Register).
+      Процедура поиска регистраций и хелперов чтения (своих у плагина или
+      стандартных PCGet_*/PCSingle_*), чтения колбеков, выписки контракта типа
+      (JSON-форматы, результат в Trie, теги, условия ошибки, прекеш) и сборки
+      составного скилла SKILL.md + references (включая групповые _<группа>.md)
+      с записью в skills: манифеста. Только про типы.
+  - dir: skills/param-type-registration
+    name: Param type registration
+    description: >-
+      Как плагину зарегистрировать собственный тип параметра в ParamsController:
+      ParamsController_OnRegisterTypes, ParamsController_RegSimpleType /
+      ParamsController_ParamType_Register + SetReadCallback, контракт колбека
+      чтения, запись значения в Trie, теги, условия ошибки, а также создание
+      хелперов чтения PCSingle_*/PCGet_* для своего типа. Триггеры: register
+      param type, custom param type, ParamsController_OnRegisterTypes,
+      PCSingle, PCGet helper.
+  - dir: skills/params-usage
+    name: Params usage
+    description: >-
+      Как читать параметры ParamsController в коде плагина: PCSingle_* как обёртки
+      над json_* для одиночных значений, регистрация параметров сущностей
+      (Param_Construct + Param_ReadList + PCGet_*), приём наборов через нативы
+      (ParamsController_Param_ListFromNativeParams, PCParam/PCParams). Триггеры:
+      PCSingle, PCGet, ParamsController_Param_Construct, Param_ReadList,
+      PCParam, consume params.

amxmodx/scripting/ParamsController/Objects/Param.inc

@@ -130,6 +130,16 @@ Trie:Param_ReadList(
             continue;
         }
 
+        if (paramObject[Param_IsUnknownType]) {
+            if (paramObject[Param_Required]) {
+                iErrType = ParamsReadError_UnknownParamType;
+                return p;
+            }
+
+            PCJson_LogForFile(objectJson, "WARNING", "Param '%s' has unknown type '%s', skipping.", paramObject[Param_Key], paramObject[Param_Tag]);
+            continue;
+        }
+
         if (!json_object_has_value(objectJson, paramObject[Param_Key])) {
             if (paramObject[Param_Required]) {
                 errType = ParamsReadError_RequiredParamNotPresented;

skills/param-type-registration/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: param-type-registration
+description: >-
+  Как плагину зарегистрировать собственный тип параметра в ParamsController (AMXX):
+  форвард ParamsController_OnRegisterTypes, ParamsController_RegSimpleType /
+  ParamsController_ParamType_Register + ParamsController_ParamType_SetReadCallback,
+  контракт колбека чтения bool:(const JSON, const Trie, const key[], const tag[]),
+  запись значения (ParamsController_SetCell/SetString или Trie напрямую), теги,
+  условия ошибки, а также создание хелперов чтения PCSingle_*/PCGet_* для своего
+  типа. Использовать, когда плагин добавляет свой тип параметра.
+  Триггеры: регистрация типа параметра, custom param type,
+  ParamsController_OnRegisterTypes, ParamsController_RegSimpleType,
+  ParamsController_ParamType_Register, PCSingle helper, PCGet helper,
+  read callback, register parameter type.
+  Use when a plugin adds its own ParamsController parameter type.
+---
+
+# Регистрация своих типов параметров
+
+Как плагину добавить **собственный тип** параметра в ParamsController: объявить
+имя типа, повесить на него функцию чтения и записывать результат в `Trie`.
+
+Встроенные типы (`Boolean`, `Integer`, `Model`, …) уже зарегистрированы — их
+описывать не надо. Здесь — про свои.
+
+## Когда применять
+
+- плагину нужен нестандартный формат значения параметра;
+- нужно, чтобы конфиг плагина понимал свой тип.
+
+Если нужен просто доступ к JSON без параметра — это другой скилл
+(`params-usage`, `PCSingle_*`), регистрировать тип не обязательно.
+
+## Коротко
+
+1. `ParamsController_Init()` в `plugin_init()` — инициализация контроллера.
+2. В `public ParamsController_OnRegisterTypes()` зарегистрировать тип:
+   - `ParamsController_RegSimpleType("MyType", "@OnReadMyType")` — обычный путь;
+   - либо `ParamsController_ParamType_Register("MyType")` +
+     `ParamsController_ParamType_SetReadCallback(iType, "@OnReadMyType")`.
+3. Написать колбек `bool:@OnReadMyType(const JSON:jValue, const Trie:tParams,
+   const sParamKey[], const sParamTag[])`, который разбирает `jValue`, пишет
+   результат в `tParams` и возвращает `true`/`false`.
+
+## Детали
+
+- `references/registration.md` — способы регистрации, тайминг, ограничения.
+- `references/read-callback.md` — контракт колбека, запись значения, теги, ошибки.
+- `references/helpers.md` — как написать свои хелперы `PCSingle_*` / `PCGet_*`.
+- `references/examples.md` — полный пример плагина.
+
+## Ключевые правила
+
+- Регистрировать типы — строго в `ParamsController_OnRegisterTypes`.
+- Пока `ParamsController_Init()` не вызван, любой вызов API аварийно падает.
+- Колбек **обязан** записать значение в `Trie` — иначе контроллер сообщит об ошибке.
+- `return false` = «значение невалидно для этого типа».
+- Тег (`Тип:тег`) приходит в колбек четвёртым аргументом.
+- К типу по конвенции пишутся хелперы `PCSingle_*` / `PCGet_*` (см. `helpers.md`) —
+  чтобы потребитель читал значение единообразно с встроенными типами.

skills/param-type-registration/references/examples.md

@@ -0,0 +1,60 @@
+# Пример: свои типы
+
+Полный плагин с двумя типами: скаляр `Percent` и `Duration` с тегом `minutes`.
+
+```pawn
+#include <amxmodx>
+#include <json>
+#include <ParamsController>
+
+public plugin_init() {
+    ParamsController_Init();
+}
+
+public ParamsController_OnRegisterTypes() {
+    ParamsController_RegSimpleType("Percent", "@OnReadPercent");
+    ParamsController_RegSimpleType("Duration", "@OnReadDuration");
+}
+
+// Число 0..100.
+bool:@OnReadPercent(const JSON:jValue, const Trie:tParams, const sParamKey[]) {
+    if (!json_is_number(jValue)) {
+        return false;
+    }
+
+    new value = json_get_number(jValue);
+    if (value < 0 || value > 100) {
+        return false;
+    }
+
+    return ParamsController_SetCell(value);
+}
+
+// Число; тег "minutes" трактует его как минуты.
+bool:@OnReadDuration(const JSON:jValue, const Trie:tParams, const sParamKey[], const sParamTag[]) {
+    if (!json_is_number(jValue)) {
+        return false;
+    }
+
+    new value = json_get_number(jValue);
+    if (equali(sParamTag, "minutes")) {
+        value *= 60;
+    }
+
+    return ParamsController_SetCell(value);
+}
+```
+
+Использование в параметрах:
+
+```pawn
+ParamsController_Param_Construct("Chance", "Percent", true);
+ParamsController_Param_Construct("KickTime", "Duration:minutes", true);
+```
+
+## Что тут важно
+
+- оба типа зарегистрированы в `ParamsController_OnRegisterTypes`;
+- оба колбека записывают значение и возвращают `bool`;
+- `Percent` пишет ячейку, `Duration` учитывает тег;
+- `ParamsController_Init()` вызван до любого использования API.

skills/param-type-registration/references/helpers.md

@@ -0,0 +1,79 @@
+# Хелперы для своего типа (`PCSingle_*` / `PCGet_*`)
+
+Для работы типа контроллеру достаточно колбека чтения. Но по конвенции к типу
+пишут пару хелперов-обёрток, чтобы потребителю было удобно читать значение — как
+у встроенных типов:
+
+- `PCSingle_*` — прочитать **одно** значение типа прямо из JSON, без параметра;
+- `PCGet_*` — прочитать готовое значение из **результата** (`Trie`).
+
+## Процесс
+
+1. **Определи вид значения.** Что колбек пишет в `Trie`: число/`cell` или строку.
+   Для хендлеров (напр. `Regex`) — тоже `cell`, с приведением типа.
+2. **`PCSingle_*`** (сырое значение) — обёртка над `PCSingle_Cell` (число) или
+   `PCSingle_Str` (строка).
+3. **`PCSingle_Obj*`** (из объекта по ключу) — обёртка над `PCSingle_ObjCell` /
+   `PCSingle_ObjStr`; принимает `key`, `dotNot`, `orFail`.
+4. **`PCGet_*`** (из результата) — обёртка над `PCGet_Cell` / `PCGet_Str`; для
+   строки добавь `i`-вариант.
+5. **Положи хелперы в публичный `.inc` плагина**, если API типа доступно другим
+   плагинам.
+
+## Числовое значение
+
+```pawn
+// из сырого значения
+stock any:PCSingle_MyType(const JSON:valueJson, const any:def = 0, const orFailKey[] = "") {
+    return PCSingle_Cell(valueJson, "MyType", def, orFailKey);
+}
+
+// из поля объекта по ключу
+stock any:PCSingle_ObjMyType(const JSON:objectJson, const key[], const any:def = 0, const bool:dotNot = false, const bool:orFail = false) {
+    return PCSingle_ObjCell(objectJson, key, "MyType", def, dotNot, orFail);
+}
+
+// из результата
+stock any:PCGet_MyType(const Trie:p, const key[], const any:def = 0) {
+    return PCGet_Cell(p, key, def);
+}
+```
+
+## Строковое значение
+
+```pawn
+stock PCSingle_MyStr(const JSON:valueJson, out[], const outLen, const def[] = "", const orFailKey[] = "") {
+    return PCSingle_Str(valueJson, "MyType", out, outLen, def, orFailKey);
+}
+
+stock PCSingle_iMyStr(const JSON:valueJson, const def[] = "", const orFailKey[] = "") {
+    new out[PARAM_VALUE_MAX_LEN];
+    PCSingle_Str(valueJson, "MyType", out, charsmax(out), def, orFailKey);
+    return out;
+}
+
+stock PCSingle_ObjMyStr(const JSON:objectJson, const key[], out[], const outLen, const def[] = "", const bool:dotNot = false, const bool:orFail = false) {
+    return PCSingle_ObjStr(objectJson, key, "MyType", out, outLen, def, dotNot, orFail);
+}
+
+stock PCGet_MyStr(const Trie:p, const key[], out[], const outLen, const def[] = "") {
+    return PCGet_Str(p, key, out, outLen, def);
+}
+
+stock PCGet_iMyStr(const Trie:p, const key[], const def[] = "") {
+    return PCGet_iStr(p, key, def);
+}
+```
+
+## Соглашение об именах
+
+- `..._Obj...` — значение из **объекта** по ключу; без `Obj` — из **сырого** значения;
+- `i`-префикс — возвращает временную строку;
+- внутри указывается **имя своего типа** строкой (`"MyType"`).
+
+## Замечания
+
+- Хелперы **не обязательны** для работы типа — это удобство и единый стиль.
+- `stock` компилируется только при использовании, поэтому держать их в `.inc` дёшево.
+- Свои хелперы стоит задокументировать в скилле типов плагина — см. скилл
+  `param-types-authoring`.

skills/param-type-registration/references/read-callback.md

@@ -0,0 +1,70 @@
+# Колбек чтения типа
+
+Функция, которая разбирает JSON-значение параметра и пишет результат в `Trie`.
+
+## Сигнатура
+
+```pawn
+bool:@OnReadMyType(const JSON:jValue, const Trie:tParams, const sParamKey[], const sParamTag[])
+```
+
+| Аргумент | Что это |
+|---|---|
+| `jValue` | JSON-значение параметра (то, что пришло из конфига) |
+| `tParams` | гарантированно валидный `Trie`, куда писать результат |
+| `sParamKey` | ключ параметра — под ним нужно записать значение |
+| `sParamTag` | тег после `:` в имени типа (`Тип:тег`), иначе пусто |
+
+## Возврат
+
+- `true` — значение прочитано и записано;
+- `false` — значение некорректно для этого типа (параметр считается невалидным).
+
+## Запись результата
+
+Три способа:
+
+1. `ParamsController_SetCell(value)` — число / float / bool / хендлер;
+2. `ParamsController_SetString(str)` — строка (до 4096 ячеек);
+3. напрямую в `tParams` по `sParamKey`: `TrieSetCell`, `TrieSetString`,
+   `TrieSetArray`.
+
+`SetCell` / `SetString` работают **только внутри колбека чтения** (иначе аварийное
+завершение `Attempt to set param value outside the read callback.`) и не требуют
+ключа — контроллер знает текущий параметр.
+
+> Колбек **обязан** записать значение под своим ключом. Если вернуть `true`, ничего
+> не записав, контроллер сообщит об ошибке вида «тип не пишет значение в trie».
+
+## Разбор входа
+
+- `json_get_type(jValue)` → `JSONNumber` / `JSONString` / `JSONBoolean` /
+  `JSONArray` / `JSONObject` / `JSONNull`;
+- `json_is_array` / `json_is_object` / `json_is_string` / `json_is_number` / `json_is_bool`;
+- `json_get_number` / `json_get_real` / `json_get_bool` / `json_get_string`;
+- массивы/объекты: `json_array_get_count`, `json_array_get_number`,
+  `json_object_has_value`, `json_object_get_number` и т.п.
+
+## Теги
+
+Тег приходит в `sParamTag`; пустой тег (`sParamTag[0] == EOS`) — обычный режим.
+
+```pawn
+bool:@OnReadDuration(const JSON:jValue, const Trie:tParams, const sParamKey[], const sParamTag[]) {
+    new value = json_get_number(jValue);
+    if (equali(sParamTag, "minutes")) {
+        value *= 60;
+    }
+    return ParamsController_SetCell(value);
+}
+```
+
+Такой тип объявляется как `Duration` или `Duration:minutes`.
+
+## Ошибки и мягкие преобразования
+
+- Всё, что не должно приниматься, — `return false`.
+- Осторожно с `str_to_num` / `str_to_float`: нечисловая строка даёт `0` **без**
+  ошибки. Если «мусор» должен быть ошибкой — проверяйте вручную
+  (`json_get_type`, `is_strnum` и т.п.).
+- Некорректный вход можно залогировать: `PCJson_LogForFile(jValue, "WARNING", "...")`.