vimp-engine 0.22.1 → 0.24.0

package/tests/fixtures/generations/gen-api3/host/fakeCore.js

@@ -0,0 +1,263 @@
+// Фейковое JS-ядро миниигры-фикстуры (Этап 7 плана отделения движка,
+// PLAN.md §4/Wasm Host ABI §3.4): реализует полную поверхность методов,
+// которую вызывает GameCoreAdapter, без Rust/WASM — доказательство, что
+// движок не завязан на конкретную реализацию ядра. Актёры — плоские
+// объекты { x, y, angle, team, alive }; тик — тривиальная линейная
+// интеграция скорости (та же идея, что у Rust-фикстуры TestClient,
+// core/src/client/game.rs: форма ABI важнее физики).
+export default class FakeGameCore {
+  constructor(configJson) {
+    this._config = JSON.parse(configJson);
+    this._actors = new Map(); // gameId -> { x, y, angle, team, alive, vx, vy, lastInputSeq }
+    this._map = null;
+    this._events = [];
+    this._lastBody = [];
+    this._lastFrame = null;
+  }
+
+  // ***** карта ***** //
+
+  load_map(mapJson) {
+    this._map = JSON.parse(mapJson);
+  }
+
+  map_info() {
+    if (!this._map) {
+      return 'null';
+    }
+
+    return JSON.stringify({
+      setId: this._map.setId,
+      respawns: this._map.respawns || {},
+    });
+  }
+
+  clear() {
+    this._actors.clear();
+    this._events.length = 0;
+    this._lastBody = [];
+  }
+
+  // ***** участники ***** //
+
+  spawn_actor(gameId, model, teamId, x, y, angle) {
+    this._actors.set(gameId, {
+      x,
+      y,
+      angle,
+      team: teamId,
+      alive: true,
+      vx: 0,
+      vy: 0,
+      lastInputSeq: 0,
+    });
+
+    this._events.push({ type: 'panelSet', id: gameId, field: 'energy', value: 100 });
+  }
+
+  remove_actor(gameId) {
+    this._actors.delete(gameId);
+  }
+
+  reset_actor(gameId, teamId, x, y, angle) {
+    const actor = this._actors.get(gameId);
+
+    if (actor) {
+      Object.assign(actor, { x, y, angle, team: teamId, alive: true, vx: 0, vy: 0 });
+    }
+  }
+
+  reset_all_vitals() {
+    for (const actor of this._actors.values()) {
+      actor.alive = true;
+    }
+  }
+
+  spawn_scripted_actor(gameId, model, teamId, x, y, angle) {
+    this.spawn_actor(gameId, model, teamId, x, y, angle);
+    this._actors.get(gameId).scripted = true;
+  }
+
+  remove_scripted_actor(gameId) {
+    this.remove_actor(gameId);
+  }
+
+  remove_players_and_shots() {
+    const names = [...this._actors.keys()].map(String);
+
+    this._actors.clear();
+
+    return JSON.stringify(names);
+  }
+
+  // ***** ввод ***** //
+
+  apply_input(gameId, seq, action, name) {
+    const actor = this._actors.get(gameId);
+
+    if (!actor) {
+      return;
+    }
+
+    actor.lastInputSeq = seq;
+
+    const magnitude = action === 'down' ? 40 : 0;
+
+    if (name === 'forward') {
+      actor.vy = -magnitude;
+    } else if (name === 'back') {
+      actor.vy = magnitude;
+    } else if (name === 'fire' && action === 'down') {
+      this._events.push({ type: 'custom', data: { kind: 'fire', id: gameId } });
+    }
+  }
+
+  // ввод указателем: миниигра просто запоминает последнюю точку и биты —
+  // движковым тестам важно, что канал доходит до ядра
+  apply_aim(gameId, seq, x, y, flags) {
+    const actor = this._actors.get(gameId);
+
+    if (!actor) {
+      return;
+    }
+
+    actor.lastInputSeq = seq;
+    actor.aim = { x, y, flags };
+  }
+
+  aim_of(gameId) {
+    return this._actors.get(gameId)?.aim ?? null;
+  }
+
+  last_input_seq(gameId) {
+    return this._actors.get(gameId)?.lastInputSeq ?? 0;
+  }
+
+  // ***** запросы состояния ***** //
+
+  is_alive(gameId) {
+    return Boolean(this._actors.get(gameId)?.alive);
+  }
+
+  position_of(gameId) {
+    const actor = this._actors.get(gameId);
+
+    return actor ? [actor.x, actor.y] : [];
+  }
+
+  // FIRST_SHOT_DATA: полный снапшот игроков в раскладке снапшот-схемы
+  // (ключ схемы -> id -> поля), а не плоским списком: ровно её разбирает
+  // клиент (applyShot браузера и VirtualClient._applyGameData). Плоский
+  // список доезжал до клиента ключами '0', '1' — сущность первого кадра
+  // не появлялась на холсте, и видно это только со второго участника
+  players_data() {
+    const entry = Object.entries(
+      this._config.engine?.snapshot?.keys ?? {},
+    ).find(([, spec]) => spec.class === 'hot' && spec.kind === 'indexed8');
+
+    if (!entry) {
+      return '{}';
+    }
+
+    const [key, spec] = entry;
+    const rows = {};
+
+    for (const [id, actor] of this._actors) {
+      rows[id] = spec.fields.map(field => Number(actor[field.name] ?? 0));
+    }
+
+    return JSON.stringify({ [key]: rows });
+  }
+
+  // ***** игровой тик ***** //
+
+  step(dt) {
+    for (const actor of this._actors.values()) {
+      actor.x += actor.vx * dt;
+      actor.y += actor.vy * dt;
+    }
+  }
+
+  take_events() {
+    const events = this._events;
+
+    this._events = [];
+
+    return JSON.stringify(events);
+  }
+
+  // ***** упаковка снапшота (фикстурный формат — не бинарный кодек ядра;
+  // достаточно для тестов меты, которые не декодируют реальный фрейминг) ***** //
+
+  // поля записи — по снапшот-схеме фикстуры (config/game.js, ключ a1):
+  // x, y, angle, team; клиентская половина фикстуры раскладывает их в
+  // hot-буфер той же ширины, что заявлена схемой
+  pack_body() {
+    this._lastBody = [...this._actors.entries()].map(([id, a]) => ({
+      id: Number(id),
+      x: a.x,
+      y: a.y,
+      angle: a.angle,
+      team: a.team,
+    }));
+  }
+
+  body_has_events() {
+    return false;
+  }
+
+  pack_frame(serverTime, seq, hasCamera, camX, camY, forceReset, shake, playerId) {
+    this._lastFrame = {
+      serverTime,
+      seq,
+      camera: hasCamera ? [camX, camY, Boolean(forceReset), shake ?? null] : null,
+      playerId,
+      body: this._lastBody,
+    };
+  }
+
+  frame_bytes() {
+    return new TextEncoder().encode(JSON.stringify(this._lastFrame));
+  }
+
+  // ***** отладка ***** //
+
+  // форма дампа — та же, что у движкового crate::debug (тела/карта/rng),
+  // с поправкой на фикстуру без физики: актёры и есть тела
+  debug_json() {
+    return JSON.stringify({
+      bodies: [...this._actors.entries()].map(([id, a]) => ({
+        handle: Number(id),
+        tag: 2,
+        userData: String(id),
+        translation: [a.x, a.y],
+        rotation: a.angle,
+        linvel: [a.vx, a.vy],
+        angvel: 0,
+        mass: 1,
+        bodyType: 'Dynamic',
+        ccd: false,
+      })),
+      colliders: [],
+      map: this._map
+        ? { setId: this._map.setId, step: this._map.step ?? null }
+        : null,
+      nav: null,
+      spatial: { cells: 0, entities: 0, cellCounts: [] },
+      rng: { state: '0' },
+      step: { timeStep: this._config.timeStep ?? null, accumulator: 0 },
+    });
+  }
+
+  // ***** handoff (задел, PLAN.md §6 «открытые вопросы») ***** //
+
+  serialize_state() {
+    return new TextEncoder().encode(JSON.stringify([...this._actors.entries()]));
+  }
+
+  deserialize_state(bytes) {
+    const entries = JSON.parse(new TextDecoder().decode(bytes));
+
+    this._actors = new Map(entries);
+  }
+}

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

@@ -0,0 +1,30 @@
+// ЗАМОРОЖЕНО. Снимок плагина 2026-08-29 (поколение engineApi: 3).
+// Не править: правка фикстуры маскирует слом совместимости.
+import FakeGameCore from './fakeCore.js';
+import gameConfig from '../config/game.js';
+import authSchema from '../config/auth.js';
+import clientConfig from '../config/client.js';
+import systemMessages from './systemMessages.js';
+import spawnCommand from './spawnCommand.js';
+import createModules from './createModules.js';
+
+// HostPlugin миниигры-фикстуры (Этап 7 плана отделения движка, PLAN.md
+// §3.2): доказывает, что HostGame и движковая мета работают с любым
+// HostPlugin, реализующим контракт — не только с @vimp-games/tanks. createCore
+// не грузит WASM (fake-core — обычный JS-класс), поэтому фикстура не
+// требует собранного Rust-ядра игры.
+export default {
+  id: 'gen-api3',
+  engineApi: 3,
+
+  async createCore(coreConfigJson) {
+    return new FakeGameCore(coreConfigJson);
+  },
+
+  gameConfig,
+  authSchema,
+  chatCommands: [spawnCommand],
+  systemMessages,
+  createModules,
+  buildClientGameConfig: () => clientConfig,
+};

package/tests/fixtures/generations/gen-api3/host/spawnCommand.js

@@ -0,0 +1,14 @@
+// Игровая чат-команда фикстуры: '/spawn <count>' — создаёт scripted-
+// участников без голосования (зеркало vimp-tanks/src/host/botCommand.js,
+// упрощённое — доказывает только регистрацию HostPlugin.chatCommands).
+// Регистрируется в движковом CommandProcessor.
+export default {
+  name: '/spawn',
+  handler(ctx, gameId, args) {
+    const count = Number(args[0]) || 1;
+    const created = ctx.scripted.createScripted(count);
+
+    ctx.chat.pushSystem('SCRIPTED_SPAWNED', [created]);
+    ctx.roundManager.initiateNewRound();
+  },
+};

package/tests/fixtures/generations/gen-api3/host/systemMessages.js

@@ -0,0 +1,6 @@
+// Игровые коды системных сообщений фикстуры (группа g:*) — зеркало
+// vimp-tanks/src/host/systemMessages.js (группа b:*). Merge в движковый
+// реестр через registerCodes (HostGame конструктор).
+export default {
+  SCRIPTED_SPAWNED: 'g:0', // {0} scripted participant(s) spawned
+};

package/tests/fixtures/generations/gen-api3/manifest.json

@@ -0,0 +1,25 @@
+{
+  "id": "gen-api3",
+  "engineApi": 3,
+  "assetsBase": "",
+  "entries": {
+    "host": "host/index.js",
+    "client": "client/index.js",
+    "wasm": "core/pkg-web/core_bg.wasm",
+    "wasmNode": "core/pkg-node/core.js"
+  },
+  "roomDefaults": {
+    "maxPlayers": 4
+  },
+  "maps": [
+    "arena"
+  ],
+  "roomForm": [
+    {
+      "name": "maxPlayers",
+      "control": "range",
+      "min": 2,
+      "max": 4
+    }
+  ]
+}

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

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

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

@@ -0,0 +1,307 @@
+// ЗАМОРОЖЕНО. Снимок плагина 2026-08-29 (поколение engineApi: 4).
+// Не править: правка фикстуры маскирует слом совместимости.
+// Фейковое клиентское ядро миниигры-фикстуры: минимальная реализация
+// движкового клиентского 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-api4/client/index.js

@@ -0,0 +1,38 @@
+// ЗАМОРОЖЕНО. Снимок плагина 2026-08-29 (поколение engineApi: 4).
+// Не править: правка фикстуры маскирует слом совместимости.
+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-api4',
+  engineApi: 4,
+
+  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;
+    },
+  },
+};