vimp-engine 0.3.0 → 0.5.0

package/bin/vimp-sim.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { runScenario } from '../src/devtools/ScenarioRunner.js';
+import { loadGameForSim } from '../src/devtools/pluginLoader.js';
+import {
+  checkDeterminism,
+  summarize,
+  FAIL,
+} from '../src/devtools/invariants.js';
+import { writeReport, formatMarkdown } from '../src/devtools/report.js';
+
+// CLI headless-прогона: правка → npm run sim → текстовый вердикт, без
+// браузера и без человека.
+
+const USAGE = `Usage: vimp-sim [options]
+
+  --scenario <path>  scenario JSON (default: built-in smoke scenario)
+  --game <path>      game package directory or dist/manifest.json
+  --core <path>      node build of the game core (overrides entries.wasmNode)
+  --out <dir>        report root (default: .debug)
+  --no-write         print the report to stdout instead of writing files
+  --determinism      run the scenario twice and compare the frame streams
+  --help
+`;
+
+// минимальный сценарий на фикстуре: один игрок заходит, едет вперёд,
+// отпускает клавишу — этого хватает, чтобы контур доказал, что он замкнут
+const DEFAULT_SCENARIO = {
+  version: 1,
+  seed: 3812,
+  participants: [{ id: 'p1', name: 'P1', model: 'm1' }],
+  timeline: [
+    { tick: 0, op: 'join', who: 'p1', team: 'team1' },
+    { tick: 10, op: 'key', who: 'p1', action: 'down', name: 'forward' },
+    { tick: 60, op: 'key', who: 'p1', action: 'up', name: 'forward' },
+  ],
+  // событийный ключ фикстуры в этом сценарии не стреляет — объявлено явно,
+  // иначе инвариант 2 честно посчитает это «сущность не спавнится»
+  unusedSnapshotKeys: ['e1'],
+  ticks: 120,
+};
+
+async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const scenario = args.scenario
+    ? JSON.parse(await readFile(args.scenario, 'utf8'))
+    : DEFAULT_SCENARIO;
+
+  // плагин грузится один раз: второй прогон самопроверки детерминизма
+  // обязан идти на том же ядре, иначе он проверял бы загрузчик, а не мир
+  const plugin = await loadGameForSim({ game: args.game, core: args.core });
+  // хеши потока кадров собираются только под --determinism: их единственный
+  // потребитель — сравнение двух прогонов, а объём линеен по длине матча
+  const captureFrames = args.determinism === true;
+  const report = await runScenario(scenario, { plugin, captureFrames });
+
+  if (args.determinism) {
+    const second = await runScenario(scenario, { plugin, captureFrames });
+    const check = checkDeterminism(report, second);
+
+    report.invariants = report.invariants.map(item =>
+      item.name === check.name ? check : item,
+    );
+    report.invariantSummary = summarize(report.invariants);
+  }
+
+  if (args.write === false) {
+    process.stdout.write(formatMarkdown(report));
+  } else {
+    const runDir = await writeReport(report, { outDir: args.out });
+
+    process.stdout.write(formatMarkdown(report));
+    process.stdout.write(`\nReport written to ${runDir}\n`);
+  }
+
+  const failed = report.invariants.filter(check => check.status === FAIL);
+
+  if (failed.length) {
+    process.stderr.write(
+      `\n${failed.length} broken contract(s): ` +
+        `${failed.map(check => check.name).join(', ')}\n`,
+    );
+
+    return 1;
+  }
+
+  return 0;
+}
+
+function parseArgs(argv) {
+  const args = { write: true };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+
+      case '--no-write':
+        args.write = false;
+        break;
+
+      case '--determinism':
+        args.determinism = true;
+        break;
+
+      case '--scenario':
+      case '--game':
+      case '--core':
+      case '--out':
+        i += 1;
+        args[arg.slice(2)] = argv[i];
+        break;
+
+      default:
+        throw new Error(`unknown option '${arg}'\n\n${USAGE}`);
+    }
+  }
+
+  return args;
+}
+
+main(process.argv.slice(2)).then(
+  code => {
+    process.exitCode = code;
+  },
+  error => {
+    process.stderr.write(`${error.stack ?? error.message}\n`);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {
@@ -15,12 +15,16 @@
   "exports": {
     "./lib/*": "./src/lib/*",
     "./config/*": "./src/config/*",
-    "./host/*": "./src/host/*"
+    "./host/*": "./src/host/*",
+    "./devtools/*": "./src/devtools/*"
   },
   "files": [
     "src/lib",
     "src/config",
-    "src/host"
+    "src/host",
+    "src/devtools",
+    "tests/fixtures",
+    "bin"
   ],
   "scripts": {
     "predev": "node scripts/sync-pixi-vendor.mjs",
@@ -43,5 +47,8 @@
     "nodemon": "^3.1.10",
     "vite": "^7.1.11",
     "vite-plugin-pug": "^0.4.1"
+  },
+  "bin": {
+    "vimp-sim": "bin/vimp-sim.js"
   }
 }

package/src/config/gameCodes.js

@@ -0,0 +1,8 @@
+// коды игровых информ-сообщений (порт GAME_INFORM_DATA, см.
+// docs/en/network.md) — общий контракт хоста (SocketManager) и клиента
+// (main.js): значение не должно расходиться между ними молча
+export default {
+  winnerTeam: [0],
+  roundStart: [1],
+  gameOver: [2],
+};

package/src/config/lobby.js

@@ -44,6 +44,12 @@ export default {
     stateUrl: '/auth/state',
   },
 
+  // рейтинг игры (lobby-page-plan): публичный топ-N и позиция вызывающего,
+  // проксируемые мастером под тем же origin — правки CSP не нужны
+  leaderboardUrl: '/auth/leaderboard',
+  placementUrl: '/auth/placement',
+  leaderboardLimit: 10,
+
   // переподключение сигнального WS хоста (комната без него выпадает из
   // выдачи мастера): экспоненциальный бэкофф от baseDelay до maxDelay (мс)
   reconnect: {
@@ -51,6 +57,10 @@ export default {
     maxDelay: 30000,
   },
 
+  // приёмник выгрузок отладочного контура (этап 6 плана plan/done/ai-debug):
+  // маршрут поднимается мастером только в dev, в проде вернёт 404
+  debugReportUrl: '/debug/report',
+
   // размер страницы для «Загрузить ещё» (offset/limit к мастеру)
   pageSize: 10,
 
@@ -67,11 +77,23 @@ export default {
     emptyId: 'lobby-empty',
     nameId: 'lobby-name',
     hostBtnId: 'lobby-host',
-    // селектор игры: скрыт, пока в каталоге мастера одна игра (§6, PLAN.md)
+    // селектор игры (lobby-page-plan): заполняется всем каталогом мастера,
+    // выбор меняет активную форму/leaderboard, но не активную игру для host
+    // (граница задачи — см. plan/lobby-page-plan.md)
     gameId: 'lobby-game',
     // контейнер полей комнаты: генерируются по ключам roomDefaults
     // манифеста активной игры (Д7) — движок не знает игровых полей
     fieldsId: 'lobby-fields',
+
+    // вкладки правой панели (lobby-page-plan)
+    tabServersBtnId: 'btn-show-servers',
+    tabLeaderboardBtnId: 'btn-show-leaderboard',
+    serversContentId: 'lobby-servers-content',
+    leaderboardContentId: 'lobby-leaderboard-content',
+    leaderboardListId: 'lobby-leaderboard-list',
+    leaderboardTitleId: 'leaderboard-title',
+    leaderboardTotalId: 'leaderboard-total',
+    myPlacementId: 'lobby-my-placement',
   },
 
   // создание комнаты (хост в этой же вкладке); лимит игроков/время

package/src/config/master.js

@@ -45,6 +45,14 @@ export default {
     sweepInterval: 10000, // период проверки протухших комнат
   },
 
+  // GET /auth/leaderboard (code review L2): TTL кэша на мастере (мс) и
+  // верхняя граница ?limit= — публичный анонимный эндпоинт, самый частый
+  // запрос лобби, выборка меняется медленно
+  leaderboard: {
+    cacheTtl: 15000,
+    maxLimit: 100,
+  },
+
   // рейтинг хостера комнаты (server-rating этап 2, plan/server-rating/
   // stage_2.md): /like·/unlike гостей комнаты вместо соц-модерации /ban.
   // Дефолт движка для всех игр; auth-сервис хранит и клампит рейтинг

package/src/devtools/RecordingSocketManager.js

@@ -0,0 +1,143 @@
+import wsports from '../config/wsports.js';
+import SocketManager from '../host/meta/SocketManager.js';
+
+// Транспорт хоста, который вместо сети пишет исходящие вызовы в память.
+// Наследует боевой SocketManager, а не копирует его отправителей: составные
+// отправители (sendFirstShot и компания), нагрузка портов и их номера
+// остаются одни на прод и на headless — ручная копия уже расходилась с
+// оригиналом и стоила прогону keySet, панели и первого снапшота мира.
+//
+// Записывается сам вызов (метод + аргументы, как их видит хост), а нагрузка
+// транспорта — тем, что настоящий код успел передать в _send/_sendBinary:
+// проверки инвариантов рассуждают о семантике («roundEnd объявил победителя»),
+// а VirtualClient — о том, что реально уехало бы в data channel.
+
+// имена отправителей берутся из прототипа: ручной список неизбежно отстаёт
+// от боевого класса, что уже случалось
+const SENDER_METHODS = Object.getOwnPropertyNames(SocketManager.prototype)
+  .filter(name => name.startsWith('send'));
+
+class RecordingSocketManager extends SocketManager {
+  /**
+   * @param {Object} [ports] - Карта портов host→client; по умолчанию боевая
+   *   (движковые тесты меты создают транспорт без аргументов).
+   * @param {Object} [gameOpts] - Игровая параметризация ({ soundCues,
+   *   initialVote }) — та же, что получает боевой SocketManager.
+   * @param {Object} [options]
+   * @param {Function} [options.onFrame] - Вызывается на каждый исходящий кадр
+   *   ({ method, socketId, args, tick, sent }) — runner раздаёт их
+   *   VirtualClient'ам, не дожидаясь конца прогона.
+   */
+  constructor(ports = wsports.server, gameOpts = {}, { onFrame = null } = {}) {
+    super(ports, gameOpts);
+
+    this.frames = []; // [{ method, socketId, args, tick, sent }]
+
+    // номер тика прогона: runner двигает его перед каждым шагом, кадры
+    // получают метку — без неё проверки жизненного цикла раунда не могут
+    // сказать «кому именно не доехал roundEnd на этом тике»
+    this.tick = 0;
+    this._onFrame = onFrame;
+
+    // кадр, чьё тело сейчас исполняется: в него уходит нагрузка _send;
+    // составные отправители вкладываются друг в друга, поэтому это стек
+    // через локальную переменную в _record
+    this._current = null;
+
+    for (const method of SENDER_METHODS) {
+      this[method] = (socketId, ...args) => {
+        this._record(method, socketId, args, () =>
+          SocketManager.prototype[method].call(this, socketId, ...args),
+        );
+      };
+    }
+  }
+
+  close(socketId, code, key, arr) {
+    this._record('close', socketId, [code, key, arr], () =>
+      super.close(socketId, code, key, arr),
+    );
+  }
+
+  // все кадры указанного метода
+  framesOf(method) {
+    return this.frames.filter(frame => frame.method === method);
+  }
+
+  clearFrames() {
+    this.frames.length = 0;
+  }
+
+  // сети нет: всё, что боевой код отдал бы сокету, оседает в текущем кадре
+  _send(socketId, port, data, reliable = true) {
+    this._payload({ port, data, reliable });
+  }
+
+  _sendBinary(socketId, buffer, reliable) {
+    this._payload({ port: this._PORT_SHOT_DATA, data: buffer, reliable });
+  }
+
+  _close(socketId, code, data) {
+    this._payload({ port: null, data: { code, data } });
+  }
+
+  // Кадр публикуется в момент первой отправки — это и есть порядок провода:
+  // составной отправитель отдаёт свою нагрузку раньше вложенных вызовов
+  // (FIRST_SHOT_DATA → STAT → PANEL → KEYSET), и клиент прогона видит ту же
+  // последовательность, что и браузер. Публикация после invoke() отдавала бы
+  // родителя последним.
+  //
+  // Отсюда несущее допущение: у отправителя не больше ОДНОЙ собственной
+  // нагрузки (составные раскладываются во вложенные вызовы, а два _send в
+  // sendClear/sendTechInform — это ветки if/else). Нарушь его — и подписчик
+  // получит кадр, собранный наполовину, уже после решения о маршрутизации.
+  // Поэтому не молчим, а называем контракт.
+  _payload(entry) {
+    const frame = this._current;
+
+    if (!frame) {
+      return;
+    }
+
+    if (frame.sent.length) {
+      throw new Error(
+        `RecordingSocketManager: '${frame.method}' sent a second payload ` +
+          `(port ${entry.port}) — a sender may hand the socket at most one, ` +
+          'otherwise the subscriber already routed a half-built frame; ' +
+          'split it into nested senders like sendFirstShot does',
+      );
+    }
+
+    frame.sent.push(entry);
+    this._emit(frame);
+  }
+
+  _record(method, socketId, args, invoke) {
+    const frame = { method, socketId, args, tick: this.tick, sent: [] };
+    const parent = this._current;
+
+    this.frames.push(frame);
+    this._current = frame;
+
+    try {
+      invoke();
+    } finally {
+      this._current = parent;
+    }
+
+    // отправитель без собственной нагрузки (составной вроде
+    // sendPlayerDefaultShot либо отфильтрованный прод-кодом незамапленный
+    // soundCue) всё равно доезжает до подписчика — но ровно один раз
+    if (!frame.sent.length) {
+      this._emit(frame);
+    }
+  }
+
+  _emit(frame) {
+    if (this._onFrame) {
+      this._onFrame(frame);
+    }
+  }
+}
+
+export default RecordingSocketManager;