vimp-engine 0.22.1 → 0.24.0

package/src/devtools/contract/rules/b10-respawns.js

@@ -18,9 +18,11 @@ export default {
       return skip('no gameConfig.maps or gameConfig.teams');
     }
 
-    const playing = Object.keys(teams).filter(
-      team => team !== ctx.gameConfig.spectatorTeam,
-    );
+    // эффективное значение: игра вправе не объявлять spectatorTeam (И2), а
+    // по объявленному команда наблюдателей попала бы в играющие и правило
+    // потребовало бы для неё респауны
+    const spectatorTeam = ctx.gameConfigView?.spectatorTeam ?? null;
+    const playing = Object.keys(teams).filter(team => team !== spectatorTeam);
     const maxPlayers = ctx.gameConfig.roomDefaults?.maxPlayers;
     const violations = [];
 

package/src/devtools/contract/rules/b2-engine-api.js

@@ -1,20 +1,35 @@
-import { ERROR, skip, verdict } from '../result.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
+import {
+  ENGINE_CAPABILITIES,
+  CAPABILITIES,
+} from '../../../lib/capabilities.js';
 
-// engineApi живёт в трёх местах (манифест, HostPlugin, ClientPlugin) и во
-// всех трёх обязан быть импортом ENGINE_API_VERSION, а не числом: литерал
-// не расходится со сборкой движка в момент написания и молча расходится
-// через релиз, после чего плагин отклоняется гейтом совместимости.
+// `engineApi` живёт в трёх местах (манифест, HostPlugin, ClientPlugin).
+// Расхождение между ними — рассинхрон сборки внутри пакета, и это ошибка.
+// Расхождение с установленным движком ошибкой БОЛЬШЕ НЕ является (этап 5
+// плана plugin-forward-compat): `ENGINE_API_VERSION` заморожен на 4 и не
+// гейт, а игра, собранная год назад против движка не последней версии, —
+// нормальное состояние, ради которого весь план и делался.
+//
+// Импортом, а не литералом, значение остаётся по-прежнему: литерал не
+// расходится со сборкой движка в момент написания и молча расходится через
+// релиз, после чего манифест игры врёт о своём поколении.
+//
+// Возможности из `manifest.requires` проверяются по реестру установленного
+// движка: имени, которого нет, движок дать не может — игра просит будущее.
 export default {
   id: 'B2',
   name: 'engineApiVersion',
   level: ERROR,
-  title: 'engineApi matches ENGINE_API_VERSION in all three places',
+  title: 'engineApi is consistent and requires name existing capabilities',
 
   check(ctx) {
+    // манифест первый: он — то, что о поколении пакета читает движок,
+    // и с ним сверяются половины плагина
     const declared = [
+      ['manifest', ctx.manifest?.engineApi],
       ['host plugin', ctx.hostPlugin?.engineApi],
       ['client plugin', ctx.clientPlugin?.engineApi],
-      ['manifest', ctx.manifest?.engineApi],
     ].filter(([, value]) => value !== undefined);
 
     if (!declared.length) {
@@ -22,11 +37,14 @@ export default {
     }
 
     const violations = [];
+    const retired = [];
+    const [source, reference] = declared[0];
 
     for (const [where, value] of declared) {
-      if (value !== ctx.engineApi) {
+      if (value !== reference) {
         violations.push(
-          `${where} declares engineApi v${value}, this engine is v${ctx.engineApi}`,
+          `${where} declares engineApi v${value}, but ${source} declares ` +
+            `v${reference} — rebuild the package`,
         );
       }
     }
@@ -42,6 +60,59 @@ export default {
       }
     }
 
-    return verdict(violations);
+    // форма `requires` — то же недоверие, что в checkPluginCompatibility:
+    // строка проитерировалась бы здесь посимвольно, объект уронил бы чекер
+    // «not iterable»
+    const requires = ctx.manifest?.requires;
+
+    if (requires === undefined || requires === null) {
+      return finish(violations, retired);
+    }
+
+    if (
+      !Array.isArray(requires) ||
+      requires.some(name => typeof name !== 'string')
+    ) {
+      violations.push(
+        'manifest.requires must be an array of capability names, got ' +
+          `${JSON.stringify(requires)} — the engine reads it before it ` +
+          'loads the plugin',
+      );
+
+      return finish(violations, retired);
+    }
+
+    for (const name of requires) {
+      // has, а не CAPABILITIES.includes: реестр возможностей append-only,
+      // и выведенное алиасом имя движок принимает вечно (ENGINE_CAPABILITIES.
+      // has в checkPluginCompatibility). Сверка с одними активными именами
+      // отвергала бы игру за то, что движок переименовал возможность — тот
+      // самый отказ по возрасту, который план и снимал
+      if (!ENGINE_CAPABILITIES.has(name)) {
+        violations.push(
+          `manifest.requires names '${name}', which this engine does not ` +
+            `provide — known capabilities: ${CAPABILITIES.join(', ')}`,
+        );
+      } else if (ENGINE_CAPABILITIES.isRetired(name)) {
+        retired.push(
+          `manifest.requires names '${name}', which was retired — it still ` +
+            `works (the engine resolves it to ` +
+            `'${ENGINE_CAPABILITIES.resolve(name)}' forever), but a new game ` +
+            `should declare '${ENGINE_CAPABILITIES.resolve(name)}' itself`,
+        );
+      }
+    }
+
+    return finish(violations, retired);
   },
 };
+
+// то же, что делают B5 и C10: выведенное имя — не отказ, а предупреждение.
+// Отвергать за него значило бы отвергать игру за возраст (И1)
+function finish(violations, retired) {
+  if (violations.length === 0 && retired.length > 0) {
+    return verdict(retired, 'retired capability names still resolve', WARN);
+  }
+
+  return verdict(violations);
+}

package/src/devtools/contract/rules/b3-game-config-shape.js

@@ -1,11 +1,31 @@
-import { assertGameConfigShape } from '../../../lib/gamePlugin.js';
-import { ERROR, skip, verdict } from '../result.js';
+import {
+  REQUIRED_GAME_CONFIG_PATHS,
+  createGameConfigView,
+} from '../../../lib/gameConfigView.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 
 // Тот же гейт, что стоит на боевом пути загрузки плагина
-// (lib/gamePlugin.js): обязательные пути gameConfig плюс связь
+// (lib/gameConfigView.js): обязательные пути gameConfig плюс связь
 // spectatorTeam ↔ teams (под noSpectators — «ровно одна команда»).
 // Дублировать его список здесь нельзя — он обязан эволюционировать в одном
 // месте.
+//
+// Всё, что не в REQUIRED, движок подставляет сам (И2 этапа 2 плана
+// plugin-forward-compat) — это не отказ. Но полагаться на движковое
+// умолчание разработчик должен осознанно, поэтому необъявленные поля
+// перечисляются предупреждением.
+const DEFAULTED = [
+  'roomDefaults.maxPlayers',
+  'parts.weapons',
+  'parts.friendlyFire',
+  'panel.fields',
+  'spectatorTeam',
+];
+
+function getPath(source, dottedPath) {
+  return dottedPath.split('.').reduce((value, key) => value?.[key], source);
+}
+
 export default {
   id: 'B3',
   name: 'gameConfigShape',
@@ -18,11 +38,32 @@ export default {
     }
 
     try {
-      assertGameConfigShape(ctx.hostPlugin);
+      createGameConfigView(ctx.hostPlugin.gameConfig, ctx.hostPlugin.id);
     } catch (error) {
       return verdict([error.message]);
     }
 
-    return verdict([]);
+    // noSpectators — своя ветка контракта: spectatorTeam там не бывает
+    const declared = ctx.hostPlugin.gameConfig;
+    const paths =
+      declared?.noSpectators === true
+        ? DEFAULTED.filter(path => path !== 'spectatorTeam')
+        : DEFAULTED;
+
+    const relied = paths.filter(path => {
+      const value = getPath(declared, path);
+
+      return value === undefined || value === null;
+    });
+
+    return verdict(
+      relied.map(
+        path =>
+          `gameConfig.${path} is not declared — the engine falls back to ` +
+          'its own default; declare it if the game means something else',
+      ),
+      `required: ${REQUIRED_GAME_CONFIG_PATHS.join(', ')}`,
+      WARN,
+    );
   },
 };

package/src/devtools/contract/rules/b4-teams.js

@@ -17,7 +17,10 @@ export default {
       return skip('no gameConfig.teams');
     }
 
-    const { spectatorTeam } = ctx.gameConfig;
+    // эффективное значение, а не объявленное: движок выводит spectatorTeam
+    // из команды `spectators`, и игра вправе его не писать (И2)
+    const spectatorTeam = ctx.gameConfigView?.spectatorTeam ?? null;
+    const declared = ctx.gameConfig.spectatorTeam;
     const violations = [];
 
     if (ctx.gameConfig.noSpectators === true) {
@@ -33,9 +36,9 @@ export default {
       return verdict(violations);
     }
 
-    if (teams[spectatorTeam] === undefined) {
+    if (declared !== undefined && teams[declared] === undefined) {
       violations.push(
-        `spectatorTeam "${spectatorTeam}" is not a key of teams ` +
+        `spectatorTeam "${declared}" is not a key of teams ` +
           `(${Object.keys(teams).join(', ')})`,
       );
     }

package/src/devtools/contract/rules/b5-room-form.js

@@ -1,13 +1,26 @@
-import { ERROR, skip, verdict } from '../result.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 import { anchorPattern } from '../../../lib/formPattern.js';
+import {
+  formControls,
+  ACTIVE_FORM_CONTROLS,
+} from '../../../lib/formControls.js';
 
 // roomForm. Поле вне белого списка форма показывает, лобби отправляет, а
 // хост молча выбрасывает — правило игры, построенное на своей настройке
-// комнаты, не работает и ничего об этом не сообщает. Контролов в v3 ровно
-// четыре: неизвестный пропускается с console.error. `regExp` едет в манифесте
-// строкой и компилируется уже у игрока — некомпилируемая ловится здесь.
-const HONOURED = ['maps', 'maxPlayers', 'map', 'roundTime', 'mapTime', 'friendlyFire'];
-const CONTROLS = ['text', 'select', 'checkbox', 'radio'];
+// комнаты, не работает и ничего об этом не сообщает. Контрол проверяется по
+// реестру (lib/formControls.js): неизвестный пропускается с console.error,
+// выведенный из эксплуатации строится алиасом и потому только WARN — новая
+// игра его писать не должна, старая продолжает работать. `regExp` едет в
+// манифесте строкой и компилируется уже у игрока — некомпилируемая ловится
+// здесь.
+const HONOURED = [
+  'maps',
+  'maxPlayers',
+  'map',
+  'roundTime',
+  'mapTime',
+  'friendlyFire',
+];
 
 export default {
   id: 'B5',
@@ -23,6 +36,7 @@ export default {
     }
 
     const violations = [];
+    const retired = [];
 
     for (const field of roomForm) {
       if (!HONOURED.includes(field.name)) {
@@ -32,10 +46,20 @@ export default {
         );
       }
 
-      if (!CONTROLS.includes(field.control)) {
+      if (!formControls.has(field.control)) {
         violations.push(
           `roomForm field "${field.name}": control "${field.control}" does ` +
-            `not exist (${CONTROLS.join(', ')})`,
+            `not exist (${ACTIVE_FORM_CONTROLS.join(', ')})`,
+        );
+      } else if (formControls.isRetired(field.control)) {
+        const entry = formControls.get(field.control);
+
+        retired.push(
+          `roomForm field "${field.name}": control "${field.control}" was ` +
+            `retired in plugin API v${entry.retiredIn} — it still works ` +
+            `(the engine builds it as "${formControls.resolve(field.control)}" ` +
+            `forever), but a new game should declare ` +
+            `"${formControls.resolve(field.control)}" itself`,
         );
       }
 
@@ -54,6 +78,14 @@ export default {
       }
     }
 
+    if (violations.length === 0 && retired.length > 0) {
+      return verdict(
+        retired,
+        'retired controls still build, via aliases',
+        WARN,
+      );
+    }
+
     return verdict(violations);
   },
 };

package/src/devtools/contract/rules/c10-auth-schema.js

@@ -1,5 +1,9 @@
-import { ERROR, skip, verdict } from '../result.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 import { resolveValidator } from '../../../lib/validators.js';
+import {
+  formControls,
+  ACTIVE_FORM_CONTROLS,
+} from '../../../lib/formControls.js';
 
 // authSchema. Четыре ошибки, каждая из которых уже случалась:
 // formId вместо fieldsId (контейнер резолвится в null и экран авторизации
@@ -24,6 +28,7 @@ export default {
 
     const { elems = {}, params = [] } = ctx.authSchema;
     const violations = [];
+    const retired = [];
 
     if (elems.formId !== undefined) {
       violations.push(
@@ -48,6 +53,24 @@ export default {
         );
       }
 
+      const control = field.options?.control;
+
+      if (control !== undefined && !formControls.has(control)) {
+        violations.push(
+          `authSchema param "${field.name}": control "${control}" does not ` +
+            `exist (${ACTIVE_FORM_CONTROLS.join(', ')}) — the form throws ` +
+            "'unknown control' and the auth screen never renders",
+        );
+      } else if (control !== undefined && formControls.isRetired(control)) {
+        retired.push(
+          `authSchema param "${field.name}": control "${control}" was ` +
+            `retired in plugin API v${formControls.get(control).retiredIn} — ` +
+            `it still works (the engine builds and validates it as ` +
+            `"${formControls.resolve(control)}" forever), but a new game ` +
+            `should declare "${formControls.resolve(control)}" itself`,
+        );
+      }
+
       const validatorName = field.options?.validator;
 
       // опечатка в имени (как и не-функция под верным именем) = поле не
@@ -73,6 +96,16 @@ export default {
       );
     }
 
+    // то же, что делает B5 для roomForm: выведенный контрол — не отказ, а
+    // предупреждение, иначе правило отвергало бы игру за возраст (И1)
+    if (violations.length === 0 && retired.length > 0) {
+      return verdict(
+        retired,
+        'retired controls still build and validate, via aliases',
+        WARN,
+      );
+    }
+
     return verdict(violations);
   },
 };

package/src/devtools/contract/rules/c4-component-dependencies.js

@@ -1,20 +1,15 @@
 import { ERROR, WARN, skip, verdict } from '../result.js';
+import { SERVICES } from '../../../config/clientServices.js';
 
-// Движковых сервисов ровно пять (client/main.js), но пул ими не
-// исчерпывается: игра доливает туда свои через ClientPlugin.hooks.services(core)
-// — например геометрию предсказанной динамики карты
-// (docs/en/plugin-api.md «hooks.services»). Незнакомое имя не ошибка для
-// движка: part получает undefined и рисует пустоту — карта без assetsBase
-// выглядит как чистый холст без единой строки в консоли, ради этого правило
-// и существует.
-const SERVICES = [
-  'renderer',
-  'soundManager',
-  'assetsBase',
-  'localPlayer',
-  // места в глобальном топе (snakes-v3 этап 4)
-  'accolades',
-];
+// Движковый пул сервисов держит реестр (config/clientServices.js), но пул
+// ими не исчерпывается: игра доливает туда свои через
+// ClientPlugin.hooks.services(core) — например геометрию предсказанной
+// динамики карты (docs/en/plugin-api.md «hooks.services»). Незнакомое имя не
+// ошибка для движка: part получает undefined и рисует пустоту — карта без
+// assetsBase выглядит как чистый холст без единой строки в консоли, ради
+// этого правило и существует. Правило остаётся ERROR: оно работает на этапе
+// разработки игры, а не в рантайме.
+export { SERVICES };
 
 export default {
   id: 'C4',

package/src/devtools/surface/abiParse.js

@@ -0,0 +1,175 @@
+// Разбор `core/src/abi.rs` — единственный раздел слепка плагинной
+// поверхности, который нельзя собрать импортом: методы wasm-ABI живут внутри
+// `macro_rules!`, раскрывающихся уже в крейте игры. Слепок читает файл как
+// текст и вытаскивает имена и нормализованные сигнатуры `pub fn`.
+//
+// Разбор обязан ПАДАТЬ, а не возвращать пустоту: молчаливо пустой раздел
+// слепка пропустит любое нарушение И1/И3 (plan/plugin-forward-compat).
+
+// имя макроса → раздел слепка (`abi.game` / `abi.client`)
+const MACRO_SECTIONS = {
+  // имена макросов Rust — строками: camelCase к ним неприменим
+  'export_game_core_abi': 'game',
+  'export_client_core_abi': 'client',
+};
+
+/**
+ * @param {string} source - Содержимое `core/src/abi.rs`.
+ * @returns {{game: Object[], client: Object[]}} Методы ABI по разделам,
+ *   каждый — { name, args, ret }, отсортированные по имени.
+ */
+export function parseAbi(source) {
+  const blocks = splitMacros(source);
+
+  if (blocks.length === 0) {
+    throw new Error(
+      'abiParse: no macro_rules! block found in core/src/abi.rs — the file ' +
+        'was restructured; fix the parser instead of letting the surface ' +
+        'snapshot go silently empty',
+    );
+  }
+
+  const sections = {};
+
+  for (const block of blocks) {
+    const section = MACRO_SECTIONS[block.macro];
+
+    if (!section) {
+      continue; // макрос вне ABI плагина — не часть поверхности
+    }
+
+    const methods = parseMethods(block.body);
+
+    if (methods.length === 0) {
+      throw new Error(
+        `abiParse: macro_rules! ${block.macro} yielded no "pub fn" — the ` +
+          'file was restructured; fix the parser',
+      );
+    }
+
+    sections[section] = methods.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  for (const [macro, section] of Object.entries(MACRO_SECTIONS)) {
+    if (!sections[section]) {
+      throw new Error(
+        `abiParse: macro_rules! ${macro} not found in core/src/abi.rs`,
+      );
+    }
+  }
+
+  return sections;
+}
+
+// тело каждого `macro_rules! <name> { … }` — от имени до парной скобке
+function splitMacros(source) {
+  const re = /macro_rules!\s+([a-z_0-9]+)\s*\{/g;
+  const blocks = [];
+  let match;
+
+  while ((match = re.exec(source)) !== null) {
+    const open = re.lastIndex - 1;
+    const close = matchBrace(source, open, '{', '}');
+
+    blocks.push({
+      macro: match[1],
+      body: source.slice(open + 1, close),
+    });
+  }
+
+  return blocks;
+}
+
+// `pub fn name(args) -> ret` внутри тела макроса; тело метода пропускается
+function parseMethods(body) {
+  const re = /pub\s+fn\s+([a-z_0-9]+)\s*\(/g;
+  const methods = [];
+  let match;
+
+  while ((match = re.exec(body)) !== null) {
+    const open = re.lastIndex - 1;
+    const close = matchBrace(body, open, '(', ')');
+    const tail = body.slice(close + 1);
+    const arrow = /^\s*->([^{;]+)/.exec(tail);
+
+    methods.push({
+      name: match[1],
+      args: splitArgs(body.slice(open + 1, close)).map(normalizeType),
+      ret: arrow ? normalizeType(arrow[1]) : '()',
+    });
+  }
+
+  return methods;
+}
+
+// индекс скобки, парной открывающей на позиции `open`
+function matchBrace(source, open, openChar, closeChar) {
+  let depth = 0;
+
+  for (let i = open; i < source.length; i += 1) {
+    if (source[i] === openChar) {
+      depth += 1;
+    } else if (source[i] === closeChar) {
+      depth -= 1;
+
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+
+  throw new Error(`abiParse: unbalanced ${openChar} at offset ${open}`);
+}
+
+// список аргументов по запятым верхнего уровня; получатель (`&self`,
+// `&mut self`) в сигнатуру не входит — он не часть бинарного контракта
+function splitArgs(list) {
+  const args = [];
+  let depth = 0;
+  let current = '';
+
+  for (const ch of list) {
+    if (ch === '<' || ch === '(' || ch === '[') {
+      depth += 1;
+    } else if (ch === '>' || ch === ')' || ch === ']') {
+      depth -= 1;
+    }
+
+    if (ch === ',' && depth === 0) {
+      args.push(current);
+      current = '';
+      continue;
+    }
+
+    current += ch;
+  }
+
+  args.push(current);
+
+  return args
+    .map(arg => arg.trim())
+    .filter(arg => arg.length > 0 && !/^&?\s*(mut\s+)?self$/.test(arg))
+    .map(arg => {
+      const colon = arg.indexOf(':');
+
+      // аргумент без имени в этих макросах не встречается: имя есть всегда
+      return colon === -1 ? arg : arg.slice(colon + 1);
+    });
+}
+
+// Стабильная строка типа: меняется тогда и только тогда, когда меняется
+// бинарный контракт. Ссылка/`mut`/пробелы/путь до wasm-bindgen на него не
+// влияют; `Result<T, JsError>` сворачивается в `Result<T>` — вариант ошибки
+// у всех методов один.
+function normalizeType(type) {
+  const flat = type
+    .replaceAll('::wasm_bindgen::', '')
+    .replaceAll('wasm_bindgen::', '')
+    .replace(/\bmut\b/g, '')
+    .replaceAll('&', '')
+    .replace(/\s+/g, '');
+
+  return flat.replace(/^Result<(.*),JsError>$/, 'Result<$1>');
+}
+
+export default parseAbi;