vimp-engine 0.2.0 → 0.4.0

package/bin/vimp-sim.js

@@ -0,0 +1,137 @@
+#!/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 });
+  const report = await runScenario(scenario, { plugin });
+
+  if (args.determinism) {
+    const second = await runScenario(scenario, { plugin });
+    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.2.0",
+  "version": "0.4.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/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/config/opcodes.js

@@ -7,7 +7,9 @@
 // проверяется при загрузке плагинов; ломающие изменения контрактов → +1.
 // v2: явная схема форм (roomForm/authSchema.params[].options — Form schema
 // в plugin-api.md), движок больше не выводит контролы из типа значения
-export const ENGINE_API_VERSION = 2;
+// v3: набор control сокращён до нативных элементов — 'select'|'text'|
+// 'checkbox'|'radio' (были ещё 'range'/'number'/'toggle'/'segmented')
+export const ENGINE_API_VERSION = 3;
 
 // версия формата кадра: первый байт после порта;
 // увеличивать при любом изменении байтовой раскладки в ядре

package/src/devtools/RecordingSocketManager.js

@@ -0,0 +1,118 @@
+// Транспорт хоста, который вместо сети пишет исходящие кадры в память.
+// Обобщение FakeSocketManager из tests/host/fixtureHarness.js: одну и ту же
+// подмену используют и движковые тесты меты, и headless-runner — иначе
+// пришлось бы держать две копии перечня отправителей SocketManager.
+
+// Все отправители SocketManager, которые дёргает host-фасад.
+export const SENDER_METHODS = [
+  'sendConfig',
+  'sendAuthData',
+  'sendAuthResult',
+  'sendPing',
+  'sendClear',
+  'sendTechInform',
+  'sendMap',
+  'sendFirstShot',
+  'sendFirstVote',
+  'sendShot',
+  'sendPanel',
+  'sendStat',
+  'sendChat',
+  'sendVote',
+  'sendKeySet',
+  'sendPlayerDefaultShot',
+  'sendSpectatorDefaultShot',
+  'sendConsole',
+  'sendGameInform',
+  'sendRoundEnd',
+  'sendSoundCue',
+  'sendName',
+];
+
+class RecordingSocketManager {
+  /**
+   * @param {Object} [options]
+   * @param {Function} [options.onFrame] - Вызывается на каждый исходящий кадр
+   *   ({ method, socketId, args }) — runner раздаёт их VirtualClient'ам, не
+   *   дожидаясь конца прогона.
+   */
+  constructor({ onFrame = null } = {}) {
+    this.frames = []; // [{ method, socketId, args, tick }]
+
+    // номер тика прогона: runner двигает его перед каждым шагом, кадры
+    // получают метку — без неё проверки жизненного цикла раунда не могут
+    // сказать «кому именно не доехал roundEnd на этом тике»
+    this.tick = 0;
+    this._onFrame = onFrame;
+    this._game = null;
+    this._panel = null;
+    this._stat = null;
+
+    for (const method of SENDER_METHODS) {
+      this[method] = (socketId, ...args) => {
+        this._record({ method, socketId, args });
+      };
+    }
+
+    // Составные отправители боевого SocketManager сами дёргают панель,
+    // статистику и keySet. Плоская запись их не раскрывает — тогда клиент
+    // headless-прогона живёт с пустой панелью и без keySet, то есть предикт
+    // у него не включается никогда. Развёртка обязана повторять
+    // host/meta/SocketManager.js.
+    this.sendFirstShot = socketId => {
+      this._record({ method: 'sendFirstShot', socketId, args: [] });
+      this.sendStat(socketId, this._stat?.getFull());
+      this.sendPanel(socketId, this._panel?.getEmptyPanel());
+      this.sendKeySet(socketId, 0); // наблюдатель
+    };
+
+    this.sendPlayerDefaultShot = (socketId, gameId) => {
+      this._record({
+        method: 'sendPlayerDefaultShot',
+        socketId,
+        args: [gameId],
+      });
+      this.sendPanel(socketId, this._panel?.getFullPanel(gameId));
+      this.sendKeySet(socketId, 1); // играющий
+    };
+
+    this.sendSpectatorDefaultShot = socketId => {
+      this._record({ method: 'sendSpectatorDefaultShot', socketId, args: [] });
+      this.sendPanel(socketId, this._panel?.getEmptyPanel());
+      this.sendKeySet(socketId, 0);
+    };
+  }
+
+  injectServices(game, panel, stat) {
+    this._game = game;
+    this._panel = panel;
+    this._stat = stat;
+  }
+
+  addUser() {}
+  removeUser() {}
+
+  close(socketId, code, key, arr) {
+    this._record({ method: 'close', socketId, args: [code, key, arr] });
+  }
+
+  // все кадры указанного метода
+  framesOf(method) {
+    return this.frames.filter(frame => frame.method === method);
+  }
+
+  clear() {
+    this.frames.length = 0;
+  }
+
+  _record(frame) {
+    frame.tick = this.tick;
+    this.frames.push(frame);
+
+    if (this._onFrame) {
+      this._onFrame(frame);
+    }
+  }
+}
+
+export default RecordingSocketManager;