vimp-engine 0.8.0 → 0.10.0

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

@@ -0,0 +1,43 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// roomForm. Поле вне белого списка форма показывает, лобби отправляет, а
+// хост молча выбрасывает — правило игры, построенное на своей настройке
+// комнаты, не работает и ничего об этом не сообщает. Контролов в v3 ровно
+// четыре: неизвестный пропускается с console.error.
+const HONOURED = ['maps', 'maxPlayers', 'map', 'roundTime', 'mapTime', 'friendlyFire'];
+const CONTROLS = ['text', 'select', 'checkbox', 'radio'];
+
+export default {
+  id: 'B5',
+  name: 'roomForm',
+  level: ERROR,
+  title: 'roomForm uses honoured field names and existing controls',
+
+  check(ctx) {
+    const roomForm = ctx.gameConfig?.roomForm ?? ctx.manifest?.roomForm;
+
+    if (!Array.isArray(roomForm)) {
+      return skip('no roomForm');
+    }
+
+    const violations = [];
+
+    for (const field of roomForm) {
+      if (!HONOURED.includes(field.name)) {
+        violations.push(
+          `roomForm field "${field.name}" is not read by the host ` +
+            `(honoured: ${HONOURED.join(', ')}) — it is silently dropped`,
+        );
+      }
+
+      if (!CONTROLS.includes(field.control)) {
+        violations.push(
+          `roomForm field "${field.name}": control "${field.control}" does ` +
+            `not exist (${CONTROLS.join(', ')})`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b6-panel-reserved-key.js

@@ -0,0 +1,29 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Ключ панели 't' зарезервирован движком под время раунда (Panel шлёт его
+// сама). Игра, занявшая 't' своим полем, получает ячейку, которую движок
+// перезаписывает секундами — без единого предупреждения.
+export default {
+  id: 'B6',
+  name: 'panelReservedKey',
+  level: ERROR,
+  title: "host panel.fields does not use the engine key 't'",
+
+  check(ctx) {
+    const fields = ctx.gameConfig?.panel?.fields;
+
+    if (!fields) {
+      return skip('no gameConfig.panel.fields');
+    }
+
+    const violations = Object.entries(fields)
+      .filter(([, field]) => field?.key === 't')
+      .map(
+        ([name]) =>
+          `panel field "${name}" uses key 't' — reserved by the engine for ` +
+          'the round time',
+      );
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b7-chat-commands.js

@@ -0,0 +1,49 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Движковые команды разбираются switch'ем раньше реестра игровых
+// (CommandProcessor.parseCommand): одноимённая команда плагина
+// регистрируется, но не вызывается никогда.
+const RESERVED = ['/name', '/nr', '/timeleft', '/mapname', '/rank'];
+
+export default {
+  id: 'B7',
+  name: 'chatCommands',
+  level: ERROR,
+  title: 'chat commands do not shadow the engine commands',
+
+  check(ctx) {
+    const commands = ctx.hostPlugin?.chatCommands;
+
+    if (!Array.isArray(commands)) {
+      return skip('no chatCommands array');
+    }
+
+    const violations = [];
+    const seen = new Set();
+
+    for (const command of commands) {
+      const { name } = command ?? {};
+
+      if (typeof name !== 'string' || !name.startsWith('/')) {
+        violations.push(
+          `chat command ${JSON.stringify(name)} has no leading-slash name`,
+        );
+        continue;
+      }
+
+      if (RESERVED.includes(name)) {
+        violations.push(
+          `chat command "${name}" is an engine command — it will never fire`,
+        );
+      }
+
+      if (seen.has(name)) {
+        violations.push(`chat command "${name}" is registered twice`);
+      }
+
+      seen.add(name);
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b8-system-messages.js

@@ -0,0 +1,48 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Регистрация игровых кодов — слепой Object.assign поверх движкового
+// реестра: код в зарезервированном диапазоне затирает движковое сообщение
+// без предупреждения, и вместо «Vote passed» игрок видит игровой текст.
+// Диапазоны — длины движковых групп (client/config/chat messages).
+const RESERVED = { s: 6, v: 5, m: 1, c: 1, n: 1 };
+
+export default {
+  id: 'B8',
+  name: 'systemMessages',
+  level: ERROR,
+  title: 'system message codes stay out of the engine ranges',
+
+  check(ctx) {
+    const messages = ctx.hostPlugin?.systemMessages;
+
+    if (!messages) {
+      return skip('no HostPlugin.systemMessages');
+    }
+
+    const violations = [];
+
+    for (const [name, code] of Object.entries(messages)) {
+      const parsed = /^([a-z]):(\d+)$/.exec(String(code));
+
+      if (!parsed) {
+        violations.push(
+          `systemMessages.${name} is "${code}" — expected "<group>:<index>"`,
+        );
+        continue;
+      }
+
+      const group = parsed[1];
+      const index = Number(parsed[2]);
+      const last = RESERVED[group];
+
+      if (last !== undefined && index <= last) {
+        violations.push(
+          `systemMessages.${name} ("${code}") overwrites the engine message ` +
+            `${group}:${index} (group "${group}" is reserved up to index ${last})`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b9-vote-names.js

@@ -0,0 +1,48 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Имена голосований mapChange/teamChange принадлежат движку. Своё
+// голосование под этим именем не «переопределяет» движковое, а тонет:
+// категорию разбирает HostGame раньше плагина. Обратная сторона той же
+// ошибки — шаблон с именем категории (mapChange): движок рисует
+// mapChangeBySystem/mapChangeByUser, и такой шаблон не показывается никогда.
+const ENGINE_MENU = ['teamChange', 'mapChange'];
+const ENGINE_TEMPLATES = ['teamChange', 'mapChangeBySystem', 'mapChangeByUser'];
+
+export default {
+  id: 'B9',
+  name: 'voteNames',
+  level: ERROR,
+  title: 'custom votes do not reuse the reserved vote names',
+
+  check(ctx) {
+    const vote = ctx.clientConfig?.modules?.vote?.params;
+
+    if (!vote) {
+      return skip('no client vote config');
+    }
+
+    const templates = Object.keys(vote.templates ?? {});
+    const violations = [];
+
+    for (const name of templates) {
+      if (ENGINE_MENU.includes(name) && !ENGINE_TEMPLATES.includes(name)) {
+        violations.push(
+          `vote template "${name}" reuses a reserved vote name — the engine ` +
+            `renders ${ENGINE_TEMPLATES.join(' / ')}`,
+        );
+      }
+    }
+
+    for (const entry of vote.menu ?? []) {
+      const name = Array.isArray(entry) ? entry[0] : entry;
+
+      if (!ENGINE_MENU.includes(name) && !templates.includes(name)) {
+        violations.push(
+          `vote menu entry "${name}" has no template — the vote renders empty`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c1-client-shape.js

@@ -0,0 +1,52 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Поля ClientPlugin и все три хука. Хук с пустым телом — норма,
+// отсутствующий — краш на первом же вызове (движок зовёт их безусловно).
+const REQUIRED = [
+  ['id', 'string'],
+  ['engineApi', 'number'],
+  ['createClientCore', 'function'],
+  ['parts', 'object'],
+  ['bakers', 'object'],
+  ['styles', 'string'],
+];
+
+const HOOKS = ['onAuth', 'onPanel', 'onLocalAction'];
+
+export default {
+  id: 'C1',
+  name: 'clientPluginShape',
+  level: ERROR,
+  title: 'ClientPlugin exports parts, bakers, styles and all three hooks',
+
+  check(ctx) {
+    if (!ctx.clientPlugin) {
+      return skip('client plugin not loaded');
+    }
+
+    const violations = [];
+
+    for (const [field, type] of REQUIRED) {
+      const value = ctx.clientPlugin[field];
+
+      if (value === undefined || value === null) {
+        violations.push(`ClientPlugin.${field} is missing`);
+      } else if (typeof value !== type) {
+        violations.push(
+          `ClientPlugin.${field} is ${typeof value}, expected ${type}`,
+        );
+      }
+    }
+
+    for (const hook of HOOKS) {
+      if (typeof ctx.clientPlugin.hooks?.[hook] !== 'function') {
+        violations.push(
+          `ClientPlugin.hooks.${hook} is missing — an empty body is fine, ` +
+            'a missing hook crashes',
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

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

@@ -0,0 +1,55 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// authSchema. Три ошибки, каждая из которых уже случалась:
+// formId вместо fieldsId (контейнер резолвится в null и экран авторизации
+// умирает TypeError на первом рендере), поле ника (личность приходит из
+// JWT лобби) и поле выбора модели под своим именем — движок читает
+// params.model, всё остальное до Participant не доезжает.
+const NICKNAME = /^(name|nick|nickname|player|playername|login|username)$/i;
+
+export default {
+  id: 'C10',
+  name: 'authSchema',
+  level: ERROR,
+  title: 'authSchema: fieldsId, no nickname field, the model field',
+
+  check(ctx) {
+    if (!ctx.authSchema) {
+      return skip('no HostPlugin.authSchema');
+    }
+
+    const { elems = {}, params = [] } = ctx.authSchema;
+    const violations = [];
+
+    if (elems.formId !== undefined) {
+      violations.push(
+        "authSchema.elems.formId does not exist — the key is 'fieldsId'",
+      );
+    }
+
+    if (elems.fieldsId === undefined) {
+      violations.push(
+        'authSchema.elems.fieldsId is missing — the engine fills that ' +
+          'container with the form fields',
+      );
+    }
+
+    for (const field of params) {
+      if (NICKNAME.test(field.name)) {
+        violations.push(
+          `authSchema param "${field.name}" looks like a nickname field — ` +
+            'identity comes from the lobby JWT',
+        );
+      }
+    }
+
+    if (!params.some(field => field.name === 'model')) {
+      violations.push(
+        'authSchema has no param named exactly "model" — the engine reads ' +
+          'params.model when it creates the participant',
+      );
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c2-parts-registered.js

@@ -0,0 +1,43 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Класс парта регистрируется во Factory только через entitiesOnCanvas.
+// Перечисления в parts и gameSets недостаточно: движок отвечает
+// «Constructor for X not found.» на первом кадре, где ключ ожил.
+export default {
+  id: 'C2',
+  name: 'partsRegistered',
+  level: ERROR,
+  title: 'every gameSets class is in entitiesOnCanvas and exported in parts',
+
+  check(ctx) {
+    const parts = ctx.clientConfig?.parts;
+
+    if (!parts?.gameSets) {
+      return skip('no client parts.gameSets');
+    }
+
+    const onCanvas = parts.entitiesOnCanvas ?? {};
+    const exported = ctx.clientPlugin?.parts ?? null;
+    const violations = [];
+
+    for (const [key, names] of Object.entries(parts.gameSets)) {
+      for (const name of names ?? []) {
+        if (onCanvas[name] === undefined) {
+          violations.push(
+            `gameSets["${key}"] uses part "${name}", missing from ` +
+              'entitiesOnCanvas — it is never registered',
+          );
+        }
+
+        if (exported && exported[name] === undefined) {
+          violations.push(
+            `gameSets["${key}"] uses part "${name}", not exported in ` +
+              'ClientPlugin.parts',
+          );
+        }
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c3-game-sets-coverage.js

@@ -0,0 +1,35 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Ключ снапшот-схемы без записи в gameSets — чёрный холст: клиент получает
+// строки кадра и не знает, чем их рисовать. То же для setId карты: без него
+// статика полотна не создаётся. Раннер ловит это только для ключей, ожив-
+// ших в конкретном прогоне, — статически видно все.
+export default {
+  id: 'C3',
+  name: 'gameSetsCoverage',
+  level: ERROR,
+  title: 'every snapshot key and map setId has a gameSets entry',
+
+  check(ctx) {
+    const gameSets = ctx.clientConfig?.parts?.gameSets;
+    const snapshot = ctx.gameConfig?.snapshot;
+
+    if (!gameSets || !snapshot) {
+      return skip('no client parts.gameSets or gameConfig.snapshot');
+    }
+
+    const violations = Object.keys(snapshot)
+      .filter(key => !gameSets[key])
+      .map(key => `snapshot key "${key}" has no parts.gameSets entry`);
+
+    for (const [name, map] of Object.entries(ctx.gameConfig.maps ?? {})) {
+      if (map?.setId !== undefined && !gameSets[map.setId]) {
+        violations.push(
+          `map "${name}": setId "${map.setId}" has no parts.gameSets entry`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

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

@@ -0,0 +1,33 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Пул сервисов клиента ровно из трёх имён (client/main.js). Незнакомое имя
+// не ошибка для движка: part получает undefined и рисует пустоту — карта
+// без assetsBase выглядит как чистый холст без единой строки в консоли.
+const SERVICES = ['renderer', 'soundManager', 'assetsBase'];
+
+export default {
+  id: 'C4',
+  name: 'componentDependencies',
+  level: ERROR,
+  title: 'componentDependencies name only existing services',
+
+  check(ctx) {
+    const deps = ctx.clientConfig?.parts?.componentDependencies;
+
+    if (!deps) {
+      return skip('no client parts.componentDependencies');
+    }
+
+    // раскладка «сервис → парты, которым он нужен» (client.js игры)
+    const violations = Object.keys(deps)
+      .filter(service => !SERVICES.includes(service))
+      .map(
+        service =>
+          `componentDependencies declares service "${service}" — the engine ` +
+          `provides only ${SERVICES.join(', ')} (an unknown one is silently ` +
+          'undefined in the part)',
+      );
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c5-panel-time-field.js

@@ -0,0 +1,42 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Панель шлёт время раунда под ключом 't' безусловно. Клиент, не
+// объявивший для него поле type: 'time', получает значение с именем
+// undefined — время просто не появляется на HUD.
+export default {
+  id: 'C5',
+  name: 'panelTimeField',
+  level: ERROR,
+  title: "the client panel maps key 't' to a type: 'time' field",
+
+  check(ctx) {
+    const panel = ctx.clientConfig?.modules?.panel;
+
+    if (!panel) {
+      return skip('no client panel config');
+    }
+
+    const name = panel.keys?.t;
+
+    if (name === undefined) {
+      return verdict([
+        "panel.keys has no 't' — the engine sends the round time under it",
+      ]);
+    }
+
+    const field = (panel.fields ?? []).find(item => item.name === name);
+
+    if (!field) {
+      return verdict([`panel.keys.t maps to "${name}", which has no field`]);
+    }
+
+    if (field.type !== 'time') {
+      return verdict([
+        `panel field "${name}" (key 't') has type "${field.type}", ` +
+          "expected 'time'",
+      ]);
+    }
+
+    return verdict([]);
+  },
+};

package/src/devtools/contract/rules/c6-stat-columns.js

@@ -0,0 +1,36 @@
+import { WARN, skip, verdict } from '../result.js';
+
+// Движок пишет ровно пять имён (name, status, score, deaths, latency), и
+// его CSS свёрстана под пять колонок. Другое число — не отказ: игра вправе
+// привезти свои стили в ClientPlugin.styles. Поэтому warn, а не error.
+export default {
+  id: 'C6',
+  name: 'statColumns',
+  level: WARN,
+  title: 'stat declares five columns (the engine CSS assumes five)',
+
+  check(ctx) {
+    const columns = ctx.clientConfig?.modules?.stat?.params?.columns;
+
+    if (!columns) {
+      return skip('no client stat columns');
+    }
+
+    if (columns.length === 5) {
+      return verdict([]);
+    }
+
+    const note = ctx.clientPlugin?.styles
+      ? 'the plugin ships its own styles'
+      : undefined;
+
+    return verdict(
+      [
+        `stat declares ${columns.length} column(s): the engine populates ` +
+          'exactly name, status, score, deaths, latency and its CSS is laid ' +
+          'out for five',
+      ],
+      note,
+    );
+  },
+};

package/src/devtools/contract/rules/c7-key-sets.js

@@ -0,0 +1,71 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// keySetList: [0] — набор наблюдателя, [1] — игрока. Без nextPlayer/
+// prevPlayer наблюдатель заперт на одной камере; занятый движковый код
+// (чат, голосование, статистика, escape, enter) до игры не доходит;
+// расхождение имён с playerKeys даёт клавишу, которая ничего не шлёт.
+const ENGINE_CODES = { 9: 'stat', 13: 'enter', 27: 'escape', 67: 'chat', 77: 'vote' };
+const SPECTATOR_ACTIONS = ['nextPlayer', 'prevPlayer'];
+
+export default {
+  id: 'C7',
+  name: 'keySets',
+  level: ERROR,
+  title: 'keySetList: spectator actions, engine codes, playerKeys parity',
+
+  check(ctx) {
+    const keySetList = ctx.clientConfig?.modules?.controls?.keySetList;
+
+    if (!Array.isArray(keySetList)) {
+      return skip('no client controls.keySetList');
+    }
+
+    const violations = [];
+    const spectator = Object.values(keySetList[0] ?? {});
+
+    for (const action of SPECTATOR_ACTIONS) {
+      if (!spectator.includes(action)) {
+        violations.push(
+          `keySetList[0] (spectator) has no "${action}" — the spectator ` +
+            'cannot switch camera',
+        );
+      }
+    }
+
+    keySetList.forEach((set, index) => {
+      for (const code of Object.keys(set ?? {})) {
+        if (ENGINE_CODES[code]) {
+          violations.push(
+            `keySetList[${index}] binds code ${code} — the engine owns it ` +
+              `(${ENGINE_CODES[code]})`,
+          );
+        }
+      }
+    });
+
+    const playerKeys = ctx.gameConfig?.playerKeys;
+
+    if (playerKeys) {
+      const bound = new Set(Object.values(keySetList[1] ?? {}));
+      const declared = new Set(Object.keys(playerKeys));
+
+      for (const action of declared) {
+        if (!bound.has(action)) {
+          violations.push(
+            `playerKeys."${action}" has no key in keySetList[1]`,
+          );
+        }
+      }
+
+      for (const action of bound) {
+        if (!declared.has(action)) {
+          violations.push(
+            `keySetList[1] binds "${action}", missing from gameConfig.playerKeys`,
+          );
+        }
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c8-baked-assets.js

@@ -0,0 +1,34 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Неизвестное имя запекаемого ассета пропускается молча: part получает
+// пустой assets и рисует ничего.
+export default {
+  id: 'C8',
+  name: 'bakedAssets',
+  level: ERROR,
+  title: 'bakedAssets names exist in ClientPlugin.bakers',
+
+  check(ctx) {
+    const baked = ctx.clientConfig?.parts?.bakedAssets;
+    const bakers = ctx.clientPlugin?.bakers;
+
+    if (!baked || !bakers) {
+      return skip('no bakedAssets or client plugin not loaded');
+    }
+
+    const violations = [];
+
+    for (const [canvas, entries] of Object.entries(baked)) {
+      for (const entry of entries ?? []) {
+        if (bakers[entry.name] === undefined) {
+          violations.push(
+            `bakedAssets["${canvas}"]: baker "${entry.name}" is not in ` +
+              'ClientPlugin.bakers — the entry is skipped silently',
+          );
+        }
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/c9-chat-messages.js

@@ -0,0 +1,41 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Каждому зарегистрированному коду нужен текст на том же индексе в
+// клиентском реестре. Недостающий текст рендерится пустотой: событие
+// произошло, в чате ничего.
+export default {
+  id: 'C9',
+  name: 'chatMessages',
+  level: ERROR,
+  title: 'every system message code has a client text',
+
+  check(ctx) {
+    const messages = ctx.hostPlugin?.systemMessages;
+    const texts = ctx.clientConfig?.modules?.chat?.params?.messages;
+
+    if (!messages || !texts) {
+      return skip('no systemMessages or client chat messages');
+    }
+
+    const violations = [];
+
+    for (const [name, code] of Object.entries(messages)) {
+      const parsed = /^([a-z]):(\d+)$/.exec(String(code));
+
+      if (!parsed) {
+        continue;
+      }
+
+      const group = texts[parsed[1]];
+
+      if (group?.[Number(parsed[2])] === undefined) {
+        violations.push(
+          `systemMessages.${name} ("${code}") has no text in ` +
+            `chat.params.messages.${parsed[1]}[${parsed[2]}]`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};