vimp-engine 0.8.0 → 0.10.0

package/bin/vimp-contract.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import {
+  checkContract,
+  hasBlockingFailure,
+} from '../src/devtools/contract/index.js';
+import { formatContract } from '../src/devtools/contract/format.js';
+
+// CLI статической проверки контракта: правка → npm run check:contract →
+// список нарушенных правил, без сборки и без браузера. Дополняет
+// vimp-sim: раннер судит по прогону, этот инструмент — по конфигам.
+
+class UsageError extends Error {}
+
+const USAGE = `Usage: vimp-contract [options]
+
+  --game <path>  game package directory (default: .)
+  --json         print the machine-readable report instead of text
+  --quiet        print only failures and the summary
+  --strict       treat warnings as errors (exit code 1)
+  --help
+`;
+
+async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const game = args.game ?? '.';
+  const report = await checkContract(game);
+
+  process.stdout.write(
+    args.json
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : formatContract(report, { quiet: args.quiet }),
+  );
+
+  // ни одного вердикта — обычно опечатка в пути. Нулевой код выхода здесь
+  // читался бы как «проверено, всё хорошо», хотя проверено ничего
+  if (report.summary.passed === 0 && report.summary.failed === 0) {
+    process.stderr.write(
+      `nothing to check in '${game}' — no rule found its input; ` +
+        'is this a game package directory?\n',
+    );
+
+    return 1;
+  }
+
+  return hasBlockingFailure(report, args.strict === true) ? 1 : 0;
+}
+
+function parseArgs(argv) {
+  const args = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+
+      case '--json':
+        args.json = true;
+        break;
+
+      case '--quiet':
+        args.quiet = true;
+        break;
+
+      case '--strict':
+        args.strict = true;
+        break;
+
+      case '--game':
+        i += 1;
+
+        // «--game» без значения тихо проверял бы текущий каталог — то есть
+        // сам движок; путь, начинающийся с '--', тем самым запрещён
+        if (argv[i] === undefined || argv[i].startsWith('--')) {
+          throw new UsageError(`option '${arg}' needs a value\n\n${USAGE}`);
+        }
+
+        args.game = argv[i];
+        break;
+
+      default:
+        throw new UsageError(`unknown option '${arg}'\n\n${USAGE}`);
+    }
+  }
+
+  return args;
+}
+
+main(process.argv.slice(2)).then(
+  code => {
+    process.exitCode = code;
+  },
+  error => {
+    process.stderr.write(
+      error instanceof UsageError
+        ? `${error.message}\n`
+        : `${error.stack ?? error.message}\n`,
+    );
+    process.exitCode = 1;
+  },
+);

package/core/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "vimp-engine-core"
+version = "0.3.2"
+edition = "2024"
+description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
+license = "MIT"
+repository = "https://github.com/lgick/vimp"
+readme = "README.md"
+
+[lib]
+crate-type = ["rlib"]
+
+[dependencies]
+indexmap = { workspace = true }
+rapier2d = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,7 @@
     "src/standalone",
     "src/devtools",
     "tests/fixtures",
+    "core/Cargo.toml",
     "bin"
   ],
   "scripts": {
@@ -56,6 +57,7 @@
     "vite-plugin-pug": "^0.4.1"
   },
   "bin": {
-    "vimp-sim": "bin/vimp-sim.js"
+    "vimp-sim": "bin/vimp-sim.js",
+    "vimp-contract": "bin/vimp-contract.js"
   }
 }

package/src/client/components/view/Game.js

@@ -20,19 +20,15 @@ export default class GameView {
 
   // создает экземпляр на полотне
   add(instance) {
+    // порядок отрисовки задаёт только zIndex парта. sortChildren() в
+    // PixiJS 8 компаратор не принимает (сортирует по zIndex) и выходит на
+    // первой строке, пока не поднят sortDirty; сам Pixi поднимает его лишь
+    // при записи zIndex уже добавленному в сцену объекту, а парты ставят
+    // zIndex в конструкторе — без sortableChildren сортировки не будет
+    // вовсе, и слои лягут в порядке добавления
+    this._app.stage.sortableChildren = true;
     this._app.stage.addChild(instance);
-
-    this._app.stage.sortChildren((a, b) => {
-      if (a.layer < b.layer) {
-        return -1;
-      }
-
-      if (a.layer > b.layer) {
-        return 1;
-      }
-
-      return 0;
-    });
+    this._app.stage.sortChildren();
   }
 
   // создаёт эффект и запускает его

package/src/client/main.js

@@ -345,6 +345,11 @@ socketMethods[PS_CONFIG_DATA] = async data => {
     const availableServices = {
       renderer: app.renderer,
       soundManager,
+      // база ассетов игры — тем же каналом, что и путь к звукам (см. выше):
+      // картинки карт живут в пакете игры (dist/img/), движок их не раздаёт.
+      // part, объявивший сервис в componentDependencies, строит URL сам —
+      // движок не знает ни имён файлов, ни их раскладки внутри пакета
+      assetsBase: activeGameManifest.assetsBase,
     };
 
     // если есть данные для запекания компонентов

package/src/devtools/contract/format.js

@@ -0,0 +1,65 @@
+import { ERROR, FAIL, PASS, SKIP } from './result.js';
+
+// Человекочитаемый отчёт — та же разметка, что у секции инвариантов
+// headless-раннера (devtools/report.js): один значок, id, имя правила,
+// заголовок, ниже — нарушения.
+const MARKS = { [PASS]: '✅', [FAIL]: '❌', [SKIP]: '⏭️' };
+
+/**
+ * @param {Object} report - Результат checkContract.
+ * @param {Object} [options]
+ * @param {boolean} [options.quiet] - Только нарушения и сводка.
+ * @returns {string}
+ */
+export function formatContract(report, { quiet = false } = {}) {
+  const { summary } = report;
+  const lines = [`# Contract report — ${report.game.id ?? '(unknown game)'}`, ''];
+
+  lines.push(`- game: \`${report.game.dir}\``);
+  lines.push(`- engine API: v${report.game.engineApi}`);
+  lines.push(
+    `- host: \`${report.game.hostSource ?? '(not loaded)'}\`, ` +
+      `client: \`${report.game.clientSource ?? '(not loaded)'}\``,
+  );
+  lines.push(`- built: ${report.game.built ? 'yes' : 'no (dist/ is missing)'}`);
+  lines.push('');
+
+  for (const note of report.notes) {
+    lines.push(`> ${note}`);
+  }
+
+  if (report.notes.length) {
+    lines.push('');
+  }
+
+  lines.push(
+    `${summary.passed} passed, ${summary.failed} failed ` +
+      `(${summary.errors} error, ${summary.warnings} warning), ` +
+      `${summary.skipped} skipped`,
+  );
+  lines.push('');
+
+  for (const result of report.results) {
+    if (quiet && result.status !== FAIL) {
+      continue;
+    }
+
+    const level = result.level === ERROR ? '' : ` (${result.level})`;
+    const note = result.note ? ` — ${result.note}` : '';
+
+    lines.push(
+      `- ${MARKS[result.status]} ${result.id}. \`${result.name}\`${level}: ` +
+        `${result.title}${note}`,
+    );
+
+    for (const violation of result.violations) {
+      lines.push(`  - ${violation}`);
+    }
+  }
+
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+export default formatContract;

package/src/devtools/contract/index.js

@@ -0,0 +1,69 @@
+import { loadContext } from './loadContext.js';
+import { rules } from './rules/index.js';
+import { ERROR, FAIL, summarize } from './result.js';
+
+// Статическая проверка контракта «движок ↔ игра»: то же намерение, что у
+// headless-раннера (молчаливое нарушение обязано становиться строкой),
+// только без прогона матча — по конфигам, манифесту и живым объектам
+// плагина. Живёт в движке, а не копируется в каждую игру: правила
+// эволюционируют вместе с ENGINE_API_VERSION и применимы к любой игре.
+
+export { loadContext } from './loadContext.js';
+export { rules } from './rules/index.js';
+export * from './result.js';
+
+/**
+ * @param {string} gameDir - Каталог пакета игры.
+ * @returns {Promise<Object>} { game, results, summary, notes }.
+ */
+export async function checkContract(gameDir) {
+  const ctx = await loadContext(gameDir);
+  const results = runRules(ctx);
+
+  return {
+    game: {
+      id: ctx.hostPlugin?.id ?? ctx.manifest?.id ?? null,
+      dir: ctx.dir,
+      hostSource: ctx.hostSource ?? null,
+      clientSource: ctx.clientSource ?? null,
+      built: Boolean(ctx.manifest),
+      engineApi: ctx.engineApi,
+    },
+    results,
+    summary: summarize(results),
+    notes: ctx.notes,
+  };
+}
+
+/**
+ * Прогон правил по готовому контексту (тесты собирают его вручную).
+ * @param {Object} ctx
+ * @returns {Array<Object>} Результаты правил.
+ */
+export function runRules(ctx) {
+  return rules.map(rule => {
+    const { status, violations, note } = rule.check(ctx);
+
+    return {
+      id: rule.id,
+      name: rule.name,
+      title: rule.title,
+      level: rule.level,
+      status,
+      violations,
+      note,
+    };
+  });
+}
+
+/**
+ * @param {Object} report - Результат checkContract.
+ * @param {boolean} [strict] - Считать предупреждения ошибками.
+ * @returns {boolean} Есть ли отказ, который обязан валить прогон.
+ */
+export function hasBlockingFailure(report, strict = false) {
+  return report.results.some(
+    result =>
+      result.status === FAIL && (strict || result.level === ERROR),
+  );
+}

package/src/devtools/contract/loadContext.js

@@ -0,0 +1,250 @@
+import { access, readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ENGINE_API_VERSION } from '../../config/opcodes.js';
+
+// Сбор контекста статической проверки: по каталогу пакета игры собирается
+// всё, что удалось прочитать, и помечается недостающее. Ни одна неудача не
+// бросает — правило, которому не хватило входа, вернёт skip.
+//
+// Живые объекты плагинов важнее исходников: gameConfig/authSchema/parts —
+// это вычисленные структуры (импорты, спреды, сгенерированные карты), и
+// парсинг текста врал бы. Поэтому половины плагина импортируются как
+// модули; исходники читаются только там, где проверяется буква кода
+// (engineApi литералом или импортом).
+
+// каталог движка (packages/engine) — из него берётся версия крейта, с
+// которой сверяется пин игры. core/Cargo.toml числится в "files"
+// package.json именно ради этого: иначе в установке из npm версии крейта
+// нет, и правило A5 проверяло бы пин только внутри монорепозитория
+const ENGINE_DIR = new URL('../../../', import.meta.url);
+
+const HOST_ENTRIES = ['src/host/index.js', 'host/index.js'];
+const CLIENT_ENTRIES = ['src/client/index.js', 'client/index.js'];
+
+/**
+ * @param {string} gameDir - Каталог пакета игры.
+ * @returns {Promise<Object>} Контекст правил.
+ */
+export async function loadContext(gameDir) {
+  const dir = path.resolve(gameDir);
+  const ctx = {
+    dir,
+    engineApi: ENGINE_API_VERSION,
+    engineCoreVersion: await readEngineCoreVersion(),
+    pkg: await readJson(path.join(dir, 'package.json')),
+    viteText: await readText(path.join(dir, 'vite.config.js')),
+    cargoText: await readText(path.join(dir, 'core', 'Cargo.toml')),
+    workspaceCargoText: await readText(path.join(dir, 'Cargo.toml')),
+    hostText: await readFirstText(dir, HOST_ENTRIES),
+    clientText: await readFirstText(dir, CLIENT_ENTRIES),
+    hostEntryExists: await exists(path.join(dir, 'src/host/index.js')),
+    clientEntryExists: await exists(path.join(dir, 'src/client/index.js')),
+    notes: [],
+  };
+
+  const distDir = path.join(dir, 'dist');
+
+  ctx.manifest = await readJson(path.join(distDir, 'manifest.json'));
+  ctx.distDir = ctx.manifest ? distDir : null;
+  ctx.distFiles = ctx.manifest ? await listFiles(distDir) : null;
+
+  ctx.hostPlugin = await loadHalf(ctx, 'host', HOST_ENTRIES);
+  ctx.clientPlugin = await loadHalf(ctx, 'client', CLIENT_ENTRIES);
+
+  ctx.gameConfig = ctx.hostPlugin?.gameConfig ?? null;
+  ctx.authSchema = ctx.hostPlugin?.authSchema ?? null;
+  ctx.clientConfig = buildClientConfig(ctx);
+
+  return ctx;
+}
+
+// Половина плагина: сначала исходник (он свежее сборки), при неудаче —
+// собранный entry из манифеста. Клиентский исходник в Node обычно не
+// импортируется вовсе (`import './game.css'` — расширение Vite, не Node),
+// поэтому падение первого кандидата — норма, а не ошибка.
+async function loadHalf(ctx, half, candidates) {
+  const sources = [
+    ...candidates.map(rel => path.join(ctx.dir, rel)),
+    distEntry(ctx, half),
+  ].filter(Boolean);
+
+  const failures = [];
+
+  for (const file of sources) {
+    if (!(await exists(file))) {
+      continue;
+    }
+
+    try {
+      const module = await import(pathToFileURL(file).href);
+      const source = path.relative(ctx.dir, file);
+
+      ctx[`${half}Source`] = source;
+
+      // модуль импортировался, но плагина не отдал: движок берёт половину
+      // ровно из default-экспорта, поэтому это отказ, а не «нечего
+      // проверять» — без ноты автор увидел бы десяток немых skip
+      if (module.default === undefined || module.default === null) {
+        ctx.notes.push(
+          `${half} plugin has no default export (${source}) — the engine ` +
+            'loads the half by it',
+        );
+      }
+
+      return module.default ?? null;
+    } catch (error) {
+      failures.push(`${path.relative(ctx.dir, file)}: ${error.message}`);
+    }
+  }
+
+  ctx.notes.push(
+    failures.length
+      ? `${half} plugin not loaded — ${failures.join('; ')}`
+      : `${half} plugin not found (looked for ${candidates.join(', ')})`,
+  );
+
+  return null;
+}
+
+// entries.* манифеста — URL-ы, какими их видит браузер; на диске им
+// соответствует каталог манифеста (та же арифметика, что в
+// lib/loadGamePackage.js)
+function distEntry(ctx, half) {
+  const entry = ctx.manifest?.entries?.[half];
+
+  if (!entry || !ctx.distDir) {
+    return null;
+  }
+
+  const { assetsBase } = ctx.manifest;
+  const rel =
+    assetsBase && entry.startsWith(assetsBase)
+      ? entry.slice(assetsBase.length)
+      : entry.replace(/^\/+/, '');
+
+  return path.resolve(ctx.distDir, rel);
+}
+
+// клиентский CONFIG_DATA игры собирается хостом (buildClientGameConfig
+// вызывается движком безусловно) — своего файла у него нет
+function buildClientConfig(ctx) {
+  if (typeof ctx.hostPlugin?.buildClientGameConfig !== 'function') {
+    return null;
+  }
+
+  try {
+    return ctx.hostPlugin.buildClientGameConfig();
+  } catch (error) {
+    ctx.notes.push(`buildClientGameConfig() threw: ${error.message}`);
+
+    return null;
+  }
+}
+
+async function readEngineCoreVersion() {
+  const text = await readText(new URL('core/Cargo.toml', ENGINE_DIR));
+
+  return text ? (parseCrateVersion(text) ?? null) : null;
+}
+
+// версия пакета в секции [package] — первый `version = "…"` до следующей
+// секции; TOML-парсера в зависимостях движка нет, а формат здесь наш.
+//
+// Копия живёт в packages/create-vimp-game/src/versions.js: скаффолдер
+// ставится через `npm create` и обязан работать без движка в зависимостях.
+// Разбор обязан совпадать — правьте обе или ни одной (см. тест
+// tests/scaffold/versions.test.js).
+export function parseCrateVersion(text) {
+  const section = text.split(/^\s*\[/m).find(part => part.startsWith('package]'));
+
+  return section?.match(/^\s*version\s*=\s*"([^"]+)"/m)?.[1] ?? null;
+}
+
+async function readJson(file) {
+  const text = await readText(file);
+
+  if (text === null) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+async function readText(file) {
+  try {
+    return await readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function readFirstText(dir, candidates) {
+  for (const rel of candidates) {
+    const text = await readText(path.join(dir, rel));
+
+    if (text !== null) {
+      return text;
+    }
+  }
+
+  return null;
+}
+
+async function exists(file) {
+  try {
+    await access(file);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// плоский список путей внутри dist/ (posix-разделители): правила проверяют
+// наличие ассетов и entry-файлов по нему, а не десятком stat()
+async function listFiles(root) {
+  const found = new Set();
+
+  async function walk(dir, prefix) {
+    let entries;
+
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const full = path.join(dir, entry.name);
+
+      // симлинк-каталог (обычная dev-раскладка: dist/img -> ../assets/img)
+      // у readdir не isDirectory(); без разыменования он попал бы в список
+      // файлом, и правила ассетов дали бы ложный отказ
+      if (entry.isSymbolicLink() ? await isDirectory(full) : entry.isDirectory()) {
+        await walk(full, rel);
+      } else {
+        found.add(rel);
+      }
+    }
+  }
+
+  await walk(root, '');
+
+  return found;
+}
+
+async function isDirectory(file) {
+  try {
+    return (await stat(file)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export default loadContext;

package/src/devtools/contract/result.js

@@ -0,0 +1,55 @@
+// Словарь результатов статической проверки контракта. Он намеренно тот же,
+// что у headless-раннера (devtools/invariants.js): pass / fail / skip —
+// автор плагина читает оба отчёта подряд и не должен держать в голове две
+// системы вердиктов. Отличие одно: у правила есть уровень (error / warn),
+// потому что часть контракта — соглашения (пять колонок статистики), а не
+// жёсткие отказы.
+
+export const PASS = 'pass';
+export const FAIL = 'fail';
+export const SKIP = 'skip';
+
+export const ERROR = 'error';
+export const WARN = 'warn';
+
+/**
+ * «Проверять нечего»: входа нет (игра не собрана, нет package.json).
+ * skip никогда не маскирует нарушение — он означает отсутствие данных.
+ * @param {string} note - Чего именно не хватило.
+ * @returns {Object} { status, violations, note }.
+ */
+export function skip(note) {
+  return { status: SKIP, violations: [], note };
+}
+
+/**
+ * Вердикт по списку нарушений: пустой список — pass.
+ * @param {Array<string>} violations
+ * @param {string} [note]
+ * @returns {Object} { status, violations, note }.
+ */
+export function verdict(violations, note) {
+  return {
+    status: violations.length ? FAIL : PASS,
+    violations,
+    note,
+  };
+}
+
+/**
+ * Сводка по результатам правил.
+ * @param {Array<Object>} results
+ * @returns {Object} { passed, failed, skipped, errors, warnings, violations }.
+ */
+export function summarize(results) {
+  const failed = results.filter(r => r.status === FAIL);
+
+  return {
+    passed: results.filter(r => r.status === PASS).length,
+    failed: failed.length,
+    skipped: results.filter(r => r.status === SKIP).length,
+    errors: failed.filter(r => r.level === ERROR).length,
+    warnings: failed.filter(r => r.level === WARN).length,
+    violations: results.reduce((sum, r) => sum + r.violations.length, 0),
+  };
+}