vimp-engine 0.7.2 → 0.8.0

package/src/client/debug.js

@@ -0,0 +1,158 @@
+// Браузерная половина отладочного контура (этап 6 плана plan/done/ai-debug).
+//
+// Всё, что headless-прогон не воспроизводит — реальный WebRTC, PixiJS, живой
+// ввод человека — читается и записывается отсюда: `window.__vimpDebug`
+// вызывается из DevTools или через Chrome MCP (javascript_tool,
+// read_console_messages), без участия человека в разборе.
+//
+// Записанный сценарий уезжает на мастер (POST /debug/report, только dev) в
+// тот же `.debug/`, откуда его берёт `npm run sim:replay` — браузерный баг
+// становится headless-прогоном.
+
+// Единый префикс структурированного лога: по нему Chrome MCP фильтрует
+// консоль (read_console_messages pattern) вместо чтения всего потока.
+export const DEBUG_PREFIX = '[vimp:debug]';
+
+export function debugLog(...args) {
+  console.log(DEBUG_PREFIX, ...args);
+}
+
+/**
+ * Собирает отладочный API вкладки.
+ * @param {Object} params
+ * @param {Function} params.getHostController - Текущий HostController (null,
+ *   если вкладка не хостит комнату).
+ * @param {Function} params.getClientCore - Текущий ClientCore.
+ * @param {string} params.reportUrl - Эндпоинт выгрузки на мастере.
+ * @param {Function} [params.fetchImpl] - fetch (подменяется в тестах).
+ * @param {Function} [params.log] - Логгер (подменяется в тестах).
+ * @returns {Object} API для window.__vimpDebug.
+ */
+export function createDebugApi({
+  getHostController,
+  getClientCore,
+  reportUrl,
+  fetchImpl,
+  log = debugLog,
+}) {
+  const post = fetchImpl ?? ((...args) => fetch(...args));
+
+  // отладка не должна молча возвращать null там, где вкладка просто не
+  // хостит комнату: причина «нечего дампить» и «дамп сломался» — разные
+  const requireHost = () => {
+    const hostController = getHostController();
+
+    if (!hostController) {
+      throw new Error('this tab is not hosting a room');
+    }
+
+    return hostController;
+  };
+
+  /**
+   * Выгружает произвольную полезную нагрузку на мастер.
+   * @param {string} kind - scenario | dump | divergence.
+   * @param {*} payload
+   * @param {string} [note] - Пометка человека («танк в стене на respawn»).
+   * @returns {Promise<Object>} Ответ мастера ({ file, bytes }).
+   */
+  const save = async (kind, payload, note) => {
+    const res = await post(reportUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ kind, payload, note }),
+    });
+
+    const body = await res.json();
+
+    if (!res.ok) {
+      throw new Error(`debug report rejected: ${body.error ?? res.status}`);
+    }
+
+    log(`${kind} saved to .debug/${body.file}`);
+
+    return body;
+  };
+
+  return {
+    save,
+
+    /**
+     * Дамп авторитетной половины (мета хоста + мир ядра, этап 4) рядом со
+     * сценой этого клиента — «в ядре тело есть, на холсте пусто» видно
+     * только при обеих половинах разом.
+     * @param {Object} [options]
+     * @param {boolean} [options.save] - Выгрузить на мастер.
+     * @param {string} [options.note]
+     * @returns {Promise<Object>}
+     */
+    async dump({ save: doSave = false, note } = {}) {
+      const host = await requireHost().dump();
+
+      log('dump', host);
+
+      if (doSave) {
+        await save('dump', host, note);
+      }
+
+      return host;
+    },
+
+    /**
+     * Начинает запись живого матча в формат сценария.
+     * @returns {Promise<boolean>} false — комната поднята без dev-режима.
+     */
+    async startRecording() {
+      const started = await requireHost().startRecording();
+
+      log(started ? 'recording started' : 'recording unavailable (no dev mode)');
+
+      return started;
+    },
+
+    /**
+     * Останавливает запись и (по умолчанию) выгружает сценарий на мастер.
+     * @param {Object} [options]
+     * @param {boolean} [options.save]
+     * @param {string} [options.note]
+     * @returns {Promise<Object|null>} { scenario, file } или null.
+     */
+    async stopRecording({ save: doSave = true, note } = {}) {
+      const scenario = await requireHost().stopRecording();
+
+      if (!scenario) {
+        log('recording was not running');
+
+        return null;
+      }
+
+      log(
+        `recording stopped: ${scenario.ticks} tick(s), ` +
+          `${scenario.timeline.length} op(s)`,
+      );
+
+      const saved = doSave ? await save('scenario', scenario, note) : null;
+
+      return { scenario, file: saved?.file ?? null };
+    },
+
+    /**
+     * Записи детектора рассинхрона предикта (этап 5) этого клиента.
+     * Вычерпывающая операция: ядро отдаёт накопленное и обнуляет буфер.
+     * @returns {Object|null} null — ядро без детектора/секции divergence.
+     */
+    divergence() {
+      const core = getClientCore();
+
+      if (!core || typeof core.take_divergence !== 'function') {
+        return null;
+      }
+
+      const dump = JSON.parse(core.take_divergence());
+
+      log('divergence', dump);
+
+      return dump;
+    },
+  };
+}

package/src/client/lib/autostart.js

@@ -0,0 +1,61 @@
+// Автостарт клиента в solo-режиме (Этап 2 плана standalone-sdk): без лобби и
+// без живого игрока за клавиатурой матч должен сам довести себя до игрового
+// состояния — выйти из наблюдателей и позвать ботов игры.
+//
+// Порядок «сначала голоса, потом чат-команды» обязателен, и он не про гонку
+// доставки:
+//   - порт CHAT_DATA открывается ещё на MODULES_READY, а реальный гейт —
+//     HostGame.pushMessage: он отбрасывает сообщение, пока user.isReady=false
+//     (флаг ставится синхронно в firstShotReady);
+//   - настоящая блокировка — команда: участник входит наблюдателем, а игра
+//     вправе требовать активной команды (у танков /bot отбивается
+//     наблюдателю). Выйти из наблюдателей можно только ответом на initialVote
+//     (['teamChange', '<team>'] на порт VOTE_DATA).
+// Отсюда: голоса строго раньше команд, и вся пачка — после FIRST_SHOT_READY.
+//
+// Дробить команды по кадрам не нужно: лимита частоты чата на хосте нет,
+// ограничение только по длине (chatMaxLength).
+
+/**
+ * @param {Object} deps
+ * @param {Array} [deps.votes] - Ответы на initialVote (VOTE_DATA).
+ * @param {Array<string>} [deps.commands] - Чат-команды игры (CHAT_DATA).
+ * @param {Function} deps.sendVote - (payload) => void.
+ * @param {Function} deps.sendCommand - (message) => void.
+ * @param {Function} deps.schedule - (fn) => void: отложить на первый
+ *   renderTick (страховка поверх синхронного гейта isReady и симметрия с
+ *   задержкой интерполяции).
+ * @returns {Function} start(): запускает автостарт не более одного раза.
+ */
+export default function createAutostart({
+  votes = [],
+  commands = [],
+  sendVote,
+  sendCommand,
+  schedule,
+}) {
+  let started = false;
+
+  return () => {
+    // FIRST_SHOT_DATA приходит и после смены карты — автостарт разовый
+    if (started) {
+      return;
+    }
+
+    started = true;
+
+    if (!votes.length && !commands.length) {
+      return;
+    }
+
+    schedule(() => {
+      for (const vote of votes) {
+        sendVote(vote);
+      }
+
+      for (const command of commands) {
+        sendCommand(command);
+      }
+    });
+  };
+}

package/src/client/lib/contextTracker.js

@@ -0,0 +1,46 @@
+// Учёт потери/восстановления WebGL-контекста по каждому полотну отдельно.
+// Полотен несколько (игровое, радар и т.п.) — это независимые контексты, и
+// браузер шлёт webglcontextrestored по каждому из них асинхронно. Общий
+// булев флаг здесь не годится: перепечка ассетов в ещё мёртвый контекст
+// даёт пустые текстуры, а второго шанса не будет — событие уже прошло.
+// Вынесено из main.js (бутстрап тестами не покрывается), чтобы поведение
+// проверялось юнит-тестом.
+export function createContextTracker() {
+  const lost = new Set();
+
+  return {
+    // true — рендер надо остановить (первая потеря из всех полотен)
+    markLost(id) {
+      if (lost.has(id)) {
+        return false;
+      }
+
+      const wasAlive = lost.size === 0;
+
+      lost.add(id);
+
+      return wasAlive;
+    },
+
+    // true — пора пересобирать сцену: живы все контексты
+    markRestored(id) {
+      if (!lost.delete(id)) {
+        return false;
+      }
+
+      return lost.size === 0;
+    },
+
+    isLost(id) {
+      return lost.has(id);
+    },
+
+    hasLost() {
+      return lost.size > 0;
+    },
+
+    reset() {
+      lost.clear();
+    },
+  };
+}

package/src/client/lib/formBuilder.js

@@ -0,0 +1,280 @@
+// Общий билдер полей форм (room-форма и auth-форма используют один
+// контракт дескрипторов — docs/en/plugin-api.md, раздел "Form schema").
+// control: 'select'|'text'|'checkbox'|'radio'; все контролы — нативные
+// элементы формы, без визуальной кастомизации.
+
+function normalizeOptions(list) {
+  return (list || []).map(opt =>
+    opt !== null && typeof opt === 'object' ? opt : { value: opt, label: String(opt) },
+  );
+}
+
+// 'source' — спец-источник вариантов из каталога движка (например карты),
+// прокидывается вызывающей стороной через ctx.sources
+function resolveOptions(descriptor, ctx) {
+  if (descriptor.source) {
+    return normalizeOptions(ctx?.sources?.[descriptor.source]);
+  }
+
+  return normalizeOptions(descriptor.options);
+}
+
+// unit:'s' — значение хранится в мс, показывается/редактируется в секундах
+function toDisplay(descriptor, value) {
+  return descriptor.unit === 's' ? value / 1000 : value;
+}
+
+function toStored(descriptor, value) {
+  return descriptor.unit === 's' ? value * 1000 : value;
+}
+
+function buildSelect(descriptor, ctx) {
+  const el = document.createElement('select');
+
+  el.name = descriptor.name;
+
+  resolveOptions(descriptor, ctx).forEach(({ value, label }) => {
+    const option = document.createElement('option');
+
+    option.value = value;
+    option.textContent = label;
+    el.appendChild(option);
+  });
+
+  return {
+    el,
+    getValue: () => el.value,
+    setValue(value) {
+      el.value = value;
+    },
+    onChange(cb) {
+      el.addEventListener('change', () => cb({ name: descriptor.name, value: el.value }));
+    },
+  };
+}
+
+// numeric text-поле (unit задан или numeric:true) — переиспользует
+// toDisplay/toStored, откатывается к default при пустом/невалидном вводе,
+// вместо превращения его в 0 на сабмите
+function buildText(descriptor) {
+  const el = document.createElement('input');
+  const numeric = descriptor.numeric || descriptor.unit !== undefined;
+
+  el.type = 'text';
+  el.name = descriptor.name;
+
+  if (descriptor.regExp) {
+    el.pattern = descriptor.regExp;
+  }
+
+  if (descriptor.required) {
+    el.required = true;
+  }
+
+  if (descriptor.maxlength !== undefined) {
+    el.maxLength = descriptor.maxlength;
+  }
+
+  const fallback = () => toDisplay(descriptor, descriptor.default ?? 0);
+
+  const getValue = () => {
+    if (!numeric) {
+      return el.value;
+    }
+
+    const n = Number(el.value);
+    const value = el.value !== '' && Number.isFinite(n) ? n : fallback();
+
+    return toStored(descriptor, value);
+  };
+
+  return {
+    el,
+    getValue,
+    setValue(value) {
+      el.value = numeric ? toDisplay(descriptor, value) : (value ?? '');
+    },
+    onChange(cb) {
+      el.addEventListener('change', () => cb({ name: descriptor.name, value: getValue() }));
+    },
+  };
+}
+
+// уникальный id для <label for> подписи (несколько форм с одноимённым полем
+// могут сосуществовать в DOM — room-форма и auth-форма рендерятся в разные
+// моменты, но обе всегда присутствуют в разметке)
+let idSeq = 0;
+
+function buildCheckbox(descriptor) {
+  const el = document.createElement('input');
+
+  el.type = 'checkbox';
+  el.name = descriptor.name;
+  el.id = `field-checkbox-${++idSeq}`;
+
+  return {
+    el,
+    labelFor: el.id,
+    getValue: () => el.checked,
+    setValue(value) {
+      el.checked = Boolean(value);
+    },
+    onChange(cb) {
+      el.addEventListener('change', () => cb({ name: descriptor.name, value: el.checked }));
+    },
+  };
+}
+
+// группа нативных radio с общим name; подпись каждого варианта — соседний
+// <label for>, как у checkbox
+function buildRadio(descriptor, ctx) {
+  const el = document.createElement('div');
+  const groupName = `field-radio-${descriptor.name}-${++idSeq}`;
+  const inputs = [];
+
+  resolveOptions(descriptor, ctx).forEach(({ value, label }) => {
+    const wrap = document.createElement('span');
+    const input = document.createElement('input');
+
+    input.type = 'radio';
+    input.name = groupName;
+    input.id = `${groupName}-${inputs.length}`;
+    input.value = value;
+
+    const optionLabel = document.createElement('label');
+
+    optionLabel.htmlFor = input.id;
+    optionLabel.textContent = label;
+
+    wrap.append(input, optionLabel);
+    el.appendChild(wrap);
+    inputs.push(input);
+  });
+
+  const getValue = () => inputs.find(input => input.checked)?.value;
+
+  return {
+    el,
+    getValue,
+    setValue(value) {
+      inputs.forEach(input => {
+        input.checked = input.value === String(value);
+      });
+    },
+    onChange(cb) {
+      inputs.forEach(input => {
+        input.addEventListener('change', () => cb({ name: descriptor.name, value: getValue() }));
+      });
+    },
+  };
+}
+
+const builders = {
+  select: buildSelect,
+  text: buildText,
+  checkbox: buildCheckbox,
+  radio: buildRadio,
+};
+
+// строит одно поле формы по дескриптору (docs/en/plugin-api.md, "Form schema")
+export function buildField(descriptor, ctx = {}) {
+  const build = builders[descriptor.control];
+
+  if (!build) {
+    throw new Error(`formBuilder: unknown control "${descriptor.control}"`);
+  }
+
+  const field = build(descriptor, ctx);
+
+  if (descriptor.default !== undefined) {
+    field.setValue(descriptor.default);
+  }
+
+  return field;
+}
+
+// засеивает default каждого дескриптора room-формы значением из roomDefaults
+// (docs/en/plugin-api.md "Form schema": roomDefaults остаётся единственным
+// источником значений по умолчанию); явный descriptor.default, если он есть
+// в схеме, побеждает. Вынесено из populateRoomForm (main.js), чтобы этот же
+// код был накрыт тестом, а не продублирован в нём
+export function mergeRoomDefaults(descriptors, roomDefaults) {
+  return descriptors.map(descriptor => ({
+    default: roomDefaults[descriptor.name],
+    ...descriptor,
+  }));
+}
+
+// нативная валидация (pattern/required/maxlength) перед сабмитом room- и
+// auth-формы: обе — обычные div (lobby.pug/auth.pug), не <form>, поэтому
+// reportValidity вызывается на каждом контроле напрямую (Constraint
+// Validation API работает и вне <form>). Останавливается на первом
+// невалидном контроле — иначе браузер фокусирует/подсвечивает последний
+// вызванный reportValidity, а не первый по порядку поля
+export function reportFormValidity(container) {
+  if (!container) {
+    return true;
+  }
+
+  for (const el of container.querySelectorAll('input, select')) {
+    if (!el.reportValidity()) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+// собирает форму (упорядоченный массив дескрипторов = порядок полей) в
+// контейнер: одна .form-row на дескриптор (.form-label + контрол); onChange,
+// если передан, подписывается на все поля разом. hidden:true — поле строится
+// и участвует в сабмите (fields Map), но строка не попадает в DOM
+export function buildForm(descriptors, container, ctx = {}, onChange) {
+  const fields = new Map();
+
+  container.textContent = '';
+
+  descriptors.forEach(descriptor => {
+    let field;
+
+    try {
+      field = buildField(descriptor, ctx);
+    } catch (e) {
+      // одно поле с кривой/неизвестной схемой не должно ронять всю форму
+      // (room-форма и особенно auth-форма — единственный путь к кнопке Start)
+      console.error(`formBuilder: skipping field "${descriptor.name}" — ${e.message}`);
+      return;
+    }
+
+    if (onChange) {
+      field.onChange(onChange);
+    }
+
+    fields.set(descriptor.name, field);
+
+    if (descriptor.hidden) {
+      return;
+    }
+
+    const row = document.createElement('div');
+
+    row.className = 'form-row';
+
+    // checkbox подписывается через <label for>, чтобы клик по тексту
+    // переключал его (a11y) и строка выглядела как у остальных полей
+    // (подпись слева, контрол справа)
+    const label = document.createElement(field.labelFor ? 'label' : 'span');
+
+    label.className = 'form-label';
+    label.textContent = (descriptor.label || descriptor.name) + (descriptor.unit === 's' ? ' (s)' : '');
+
+    if (field.labelFor) {
+      label.htmlFor = field.labelFor;
+    }
+
+    row.append(label, field.el);
+    container.appendChild(row);
+  });
+
+  return fields;
+}

package/src/client/lib/hostGate.js

@@ -0,0 +1,16 @@
+// Пока хост всегда поднимает activeGameManifest (динамическая загрузка
+// ClientPlugin по выбору игры отложена — граница задачи, plan/lobby-page-plan.md),
+// нельзя дать создать комнату с полями формы игры, отличной от активной
+// (code review lobby-page 2.1). Вынесено в чистую функцию, чтобы поведение
+// было проверяемо юнит-тестом отдельно от main.js (main.js — бутстрап, тестами
+// не покрывается).
+export function getHostGateState(selectedGameId, activeGameManifest) {
+  if (selectedGameId === activeGameManifest.id) {
+    return { disabled: false, title: '' };
+  }
+
+  return {
+    disabled: true,
+    title: `Hosting ${activeGameManifest.title} — switch back to create a server`,
+  };
+}