vimp-engine 0.23.0 → 0.24.0

package/bin/vimp-surface.js

@@ -44,7 +44,7 @@ async function main(argv) {
 
   try {
     committed = JSON.parse(await readFile(SURFACE_PATH, 'utf8'));
-  } catch (err) {
+  } catch {
     process.stderr.write(
       `surface: no snapshot at ${SURFACE_PATH} — run ` +
         '`npm run surface:update` to create it\n',

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vimp-engine-core"
-version = "0.9.0"
+version = "0.9.1"
 edition = "2024"
 description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/client/lib/formBuilder.js

@@ -1,16 +1,23 @@
 import { anchorPattern } from '../../lib/formPattern.js';
 import { normalizeOptions } from '../../lib/formOptions.js';
 import { resolveDescriptor } from '../../lib/formControls.js';
+import { toDisplay, toStored, isNumericField } from '../../lib/formUnit.js';
 
 // Общий билдер полей форм (room-форма и auth-форма используют один
 // контракт дескрипторов — docs/en/plugin-api.md, раздел "Form schema").
 // control: 'select'|'text'|'checkbox'|'radio'; все контролы — нативные
-// элементы формы, без визуальной кастомизации. Имя контрола приезжает от
-// игры и разрешается через append-only реестр (lib/formControls.js): имена,
-// выведенные из эксплуатации в v3 ('range', 'number', 'toggle',
-// 'segmented'), продолжают строиться алиасами своих нативных замен (И1). Валидация — не нативная
-// (никаких браузерных попапов): collectFormErrors/renderFormErrors ниже
-// собирают и рисуют ошибки в разметку (#lobby-error/#auth-error).
+// элементы формы, без визуальной кастомизации.
+//
+// Имя контрола приезжает от игры и разрешается через append-only реестр
+// (lib/formControls.js): имена, выведенные из эксплуатации в v3 ('range',
+// 'number', 'toggle', 'segmented'), продолжают строиться алиасами своих
+// нативных замен (И1). Тот же резолв обязана делать авторитетная валидация
+// хоста (lib/validators.js) — иначе поле строится одним контролом, а
+// проверяется как другой.
+//
+// Валидация — не нативная (никаких браузерных попапов):
+// collectFormErrors/renderFormErrors ниже собирают и рисуют ошибки в
+// разметку (#lobby-error/#auth-error).
 // Проверяются только поля, у которых есть строка в DOM: ошибка на скрытом
 // поле игроку не видна и исправить её нечем — она просто запирает форму.
 
@@ -18,12 +25,6 @@ import { resolveDescriptor } from '../../lib/formControls.js';
 // resolveForcedValue не расходился с builders при добавлении нового
 const OPTION_CONTROLS = ['select', 'radio'];
 
-// числовое text-поле: unit задан или numeric:true. Правило одно на билдер и
-// на валидацию, поэтому живёт в одном месте
-function isNumeric(descriptor) {
-  return descriptor.numeric === true || descriptor.unit !== undefined;
-}
-
 // 'source' — спец-источник вариантов из каталога движка (например карты),
 // прокидывается вызывающей стороной через ctx.sources
 function resolveOptions(descriptor, ctx) {
@@ -63,15 +64,6 @@ export function resolveForcedValue(descriptor, ctx = {}) {
   return forced === undefined ? undefined : String(forced);
 }
 
-// unit:'s' — значение хранится в мс, показывается/редактируется в секундах
-function toDisplay(descriptor, value) {
-  return descriptor.unit === 's' ? value / 1000 : value;
-}
-
-function toStored(descriptor, value) {
-  return descriptor.unit === 's' ? value * 1000 : value;
-}
-
 function buildSelect(descriptor, ctx) {
   const el = document.createElement('select');
   const options = resolveOptions(descriptor, ctx);
@@ -116,7 +108,7 @@ function buildSelect(descriptor, ctx) {
 // вместо превращения его в 0 на сабмите
 function buildText(descriptor) {
   const el = document.createElement('input');
-  const numeric = isNumeric(descriptor);
+  const numeric = isNumericField(descriptor);
 
   el.type = 'text';
   // выпадашка прошлых значений/автозаполнения кроет форму, а подставить в
@@ -386,7 +378,7 @@ function validateField(descriptor, field) {
   const isEmpty = isText
     ? raw === ''
     : value === undefined || value === null || value === '';
-  const numeric = isText && isNumeric(descriptor);
+  const numeric = isText && isNumericField(descriptor);
 
   // числовое поле всегда несёт число и «необязательным» быть не может:
   // пустой ввод getValue() подменяет default'ом (чтобы не уехал нолём), и

package/src/client/lib/pickActiveGame.js

@@ -0,0 +1,59 @@
+// Выбор активной игры из каталога мастера. Вынесено из client/main.js по той
+// же причине, что и socketDispatch.js: main.js исполняется при импорте, и
+// проверить ветвление внутри него нечем.
+//
+// Недоступная игра (manifest.compat.ok === false, этап 5 плана
+// plugin-forward-compat) в СПИСОК лобби попадает — с причиной, — но активной
+// быть не может: её плагин не загрузится, и вкладка встала бы на первой же
+// игре каталога.
+
+/**
+ * Доступна ли игра. Поле `compat` появляется у манифеста каталога мастера,
+ * только когда игра просит возможность, которой в этой сборке движка нет;
+ * манифест без него (все опубликованные до этапа 5) доступен по определению.
+ * @param {Object} manifest - GameManifest из каталога мастера.
+ * @returns {boolean}
+ */
+export function isGameAvailable(manifest) {
+  return manifest.compat?.ok !== false;
+}
+
+/**
+ * Активная игра вкладки.
+ *
+ * Обе ветки фильтруются одинаково: сохранённый выбор игры (`gameId`) тоже мог
+ * указывать на игру, ставшую недоступной после обновления движка, и брать её
+ * «раз уж попросили» значило бы падать там, где можно объяснить.
+ * @param {Array<Object>} manifests - Каталог мастера.
+ * @param {string} [gameId] - Сохранённый выбор игры (boot.gameId).
+ * @returns {Object|undefined} Манифест активной игры.
+ * @throws {Error} Если каталог непустой, но играбельной игры в нём нет —
+ *   с причиной по каждой строке.
+ */
+export function pickActiveGame(manifests, gameId) {
+  const active = gameId
+    ? manifests.find(
+        manifest => manifest.id === gameId && isGameAvailable(manifest),
+      )
+    : manifests.find(isGameAvailable);
+
+  if (active) {
+    return active;
+  }
+
+  // непустой каталог без единой играбельной строки — сказать это одной
+  // понятной фразой, а не отдать наверх первую попавшуюся и упасть в
+  // loadClientPlugin непрозрачной ошибкой
+  if (manifests.length) {
+    throw new Error(
+      'no playable game in the lobby catalog: ' +
+        manifests
+          .map(manifest => manifest.compat?.text ?? `"${manifest.id}"`)
+          .join('; '),
+    );
+  }
+
+  return undefined;
+}
+
+export default pickActiveGame;

package/src/client/main.js

@@ -26,7 +26,11 @@ import StatCtrl from './components/controller/Stat.js';
 import VoteModel from './components/model/Vote.js';
 import VoteView from './components/view/Vote.js';
 import VoteCtrl from './components/controller/Vote.js';
-import { buildForm, mergeRoomDefaults, bindLiveErrors } from './lib/formBuilder.js';
+import {
+  buildForm,
+  mergeRoomDefaults,
+  bindLiveErrors,
+} from './lib/formBuilder.js';
 import { normalizeAuthParams } from './lib/authParams.js';
 import { renderProjectLink } from './lib/footerLink.js';
 import { createGameActivator } from './lib/gameActivator.js';
@@ -37,6 +41,9 @@ import { createContextTracker } from './lib/contextTracker.js';
 import { createLocalPlayer } from './lib/localPlayer.js';
 import { createAccolades } from './lib/accolades.js';
 import { dispatchSocketMessage } from './lib/socketDispatch.js';
+import { pickActiveGame, isGameAvailable } from './lib/pickActiveGame.js';
+import { readCoreAbi, dispatchCoreOp, ABI_UNKNOWN } from '../lib/coreAbi.js';
+import { ABI_OP_DEBUG_JSON } from '../config/abiOps.js';
 import { createDebugApi, debugLog, DEBUG_PREFIX } from './debug.js';
 import { buildClientCoreConfig } from '../lib/clientCoreConfig.js';
 import {
@@ -110,13 +117,6 @@ function bindActiveGame(manifest, plugin) {
   gameStyleNode.textContent = plugin.styles ?? '';
 }
 
-// поле `compat` появляется у манифеста каталога мастера, только когда игра
-// просит возможность, которой в этой сборке движка нет; манифест без него
-// (все опубликованные до этапа 5) доступен по определению
-function isGameAvailable(manifest) {
-  return manifest.compat?.ok !== false;
-}
-
 // режим загрузки (Этап 2 плана standalone-sdk): lobby — прод с мастером,
 // solo — хост в этой же вкладке (standalone SDK), dedicated — прямой WS к
 // Node-серверу. Ветвлений ровно пять: манифест, сигналинг/лобби, транспорт,
@@ -154,13 +154,8 @@ try {
       throw gamesManifest;
     }
 
-    // недоступная игра (manifest.compat.ok === false, этап 5 плана
-    // plugin-forward-compat) не годится в активные: её плагин не загрузится,
-    // и вкладка встала бы на первой же игре каталога. В список лобби она
-    // при этом попадает — с причиной
-    activeGameManifest = boot.gameId
-      ? gamesManifest.find(manifest => manifest.id === boot.gameId)
-      : (gamesManifest.find(isGameAvailable) ?? gamesManifest[0]);
+    // недоступная игра активной быть не может (lib/pickActiveGame.js)
+    activeGameManifest = pickActiveGame(gamesManifest, boot.gameId);
   }
 
   if (!activeGameManifest) {
@@ -294,7 +289,7 @@ let wasm = null;
 // читаются один раз при создании ядра, а не в момент вызова. Ядро старше
 // самоописания даёт поколение 0 с пустым списком опкодов: это не ошибка,
 // а игра, собранная до появления механизма (И2 плана plugin-forward-compat)
-let clientCoreAbi = { abi: 0, core: null, ops: [] };
+let clientCoreAbi = ABI_UNKNOWN;
 
 // сервис пула зависимостей: «эта сущность моя или чужая?». Ядро читается
 // геттером — оно создаётся позже пула сервисов (см. lib/localPlayer.js)
@@ -330,10 +325,7 @@ socketMethods[PS_CONFIG_DATA] = async data => {
 
   clientCore = core;
   wasm = { memory };
-  clientCoreAbi =
-    typeof core.abi_describe === 'function'
-      ? JSON.parse(core.abi_describe())
-      : { abi: 0, core: null, ops: [] };
+  clientCoreAbi = readCoreAbi(core, 'client core');
 
   // инициализация сущностей игры
   for (const entity of Object.keys(entitiesOnCanvas)) {
@@ -1152,8 +1144,7 @@ const RESYNC_AFTER_HIDDEN_MS = 3000;
 
 // вкладка могла быть скрыта уже в момент навешивания слушателя — события
 // 'hidden' тогда не будет, а пауза всё равно идёт
-let hiddenAt =
-  document.visibilityState === 'hidden' ? performance.now() : null;
+let hiddenAt = document.visibilityState === 'hidden' ? performance.now() : null;
 
 // обработчик видимости вкладки
 function handleVisibilityChange() {
@@ -1199,18 +1190,22 @@ function handleVisibilityChange() {
 
 // дамп клиентского ядра: сначала опкод dispatch, затем замороженный метод.
 // Метод не удаляется никогда (И1), поэтому запасной путь остаётся навсегда:
-// ядро, собранное до появления dispatch, отдаёт дамп по-старому
+// ядро, собранное до появления dispatch, отдаёт дамп по-старому.
+// dispatchCoreOp — та же точка вызова, что у хостового GameCoreAdapter._op:
+// имя опкода читается из реестра, три исхода ответа различимы
 function clientCoreDebug() {
   if (!clientCore) {
     return undefined;
   }
 
-  if (clientCoreAbi.ops.includes('debug.json')) {
-    const out = clientCore.dispatch('debug.json', new Uint8Array(0));
+  const { handled, bytes } = dispatchCoreOp(
+    clientCore,
+    clientCoreAbi,
+    ABI_OP_DEBUG_JSON,
+  );
 
-    if (out.length > 0) {
-      return new TextDecoder().decode(out);
-    }
+  if (handled && bytes !== null) {
+    return new TextDecoder().decode(bytes);
   }
 
   return clientCore.debug_json?.();
@@ -1413,7 +1408,9 @@ if (isDevBuild) {
     reportUrl: lobbyConfig.debugReportUrl,
   });
 
-  debugLog('window.__vimpDebug is available: dump, startRecording, stopRecording, divergence');
+  debugLog(
+    'window.__vimpDebug is available: dump, startRecording, stopRecording, divergence',
+  );
 }
 
 // WebRTC обязателен для P2P-игры. В Firefox RTCPeerConnection может
@@ -1944,7 +1941,9 @@ function populateRoomForm(manifest) {
 
 // каталог манифестов по id: форма и leaderboard селектора игр, а также
 // активация игры перед созданием комнаты и входом в чужую
-const gamesById = new Map(gamesManifest.map(manifest => [manifest.id, manifest]));
+const gamesById = new Map(
+  gamesManifest.map(manifest => [manifest.id, manifest]),
+);
 
 // ClientPlugin выбранной игры грузится в момент клика (создание комнаты /
 // вход в комнату), а не при смене селектора: просмотр каталога не должен

package/src/config/abiOps.js

@@ -28,4 +28,10 @@ export const abiOps = createRegistry('abiOps', [
 // плоский список активных опкодов — то, что вправе позвать движок
 export const ABI_OPS = abiOps.values();
 
+// Именованные константы вместо литералов в местах вызова: строка 'debug.json',
+// написанная руками у хоста и у клиента, обходила бы реестр молча — новый
+// опкод уехал бы в прод, не попав ни в слепок поверхности, ни в
+// CHANGELOG. Имя опкода читается ТОЛЬКО отсюда.
+export const ABI_OP_DEBUG_JSON = 'debug.json';
+
 export default abiOps;

package/src/devtools/contract/rules/b2-engine-api.js

@@ -1,5 +1,8 @@
-import { ERROR, skip, verdict } from '../result.js';
-import { CAPABILITIES } from '../../../lib/capabilities.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
+import {
+  ENGINE_CAPABILITIES,
+  CAPABILITIES,
+} from '../../../lib/capabilities.js';
 
 // `engineApi` живёт в трёх местах (манифест, HostPlugin, ClientPlugin).
 // Расхождение между ними — рассинхрон сборки внутри пакета, и это ошибка.
@@ -34,6 +37,7 @@ export default {
     }
 
     const violations = [];
+    const retired = [];
     const [source, reference] = declared[0];
 
     for (const [where, value] of declared) {
@@ -56,15 +60,59 @@ export default {
       }
     }
 
-    for (const name of ctx.manifest?.requires ?? []) {
-      if (!CAPABILITIES.includes(name)) {
+    // форма `requires` — то же недоверие, что в checkPluginCompatibility:
+    // строка проитерировалась бы здесь посимвольно, объект уронил бы чекер
+    // «not iterable»
+    const requires = ctx.manifest?.requires;
+
+    if (requires === undefined || requires === null) {
+      return finish(violations, retired);
+    }
+
+    if (
+      !Array.isArray(requires) ||
+      requires.some(name => typeof name !== 'string')
+    ) {
+      violations.push(
+        'manifest.requires must be an array of capability names, got ' +
+          `${JSON.stringify(requires)} — the engine reads it before it ` +
+          'loads the plugin',
+      );
+
+      return finish(violations, retired);
+    }
+
+    for (const name of requires) {
+      // has, а не CAPABILITIES.includes: реестр возможностей append-only,
+      // и выведенное алиасом имя движок принимает вечно (ENGINE_CAPABILITIES.
+      // has в checkPluginCompatibility). Сверка с одними активными именами
+      // отвергала бы игру за то, что движок переименовал возможность — тот
+      // самый отказ по возрасту, который план и снимал
+      if (!ENGINE_CAPABILITIES.has(name)) {
         violations.push(
           `manifest.requires names '${name}', which this engine does not ` +
             `provide — known capabilities: ${CAPABILITIES.join(', ')}`,
         );
+      } else if (ENGINE_CAPABILITIES.isRetired(name)) {
+        retired.push(
+          `manifest.requires names '${name}', which was retired — it still ` +
+            `works (the engine resolves it to ` +
+            `'${ENGINE_CAPABILITIES.resolve(name)}' forever), but a new game ` +
+            `should declare '${ENGINE_CAPABILITIES.resolve(name)}' itself`,
+        );
       }
     }
 
-    return verdict(violations);
+    return finish(violations, retired);
   },
 };
+
+// то же, что делают B5 и C10: выведенное имя — не отказ, а предупреждение.
+// Отвергать за него значило бы отвергать игру за возраст (И1)
+function finish(violations, retired) {
+  if (violations.length === 0 && retired.length > 0) {
+    return verdict(retired, 'retired capability names still resolve', WARN);
+  }
+
+  return verdict(violations);
+}

package/src/devtools/contract/rules/c10-auth-schema.js

@@ -1,5 +1,9 @@
-import { ERROR, skip, verdict } from '../result.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 import { resolveValidator } from '../../../lib/validators.js';
+import {
+  formControls,
+  ACTIVE_FORM_CONTROLS,
+} from '../../../lib/formControls.js';
 
 // authSchema. Четыре ошибки, каждая из которых уже случалась:
 // formId вместо fieldsId (контейнер резолвится в null и экран авторизации
@@ -24,6 +28,7 @@ export default {
 
     const { elems = {}, params = [] } = ctx.authSchema;
     const violations = [];
+    const retired = [];
 
     if (elems.formId !== undefined) {
       violations.push(
@@ -48,6 +53,24 @@ export default {
         );
       }
 
+      const control = field.options?.control;
+
+      if (control !== undefined && !formControls.has(control)) {
+        violations.push(
+          `authSchema param "${field.name}": control "${control}" does not ` +
+            `exist (${ACTIVE_FORM_CONTROLS.join(', ')}) — the form throws ` +
+            "'unknown control' and the auth screen never renders",
+        );
+      } else if (control !== undefined && formControls.isRetired(control)) {
+        retired.push(
+          `authSchema param "${field.name}": control "${control}" was ` +
+            `retired in plugin API v${formControls.get(control).retiredIn} — ` +
+            `it still works (the engine builds and validates it as ` +
+            `"${formControls.resolve(control)}" forever), but a new game ` +
+            `should declare "${formControls.resolve(control)}" itself`,
+        );
+      }
+
       const validatorName = field.options?.validator;
 
       // опечатка в имени (как и не-функция под верным именем) = поле не
@@ -73,6 +96,16 @@ export default {
       );
     }
 
+    // то же, что делает B5 для roomForm: выведенный контрол — не отказ, а
+    // предупреждение, иначе правило отвергало бы игру за возраст (И1)
+    if (violations.length === 0 && retired.length > 0) {
+      return verdict(
+        retired,
+        'retired controls still build and validate, via aliases',
+        WARN,
+      );
+    }
+
     return verdict(violations);
   },
 };

package/src/host/GameCoreAdapter.js

@@ -1,3 +1,5 @@
+import { ABI_OP_DEBUG_JSON } from '../config/abiOps.js';
+import { readCoreAbi, dispatchCoreOp } from '../lib/coreAbi.js';
 // Адаптер Rust-ядра (GameCore) под интерфейс, который потребляют мета-модули
 // хоста (RoundManager, SocketManager) и host-фасад. За поверхностью Game.js
 // (+ упаковка снапшотов) стоит WASM-ядро; события ядра (take_events) несут
@@ -10,9 +12,6 @@
 // (spawn_scripted_actor/remove_scripted_actor), человек — только танк
 // (spawn_actor/remove_actor).
 
-// пустая нагрузка опкода: ядро ждёт байты всегда, даже когда их нет
-const EMPTY_PAYLOAD = new Uint8Array(0);
-
 export default class GameCoreAdapter {
   /**
    * @param {GameCore} core - экземпляр WASM-ядра.
@@ -28,14 +27,11 @@ export default class GameCoreAdapter {
     this._onCoreEvent = onCoreEvent;
     this._services = {}; // { vimp, panel } — инъекция как у Game.js
 
-    // Метода нет — ядро собрано до появления самоописания. Это не ошибка:
-    // поколение 0, ни одного опционального опкода (И2). Читается один раз
-    // здесь, а не при вызове: ветку упаковки, поле формы или ответ лобби
-    // движок выбирает заранее, а не посреди матча.
-    this._abi =
-      typeof core.abi_describe === 'function'
-        ? JSON.parse(core.abi_describe())
-        : { abi: 0, core: null, ops: [] };
+    // Метода нет (или самоописание нечитаемо) — ядро собрано до появления
+    // механизма. Это не ошибка: поколение 0, ни одного опционального опкода
+    // (И2). Читается один раз здесь, а не при вызове: ветку упаковки, поле
+    // формы или ответ лобби движок выбирает заранее, а не посреди матча.
+    this._abi = readCoreAbi(core, 'game core');
   }
 
   /**
@@ -237,10 +233,10 @@ export default class GameCoreAdapter {
    * @returns {Object|null}
    */
   debugJson() {
-    const out = this._op('debug.json');
+    const { handled, bytes } = this._op(ABI_OP_DEBUG_JSON);
 
-    if (out !== null) {
-      return JSON.parse(new TextDecoder().decode(out));
+    if (handled && bytes !== null) {
+      return JSON.parse(new TextDecoder().decode(bytes));
     }
 
     // ядро старше опкода, но с замороженным методом — метод не удаляется
@@ -257,18 +253,22 @@ export default class GameCoreAdapter {
    * ядра: прямой вызов нового метода на `this._core` запрещён (И2) — у
    * ядра, собранного год назад, его нет и не будет. ESLint стережёт это
    * правилом no-restricted-syntax.
+   *
+   * Исходов ровно три, и они РАЗЛИЧИМЫ (соглашение `abi::dispatch_result`,
+   * core/src/abi.rs): пустой ответ — «опкод не понят», маркер `[0x00]` —
+   * «понят, ответа нет», иначе — полезные байты. Схлопывать первые два в
+   * один `null` нельзя: опкод-команда (ради них механизм и делался) отдавала
+   * бы вызывающему сырой `Uint8Array [0]`, который поехал бы в TextDecoder
+   * и JSON.parse.
    * @param {string} op - Опкод из config/abiOps.js.
    * @param {Uint8Array} [payload] - Полезная нагрузка опкода.
-   * @returns {Uint8Array|null} null — ядро опкод не умеет либо не обработало.
+   * @returns {{handled: boolean, bytes: Uint8Array|null}} `handled: false` —
+   *   ядро опкода не знает (вызывающий идёт по запасному пути);
+   *   `handled: true, bytes: null` — обработано без ответа.
+   * @see lib/coreAbi.js — то же для клиентского ядра
    */
-  _op(op, payload = EMPTY_PAYLOAD) {
-    if (!this._abi.ops.includes(op)) {
-      return null;
-    }
-
-    const out = this._core.dispatch(op, payload);
-
-    return out.length === 0 ? null : out;
+  _op(op, payload) {
+    return dispatchCoreOp(this._core, this._abi, op, payload);
   }
 
   // бот ли участник (спавн/удаление в ядре различаются)

package/src/lib/applyRoomOverrides.js

@@ -8,7 +8,9 @@ import { createGameConfigView } from './gameConfigView.js';
  * @param {Object} [room] - Переопределения комнаты.
  * @param {Object} plugin - HostPlugin игры.
  * @param {Object} [view] - Готовая gameConfig-view (createHostRuntime строит
- *   её один раз на прогон); без неё собирается своя.
+ *   её один раз на прогон). Путь по умолчанию — ТЕСТОВЫЙ: он строит вторую
+ *   view, и deriveSpectatorTeam предупреждает в консоль дважды за прогон.
+ *   Прод-вызов всегда передаёт готовую.
  * @returns {Object} Конфиг матча: движковые дефолты + игровая половина.
  */
 export function applyRoomOverrides(

package/src/lib/coreAbi.js

@@ -0,0 +1,116 @@
+// Единственная точка чтения самоописания wasm-ядра (`abi_describe`).
+//
+// Фрагмент жил в трёх местах — конструкторе GameCoreAdapter и двух местах
+// client/main.js — и дефолт `{abi: 0, core: null, ops: []}` был написан
+// руками трижды: разъехавшись, они дали бы `ops === undefined` и TypeError
+// в первом же вызове опкода.
+//
+// Плюс `JSON.parse` не был обёрнут. Ядро, отдающее не-JSON, роняло
+// конструктор адаптера и (на клиенте) async-обработчик PS_CONFIG_DATA —
+// невыловленным промисом, после которого конфиг не применяется вовсе. Это
+// тот же режим «получатель падает от того, что отправитель другой», который
+// на JSON-портах уже вылечен веткой по умолчанию
+// (client/lib/socketDispatch.js): битое самоописание обязано читаться как
+// поколение 0, а не как отказ движка.
+
+import { abiOps } from '../config/abiOps.js';
+
+// пустая нагрузка опкода: ядро ждёт байты всегда, даже когда их нет
+const EMPTY_PAYLOAD = new Uint8Array(0);
+
+// «опкод не обработан»: ядро его не знает либо вернуло пустой вектор
+// (соглашение abi::dispatch_result в крейте)
+const NOT_HANDLED = Object.freeze({ handled: false, bytes: null });
+
+// ядро старше самоописания: ни одного опционального опкода (И2 плана
+// plugin-forward-compat). Один объект на все такие ядра — он заморожен и
+// никем не правится
+export const ABI_UNKNOWN = Object.freeze({ abi: 0, core: null, ops: [] });
+
+/**
+ * Читает самоописание ядра: версия формата, версия движкового крейта,
+ * список опкодов `dispatch`.
+ * @param {Object} core - Экземпляр wasm-ядра (игрового или клиентского).
+ * @param {string} [label] - Имя ядра в тексте предупреждения.
+ * @returns {{abi: number, core: string|null, ops: Array<string>}} Всегда
+ *   пригодный к чтению объект: `abi: 0` с пустым `ops` — ядро старше
+ *   механизма ЛИБО его самоописание нечитаемо.
+ */
+export function readCoreAbi(core, label = 'core') {
+  if (typeof core?.abi_describe !== 'function') {
+    return ABI_UNKNOWN;
+  }
+
+  let described;
+
+  try {
+    described = JSON.parse(core.abi_describe());
+  } catch (err) {
+    console.warn(`${label}: abi_describe is not JSON (${err.message})`);
+
+    return ABI_UNKNOWN;
+  }
+
+  // нормализация, а не проверка: движок обязан продолжить работу на любом
+  // содержимом. Не-строки из ops выбрасываются — по ним всё равно нечего
+  // диспетчеризовать
+  return {
+    abi: Number.isInteger(described?.abi) ? described.abi : 0,
+    core: typeof described?.core === 'string' ? described.core : null,
+    ops: Array.isArray(described?.ops)
+      ? described.ops.filter(op => typeof op === 'string')
+      : [],
+  };
+}
+
+export default readCoreAbi;
+
+/**
+ * Зовёт необязательную возможность ядра опкодом. Единственное место, где
+ * движок вызывает `dispatch` — и игровой половины, и клиентской: таблица
+ * экспортов wasm заморожена (И1/И3), поэтому новая возможность приезжает
+ * строкой, а не новым символом.
+ *
+ * Исходов ровно три, и они РАЗЛИЧИМЫ (соглашение `abi::dispatch_result`,
+ * core/src/abi.rs): пустой ответ — «опкод не понят», маркер `[0x00]` —
+ * «понят, ответа нет», иначе — полезные байты. Схлопывать первые два в один
+ * `null` нельзя: опкод-команда (ради них механизм и делался) отдавала бы
+ * вызывающему сырой `Uint8Array [0]`, который поехал бы в TextDecoder и
+ * JSON.parse.
+ * @param {Object} core - Экземпляр wasm-ядра.
+ * @param {Object} abi - Результат readCoreAbi для этого ядра.
+ * @param {string} op - Опкод из config/abiOps.js.
+ * @param {Uint8Array} [payload] - Полезная нагрузка опкода.
+ * @returns {{handled: boolean, bytes: Uint8Array|null}} `handled: false` —
+ *   ядро опкода не знает (вызывающий идёт по запасному пути);
+ *   `handled: true, bytes: null` — обработано без ответа.
+ */
+export function dispatchCoreOp(core, abi, op, payload = EMPTY_PAYLOAD) {
+  // опкод вне реестра — дефект ДВИЖКА, а не старого ядра: имя, которого нет
+  // в config/abiOps.js, не попадает ни в слепок поверхности, ни в CHANGELOG.
+  // Падаем сразу, а не на игре, которая его однажды поймёт
+  if (!abiOps.has(op)) {
+    throw new Error(
+      `dispatchCoreOp: unknown opcode "${op}" — declare it in ` +
+        'config/abiOps.js (append-only, И1)',
+    );
+  }
+
+  const resolved = abiOps.resolve(op);
+
+  if (!abi.ops.includes(resolved)) {
+    return NOT_HANDLED;
+  }
+
+  const out = core.dispatch(resolved, payload);
+
+  if (out.length === 0) {
+    return NOT_HANDLED;
+  }
+
+  // [0x00] — «обработан, ответа нет»: полезных байтов у него нет
+  return {
+    handled: true,
+    bytes: out.length === 1 && out[0] === 0x00 ? null : out,
+  };
+}

package/src/lib/formUnit.js

@@ -0,0 +1,25 @@
+// Единица измерения числового поля формы: `unit: 's'` значит, что игра
+// хранит значение в миллисекундах, а игрок видит и вводит секунды.
+//
+// Определение общее на движок (как anchorPattern и normalizeOptions рядом):
+// конвертацию делают и билдер формы (client/lib/formBuilder.js), и
+// авторитетная валидация хоста (lib/validators.js) — min/max дескриптора
+// объявлены в единице ОТОБРАЖЕНИЯ, а по сети едет единица хранения. Две
+// копии этого правила разъехались бы молча: форма пропускала бы то, что
+// отбивает хост, или наоборот.
+
+/** Значение хранения → значение, в котором объявлены min/max и default. */
+export function toDisplay(descriptor, value) {
+  return descriptor.unit === 's' ? value / 1000 : value;
+}
+
+/** Обратное преобразование: то, что вводит игрок → то, что едет на хост. */
+export function toStored(descriptor, value) {
+  return descriptor.unit === 's' ? value * 1000 : value;
+}
+
+// числовое text-поле: unit задан или numeric:true. Правило одно на билдер и
+// на валидацию — иначе поле строится числовым, а проверяется как текст
+export function isNumericField(descriptor) {
+  return descriptor?.numeric === true || descriptor?.unit !== undefined;
+}

package/src/lib/gameConfigView.js

@@ -126,7 +126,10 @@ function setPath(target, dottedPath, value) {
  * Строит представление gameConfig с умолчаниями и проверяет обязательное.
  * @param {Object} gameConfig - HostPlugin.gameConfig игры как есть.
  * @param {string} [gameId] - id плагина; попадает в текст ошибок.
- * @returns {Object} Замороженный конфиг: поля игры плюс умолчания движка.
+ * @returns {Object} Конфиг: поля игры плюс умолчания движка. Заморожен
+ *   ПОВЕРХНОСТНО — вложенные ветки (parts, roomDefaults) правятся; глубокая
+ *   заморозка стоила бы обхода всего конфига игры на каждом старте матча, а
+ *   единственный потребитель (applyRoomOverrides) и так делает structuredClone.
  * @throws {Error} Если нет поля из REQUIRED_GAME_CONFIG_PATHS или конфиг
  *   внутренне противоречив (spectatorTeam вне teams, noSpectators при двух
  *   командах).

package/src/lib/gamePlugin.js

@@ -42,8 +42,30 @@ export async function fetchGameManifest(url) {
 // правильная реакция — каталог помечает игру недоступной и продолжает
 // раздавать остальные, остальные три бросают.
 export function checkPluginCompatibility(manifest) {
-  const wanted = manifest.requires ?? [];
-  const missing = wanted.filter(name => !ENGINE_CAPABILITIES.has(name));
+  const wanted = manifest.requires;
+
+  // `requires` пишет ЧУЖОЙ репозиторий игры, и его форме нельзя доверять:
+  // строка или объект вместо массива давали здесь TypeError, который уходил
+  // из конструктора GameCatalog и не давал стартовать мастеру целиком —
+  // одна битая игра уносила весь каталог. Битый манифест обязан вести себя
+  // как несовместимый (вердикт), а не как краш движка
+  if (wanted !== undefined && wanted !== null) {
+    if (
+      !Array.isArray(wanted) ||
+      wanted.some(name => typeof name !== 'string')
+    ) {
+      return {
+        ok: false,
+        reason: 'bad-manifest',
+        missing: [],
+        text:
+          `game "${manifest.id}": manifest.requires must be an array of ` +
+          'capability names — rebuild the game package',
+      };
+    }
+  }
+
+  const missing = (wanted ?? []).filter(name => !ENGINE_CAPABILITIES.has(name));
 
   if (missing.length === 0) {
     return { ok: true };

package/src/lib/validators.js

@@ -1,5 +1,7 @@
 import { anchorPattern } from './formPattern.js';
 import { normalizeOptions } from './formOptions.js';
+import { resolveDescriptor } from './formControls.js';
+import { toDisplay, isNumericField } from './formUnit.js';
 
 const NAME_REGEXP = new RegExp('^[a-zA-Z]([\\w\\s#]{0,13})[\\w]{1}$');
 
@@ -30,6 +32,33 @@ const OPTION_CONTROLS = ['select', 'radio'];
 // умолчанию — text (тот же дефолт, что у билдера формы)
 const isTextControl = control => control === 'text' || control === undefined;
 
+// числовое поле (control 'text' + numeric/unit — в том числе разрешённые из
+// выведенных 'number' и 'range'). Форма отдаёт его ЧИСЛОМ в единице
+// хранения (formBuilder.buildText: getValue → toStored(Number(...))), а не
+// строкой, поэтому оно идёт отдельной веткой до проверки типа
+const isNumericControl = options =>
+  isTextControl(options?.control) && isNumericField(options);
+
+// min/max дескриптора объявлены в единице ОТОБРАЖЕНИЯ, а по сети едет
+// единица хранения — сравниваем ровно так же, как validateField на клиенте
+const numericError = (options, value) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 'must be a number';
+  }
+
+  const shown = toDisplay(options, value);
+
+  if (options.min !== undefined && shown < options.min) {
+    return `must be >= ${options.min}`;
+  }
+
+  if (options.max !== undefined && shown > options.max) {
+    return `must be <= ${options.max}`;
+  }
+
+  return null;
+};
+
 // source-варианты хост не резолвит (их и форма в auth не резолвит: она
 // строится с пустым ctx) — сверяем только объявленный inline-список.
 // String(): и <option>.value, и <input type=radio>.value — DOM-свойства,
@@ -76,6 +105,26 @@ export const resolveValidator = (name, validators = {}) => {
   return typeof fn === 'function' ? fn : undefined;
 };
 
+// игровой валидатор поля (authSchema.validators). Нерезолвнутое имя
+// (опечатка) и не-функция ведут себя одинаково — поле проходит. Для клиента
+// это норма (игровые валидаторы к нему не едут, авторитет проверки на
+// хосте), для хоста — дефект схемы, о котором говорят C10 и console.error в
+// PortMachine: звать что попало нельзя, TypeError отсюда уходит прямо в
+// обработчик сообщения
+const gameValidatorError = (options, value, validators) => {
+  if (options?.validator === undefined) {
+    return null;
+  }
+
+  const validatorFn = resolveValidator(options.validator, validators);
+
+  return validatorFn && !validatorFn(value) ? 'not valid' : null;
+};
+
+// null → ничего не добавляем: errors.push(...withName(...)) читается одной
+// строкой на обеих ветках поля
+const withName = (name, error) => (error === null ? [] : [{ name, error }]);
+
 /**
  * Валидирует объект с данными для авторизации.
  * @param {object} data - Объект с данными для проверки.
@@ -87,13 +136,38 @@ export const resolveValidator = (name, validators = {}) => {
 export const validateAuth = (data, authParams, validators = {}) => {
   const errors = [];
 
-  for (const { name, options } of authParams) {
+  for (const { name, options: declared } of authParams) {
     if (!(name in data)) {
       return [{ name, error: `Property is missing` }];
     }
 
+    // Тот же резолв алиаса, что делает билдер формы (client/lib/formBuilder.js:
+    // buildField, collectFormErrors, resolveForcedValue). Без него контрол,
+    // выведенный из эксплуатации в v3 ('segmented', 'number', 'range',
+    // 'toggle'), не совпадает ни с одним именем ниже, и клиент, обошедший
+    // форму, получает поле ВООБЩЕ без проверок — ровно то превосходство над
+    // заполнившим форму, которого здесь быть не должно. Алиасы стали
+    // достижимы вместе с реестром контролов (этап 3 plugin-forward-compat):
+    // до него такое поле не строилось у клиента и сюда не доезжало
+    const options = resolveDescriptor(declared);
     const value = data[name];
 
+    // Числовое поле идёт своей веткой: форма отдаёт его числом, и общий
+    // путь ниже (длина, список вариантов, regExp) к нему не применим —
+    // проверяется диапазон, ровно как validateField делает на клиенте.
+    // Игровой валидатор зовётся для обоих видов поля одинаково
+    if (isNumericControl(options)) {
+      const error = numericError(options, value);
+
+      errors.push(
+        ...withName(
+          name,
+          error ?? gameValidatorError(options, value, validators),
+        ),
+      );
+      continue;
+    }
+
     if (typeof value !== 'string') {
       return [{ name, error: `Property must be a string` }];
     }
@@ -103,10 +177,7 @@ export const validateAuth = (data, authParams, validators = {}) => {
     // не должен получать больше прав, чем клиент, её заполнивший. Пустое
     // значение пропускается ровно как на клиенте (required здесь не
     // проверяется: solo-путь boot.autoAuth отвечает дефолтами схемы, среди
-    // которых бывает '') — пустота остаётся делом игрового валидатора.
-    // min/max формы здесь не применяются и не нужны: числовое поле отдаёт из
-    // формы число, а нестроковое значение отбито выше, то есть числовых
-    // полей в authSchema не бывает вовсе
+    // которых бывает '') — пустота остаётся делом игрового валидатора
 
     // длина — первой и безусловно: потолок ограничивает не столько ввод,
     // сколько работу паттерна ниже (см. MAX_FIELD_LENGTH)
@@ -142,18 +213,9 @@ export const validateAuth = (data, authParams, validators = {}) => {
       continue;
     }
 
-    if (options?.validator) {
-      const validatorFn = resolveValidator(options.validator, validators);
-
-      // нерезолвнутое имя (опечатка) и не-функция ведут себя одинаково —
-      // поле проходит. Для клиента это норма (игровые валидаторы к нему не
-      // едут, авторитет проверки на хосте), для хоста — дефект схемы, о
-      // котором говорят C10 и console.error в PortMachine: звать что попало
-      // нельзя, TypeError отсюда уходит прямо в обработчик сообщения
-      if (validatorFn && !validatorFn(value)) {
-        errors.push({ name, error: 'not valid' });
-      }
-    }
+    errors.push(
+      ...withName(name, gameValidatorError(options, value, validators)),
+    );
   }
 
   return errors.length ? errors : undefined;

package/src/standalone/index.js

@@ -36,6 +36,10 @@ import { ensureGameShell } from '../client/views/gameShell.js';
  *   голосований, например `['/bot 4']`.
  * @param {Object} [options.room] - Переопределения комнаты (map, maxPlayers,
  *   roundTime, friendlyFire, seed).
+ * @param {Array<string>} [options.requires] - Возможности движка, без
+ *   которых игра не запустится (аналог `GameManifest.requires`, которого в
+ *   solo-режиме нет). По умолчанию — объединение `requires` обеих половин
+ *   плагина.
  * @param {boolean} [options.devMode] - room.isDevMode: рекордер и хостовый
  *   CONSOLE-лог.
  * @returns {Promise<Object>} `{ stop() }` — останов матча.
@@ -52,6 +56,7 @@ export async function startStandaloneGame({
   startupVotes = [],
   startupCommands = [],
   room = {},
+  requires,
   devMode = false,
 } = {}) {
   requireOption(hostPlugin, 'hostPlugin');
@@ -59,9 +64,19 @@ export async function startStandaloneGame({
   requireOption(wasmUrl, 'wasmUrl');
 
   // возможность, которой в этой сборке движка нет, иначе всплыла бы где-то
-  // в середине хендшейка непрозрачной ошибкой
-  requireCompatible(hostPlugin);
-  requireCompatible(clientPlugin);
+  // в середине хендшейка непрозрачной ошибкой. Мастера тут нет, а значит нет
+  // и GameManifest с его `requires` — источником служат сами половины
+  // плагина (необязательное поле `requires`, docs/en/plugin-api.md) либо
+  // опция вызова, если встраивающий знает лучше. Одна проверка вместо двух:
+  // сообщение адресовано разработчику встраивания, делить его по половинам
+  // незачем
+  requireCompatible({
+    id: hostPlugin.id,
+    requires: requires ?? [
+      ...(hostPlugin.requires ?? []),
+      ...(clientPlugin.requires ?? []),
+    ],
+  });
 
   // одна view на прогон: умолчания вместо обязательных полей (И2 этапа 2)
   const configView = assertGameConfigShape(hostPlugin);
@@ -97,8 +112,8 @@ export async function startStandaloneGame({
   };
 }
 
-// половина плагина просит возможность, которой в этой сборке движка нет:
-// подменить её в SDK нечем — матч не поднимется
+// игра просит возможность, которой в этой сборке движка нет: подменить её в
+// SDK нечем — матч не поднимется
 function requireCompatible(plugin) {
   const compat = checkPluginCompatibility(plugin);