vimp-engine 0.22.1 → 0.24.0

package/src/lib/registry.js

@@ -0,0 +1,94 @@
+// Append-only реестр (И1 плана plugin-forward-compat, этап 3). Движок держит
+// закрытые словари, из которых игра выбирает значения: контролы формы, имена
+// клиентских сервисов. Запись НИКОГДА не удаляется: игра, собранная два года
+// назад, могла её написать, и её dist больше никто не тронет — сокращение
+// словаря отвергает такую игру молча. Вывод из эксплуатации =
+// { alias: 'новое-имя' } + запись в CHANGELOG, но не удаление строки.
+//
+// Именно так сломался v2 → v3: набор `control` урезали до четырёх нативных
+// элементов, и `range`/`number`/`toggle`/`segmented` перестали строиться.
+
+/**
+ * Создаёт append-only реестр имён плагинной поверхности.
+ * @param {string} name - Имя реестра (в тексте ошибок).
+ * @param {Array<Object>} entries - Записи `{ value, since, alias?,
+ *   retiredIn?, note?, ...полезная нагрузка }`. Запись с `alias` — выведенное
+ *   из эксплуатации имя: оно продолжает работать, разрешаясь в указанное.
+ * @returns {Object} Реестр: `has`, `get`, `resolve`, `chain`, `isRetired`,
+ *   `list`, `values`.
+ */
+export function createRegistry(name, entries) {
+  const byValue = new Map();
+
+  for (const entry of entries) {
+    if (byValue.has(entry.value)) {
+      throw new Error(`registry ${name}: duplicate entry "${entry.value}"`);
+    }
+
+    byValue.set(entry.value, Object.freeze({ ...entry }));
+  }
+
+  // цепочка алиасов от имени к активной записи; пустая, если имени нет
+  const chain = value => {
+    const trail = [];
+    const seen = new Set();
+    let current = byValue.get(value);
+
+    while (current !== undefined) {
+      if (seen.has(current.value)) {
+        throw new Error(
+          `registry ${name}: alias cycle at "${current.value}" — ` +
+            'a retired name must resolve to an active one',
+        );
+      }
+
+      seen.add(current.value);
+      trail.push(current);
+
+      if (current.alias === undefined) {
+        return trail;
+      }
+
+      const next = byValue.get(current.alias);
+
+      if (next === undefined) {
+        throw new Error(
+          `registry ${name}: "${current.value}" is aliased to unknown ` +
+            `"${current.alias}"`,
+        );
+      }
+
+      current = next;
+    }
+
+    return trail;
+  };
+
+  // битый реестр — дефект движка, а не плагина: пусть падает на загрузке
+  // модуля, а не на первой игре, которая напишет выведенное имя
+  for (const value of byValue.keys()) {
+    chain(value);
+  }
+
+  return Object.freeze({
+    name,
+    has: value => byValue.has(value),
+    get: value => byValue.get(value),
+    // разрешает имя в активное (проходит цепочку алиасов). undefined — имя
+    // неизвестно; это ВСЕГДА ошибка плагина (он попросил будущее), никогда
+    // не ошибка движка за то, что у него список длиннее
+    resolve: value => chain(value).at(-1)?.value,
+    chain,
+    isRetired: value => byValue.get(value)?.alias !== undefined,
+    // все записи, включая выведенные: слепок поверхности (этап 1) не считает
+    // вывод из эксплуатации удалением
+    list: () => [...byValue.values()],
+    // только активные имена — то, что вправе написать НОВАЯ игра
+    values: () =>
+      [...byValue.values()]
+        .filter(e => e.alias === undefined)
+        .map(e => e.value),
+  });
+}
+
+export default createRegistry;

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

@@ -1,4 +1,7 @@
-import { assertEngineApiCompatible } from '../lib/gamePlugin.js';
+import {
+  assertGameConfigShape,
+  checkPluginCompatibility,
+} from '../lib/gamePlugin.js';
 import { setBootConfig } from '../client/boot.js';
 import { ensureGameShell } from '../client/views/gameShell.js';
 
@@ -33,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() }` — останов матча.
@@ -49,27 +56,41 @@ export async function startStandaloneGame({
   startupVotes = [],
   startupCommands = [],
   room = {},
+  requires,
   devMode = false,
 } = {}) {
   requireOption(hostPlugin, 'hostPlugin');
   requireOption(clientPlugin, 'clientPlugin');
   requireOption(wasmUrl, 'wasmUrl');
 
-  // несовпадение ENGINE_API_VERSION иначе всплыло бы где-то в середине
-  // хендшейка непрозрачной ошибкой
-  assertEngineApiCompatible(hostPlugin);
-  assertEngineApiCompatible(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);
 
   ensureGameShell(container);
 
   setBootConfig({
     mode: 'solo',
     container,
-    manifest: buildManifest(hostPlugin, { wasmUrl, assetsBase }),
+    manifest: buildManifest(hostPlugin, configView, { wasmUrl, assetsBase }),
     clientPlugin,
     hostPlugin,
     room: {
-      ...hostPlugin.gameConfig.roomDefaults,
+      ...configView.roomDefaults,
       ...room,
       isDevMode: devMode,
     },
@@ -91,6 +112,16 @@ export async function startStandaloneGame({
   };
 }
 
+// игра просит возможность, которой в этой сборке движка нет: подменить её в
+// SDK нечем — матч не поднимется
+function requireCompatible(plugin) {
+  const compat = checkPluginCompatibility(plugin);
+
+  if (!compat.ok) {
+    throw new Error(compat.text);
+  }
+}
+
 // незаданное поле — это «взять дефолт схемы», а не «отправить undefined»:
 // JSON.stringify ключ с undefined выбрасывает, и хост отвечает
 // 'Property is missing' (main.js накрывает autoAuth поверх дефолтов схемы)
@@ -103,18 +134,16 @@ function pruneUndefined(source) {
 // манифест-подобный объект в памяти: мастера нет, а клиент читает из
 // манифеста id/version, entries.wasm и assetsBase. entries.client/host не
 // нужны — оба плагина уже живые объекты
-function buildManifest(hostPlugin, { wasmUrl, assetsBase }) {
-  const { gameConfig } = hostPlugin;
-
+function buildManifest(hostPlugin, configView, { wasmUrl, assetsBase }) {
   return {
     id: hostPlugin.id,
     engineApi: hostPlugin.engineApi,
     version: 'dev',
-    title: gameConfig.title ?? hostPlugin.id,
+    title: configView.title ?? hostPlugin.id,
     entries: { wasm: wasmUrl },
     assetsBase,
-    maps: { version: 'dev', list: Object.keys(gameConfig.maps) },
-    roomDefaults: gameConfig.roomDefaults,
+    maps: { version: 'dev', list: Object.keys(configView.maps) },
+    roomDefaults: configView.roomDefaults,
   };
 }
 

package/tests/fixtures/generations/gen-api3/README.md

@@ -0,0 +1,7 @@
+# gen-api3 — ЗАМОРОЖЕНО
+
+Снимок плагина 2026-08-29, поколение `engineApi: 3`.
+Не править: правка фикстуры маскирует слом совместимости
+(этап 1 плана `plan/plugin-forward-compat`). Новое поколение
+добавляется копированием текущего `../../miniGame`, а не правкой
+этого каталога.

package/tests/fixtures/generations/gen-api3/client/fakeClientCore.js

@@ -0,0 +1,307 @@
+// ЗАМОРОЖЕНО. Снимок плагина 2026-08-29 (поколение engineApi: 3).
+// Не править: правка фикстуры маскирует слом совместимости.
+// Фейковое клиентское ядро миниигры-фикстуры: минимальная реализация
+// движкового клиентского ABI (см. export_client_core_abi!, PLAN.md §3.4).
+//
+// Кадры фикстуры — не бинарный кодек ядра, а JSON (см. host/fakeCore.js:
+// frame_bytes), поэтому push_frame их просто разбирает, а интерполяции нет:
+// sample() отдаёт последний принятый кадр. Раскладка hot-буфера при этом
+// настоящая (флаги, две группы, ширина записи = 2 + поля схемы) — именно её
+// читает движковый reconstructHot, и именно она замыкает headless-контур
+// «хост → байты → клиентское ядро → сцена» без WASM.
+
+// флаги hot-буфера на момент снимка (движковый src/config/opcodes.js)
+const HOT_FLAGS = { GAME: 1, CAMERA: 2, PREDICTED: 4, FRAMES: 8 };
+
+export default class FakeClientCore {
+  constructor(configJson) {
+    this._config = JSON.parse(configJson);
+    this._active = false;
+    this._frame = null;
+    this._hot = new Float32Array(0);
+
+    // обратный индекс снапшот-схемы: keyId → { key, kind, fields }
+    const keys = this._config.engine?.snapshot?.keys ?? {};
+
+    this._hotKey = Object.entries(keys).find(
+      ([, spec]) => spec.class === 'hot' && spec.kind === 'indexed8',
+    );
+
+    // детектор рассинхрона предикта (этап 5): включается секцией divergence
+    // движкового конфига, как и в Rust-ядре
+    const cfg = this._config.engine?.divergence;
+
+    this._divergenceCfg = cfg ?? null;
+    this._divergence = cfg
+      ? { samples: 0, violations: 0, dropped: 0, maxDelta: [0, 0], records: [] }
+      : null;
+
+    // предикт фикстуры: та же таблица скоростей, что у host/fakeCore, плюс
+    // история её изменений — реконсиляция идёт по времени кадра, поэтому
+    // история переигрывается от момента авторитетного состояния, а не от seq
+    this._vy = 0;
+    this._inputs = []; // [{ time, vy }] в локальном времени
+    this._base = null; // { x, y, time, vy } — последнее авторитетное, в серверном
+    this._offset = 0;
+  }
+
+  push_frame(data, localNow = 0) {
+    let frame;
+
+    try {
+      frame = JSON.parse(new TextDecoder().decode(data));
+    } catch {
+      return false;
+    }
+
+    this._offset = frame.serverTime - localNow;
+    this._observeDivergence(frame);
+    this._frame = frame;
+
+    return true;
+  }
+
+  my_game_id() {
+    return this._frame?.playerId ?? null;
+  }
+
+  offset() {
+    return 0;
+  }
+
+  sample() {
+    if (!this._frame || !this._hotKey) {
+      this._hot = new Float32Array(0);
+
+      return 0;
+    }
+
+    const [, spec] = this._hotKey;
+    const body = this._frame.body ?? [];
+    const camera = this._frame.camera;
+    const values = [
+      HOT_FLAGS.GAME | (camera ? HOT_FLAGS.CAMERA : 0),
+      camera ? camera[0] : 0,
+      camera ? camera[1] : 0,
+      body.length,
+    ];
+
+    for (const record of body) {
+      values.push(spec.id, record.id);
+
+      for (const field of spec.fields) {
+        values.push(Number(record[field.name] ?? 0));
+      }
+    }
+
+    // группа IndexedNoNull8 (динамика карты) — у фикстуры пуста
+    values.push(0);
+
+    this._hot = new Float32Array(values);
+
+    return this._hot.length;
+  }
+
+  hot_ptr() {
+    return 0;
+  }
+
+  hot_values() {
+    return this._hot;
+  }
+
+  take_frames() {
+    return '[]';
+  }
+
+  apply_input(action, name, localNow = 0) {
+    const magnitude = action === 'down' ? 40 : 0;
+
+    if (name === 'forward') {
+      this._vy = -magnitude;
+    } else if (name === 'back') {
+      this._vy = magnitude;
+    } else {
+      return;
+    }
+
+    this._inputs.push({ time: localNow, vy: this._vy });
+  }
+
+  // записи расхождения предикта; 'null' — детектор выключен конфигом
+  take_divergence() {
+    if (!this._divergence) {
+      return 'null';
+    }
+
+    const { records, ...stats } = this._divergence;
+
+    this._divergence.records = [];
+
+    return JSON.stringify({ ...stats, records });
+  }
+
+  // сравнение предсказанного своего актора с авторитетным player-блоком —
+  // до того, как авторитетное состояние станет новой базой предикта
+  _observeDivergence(frame) {
+    if (!this._divergence) {
+      return;
+    }
+
+    // playerId приходит в кадре хоста строкой (gameId меты) — наблюдатель
+    // помечен -1 и своего актора не имеет
+    const id = Number(frame.playerId);
+    const authoritative = (frame.body ?? []).find(row => row.id === id);
+
+    if (!Number.isInteger(id) || id < 0 || !authoritative) {
+      return;
+    }
+
+    const time = frame.serverTime;
+
+    if (this._base) {
+      const predicted = this._predictAt(time);
+
+      this._compare(predicted, authoritative, frame);
+    }
+
+    // реконсиляция: база — авторитетное состояние на serverTime кадра,
+    // история ввода до этого момента больше не переигрывается
+    const vy = this._velocityAt(time);
+
+    this._base = { x: authoritative.x, y: authoritative.y, time, vy };
+    this._inputs = this._inputs.filter(
+      input => input.time + this._offset > time,
+    );
+  }
+
+  _compare(predicted, authoritative, frame) {
+    const dump = this._divergence;
+    const cfg = this._divergenceCfg;
+    const pair = [
+      [predicted.x, authoritative.x],
+      [predicted.y, authoritative.y],
+    ];
+    const delta = pair.map(([a, b]) => a - b);
+    const thresholds = pair.map(
+      (_, index) => cfg.thresholds?.[index] ?? cfg.defaultThreshold ?? 1,
+    );
+    const exceeded = delta
+      .map((value, index) => (Math.abs(value) > thresholds[index] ? index : -1))
+      .filter(index => index !== -1);
+
+    dump.samples += 1;
+    delta.forEach((value, index) => {
+      dump.maxDelta[index] = Math.max(dump.maxDelta[index], Math.abs(value));
+    });
+
+    if (!exceeded.length) {
+      return;
+    }
+
+    dump.violations += 1;
+
+    if (dump.records.length >= (cfg.capacity ?? 64)) {
+      dump.records.shift();
+      dump.dropped += 1;
+    }
+
+    dump.records.push({
+      source: 'state',
+      serverTime: frame.serverTime,
+      localNow: frame.serverTime - this._offset,
+      offset: this._offset,
+      inputSeq: frame.seq,
+      replayed: {
+        from: this._base.time,
+        to: frame.serverTime,
+        count: this._inputs.length,
+      },
+      predicted: [predicted.x, predicted.y],
+      authoritative: [authoritative.x, authoritative.y],
+      delta,
+      exceeded,
+      thresholds,
+    });
+  }
+
+  // интегрирование скорости от базы до момента t (серверное время):
+  // кусочно-линейно по истории ввода — предикт переигрывает именно её
+  _predictAt(t) {
+    let { y, time, vy } = this._base;
+
+    for (const input of this._inputs) {
+      const at = input.time + this._offset;
+      const until = Math.min(at, t);
+
+      if (until > time) {
+        y += (vy * (until - time)) / 1000;
+        time = until;
+      }
+
+      if (at > t) {
+        return { x: this._base.x, y };
+      }
+
+      vy = input.vy;
+    }
+
+    if (t > time) {
+      y += (vy * (t - time)) / 1000;
+    }
+
+    return { x: this._base.x, y };
+  }
+
+  _velocityAt(time) {
+    let vy = this._base?.vy ?? 0;
+
+    for (const input of this._inputs) {
+      if (input.time + this._offset <= time) {
+        vy = input.vy;
+      }
+    }
+
+    return vy;
+  }
+
+  set_active(active) {
+    this._active = active;
+  }
+
+  set_map() {}
+
+  reset() {
+    this._frame = null;
+    this._hot = new Float32Array(0);
+    this._base = null;
+    this._inputs = [];
+  }
+
+  // зеркало ClientState::debug_json; у фикстуры буфер — один последний
+  // кадр, поэтому окно seq вырождено
+  debug_json() {
+    return JSON.stringify({
+      myGameId: this._frame?.playerId ?? null,
+      offset: 0,
+      interpolator: {
+        buffered: this._frame ? 1 : 0,
+        seqWindow: this._frame ? [this._frame.seq, this._frame.seq] : null,
+        lastFrame: this._frame
+          ? { seq: this._frame.seq, serverTime: this._frame.serverTime }
+          : null,
+      },
+      hotLen: this._hot.length,
+      framesOut: 0,
+      active: this._active,
+    });
+  }
+
+  decode_frame(data) {
+    try {
+      return JSON.stringify(JSON.parse(new TextDecoder().decode(data)));
+    } catch {
+      return 'null';
+    }
+  }
+}