vimp-engine 0.3.0 → 0.5.0

package/src/devtools/pluginLoader.js

@@ -0,0 +1,145 @@
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertEngineApiCompatible } from '../lib/gamePlugin.js';
+
+// Поиск игры для headless-прогона. В браузере плагин грузится по URL из
+// GameManifest мастера; в Node URL-ов нет, поэтому источников три, по
+// убыванию точности:
+//
+//   1. --game <путь>  — каталог пакета игры или прямо dist/manifest.json;
+//   2. --core <путь>  — переопределение node-сборки ядра (entries.wasmNode);
+//   3. ничего         — фикстура miniGame из этого репозитория.
+//
+// entries.wasmNode — новое ОПЦИОНАЛЬНОЕ поле манифеста: конвенция
+// core/pkg-node/ уже описана в docs/ai/02-packaging.md, не хватало только
+// пути в манифесте. Его отсутствие не ошибка — просто игра не прогоняется
+// headless своим настоящим ядром.
+
+const FIXTURE_DIR = new URL(
+  '../../tests/fixtures/miniGame/',
+  import.meta.url,
+);
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.game] - Путь к пакету игры или к манифесту.
+ * @param {string} [options.core] - Путь к node-сборке ядра (перекрывает
+ *   entries.wasmNode манифеста).
+ * @returns {Promise<Object>} { id, hostPlugin, clientPlugin, wasmUrl, manifest,
+ *   source }.
+ */
+export async function loadGameForSim({ game = null, core = null } = {}) {
+  if (!game) {
+    return loadFixture(core);
+  }
+
+  const manifestPath = game.endsWith('.json')
+    ? path.resolve(game)
+    : path.resolve(game, 'dist/manifest.json');
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+
+  assertEngineApiCompatible(manifest);
+
+  const baseDir = path.dirname(manifestPath);
+  const { assetsBase } = manifest;
+  const hostPlugin = await importDefault(
+    baseDir,
+    manifest.entries.host,
+    assetsBase,
+  );
+  const clientPlugin = await importDefault(
+    baseDir,
+    manifest.entries.client,
+    assetsBase,
+  );
+
+  assertPluginMatchesManifest(manifest, {
+    host: hostPlugin,
+    client: clientPlugin,
+  });
+
+  const nodeCore = core ?? manifest.entries.wasmNode ?? null;
+
+  if (!nodeCore) {
+    throw new Error(
+      `${manifestPath}: no node build of the core — add entries.wasmNode ` +
+        `to the manifest (core/pkg-node) or pass --core <path>`,
+    );
+  }
+
+  const corePath = path.resolve(baseDir, nodeCore);
+
+  // манифест объявляет поле, но опубликованный пакет мог не довезти файл
+  // (ignore-правила срезают каталог внутри files) — без этой проверки отказ
+  // приходит сырым ERR_MODULE_NOT_FOUND из резолвера
+  try {
+    await access(corePath);
+  } catch {
+    throw new Error(
+      `${manifestPath}: entries.wasmNode points at '${nodeCore}', but ` +
+        `${corePath} does not exist — the game package was published ` +
+        `without its node core (npm run core:build:node) or pass --core <path>`,
+    );
+  }
+
+  return {
+    id: manifest.id,
+    manifest,
+    hostPlugin,
+    clientPlugin,
+    wasmUrl: pathToFileURL(path.resolve(baseDir, nodeCore)).href,
+    source: manifestPath,
+  };
+}
+
+// фикстура даёт рабочий контур сразу, ещё до того как игра соберёт pkg-node:
+// её ядра — обычный JS, поэтому wasmUrl не нужен
+async function loadFixture(core) {
+  const [hostPlugin, clientPlugin] = await Promise.all([
+    import(new URL('host/index.js', FIXTURE_DIR).href).then(m => m.default),
+    import(new URL('client/index.js', FIXTURE_DIR).href).then(m => m.default),
+  ]);
+
+  return {
+    id: hostPlugin.id,
+    manifest: null,
+    hostPlugin,
+    clientPlugin,
+    wasmUrl: core ? pathToFileURL(path.resolve(core)).href : undefined,
+    source: 'fixture:miniGame',
+  };
+}
+
+// зеркало lib/gamePlugin.js:loadClientPlugin — манифест мог быть пересобран
+// без dist/: прогон на старом плагине даёт зелёный вердикт о том, чего в
+// сборке уже нет
+function assertPluginMatchesManifest(manifest, plugins) {
+  for (const [half, plugin] of Object.entries(plugins)) {
+    if (plugin.engineApi !== manifest.engineApi) {
+      throw new Error(
+        `game "${manifest.id}": ${half} plugin engineApi ` +
+          `v${plugin.engineApi} does not match manifest engineApi ` +
+          `v${manifest.engineApi} — stale dist/`,
+      );
+    }
+  }
+}
+
+function importDefault(baseDir, entry, assetsBase) {
+  const file = path.resolve(baseDir, stripBase(entry, assetsBase));
+
+  return import(pathToFileURL(file).href).then(module => module.default);
+}
+
+// entries.host/client — URL-ы, какими их видит браузер (`assetsBase` + путь
+// внутри пакета). На диске этой базе соответствует каталог манифеста,
+// поэтому абсолютный URL сначала обрезается до пути внутри пакета — иначе
+// path.resolve увёл бы в корень файловой системы.
+function stripBase(entry, assetsBase) {
+  if (assetsBase && entry.startsWith(assetsBase)) {
+    return entry.slice(assetsBase.length);
+  }
+
+  return entry.replace(/^\/+/, '');
+}

package/src/devtools/report.js

@@ -0,0 +1,204 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// Отчёт прогона на диск: report.json (машинный), report.md (то, что читает
+// нейросеть) и по файлу на каждый снятый срез сцены. Текстовый вердикт —
+// главный смысл всей затеи: молчаливый отказ должен становиться строкой.
+
+/**
+ * @param {Object} report - Результат runScenario (плюс invariants этапа 3).
+ * @param {Object} [options]
+ * @param {string} [options.outDir] - Корень для .debug/run-<ts>.
+ * @param {string} [options.stamp] - Метка прогона (по умолчанию — ISO-время).
+ * @returns {Promise<string>} Каталог прогона.
+ */
+export async function writeReport(report, { outDir = '.debug', stamp } = {}) {
+  const runStamp = stamp ?? new Date().toISOString().replace(/[:.]/g, '-');
+  const runDir = path.resolve(outDir, `run-${runStamp}`);
+
+  await mkdir(runDir, { recursive: true });
+
+  // срезы сцены — отдельными файлами: они самые объёмные и читаются точечно.
+  // shotHashes — служебный материал самопроверки детерминизма (длина = число
+  // кадров матча), в читаемом отчёте ему делать нечего
+  const { scenes = [], shotHashes, ...rest } = report;
+
+  await Promise.all(
+    scenes.map(scene =>
+      writeFile(
+        path.join(runDir, `scene-${scene.tick}.json`),
+        `${JSON.stringify(scene, null, 2)}\n`,
+      ),
+    ),
+  );
+
+  await writeFile(
+    path.join(runDir, 'report.json'),
+    `${JSON.stringify({ ...rest, sceneTicks: scenes.map(s => s.tick) }, null, 2)}\n`,
+  );
+
+  await writeFile(path.join(runDir, 'report.md'), formatMarkdown(report));
+
+  return runDir;
+}
+
+/**
+ * Человекочитаемая сводка прогона.
+ * @param {Object} report
+ * @returns {string}
+ */
+export function formatMarkdown(report) {
+  const lines = [];
+
+  lines.push(`# Simulation report — ${report.game.id}`);
+  lines.push('');
+  lines.push(`- game source: \`${report.game.source}\``);
+  lines.push(`- seed: \`${report.seed}\``);
+  lines.push(
+    `- ticks: ${report.scenario.ticks} × ${report.stepMs} ms = ${report.durationMs} ms`,
+  );
+  lines.push(`- map: \`${report.currentMap}\``);
+  lines.push(`- participants: ${report.participants.length}`);
+  lines.push('');
+
+  lines.push(...invariantSection(report));
+  lines.push(...worldSection(report));
+  lines.push(...driftSection(report));
+
+  lines.push('## Outgoing frames');
+  lines.push('');
+  lines.push('| method | count |');
+  lines.push('| --- | --- |');
+
+  for (const [method, count] of Object.entries(report.frameCounts).sort()) {
+    lines.push(`| ${method} | ${count} |`);
+  }
+
+  lines.push('');
+  lines.push('## Clients');
+  lines.push('');
+
+  for (const client of report.clients) {
+    const entities = Object.entries(client.entities)
+      .map(([key, ids]) => `${key}×${Object.keys(ids).length}`)
+      .join(', ');
+
+    lines.push(
+      `- \`${client.socketId}\` (gameId ${client.gameId}): ${client.frameCount} frames, ` +
+        `entities: ${entities || '(none)'}, camera: ${JSON.stringify(client.camera)}`,
+    );
+
+    for (const error of client.decodeErrors) {
+      lines.push(`  - ⚠️ ${error.message}`);
+    }
+  }
+
+  if (report.mapChanges.length) {
+    lines.push('');
+    lines.push('## Map changes');
+    lines.push('');
+
+    for (const change of report.mapChanges) {
+      lines.push(`- tick ${change.tick}: \`${change.map}\``);
+    }
+  }
+
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+// Сводка дампа мира ядра последнего среза (этап 4): счётчики отвечают на
+// «есть ли в мире то, чего нет на холсте» без открывания scene-*.json.
+function worldSection(report) {
+  const scenes = report.scenes ?? [];
+  const last = [...scenes].reverse().find(scene => scene.core);
+
+  if (!last) {
+    return [];
+  }
+
+  const { core } = last;
+  const lines = ['## World (core dump)', ''];
+
+  lines.push(`Tick ${last.tick} — \`scene-${last.tick}.json\``);
+  lines.push('');
+  lines.push(`- bodies: ${core.bodies?.length ?? 0}`);
+  lines.push(`- colliders: ${core.colliders?.length ?? 0}`);
+  lines.push(`- map: ${core.map ? `\`${core.map.setId}\`` : '(none)'}`);
+  lines.push(
+    `- nav nodes: ${core.nav ? core.nav.nodes : '(no nav graph)'}` +
+      `, spatial entities: ${core.spatial?.entities ?? 0}`,
+  );
+  lines.push(
+    `- rng state: \`${core.rng?.state}\`, accumulator: ${core.step?.accumulator}`,
+  );
+  lines.push('');
+
+  return lines;
+}
+
+// Дрейф предикта (этап 5): максимум расхождения по компонентам player-блока
+// за прогон и первые записи. Сопоставление — по времени кадра, а не по seq:
+// предиктор переигрывает историю ввода от момента авторитетного состояния.
+function driftSection(report) {
+  const tracked = report.clients.filter(client => client.divergence);
+
+  if (!tracked.length) {
+    return [];
+  }
+
+  const lines = ['## Prediction drift', ''];
+
+  for (const client of tracked) {
+    const drift = client.divergence;
+
+    lines.push(
+      `- \`${client.socketId}\`: ${drift.samples} reconciliation(s), ` +
+        `${drift.violations} over threshold, max |Δ| per component: ` +
+        `[${(drift.maxDelta ?? []).join(', ')}]`,
+    );
+
+    for (const record of drift.records ?? []) {
+      lines.push(
+        `  - serverTime ${record.serverTime} (source \`${record.source}\`): ` +
+          `Δ [${(record.delta ?? []).join(', ')}]`,
+      );
+    }
+  }
+
+  lines.push('');
+
+  return lines;
+}
+
+// Ради этой секции всё и затевалось: нарушенный контракт — строка с именем
+// проверки, а не тишина.
+function invariantSection(report) {
+  const results = report.invariants ?? [];
+
+  if (!results.length) {
+    return [];
+  }
+
+  const { passed, failed, skipped } = report.invariantSummary ?? {};
+  const lines = ['## Invariants', ''];
+
+  lines.push(`${passed} passed, ${failed} failed, ${skipped} skipped`);
+  lines.push('');
+
+  for (const check of results) {
+    const mark = { pass: '✅', fail: '❌', skip: '⏭️' }[check.status];
+    const note = check.note ? ` — ${check.note}` : '';
+
+    lines.push(`- ${mark} ${check.id}. \`${check.name}\`: ${check.title}${note}`);
+
+    for (const violation of check.violations) {
+      lines.push(`  - ${violation}`);
+    }
+  }
+
+  lines.push('');
+
+  return lines;
+}

package/src/devtools/resetHostSingletons.js

@@ -0,0 +1,23 @@
+import { resetTimerManager } from '../host/meta/modules/TimerManager.js';
+import { resetPanel } from '../host/meta/modules/Panel.js';
+import { resetStat } from '../host/meta/modules/Stat.js';
+import { resetVote } from '../host/meta/modules/Vote.js';
+import { resetChat } from '../host/meta/modules/chat/index.js';
+
+// Мета-модули хоста — синглтоны на модуль: в браузерной вкладке матч всегда
+// один, и второй `new TimerManager(...)` молча возвращает первый. Для
+// headless-прогона это ловушка: второй прогон в том же процессе получил бы
+// таймеры первого (со ссылками на его HostGame и на уже выброшенные
+// виртуальные часы) и не сделал бы ни одного тика — молча.
+//
+// Самопроверка детерминизма прогоняет сценарий дважды подряд, поэтому
+// изоляция обязана быть явной.
+export function resetHostSingletons() {
+  resetTimerManager();
+  resetPanel();
+  resetStat();
+  resetVote();
+  resetChat();
+}
+
+export default resetHostSingletons;

package/src/host/DebugRecorder.js

@@ -0,0 +1,227 @@
+import clock from '../lib/clock.js';
+
+// Рекордер живого матча (этап 6 плана plan/done/ai-debug): пишет то, что headless
+// не воспроизводит — реальный WebRTC, PixiJS и живой ввод человека — ровно в
+// формат сценария headless-runner'а (devtools/ScenarioRunner.js). Баг,
+// пойманный человеком в браузере, догоняется потом `npm run sim:replay`
+// без браузера и без человека.
+//
+// Worker-safe: только clock (Date/performance), никаких Node-глобалов.
+// Включается флагом gameConfig.isDevMode — в проде HostGame его не создаёт.
+
+// Кап записи: живой матч на 120 Гц за десять минут — 72k тиков, и без
+// границы вкладка хоста платила бы памятью за бесконечную ленту. Переполнение
+// не молчит: счётчики уезжают в meta сценария.
+const DEFAULT_LIMITS = {
+  maxOps: 20000,
+  maxDtSamples: 4000,
+};
+
+export default class DebugRecorder {
+  /**
+   * @param {Object} [limits]
+   * @param {number} [limits.maxOps] - Предел операций таймлайна.
+   * @param {number} [limits.maxDtSamples] - Предел записанных шагов цикла.
+   */
+  constructor(limits = {}) {
+    this._limits = { ...DEFAULT_LIMITS, ...limits };
+    this._reset();
+  }
+
+  get isRecording() {
+    return this._recording;
+  }
+
+  // номер тика с начала записи: сценарий адресует ввод именно границей тика
+  // (очереди у HostGame нет, updateKeys применяется синхронно)
+  get tickCount() {
+    return this._tick;
+  }
+
+  /**
+   * Начинает запись. Уже вошедшие участники превращаются в join-операции
+   * нулевого тика — иначе реплей стартовал бы с пустой комнатой.
+   * @param {Object} params
+   * @param {number|null} params.seed - Seed мира (room.seed / 'ready').
+   * @param {string} params.map - Текущая карта.
+   * @param {number} [params.networkSendRate] - Частота отправки кадров.
+   * @param {Array} [params.participants] - [{ gameId, name, model, socketId,
+   *   team }] — люди, уже находящиеся в комнате.
+   */
+  start({ seed = null, map = null, networkSendRate = null, participants = [] }) {
+    this._reset();
+
+    this._recording = true;
+    this._seed = seed;
+    this._map = map;
+    this._networkSendRate = networkSendRate;
+    this._startedAt = clock.now();
+
+    for (const participant of participants) {
+      this.noteJoin(participant);
+    }
+  }
+
+  // шаг игрового цикла: номер тика — единственная временная координата
+  // сценария, dt пишется справочно (runner крутит фиксированный timeStep)
+  tick(dt) {
+    if (!this._recording) {
+      return;
+    }
+
+    this._tick += 1;
+
+    if (this._dt.length < this._limits.maxDtSamples) {
+      this._dt.push(dt);
+    } else {
+      this._droppedDt += 1;
+    }
+  }
+
+  /**
+   * Вход участника. Идентификатор сценария выдаётся свой (p1, p2, …):
+   * gameId переиспользуется после выхода, и два разных человека получили бы
+   * в реплее одну запись.
+   * @param {Object} participant - { gameId, name, model, socketId, team }.
+   */
+  noteJoin({ gameId, name, model, socketId, team = null }) {
+    if (!this._recording) {
+      return;
+    }
+
+    const who = `p${this._participants.length + 1}`;
+
+    this._participants.push({ id: who, name, model, socketId });
+    this._byGameId.set(gameId, who);
+
+    this._push({ op: 'join', who, ...(team ? { team } : {}) });
+  }
+
+  noteLeave(gameId) {
+    const who = this._byGameId.get(gameId);
+
+    if (who === undefined) {
+      return;
+    }
+
+    this._byGameId.delete(gameId);
+    this._push({ op: 'leave', who });
+  }
+
+  noteKey(gameId, action, name) {
+    this._pushFor(gameId, who => ({ op: 'key', who, action, name }));
+  }
+
+  noteChat(gameId, text) {
+    this._pushFor(gameId, who => ({ op: 'chat', who, text }));
+  }
+
+  noteVote(gameId, data) {
+    this._pushFor(gameId, who => ({ op: 'vote', who, data }));
+  }
+
+  /**
+   * Останавливает запись и отдаёт готовый сценарий (parseScenario его
+   * принимает как есть).
+   * @returns {Object|null} Сценарий или null, если записи не было.
+   */
+  stop() {
+    if (!this._recording) {
+      return null;
+    }
+
+    const scenario = {
+      version: 1,
+      seed: this._seed,
+      map: this._map,
+      // таймеры сценария живут только в config.timers: верхний уровень
+      // config — это ключи конфига игры, и раньше запись подсовывала туда
+      // таймер в расчёте на неявный роутинг
+      config: this._networkSendRate
+        ? { timers: { networkSendRate: this._networkSendRate } }
+        : {},
+      participants: this._participants,
+      timeline: this._timeline,
+      ticks: this._tick,
+      dumpTicks: [this._tick],
+      // не поле формата: parseScenario его игнорирует, а человеку/нейросети
+      // нужно понимать, откуда взялся файл и не обрезан ли он
+      meta: {
+        source: 'browser',
+        recordedAt: this._startedAt,
+        stoppedAt: clock.now(),
+        droppedOps: this._droppedOps,
+        dt: this._dtStats(),
+      },
+    };
+
+    this._reset();
+
+    return scenario;
+  }
+
+  _reset() {
+    this._recording = false;
+    this._tick = 0;
+    this._seed = null;
+    this._map = null;
+    this._networkSendRate = null;
+    this._startedAt = null;
+    this._participants = [];
+    this._byGameId = new Map();
+    this._timeline = [];
+    this._dt = [];
+    this._droppedOps = 0;
+    this._droppedDt = 0;
+  }
+
+  _push(op) {
+    if (this._timeline.length >= this._limits.maxOps) {
+      this._droppedOps += 1;
+      return;
+    }
+
+    this._timeline.push({ tick: this._tick, ...op });
+  }
+
+  _pushFor(gameId, build) {
+    if (!this._recording) {
+      return;
+    }
+
+    const who = this._byGameId.get(gameId);
+
+    // участник вошёл до старта записи и не попал в participants — операция
+    // без адресата сломала бы реплей, поэтому не пишется вовсе
+    if (who !== undefined) {
+      this._push(build(who));
+    }
+  }
+
+  _dtStats() {
+    const samples = this._dt;
+
+    if (!samples.length) {
+      return { count: 0, dropped: this._droppedDt };
+    }
+
+    let min = samples[0];
+    let max = samples[0];
+    let sum = 0;
+
+    for (const value of samples) {
+      min = Math.min(min, value);
+      max = Math.max(max, value);
+      sum += value;
+    }
+
+    return {
+      count: samples.length,
+      dropped: this._droppedDt,
+      min,
+      max,
+      mean: sum / samples.length,
+      samples,
+    };
+  }
+}

package/src/host/GameCoreAdapter.js

@@ -197,6 +197,23 @@ export default class GameCoreAdapter {
     );
   }
 
+  // ***** отладка ***** //
+
+  /**
+   * Курированный дамп мира ядра (тела, коллайдеры, карта, нав-граф,
+   * spatial-сетка, rng). Метод приезжает из движкового ABI-макроса, но
+   * ядро игры могло быть собрано против более старого движка — тогда
+   * null, а не исключение посреди прогона.
+   * @returns {Object|null}
+   */
+  debugJson() {
+    if (typeof this._core.debug_json !== 'function') {
+      return null;
+    }
+
+    return JSON.parse(this._core.debug_json());
+  }
+
   // бот ли участник (спавн/удаление в ядре различаются)
   _isScripted(gameId) {
     const participant = this._participants.get(gameId);