vimp-engine 0.2.0 → 0.4.0

package/src/host/meta/player/HumanParticipant.js

@@ -1,4 +1,5 @@
 import Participant from './Participant.js';
+import clock from '../../../lib/clock.js';
 
 // Участник-человек: поля и поведение, специфичные для реального игрока
 class HumanParticipant extends Participant {
@@ -24,7 +25,7 @@ class HumanParticipant extends Participant {
     this.watchedGameId = watchedGameId ?? null;
     this.forceCameraReset = true;
     this.pendingShake = null;
-    this.lastActionTime = Date.now();
+    this.lastActionTime = clock.now();
     this.lastInputSeq = 0; // номер последнего обработанного ввода (предикшен)
   }
 

package/src/lib/AbstractTimer.js

@@ -1,3 +1,5 @@
+import clock from './clock.js';
+
 /**
  * @class AbstractTimer
  * @description Базовый класс для управления таймерами (setTimeout, setInterval)
@@ -25,7 +27,7 @@ class AbstractTimer {
 
     if (isInterval) {
       // setInterval живёт, пока его не остановят
-      const timerId = setInterval(callback, duration);
+      const timerId = clock.setInterval(callback, duration);
       this._timers.set(key, { timerId, isInterval });
     } else {
       // setTimeout удаляется сразу после выполнения
@@ -34,7 +36,7 @@ class AbstractTimer {
         callback();
       };
 
-      const timerId = setTimeout(wrappedCallback, duration);
+      const timerId = clock.setTimeout(wrappedCallback, duration);
       this._timers.set(key, { timerId, isInterval });
     }
   }
@@ -47,7 +49,7 @@ class AbstractTimer {
   _stopTimer(key) {
     if (this._timers.has(key)) {
       const { timerId, isInterval } = this._timers.get(key);
-      const handler = isInterval ? clearInterval : clearTimeout;
+      const handler = isInterval ? clock.clearInterval : clock.clearTimeout;
 
       handler(timerId);
 
@@ -72,7 +74,7 @@ class AbstractTimer {
   _clearAllTimers() {
     for (const timerData of this._timers.values()) {
       const { timerId, isInterval } = timerData;
-      const handler = isInterval ? clearInterval : clearTimeout;
+      const handler = isInterval ? clock.clearInterval : clock.clearTimeout;
 
       handler(timerId);
     }

package/src/lib/applyRoomOverrides.js

@@ -40,6 +40,12 @@ export function applyRoomOverrides(room = {}, plugin) {
     game.timers.mapTime = clampTime(room.mapTime);
   }
 
+  // dev-режим вкладки хоста (этап 6 плана plan/ai-debug): включает рекордер
+  // и хостовый CONSOLE-лог. Прод-бандл его не выставляет — поведение то же
+  if (typeof room.isDevMode === 'boolean') {
+    game.isDevMode = room.isDevMode;
+  }
+
   if (typeof room.friendlyFire === 'boolean') {
     game.parts.friendlyFire = room.friendlyFire;
   }

package/src/lib/clientCoreConfig.js

@@ -40,6 +40,9 @@ export const buildClientCoreConfig = (
     },
     interpolation,
     seed: undefined,
+    // детектор рассинхрона предикта: в боевом конфиге секции нет (undefined
+    // не попадает в JSON) — ядро тогда не делает на пути кадра ничего лишнего
+    divergence: undefined,
     ...overrides,
   };
 
@@ -48,6 +51,7 @@ export const buildClientCoreConfig = (
       timeStepMs: flat.timeStepMs,
       snapshot: flat.snapshot,
       interpolation: flat.interpolation,
+      divergence: flat.divergence,
     },
     game: {
       playerKeys: flat.playerKeys,

package/src/lib/clock.js

@@ -0,0 +1,53 @@
+// Единая точка доступа к времени, случайности и таймерам.
+//
+// Прод работает на реализации по умолчанию (глобалы) — поведение не меняется.
+// Headless-runner подменяет её виртуальной через install(): без этого
+// десятиминутный матч невозможно прогнать за секунды, а прогон со случайным
+// seed невозможно воспроизвести.
+//
+// now() и monotonic() разделены намеренно: игровой цикл считает dt по
+// performance.now(), разрешение которого сильно выше миллисекунды Date.now().
+// Виртуальная реализация выводит оба из одного счётчика.
+
+const defaults = {
+  now: () => Date.now(),
+  monotonic: () => performance.now(),
+  random: () => Math.random(),
+  setTimeout: (callback, delay) => setTimeout(callback, delay),
+  clearTimeout: timerId => clearTimeout(timerId),
+  setInterval: (callback, delay) => setInterval(callback, delay),
+  clearInterval: timerId => clearInterval(timerId),
+};
+
+let impl = defaults;
+
+// подменяет реализацию; недостающие методы берутся из дефолтных
+// возвращает функцию отката к предыдущей реализации
+function install(custom = {}) {
+  const previous = impl;
+
+  impl = { ...defaults, ...custom };
+
+  return () => {
+    impl = previous;
+  };
+}
+
+// возврат к глобалам
+function reset() {
+  impl = defaults;
+}
+
+// делегирование позднее (impl читается в момент вызова), чтобы install()
+// действовал на уже импортировавшие clock модули
+export default {
+  install,
+  reset,
+  now: () => impl.now(),
+  monotonic: () => impl.monotonic(),
+  random: () => impl.random(),
+  setTimeout: (callback, delay) => impl.setTimeout(callback, delay),
+  clearTimeout: timerId => impl.clearTimeout(timerId),
+  setInterval: (callback, delay) => impl.setInterval(callback, delay),
+  clearInterval: timerId => impl.clearInterval(timerId),
+};

package/src/lib/createHostRuntime.js

@@ -0,0 +1,108 @@
+import clientDefaults from '../config/clientDefaults.js';
+import wsports from '../config/wsports.js';
+import { applyRoomOverrides } from './applyRoomOverrides.js';
+import { buildClientConfig } from './buildClientConfig.js';
+import { buildCoreConfig } from './coreConfig.js';
+import { assertGameConfigShape } from './gamePlugin.js';
+import clock from './clock.js';
+import SocketManager from '../host/meta/SocketManager.js';
+import HostGame from '../host/HostGame.js';
+
+// Боевая инициализация авторитетного матча, вынутая из host.worker.js:onInit.
+// Вызывается и Worker'ом, и headless-runner'ом (devtools/ScenarioRunner.js):
+// собственная копия у runner'а неизбежно разъехалась бы с Worker'ом, а
+// расхождение здесь означало бы, что отладочный прогон проверяет не тот код,
+// который крутится в проде.
+
+/**
+ * Поднимает HostPlugin игры, ядро, SocketManager и HostGame.
+ * @param {Object} room - Описание комнаты (game.hostEntryUrl, game.wasmUrl,
+ *   game.version, hostSocketId, hostId/hostSecret, seed, переопределения).
+ * @param {Object} [options]
+ * @param {Function} [options.loadHostPlugin] - Загрузчик плагина; по умолчанию
+ *   динамический import по room.game.hostEntryUrl.
+ * @param {Function} [options.createSocketManager] - Фабрика транспорта; по
+ *   умолчанию боевой SocketManager (runner подставляет записывающий).
+ * @param {Object} [options.hostOptions] - Опции HostGame (onMapChange, handoff).
+ * @param {Function} [options.overrideGameConfig] - Правка собранного конфига
+ *   игры перед созданием ядра; в проде не задаётся, нужна отладочному
+ *   прогону (сценарий подкручивает networkSendRate и таймеры).
+ * @returns {Promise<Object>} { hostPlugin, game, seed, core, clientCfg,
+ *   socketManager, host }.
+ */
+export async function createHostRuntime(room, options = {}) {
+  const {
+    loadHostPlugin = defaultLoadHostPlugin,
+    createSocketManager = defaultCreateSocketManager,
+    hostOptions = {},
+    overrideGameConfig = null,
+  } = options;
+
+  const hostPlugin = await loadHostPlugin(room);
+
+  assertGameConfigShape(hostPlugin);
+
+  const game = applyRoomOverrides(room, hostPlugin);
+
+  if (overrideGameConfig) {
+    overrideGameConfig(game);
+  }
+
+  // seed уезжает наружу вызывающему: без него прогон матча невоспроизводим
+  // (реплей задаёт room.seed и получает тот же мир)
+  const seed =
+    room?.seed !== undefined && room.seed !== null
+      ? room.seed >>> 0
+      : (clock.random() * 2 ** 32) >>> 0;
+
+  const core = await hostPlugin.createCore(
+    JSON.stringify(
+      buildCoreConfig(hostPlugin.gameConfig, {
+        friendlyFire: game.parts.friendlyFire,
+        seed,
+      }),
+    ),
+    { wasmUrl: room.game?.wasmUrl },
+  );
+
+  const clientCfg = buildClientConfig(
+    game,
+    clientDefaults,
+    hostPlugin.buildClientGameConfig(),
+  );
+
+  const socketManager = createSocketManager(wsports.server, {
+    soundCues: game.soundCues,
+    initialVote: game.initialVote,
+  });
+
+  const host = new HostGame(game, socketManager, core, hostPlugin, {
+    hostSocketId: room?.hostSocketId ?? null,
+    gameVersion: room.game?.version ?? null,
+    // рекордер (этап 6 плана plan/ai-debug) кладёт seed в сценарий — без него
+    // записанный матч невоспроизводим
+    seed,
+    ...hostOptions,
+  });
+
+  // эстафета Worker'ов несёт уже известные hostId+секрет в room — новый
+  // Worker не должен ждать повторного register_host, чтобы возобновить
+  // атрибуцию rank/state-flush; при холодном старте они придут позже
+  if (room?.hostId) {
+    host.setHostId(room.hostId, room.hostSecret);
+  }
+
+  return { hostPlugin, game, seed, core, clientCfg, socketManager, host };
+}
+
+// до onInit движок игру не знает вовсе — только URL её host-бандла из
+// GameManifest
+function defaultLoadHostPlugin(room) {
+  return import(/* @vite-ignore */ room.game.hostEntryUrl).then(
+    module => module.default,
+  );
+}
+
+function defaultCreateSocketManager(ports, opts) {
+  return new SocketManager(ports, opts);
+}

package/src/lib/reconstructHot.js

@@ -0,0 +1,78 @@
+import { HOT_FLAGS } from '../config/opcodes.js';
+
+// Разбор плоского hot-буфера клиентского ядра. Вынесено из client/main.js:
+// раскладку читают двое — браузерный рендер-тик и headless-runner
+// (devtools/VirtualClient.js), а расходиться им нельзя.
+
+/**
+ * Строит обратный индекс снапшот-схемы игры: keyId → { key, kind, width }.
+ * Раскладку hot-буфера диктует схема игры (CONFIG_DATA.snapshot), движковый
+ * бандл её не знает.
+ * @param {Object} snapshot - Секция snapshot CONFIG_DATA.
+ * @returns {Object} Индекс по числовому id ключа.
+ */
+export const buildSnapshotKeysById = snapshot =>
+  Object.fromEntries(
+    Object.entries(snapshot).map(([key, { id, kind, fields }]) => [
+      id,
+      { key, kind, width: 2 + fields.length },
+    ]),
+  );
+
+/**
+ * Разбирает hot-буфер и сообщает, сколько float'ов ушло на разбор: длина
+ * пройденного куска обязана совпасть с длиной буфера, иначе раскладка ядра
+ * разъехалась со схемой игры (проверка инвариантов, devtools/invariants.js).
+ * @param {Float32Array} hot - Буфер рендер-тика (hot_ptr/hot_values).
+ * @param {Object} snapshotKeysById - Результат buildSnapshotKeysById.
+ * @returns {Object} { game, consumed }.
+ */
+export function parseHot(hot, snapshotKeysById) {
+  const game = {};
+  let i = 3;
+
+  const readRecord = () => {
+    const spec = snapshotKeysById[hot[i]];
+
+    if (!spec) {
+      throw new Error(`hot buffer: unknown snapshot key id ${hot[i]}`);
+    }
+
+    const { key, kind, width } = spec;
+    const id = kind === 'indexedNoNull8' ? `d${hot[i + 1]}` : hot[i + 1];
+
+    (game[key] ??= {})[id] = Array.from(hot.subarray(i + 2, i + width));
+    i += width;
+  };
+
+  // две группы: Indexed8 (акторы), затем IndexedNoNull8 (динамика карты)
+  for (let g = 0; g < 2; g += 1) {
+    const count = hot[i];
+
+    i += 1;
+
+    for (let n = 0; n < count; n += 1) {
+      readRecord();
+    }
+  }
+
+  if (hot[0] & HOT_FLAGS.PREDICTED) {
+    readRecord();
+  }
+
+  return { game, consumed: i };
+}
+
+/**
+ * Восстанавливает объект игровых данных из плоского hot-буфера ядра:
+ * [3] N записей Indexed8-группы, затем M записей IndexedNoNull8-группы;
+ * каждая запись — keyId, id, поля по схеме игры (ширина = 2 + fields);
+ * у IndexedNoNull8 id получает префикс 'd' (динамика карты, зеркало
+ * snapshot_to_json ядра). Predicted-запись (последняя) перекрывает свою —
+ * предикт поверх интерполяции тем же parse-конвейером.
+ * @param {Float32Array} hot - Буфер рендер-тика (hot_ptr/hot_values).
+ * @param {Object} snapshotKeysById - Результат buildSnapshotKeysById.
+ * @returns {Object} { [ключ схемы]: { [id]: [поля] } }.
+ */
+export const reconstructHot = (hot, snapshotKeysById) =>
+  parseHot(hot, snapshotKeysById).game;

package/src/lib/validators.js

@@ -53,3 +53,13 @@ export const validateAuth = (data, authParams, validators = {}) => {
 
   return errors.length ? errors : undefined;
 };
+
+// клампит query-параметр в целое [1, max]; невалидное значение — fallback
+// (lobby-page-plan: GET /auth/leaderboard?limit=, мастер клампит ещё раз
+// перед проксированием). Вынесено из master/main.js (code review L3), чтобы
+// клампинг был покрыт юнит-тестом отдельно от роута
+export const clampLimit = (value, fallback, max) => {
+  const num = Number(value);
+
+  return Number.isInteger(num) ? Math.min(Math.max(num, 1), max) : fallback;
+};

package/tests/fixtures/miniGame/client/fakeClientCore.js

@@ -0,0 +1,304 @@
+// Фейковое клиентское ядро миниигры-фикстуры: минимальная реализация
+// движкового клиентского ABI (см. export_client_core_abi!, PLAN.md §3.4).
+//
+// Кадры фикстуры — не бинарный кодек ядра, а JSON (см. host/fakeCore.js:
+// frame_bytes), поэтому push_frame их просто разбирает, а интерполяции нет:
+// sample() отдаёт последний принятый кадр. Раскладка hot-буфера при этом
+// настоящая (флаги, две группы, ширина записи = 2 + поля схемы) — именно её
+// читает движковый reconstructHot, и именно она замыкает headless-контур
+// «хост → байты → клиентское ядро → сцена» без WASM.
+
+import { HOT_FLAGS } from '../../../../src/config/opcodes.js';
+
+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/miniGame/client/index.js

@@ -0,0 +1,37 @@
+import { ENGINE_API_VERSION } from '../../../../src/config/opcodes.js';
+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: 'miniGame',
+  engineApi: ENGINE_API_VERSION,
+
+  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;
+    },
+  },
+};