vimp-engine 0.2.0 → 0.4.0

package/src/devtools/VirtualClient.js

@@ -0,0 +1,363 @@
+import { buildClientCoreConfig } from '../lib/clientCoreConfig.js';
+import { buildSnapshotKeysById, parseHot } from '../lib/reconstructHot.js';
+import { HOT_FLAGS } from '../config/opcodes.js';
+
+// Клиент без браузера: настоящее клиентское ядро игры, которое кормится
+// реальными байтами кадров, отправленными хостом. Замыкает контур
+// «хост → бинарный кадр → ClientCore → hot-буфер → сцена в JSON» в одном
+// процессе — без этого отказы тира 1–2 (сущность не спавнится, поля схемы
+// перепутаны, панель не обновляется) не видны нигде, кроме чёрного холста.
+//
+// Рендер-конвейер повторяет client/main.js:renderTick, но hot читается через
+// hot_values() (копия), а не hot_ptr()+память WASM: в Node нет смысла в
+// zero-copy, а копия не детачится при росте памяти ядра.
+
+// предел числа сохраняемых однотипных нарушений (дальше только счётчик)
+const NOTE_LIMIT = 20;
+
+class VirtualClient {
+  /**
+   * @param {Object} params
+   * @param {Object} params.clientPlugin - ClientPlugin игры.
+   * @param {Object} params.clientConfig - CONFIG_DATA хоста.
+   * @param {string} [params.wasmUrl] - Путь к клиентскому ядру (node-сборка).
+   * @param {string} params.socketId
+   * @param {number} params.gameId
+   * @param {Object} [params.auth] - Данные авторизации участника
+   *   ({ name, model }) — то же, что уходит хосту в createUser.
+   * @param {Object} [params.divergence] - Пороги детектора рассинхрона
+   *   предикта (thresholds/defaultThreshold/capacity); undefined — детектор
+   *   выключен, как в боевом конфиге.
+   * @returns {Promise<VirtualClient>}
+   */
+  static async create({
+    clientPlugin,
+    clientConfig,
+    wasmUrl,
+    socketId,
+    gameId,
+    auth,
+    divergence,
+  }) {
+    const { core } = await clientPlugin.createClientCore(
+      JSON.stringify(buildClientCoreConfig(clientConfig, { divergence })),
+      { wasmUrl },
+    );
+
+    const client = new VirtualClient({
+      core,
+      clientConfig,
+      socketId,
+      gameId,
+      clientPlugin,
+    });
+
+    // игровой хук авторизации (в браузере — publisher 'socket' формы auth):
+    // без него ядро не знает модель своего актора, а значит и предикт
+    // никогда не включается
+    if (auth) {
+      clientPlugin.hooks?.onAuth?.(core, auth);
+    }
+
+    return client;
+  }
+
+  constructor({ core, clientConfig, socketId, gameId, clientPlugin }) {
+    this.socketId = socketId;
+    this.gameId = gameId;
+    this.core = core;
+
+    this._plugin = clientPlugin;
+
+    this._snapshotKeysById = buildSnapshotKeysById(clientConfig.snapshot);
+    this._gameSets = clientConfig.parts.gameSets;
+    this._entitiesOnCanvas = clientConfig.parts.entitiesOnCanvas;
+
+    // накопленная сцена: ключ схемы → id → поля (то, что в браузере ушло бы
+    // в parts через Factory)
+    this.scene = {};
+    this.camera = null;
+
+    // всё, что приехало по не-кадровым портам — материал для проверок
+    // инвариантов (этап 3) и для отчёта
+    this.received = {
+      panel: [],
+      stat: [],
+      chat: [],
+      vote: [],
+      keySet: [],
+      gameInform: [],
+      soundCue: [],
+      roundEnd: [],
+      techInform: [],
+    };
+
+    this.frameCount = 0;
+    this.decodeErrors = [];
+
+    // материал проверок инвариантов (devtools/invariants.js): что реально
+    // доехало до сцены за весь прогон, а не только к финальному тику —
+    // сущность могла появиться и исчезнуть между дампами
+    this.observed = {}; // ключ схемы → { rows, ids: Set, widths: Set }
+    this.nonFinite = []; // NaN/Infinity в декодированных полях и hot-буфере
+    this.hotLayoutErrors = []; // расхождение len ↔ пройденного куска буфера
+
+    // расхождение предикта с авторитетным состоянием (этап 5): записи ядра
+    // и накопительные агрегаты; null в stats — детектор выключен или ядро
+    // игры собрано против движка без него
+    this.divergence = [];
+    this.divergenceStats = null;
+
+    // нарушение обычно повторяется каждый тик: в отчёте нужны первые
+    // экземпляры и счётчик, а не сотня одинаковых строк
+    this.truncated = { nonFinite: 0, hotLayoutErrors: 0, divergence: 0 };
+  }
+
+  // байты кадра из sendShot — ровно то, что ушло бы в data channel
+  pushFrame(bytes, localNow) {
+    const data = toUint8(bytes);
+
+    try {
+      this.core.push_frame(data, localNow);
+      this.frameCount += 1;
+    } catch (e) {
+      this.decodeErrors.push({ localNow, message: String(e) });
+    }
+  }
+
+  // не-кадровые порты (панель, статистика, чат, keyset…). Порты, которые в
+  // браузере доходят до ядра (main.js), доводятся и здесь — иначе headless
+  // гоняет ядро в режиме, которого в игре не бывает.
+  record(kind, data) {
+    if (this.received[kind]) {
+      this.received[kind].push(data);
+    }
+
+    if (kind === 'panel') {
+      this._plugin?.hooks?.onPanel?.(this.core, data);
+    } else if (kind === 'keySet') {
+      // keySet 1 — играющий, иначе спектатор (предикт выключается)
+      this.core.set_active?.(data === 1);
+    }
+  }
+
+  /**
+   * MAP_DATA: мир raycast в ядре и сброс предикта — зеркало main.js.
+   * @param {Object} data - Данные карты, как их шлёт хост.
+   */
+  setMap(data) {
+    if (typeof this.core.set_map !== 'function') {
+      return;
+    }
+
+    try {
+      this.core.set_map(
+        JSON.stringify({
+          map: data.map,
+          step: data.step,
+          scale: data.scale,
+          physicsStatic: data.physicsStatic,
+          physicsDynamic: data.physicsDynamic,
+        }),
+      );
+    } catch (e) {
+      this.decodeErrors.push({ localNow: null, message: `set_map: ${e}` });
+    }
+  }
+
+  /**
+   * Рендер-тик: зеркало client/main.js:renderTick без PixiJS.
+   * @param {number} localNow - Локальное время клиента (мс).
+   */
+  render(localNow) {
+    // записи копятся в ядре на push_frame, поэтому вычерпываются до sample —
+    // иначе тик с пустым hot-буфером (ранний выход ниже) их бы потерял
+    this._drainDivergence();
+
+    const len = this.core.sample(localNow);
+
+    if (!len) {
+      return;
+    }
+
+    const hot = this.core.hot_values();
+    const flags = hot[0];
+
+    for (let i = 0; i < len; i += 1) {
+      if (!Number.isFinite(hot[i])) {
+        this._note('nonFinite', {
+          key: 'hot',
+          id: 'buffer',
+          index: i,
+          value: String(hot[i]),
+        });
+      }
+    }
+
+    if (flags & HOT_FLAGS.FRAMES) {
+      for (const frame of JSON.parse(this.core.take_frames())) {
+        this._applyGameData(frame.game);
+
+        if (frame.camera && frame.camera !== 0) {
+          this.camera = [frame.camera[0], frame.camera[1]];
+        }
+      }
+    }
+
+    if (flags & (HOT_FLAGS.GAME | HOT_FLAGS.PREDICTED)) {
+      let parsed;
+
+      try {
+        parsed = parseHot(hot, this._snapshotKeysById);
+      } catch (e) {
+        this._note('hotLayoutErrors', { len, message: String(e) });
+        return;
+      }
+
+      // раскладку буфера диктует схема игры: разошлась ширина записи или
+      // порядок групп — обход упрётся не в конец буфера
+      if (parsed.consumed !== len) {
+        this._note('hotLayoutErrors', { len, consumed: parsed.consumed });
+      }
+
+      this._applyGameData(parsed.game);
+    }
+
+    if (flags & HOT_FLAGS.CAMERA) {
+      this.camera = [hot[1], hot[2]];
+    }
+  }
+
+  /**
+   * Дамп клиентского ядра (сетевой буфер, окно seq, оффсет) — зеркало
+   * серверного `debug_json`. null, если ядро игры собрано против движка
+   * без этого метода.
+   * @returns {Object|null}
+   */
+  debug() {
+    if (typeof this.core.debug_json !== 'function') {
+      return null;
+    }
+
+    return JSON.parse(this.core.debug_json());
+  }
+
+  // Записи детектора рассинхрона предикта из ядра. Агрегаты накопительные,
+  // поэтому просто перезаписываются; записи — вычерпываются.
+  _drainDivergence() {
+    if (typeof this.core.take_divergence !== 'function') {
+      return;
+    }
+
+    const dump = JSON.parse(this.core.take_divergence());
+
+    if (!dump) {
+      return;
+    }
+
+    const { records = [], ...stats } = dump;
+
+    this.divergenceStats = stats;
+
+    for (const record of records) {
+      this._note('divergence', record);
+    }
+  }
+
+  // Срез сцены для дампа и для дифа между тиками. Копия обязательна: сцена
+  // живая, и срез по ссылке «догонял» бы последующие тики — все дампы вышли
+  // бы одинаковыми.
+  snapshot() {
+    return {
+      socketId: this.socketId,
+      gameId: this.gameId,
+      camera: this.camera ? [...this.camera] : null,
+      frameCount: this.frameCount,
+      entities: structuredClone(this.scene),
+      debug: this.debug(),
+      // накопительные агрегаты дрейфа предикта на момент среза
+      divergence: this.divergenceStats,
+    };
+  }
+
+  // зеркало applyGameData клиента: ключ схемы → parts через gameSets;
+  // отсутствие ключа в gameSets — это и есть «чёрный холст», поэтому
+  // фиксируется, а не игнорируется
+  _applyGameData(game) {
+    for (const [key, instances] of Object.entries(game)) {
+      const names = this._gameSets[key];
+
+      if (!names) {
+        this.decodeErrors.push({
+          message: `snapshot key '${key}' is missing from parts.gameSets`,
+        });
+        continue;
+      }
+
+      for (const name of names) {
+        if (!this._entitiesOnCanvas[name]) {
+          this.decodeErrors.push({
+            message: `part '${name}' is missing from parts.entitiesOnCanvas`,
+          });
+        }
+      }
+
+      const bucket = (this.scene[key] ??= {});
+      const seen = (this.observed[key] ??= {
+        rows: 0,
+        ids: new Set(),
+        widths: new Set(),
+      });
+
+      for (const [id, fields] of Object.entries(instances)) {
+        if (fields === null) {
+          delete bucket[id];
+          continue;
+        }
+
+        bucket[id] = fields;
+        seen.rows += 1;
+        seen.ids.add(String(id));
+        seen.widths.add(Array.isArray(fields) ? fields.length : -1);
+
+        this._checkFinite(key, id, fields);
+      }
+    }
+  }
+
+  // NaN/Infinity в поле — самый тихий из отказов: холст просто перестаёт
+  // рисовать сущность, ошибки нет нигде
+  _checkFinite(key, id, fields) {
+    const values = Array.isArray(fields) ? fields : [fields];
+
+    values.forEach((value, index) => {
+      if (typeof value === 'number' && !Number.isFinite(value)) {
+        this._note('nonFinite', {
+          key,
+          id: String(id),
+          index,
+          value: String(value),
+        });
+      }
+    });
+  }
+
+  _note(name, entry) {
+    if (this[name].length < NOTE_LIMIT) {
+      this[name].push(entry);
+    } else {
+      this.truncated[name] += 1;
+    }
+  }
+}
+
+// кадр приходит как ArrayBuffer (боевой транспорт) либо Uint8Array (ядро)
+function toUint8(bytes) {
+  if (bytes instanceof Uint8Array) {
+    return bytes;
+  }
+
+  return new Uint8Array(bytes);
+}
+
+export default VirtualClient;

package/src/devtools/VirtualClock.js

@@ -0,0 +1,169 @@
+import clock from '../lib/clock.js';
+
+// Виртуальное время для headless-прогона: очередь отложенных задач + advance().
+// Без него десятиминутный матч невозможно прогнать за секунды, а два прогона
+// одного сценария не совпадут побайтово.
+//
+// Случайность тоже здесь: mulberry32 — маленький, полностью воспроизводимый
+// PRNG (тот же seed → та же последовательность), в отличие от Math.random.
+
+// одна итерация mulberry32
+const mulberry32 = seed => {
+  let state = seed >>> 0;
+
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+
+    let t = state;
+
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+class VirtualClock {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.startTime] - Стартовая метка эпохи (мс) для now().
+   * @param {number} [options.seed] - Seed PRNG для random().
+   */
+  constructor({ startTime = 1700000000000, seed = 1 } = {}) {
+    this._startTime = startTime;
+    // единый виртуальный счётчик: now() и monotonic() не могут разъехаться
+    this._elapsed = 0;
+    this._nextId = 1;
+    this._tasks = new Map(); // id → { time, callback, interval }
+    this._random = mulberry32(seed);
+  }
+
+  // ***** реализация clock ***** //
+
+  now() {
+    return this._startTime + this._elapsed;
+  }
+
+  monotonic() {
+    return this._elapsed;
+  }
+
+  random() {
+    return this._random();
+  }
+
+  setTimeout(callback, delay = 0) {
+    return this._schedule(callback, delay, null);
+  }
+
+  setInterval(callback, delay = 0) {
+    // нулевой интервал зациклил бы advance() навсегда
+    return this._schedule(callback, delay, Math.max(1, delay));
+  }
+
+  clearTimeout(timerId) {
+    this._tasks.delete(timerId);
+  }
+
+  clearInterval(timerId) {
+    this._tasks.delete(timerId);
+  }
+
+  // ***** управление ***** //
+
+  /**
+   * Подменяет глобальный clock этим экземпляром.
+   * @returns {Function} Функция отката.
+   */
+  install() {
+    return clock.install({
+      now: () => this.now(),
+      monotonic: () => this.monotonic(),
+      random: () => this.random(),
+      setTimeout: (callback, delay) => this.setTimeout(callback, delay),
+      clearTimeout: timerId => this.clearTimeout(timerId),
+      setInterval: (callback, delay) => this.setInterval(callback, delay),
+      clearInterval: timerId => this.clearInterval(timerId),
+    });
+  }
+
+  /**
+   * Прокручивает время на ms, выполняя созревшие задачи в порядке
+   * (время, номер регистрации). Между задачами вычерпываются микрозадачи —
+   * иначе очередь HostGame (queueMicrotask в createUser) отстаёт от таймеров.
+   * @param {number} ms
+   */
+  async advance(ms) {
+    const target = this._elapsed + ms;
+
+    for (;;) {
+      const next = this._earliest(target);
+
+      if (!next) {
+        break;
+      }
+
+      this._elapsed = next.time;
+
+      if (next.interval === null) {
+        this._tasks.delete(next.id);
+      } else {
+        next.time += next.interval;
+      }
+
+      next.callback();
+
+      await flushMicrotasks();
+    }
+
+    this._elapsed = target;
+
+    await flushMicrotasks();
+  }
+
+  // число зарегистрированных задач (диагностика утечек таймеров)
+  get pendingCount() {
+    return this._tasks.size;
+  }
+
+  _schedule(callback, delay, interval) {
+    const id = this._nextId;
+
+    this._nextId += 1;
+    this._tasks.set(id, {
+      id,
+      time: this._elapsed + Math.max(0, delay),
+      callback,
+      interval,
+    });
+
+    return id;
+  }
+
+  // ближайшая задача не позже target; при равном времени — та, что
+  // зарегистрирована раньше (иначе порядок зависел бы от обхода Map)
+  _earliest(target) {
+    let found = null;
+
+    for (const task of this._tasks.values()) {
+      if (task.time > target) {
+        continue;
+      }
+
+      if (
+        !found ||
+        task.time < found.time ||
+        (task.time === found.time && task.id < found.id)
+      ) {
+        found = task;
+      }
+    }
+
+    return found;
+  }
+}
+
+export const flushMicrotasks = () =>
+  new Promise(resolve => queueMicrotask(resolve));
+
+export default VirtualClock;

package/src/devtools/inspectHost.js

@@ -0,0 +1,31 @@
+// Срез меты хоста для проверок инвариантов. Читает приватные поля HostGame
+// намеренно: отладочный контур не должен ради себя расширять боевой API
+// хоста, а держать копию реестра участников в runner'е — значит проверять
+// не то состояние, которым живёт матч. Весь доступ к внутренностям собран
+// здесь, чтобы правка HostGame ломала один файл, а не пол-devtools.
+
+/**
+ * @param {Object} host - HostGame прогона.
+ * @returns {Object} { activeList, humans, scripted, total, currentMap }.
+ */
+export function inspectHost(host) {
+  const participants = host._participants;
+
+  return {
+    activeList: participants.getActiveList().map(String),
+    humans: participants.getHumans().map(user => String(user.gameId)),
+    scripted: participants.getScripted().map(user => String(user.gameId)),
+    total: participants.totalCount,
+    currentMap: host.currentMap,
+  };
+}
+
+/**
+ * Курированный дамп мира ядра через адаптер хоста (этап 4). null, если
+ * ядро игры собрано против движка без `debug_json`.
+ * @param {Object} host - HostGame прогона.
+ * @returns {Object|null}
+ */
+export function inspectCore(host) {
+  return host._game.debugJson();
+}