vimp-engine 0.22.0 → 0.23.0

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';
 
@@ -55,21 +58,24 @@ export async function startStandaloneGame({
   requireOption(clientPlugin, 'clientPlugin');
   requireOption(wasmUrl, 'wasmUrl');
 
-  // несовпадение ENGINE_API_VERSION иначе всплыло бы где-то в середине
-  // хендшейка непрозрачной ошибкой
-  assertEngineApiCompatible(hostPlugin);
-  assertEngineApiCompatible(clientPlugin);
+  // возможность, которой в этой сборке движка нет, иначе всплыла бы где-то
+  // в середине хендшейка непрозрачной ошибкой
+  requireCompatible(hostPlugin);
+  requireCompatible(clientPlugin);
+
+  // одна 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 +97,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 +119,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';
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+// ЗАМОРОЖЕНО. Снимок плагина 2026-08-29 (поколение engineApi: 3).
+// Не править: правка фикстуры маскирует слом совместимости.
+import FakeClientCore from './fakeClientCore.js';
+import Actor from './parts/Actor.js';
+import ActorRadar from './parts/ActorRadar.js';
+
+// ClientPlugin миниигры-фикстуры (Этап 7 плана отделения движка, PLAN.md
+// §3.3): минимальные заглушечные parts (без PixiJS) — доказывает, что
+// gamePlugin.js/Factory работают с любым ClientPlugin, а не только с
+// @vimp-games/tanks.
+export default {
+  id: 'gen-api3',
+  engineApi: 3,
+
+  async createClientCore(clientConfigJson) {
+    return { core: new FakeClientCore(clientConfigJson), memory: null };
+  },
+
+  parts: { Actor, ActorRadar },
+  bakers: {},
+  styles: '',
+
+  hooks: {
+    onAuth(core, authData) {
+      core.set_model?.(authData.model);
+    },
+
+    onPanel() {},
+
+    onLocalAction(core, action, name, now) {
+      if (action === 'down' && name === 'fire') {
+        return core.try_fire?.(now) || null;
+      }
+
+      return null;
+    },
+  },
+};

package/tests/fixtures/generations/gen-api3/client/parts/Actor.js

@@ -0,0 +1,18 @@
+// Заглушечный part фикстуры (ClientPlugin.parts, PLAN.md §3.3) — минимальная
+// форма рендер-сущности: конструктор + update(state)/destroy(), без PixiJS
+// (тесты не поднимают живой канвас). Доказывает, что Factory/CanvasManager
+// не требуют конкретно PixiJS-Container-класса — только этот интерфейс.
+export default class Actor {
+  constructor(id) {
+    this.id = id;
+    this.destroyed = false;
+  }
+
+  update(state) {
+    this.state = state;
+  }
+
+  destroy() {
+    this.destroyed = true;
+  }
+}

package/tests/fixtures/generations/gen-api3/client/parts/ActorRadar.js

@@ -0,0 +1,7 @@
+import Actor from './Actor.js';
+
+// Второй заглушечный part фикстуры — радар-проекция того же актёра,
+// зеркало пары Tank/TankRadar танков (доказывает, что gameSets/
+// entitiesOnCanvas умеют распределять одну сущность по нескольким
+// полотнам произвольным числом part-классов).
+export default class ActorRadar extends Actor {}

package/tests/fixtures/generations/gen-api3/config/auth.js

@@ -0,0 +1,41 @@
+import gameConfig from './game.js';
+
+// Схема авторизации фикстуры (HostPlugin.authSchema, PLAN.md §3.2) —
+// зеркало vimp-tanks/src/config/auth.js с единственной моделью.
+export default {
+  elems: {
+    authId: 'auth',
+    fieldsId: 'auth-form',
+    errorId: 'auth-error',
+    enterId: 'auth-enter',
+    titleId: 'auth-title',
+    informsId: 'auth-informs',
+  },
+  // собственные тексты фикстуры (Д2): каркас auth.pug нейтрален,
+  // заголовок/подсказки — данные игры
+  texts: {
+    title: 'Mini Game Fixture',
+    sections: [
+      {
+        heading: 'Controls',
+        lines: [
+          { keys: 'W, S', text: 'move' },
+          { keys: 'J', text: 'fire' },
+        ],
+      },
+    ],
+  },
+  params: [
+    {
+      name: 'model',
+      value: 'm1',
+      options: {
+        validator: 'isValidModel',
+        storage: 'model',
+      },
+    },
+  ],
+  validators: {
+    isValidModel: model => model in gameConfig.parts.models,
+  },
+};

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

@@ -0,0 +1,151 @@
+// Игровая половина клиентского CONFIG_DATA (HostPlugin.buildClientGameConfig,
+// PLAN.md §3.5) — зеркало vimp-tanks/src/config/client.js, минимальная
+// схема: одно полотно, одна колонка статистики сверх имени, один keySet.
+export default {
+  parts: {
+    gameSets: {
+      // ключ снапшот-схемы (a1) — по нему клиент разводит записи кадра по
+      // parts; setId карты (m1) — по нему создаётся статика полотна
+      a1: ['Actor'],
+      m1: ['Actor'],
+      // event-ключ схемы: строк он в фикстуре не даёт, но запись нужна —
+      // ключ снапшота без набора партов это чёрный холст на первом же
+      // кадре, где он ожил
+      e1: ['Actor'],
+    },
+    entitiesOnCanvas: {
+      Actor: 'vimp',
+    },
+    bakedAssets: {},
+    // пул сервисов v3 — без 'accolades' (он появился только в v4)
+    componentDependencies: {
+      renderer: ['Actor'],
+      localPlayer: ['Actor'],
+    },
+    sounds: {},
+  },
+
+  initIdList: ['vimp', 'panel', 'chat'],
+
+  modules: {
+    canvasManager: {
+      canvases: {
+        vimp: {
+          width: 640,
+          height: 400,
+          aspectRatio: '16:10',
+          baseScale: '5:1',
+          dynamicCamera: false,
+          shakeCamera: false,
+        },
+      },
+    },
+
+    controls: {
+      keySetList: [
+        // spectator keyset: переключение камеры — механизм движка
+        // (hostDefaults.spectatorKeys), без него наблюдатель заперт
+        {
+          78: 'nextPlayer', // next player (n)
+          80: 'prevPlayer', // prev player (p)
+        },
+        // player keyset
+        {
+          87: 'forward', // forward (w)
+          83: 'back', // back (s)
+          74: 'fire', // fire (j)
+        },
+      ],
+    },
+
+    chat: {
+      params: {
+        messages: {
+          s: [
+            'Team {0} is full. Your current team: {1}',
+            'Your team: {0}',
+            'Your new team: {0}',
+            'Your new status: spectator',
+            '{0} killed {1}',
+            '{0} joined the game',
+            '{0} left the game',
+          ],
+          v: [
+            'A vote has been created',
+            'Voting has started',
+            'Your vote has been accepted',
+            'Voting is temporarily unavailable',
+            'Vote passed',
+            'Vote failed',
+          ],
+          m: ['Current map: {0}', 'Next map: {0}'],
+          c: ['Command not found'],
+          n: ['Invalid name', '{0} changed name to {1}'],
+          g: ['{0} scripted participant(s) spawned'],
+        },
+      },
+    },
+
+    panel: {
+      // поле нарочно называется не health: бар обязан работать по
+      // type: 'bar', а не по имени поля (Д2)
+      // 't' — движковый ключ времени раунда: его шлёт Panel хоста, поэтому
+      // без маппинга клиент получал бы значение с именем undefined
+      keys: {
+        h: 'energy',
+        t: 'time',
+      },
+      fields: [
+        {
+          name: 'energy',
+          elem: 'panel-energy',
+          type: 'bar',
+          max: 100,
+          blocks: 10,
+        },
+        {
+          name: 'time',
+          elem: 'panel-time',
+          type: 'time',
+        },
+      ],
+    },
+
+    stat: {
+      params: {
+        columns: ['names', 'status', 'score', 'deaths', 'latency'],
+        heads: {
+          1: 'team1',
+        },
+        bodies: {
+          1: 'team1',
+          2: 'spectators',
+        },
+        sortList: {
+          team1: [
+            [2, true],
+            [3, false],
+          ],
+        },
+      },
+    },
+
+    vote: {
+      params: {
+        templates: {
+          teamChange: ['Choose a team', 'teams', true],
+          mapChangeBySystem: ['Choose the next map'],
+          mapChangeByUser: ['{0} suggested the map: {1}', ['Yes', 'No']],
+        },
+        menu: [
+          ['teamChange', ['Switch team', 'teams']],
+          ['mapChange', ['Suggest map', 'maps']],
+        ],
+      },
+    },
+  },
+
+  gameInform: {
+    list: ['{0} WINS!', 'ROUND START!', 'GAME OVER!'],
+  },
+};