vimp-engine 0.5.0 → 0.6.0

package/bin/vimp-sim.js

@@ -1,7 +1,8 @@
 #!/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 { builtinScenario } from '../src/devtools/builtinScenario.js';
+import { loadGameForSim, isFixture } from '../src/devtools/pluginLoader.js';
 import {
   checkDeterminism,
   summarize,
@@ -12,33 +13,37 @@ import { writeReport, formatMarkdown } from '../src/devtools/report.js';
 // CLI headless-прогона: правка → npm run sim → текстовый вердикт, без
 // браузера и без человека.
 
+// ошибка разбора флагов печатается без стека — см. обработчик внизу файла
+class UsageError extends Error {}
+
 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)
+  --core <path>      node build of the game core (overrides entries.wasmNode);
+                     only meaningful with --game — the built-in fixture has
+                     no WASM core to override
   --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,
-};
+// каждая строка с префиксом: дальше в stderr уходит список падений, и
+// грепалки CI не должны путать предупреждение с ними
+const BUILTIN_NOTICE =
+  'notice: the built-in smoke scenario is running against --game. It only\n' +
+  'notice: proves the loop closes on this plugin: key coverage (invariant 2)\n' +
+  'notice: and prediction drift (invariant 9) are skipped — both need a\n' +
+  'notice: scenario written for your game. See § Scenario format in the\n' +
+  "notice: engine's docs/en/debugging.md (github.com/lgick/vimp), then run\n" +
+  'notice: vimp-sim --scenario <file>.\n\n';
+
+// типичная опечатка «--core без --game»: фикстурное ядро — обычный JS и
+// wasmUrl не смотрит, поэтому прогон был бы зелёным, не тронув ядро игры
+const STRAY_CORE_NOTICE =
+  'notice: --core without --game does nothing: the run falls back to the\n' +
+  "notice: built-in fixture, whose core is plain JS. Add --game <path>.\n\n";
 
 async function main(argv) {
   const args = parseArgs(argv);
@@ -48,13 +53,23 @@ async function main(argv) {
     return 0;
   }
 
-  const scenario = args.scenario
-    ? JSON.parse(await readFile(args.scenario, 'utf8'))
-    : DEFAULT_SCENARIO;
+  if (args.core && !args.game) {
+    process.stderr.write(STRAY_CORE_NOTICE);
+  }
 
   // плагин грузится один раз: второй прогон самопроверки детерминизма
-  // обязан идти на том же ядре, иначе он проверял бы загрузчик, а не мир
+  // обязан идти на том же ядре, иначе он проверял бы загрузчик, а не мир.
+  // Загрузка идёт до сборки сценария: встроенный берёт имена модели, команды
+  // и клавиши из gameConfig игры
   const plugin = await loadGameForSim({ game: args.game, core: args.core });
+
+  if (!args.scenario && !isFixture(plugin)) {
+    process.stderr.write(BUILTIN_NOTICE);
+  }
+
+  const scenario = args.scenario
+    ? JSON.parse(await readFile(args.scenario, 'utf8'))
+    : builtinScenario(plugin);
   // хеши потока кадров собираются только под --determinism: их единственный
   // потребитель — сравнение двух прогонов, а объём линеен по длине матча
   const captureFrames = args.determinism === true;
@@ -118,11 +133,20 @@ function parseArgs(argv) {
       case '--core':
       case '--out':
         i += 1;
+
+        // «--game» последним аргументом (или перед следующим флагом) тихо
+        // уводил на фикстуру: прогон зелёный, игра не тронута. Путь,
+        // начинающийся с '--', тем самым запрещён — таких не бывает, а
+        // явный отказ лучше ENOENT про каталог '--determinism'
+        if (argv[i] === undefined || argv[i].startsWith('--')) {
+          throw new UsageError(`option '${arg}' needs a value\n\n${USAGE}`);
+        }
+
         args[arg.slice(2)] = argv[i];
         break;
 
       default:
-        throw new Error(`unknown option '${arg}'\n\n${USAGE}`);
+        throw new UsageError(`unknown option '${arg}'\n\n${USAGE}`);
     }
   }
 
@@ -134,7 +158,13 @@ main(process.argv.slice(2)).then(
     process.exitCode = code;
   },
   error => {
-    process.stderr.write(`${error.stack ?? error.message}\n`);
+    // опечатка в флаге — не краш инструмента: стек тут лишний шум поверх
+    // USAGE, который пользователь и должен прочитать
+    process.stderr.write(
+      error instanceof UsageError
+        ? `${error.message}\n`
+        : `${error.stack ?? error.message}\n`,
+    );
     process.exitCode = 1;
   },
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/devtools/ScenarioRunner.js

@@ -4,7 +4,11 @@ import RecordingSocketManager from './RecordingSocketManager.js';
 import VirtualClient from './VirtualClient.js';
 import { loadGameForSim } from './pluginLoader.js';
 import { resetHostSingletons } from './resetHostSingletons.js';
-import { checkInvariants, summarize } from './invariants.js';
+import {
+  checkInvariants,
+  summarize,
+  ALL_KEYS_UNAUDITED,
+} from './invariants.js';
 import { inspectCore, inspectHost } from './inspectHost.js';
 
 // Прогон сценария целиком в одном Node-процессе: авторитетный хост
@@ -58,6 +62,21 @@ export function parseScenario(raw) {
   const timeline = [...(raw.timeline ?? [])].sort(
     (a, b) => (a.tick ?? 0) - (b.tick ?? 0),
   );
+  const unusedSnapshotKeys = raw.unusedSnapshotKeys ?? [];
+
+  // строка тут легальна ровно одна: без проверки забытые скобки
+  // ("unusedSnapshotKeys": "w1") молча разложились бы в набор символов, и
+  // объявленный ключ всё равно попал бы в нарушения инварианта 2
+  if (
+    unusedSnapshotKeys !== ALL_KEYS_UNAUDITED &&
+    (!Array.isArray(unusedSnapshotKeys) ||
+      unusedSnapshotKeys.some(key => typeof key !== 'string'))
+  ) {
+    throw new Error(
+      'scenario: unusedSnapshotKeys must be an array of snapshot keys or ' +
+        `"${ALL_KEYS_UNAUDITED}"`,
+    );
+  }
 
   return {
     version: 1,
@@ -69,10 +88,11 @@ export function parseScenario(raw) {
     timeline,
     // ключи схемы, которых в этом сценарии заведомо не будет (инвариант 2):
     // «сущность не спавнится» отличается от «сценарий её не трогает» только
-    // этим объявлением
-    unusedSnapshotKeys: raw.unusedSnapshotKeys ?? [],
+    // этим объявлением. '*' — сценарий не берётся судить покрытие ключей
+    // вовсе (встроенный смоук на чужой игре), и инвариант честно пропускается
+    unusedSnapshotKeys,
     // пороги детектора рассинхрона предикта (инвариант 9); {} — дефолты
-    // ядра, null — детектор выключен
+    // ядра, null — детектор выключен, и инвариант тоже пропускается
     divergence: raw.divergence === null ? null : (raw.divergence ?? {}),
     ticks: raw.ticks ?? 600,
     dumpTicks: raw.dumpTicks ?? null,

package/src/devtools/builtinScenario.js

@@ -0,0 +1,95 @@
+import { ALL_KEYS_UNAUDITED } from './invariants.js';
+import { isFixture } from './pluginLoader.js';
+
+// Встроенный сценарий headless-прогона: один участник заходит, едет вперёд,
+// отпускает клавишу. Этого хватает, чтобы контур доказал, что он замкнут
+// (хост → кадр → клиентское ядро → сцена), и не хватает ни на что больше.
+//
+// Идентификаторы берутся из gameConfig самой игры: имя модели, команды и
+// клавиши — часть игры, а не движка. Захардкоженные фикстурные 'm1' /
+// 'team1' / 'forward' на чужом плагине означают падение в ядре («unknown
+// model») либо красный инвариант 8 у исправного плагина.
+
+// Ввод начинается на 40-м тике, а не сразу: кадр спавна с force_reset
+// приходит примерно на interpolation.delay (движковый дефолт — 100 мс, тут
+// ~3× запаса) позже входа и чистит удержанные клавиши предиктора
+// (docs/en/debugging.md) — встроенный сценарий не должен демонстрировать
+// ровно ту ловушку, от которой предостерегает документация
+const INPUT_DOWN_TICK = 40;
+const INPUT_UP_TICK = 100;
+const TICKS = 120;
+
+// событийный ключ фикстуры в этом сценарии не стреляет — объявлено явно,
+// иначе инвариант 2 честно посчитает это «сущность не спавнится»
+const FIXTURE_UNUSED_KEYS = ['e1'];
+
+const firstKey = dict => Object.keys(dict ?? {})[0];
+
+// Клавиша для смоука обязана быть удерживаемой: по конвенции playerKeys
+// (docs/ai/04-client-plugin.md) `type: 1` — триггер, у которого 'up'
+// игнорируется, и «нажал — отпустил» не даёт ни удержания, ни движения.
+// Порядок объявления в playerKeys контрактом не задан, поэтому берём первую
+// без type; если игра объявила одни триггеры — первую любую, смоук всё равно
+// должен запуститься. Движок сам type не интерпретирует (это дело ядра
+// игры) — здесь это эвристика выбора, а не поведение движка.
+const heldKey = playerKeys => {
+  const keys = Object.entries(playerKeys ?? {});
+
+  return (keys.find(([, spec]) => !spec?.type) ?? keys[0])?.[0];
+};
+
+/**
+ * Собирает встроенный смоук-сценарий под конкретную игру.
+ * @param {Object} plugin - Результат loadGameForSim.
+ * @returns {Object} Сценарий в формате runScenario.
+ */
+export function builtinScenario(plugin) {
+  const config = plugin.hostPlugin.gameConfig;
+  const model = firstKey(config.parts?.models);
+  const key = heldKey(config.playerKeys);
+  const team = Object.keys(config.teams ?? {}).find(
+    name => name !== config.spectatorTeam,
+  );
+
+  if (!model || !key || !team) {
+    throw new Error(
+      `game "${plugin.id}": the built-in scenario has nothing to drive ` +
+        `(model: ${model ?? '—'}, playable team: ${team ?? '—'}, ` +
+        `player key: ${key ?? '—'}) — write a scenario for this game and ` +
+        `pass --scenario <file>`,
+    );
+  }
+
+  const scenario = {
+    version: 1,
+    seed: 3812,
+    participants: [{ id: 'p1', name: 'P1', model }],
+    timeline: [
+      { tick: 0, op: 'join', who: 'p1', team },
+      {
+        tick: INPUT_DOWN_TICK,
+        op: 'key',
+        who: 'p1',
+        action: 'down',
+        name: key,
+      },
+      { tick: INPUT_UP_TICK, op: 'key', who: 'p1', action: 'up', name: key },
+    ],
+    ticks: TICKS,
+  };
+
+  if (isFixture(plugin)) {
+    return { ...scenario, unusedSnapshotKeys: FIXTURE_UNUSED_KEYS };
+  }
+
+  // На чужой игре это смоук контура, а не аудит контракта: сценарий не знает
+  // ни ключей её схемы, ни её порогов дрейфа (у каждой игры своя раскладка
+  // player-блока и свои единицы). Судить исправный плагин по фикстурным
+  // значениям значит выдавать ему красный вердикт, поэтому проверки 2 и 9
+  // честно пропускаются, а не притворяются пройденными.
+  return {
+    ...scenario,
+    unusedSnapshotKeys: ALL_KEYS_UNAUDITED,
+    divergence: null,
+  };
+}

package/src/devtools/invariants.js

@@ -15,6 +15,10 @@ export const PASS = 'pass';
 export const FAIL = 'fail';
 export const SKIP = 'skip';
 
+// scenario.unusedSnapshotKeys: вместо списка ключей — «этот сценарий вообще
+// не берётся судить покрытие схемы» (встроенный смоук на чужой игре)
+export const ALL_KEYS_UNAUDITED = '*';
+
 // список проверок в порядке plan/done/ai-debug/stage_3.md
 const CHECKS = [
   [1, 'finiteValues', 'no NaN/Infinity in decoded fields and hot buffer'],
@@ -137,6 +141,19 @@ function finiteValues({ clients }) {
 
 // 2
 function snapshotKeysUsed({ game, clients, scenario }) {
+  // сценарий, не знающий схемы этой игры (встроенный смоук на чужом плагине),
+  // не должен объявлять её ключи «не спавнящимися» — это красный вердикт
+  // исправной игре
+  if (scenario.unusedSnapshotKeys === ALL_KEYS_UNAUDITED) {
+    return result(
+      'snapshotKeysUsed',
+      SKIP,
+      [],
+      `the scenario declares unusedSnapshotKeys: "${ALL_KEYS_UNAUDITED}" — ` +
+        'key coverage is not audited',
+    );
+  }
+
   const declared = Object.keys(game.snapshot);
   const unused = new Set(scenario.unusedSnapshotKeys);
   const seen = new Set();
@@ -397,7 +414,19 @@ function keyBindings({ game, clientConfig, scenario }) {
 // player-блоком кадра. Сопоставление идёт по времени кадра, а не по seq —
 // предиктор переигрывает историю ввода от момента авторитетного состояния,
 // и «тот же seq» на клиенте и на хосте означает разные моменты.
-function predictionDrift({ clients }) {
+function predictionDrift({ clients, scenario }) {
+  // детектор выключен самим сценарием — молчит не ядро, и автор плагина не
+  // должен идти искать несуществующую проблему в take_divergence
+  if (scenario.divergence === null) {
+    return result(
+      'predictionDrift',
+      SKIP,
+      [],
+      'the scenario disables the drift detector (divergence: null) — ' +
+        'thresholds are per-game, write a scenario for yours',
+    );
+  }
+
   const violations = [];
   const tracked = clients.filter(client => client.divergenceStats);
 

package/src/devtools/pluginLoader.js

@@ -1,7 +1,10 @@
 import { access, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { assertEngineApiCompatible } from '../lib/gamePlugin.js';
+import {
+  assertEngineApiCompatible,
+  assertGameConfigShape,
+} from '../lib/gamePlugin.js';
 
 // Поиск игры для headless-прогона. В браузере плагин грузится по URL из
 // GameManifest мастера; в Node URL-ов нет, поэтому источников три, по
@@ -21,6 +24,16 @@ const FIXTURE_DIR = new URL(
   import.meta.url,
 );
 
+// значение поля source у фикстуры: по нему отличается «своя игра, схему
+// которой инструмент знает» от чужого плагина (см. builtinScenario.js)
+export const FIXTURE_SOURCE = 'fixture:miniGame';
+
+/**
+ * @param {Object} plugin - Результат loadGameForSim.
+ * @returns {boolean} Прогон идёт на встроенной фикстуре, а не на чужой игре.
+ */
+export const isFixture = plugin => plugin.source === FIXTURE_SOURCE;
+
 /**
  * @param {Object} [options]
  * @param {string} [options.game] - Путь к пакету игры или к манифесту.
@@ -30,10 +43,20 @@ const FIXTURE_DIR = new URL(
  *   source }.
  */
 export async function loadGameForSim({ game = null, core = null } = {}) {
-  if (!game) {
-    return loadFixture(core);
-  }
+  const plugin = game
+    ? await loadFromManifest(game, core)
+    : await loadFixture(core);
+
+  // контракт gameConfig проверяется здесь, а не только в createHostRuntime:
+  // встроенный сценарий собирается из gameConfig раньше, чем стартует прогон
+  // (builtinScenario.js), и плагин без конфига иначе отвечал бы сырым
+  // TypeError вместо перечисления недостающих полей
+  assertGameConfigShape(plugin.hostPlugin);
+
+  return plugin;
+}
 
+async function loadFromManifest(game, core) {
   const manifestPath = game.endsWith('.json')
     ? path.resolve(game)
     : path.resolve(game, 'dist/manifest.json');
@@ -107,7 +130,7 @@ async function loadFixture(core) {
     hostPlugin,
     clientPlugin,
     wasmUrl: core ? pathToFileURL(path.resolve(core)).href : undefined,
-    source: 'fixture:miniGame',
+    source: FIXTURE_SOURCE,
   };
 }
 

package/src/lib/gamePlugin.js

@@ -51,6 +51,10 @@ const REQUIRED_GAME_CONFIG_PATHS = [
   'parts.friendlyFire',
   'panel.fields',
   'playerKeys',
+  // без них HostGame разыменовывает undefined (this._teams[spectatorTeam])
+  // и игра умирает тремя разными сообщениями вместо одного контрактного
+  'teams',
+  'spectatorTeam',
 ];
 
 function getPath(obj, dottedPath) {
@@ -61,9 +65,14 @@ function getPath(obj, dottedPath) {
 
 // бросает при отсутствии обязательных полей HostPlugin.gameConfig
 export function assertGameConfigShape(hostPlugin) {
-  const missing = REQUIRED_GAME_CONFIG_PATHS.filter(
-    p => getPath(hostPlugin.gameConfig, p) === undefined,
-  );
+  // null проходил бы проверку присутствия, хотя ни одно из этих полей не
+  // бывает пустым по контракту: движок разыменовывает их сразу, и гейт,
+  // заведённый ради текста вместо TypeError, сам отвечал бы TypeError
+  const missing = REQUIRED_GAME_CONFIG_PATHS.filter(p => {
+    const value = getPath(hostPlugin.gameConfig, p);
+
+    return value === undefined || value === null;
+  });
 
   if (missing.length > 0) {
     throw new Error(
@@ -71,6 +80,19 @@ export function assertGameConfigShape(hostPlugin) {
         missing.join(', '),
     );
   }
+
+  // единственная связь между полями, которую стоит проверять здесь:
+  // spectatorTeam — имя ключа внутри teams, и опечатка даёт spectatorId ===
+  // undefined, после чего участник заходит в несуществующую команду
+  // (ParticipantManager.createHuman валится на её счётчике)
+  const { teams, spectatorTeam } = hostPlugin.gameConfig;
+
+  if (teams[spectatorTeam] === undefined) {
+    throw new Error(
+      `game "${hostPlugin.id}": spectatorTeam '${spectatorTeam}' is not a ` +
+        `key of teams (${Object.keys(teams).join(', ')})`,
+    );
+  }
 }
 
 // динамический import ClientPlugin игры (client-entry её сборки). Манифест и