vimp-engine 0.1.0

package/src/lib/AbstractTimer.js

@@ -0,0 +1,84 @@
+/**
+ * @class AbstractTimer
+ * @description Базовый класс для управления таймерами (setTimeout, setInterval)
+ * Унифицированные методы для запуска и остановки таймеров по ключу
+ */
+class AbstractTimer {
+  constructor() {
+    // хранилище для всех активных таймеров по их ключам
+    this._timers = new Map();
+  }
+
+  /**
+   * Централизованно запускает таймер и сохраняет его в Map,
+   * если таймер с таким ключом уже существует, он будет сперва остановлен
+   * Для setTimeout ключ удаляется автоматически после срабатывания.
+   * @protected
+   * @param {string} key - уникальный ключ для идентификации таймера
+   * @param {function} callback - функция по завершению времени
+   * @param {number} duration - длительность в миллисекундах
+   * @param {boolean} [isInterval=false] - setInterval или setTimeout
+   */
+  _startTimer(key, callback, duration, isInterval = false) {
+    // остановка существующего таймера с тем же ключом
+    this._stopTimer(key);
+
+    if (isInterval) {
+      // setInterval живёт, пока его не остановят
+      const timerId = setInterval(callback, duration);
+      this._timers.set(key, { timerId, isInterval });
+    } else {
+      // setTimeout удаляется сразу после выполнения
+      const wrappedCallback = () => {
+        this._timers.delete(key);
+        callback();
+      };
+
+      const timerId = setTimeout(wrappedCallback, duration);
+      this._timers.set(key, { timerId, isInterval });
+    }
+  }
+
+  /**
+   * Централизованно останавливает таймер по его ключу
+   * @protected
+   * @param {string} key - ключ таймера, который нужно остановить
+   */
+  _stopTimer(key) {
+    if (this._timers.has(key)) {
+      const { timerId, isInterval } = this._timers.get(key);
+      const handler = isInterval ? clearInterval : clearTimeout;
+
+      handler(timerId);
+
+      this._timers.delete(key);
+    }
+  }
+
+  /**
+   * Проверяет наличие активного таймера по ключу
+   * @protected
+   * @param {string} key - ключ для проверки
+   * @returns {boolean} - true, если таймер существует, иначе false
+   */
+  _hasTimer(key) {
+    return this._timers.has(key);
+  }
+
+  /**
+   * Останавливает и удаляет все активные таймеры, управляемые этим экземпляром
+   * @protected
+   */
+  _clearAllTimers() {
+    for (const timerData of this._timers.values()) {
+      const { timerId, isInterval } = timerData;
+      const handler = isInterval ? clearInterval : clearTimeout;
+
+      handler(timerId);
+    }
+
+    this._timers.clear();
+  }
+}
+
+export default AbstractTimer;

package/src/lib/Publisher.js

@@ -0,0 +1,43 @@
+/**
+ * Observer pattern (Publisher)
+ * on: добавляет слушателя (подписчика)
+ * emit: рассылает событие подписчикам
+ */
+class Publisher {
+  constructor() {
+    // Объект для хранения подписчиков по типу события
+    this.subs = {};
+  }
+
+  /**
+   * Добавляет подписчика для указанного типа события.
+   * @param {string} type - Тип события.
+   * @param {Function|string} fn - Функция-обработчик или имя метода.
+   * @param {Object} [context] - Контекст, в котором будет вызвана функция.
+   */
+  on(type, fn, context) {
+    this.subs[type] = this.subs[type] || [];
+
+    if (typeof fn !== 'function') {
+      // Если передано не функция, предполагаем, что это имя метода в context.
+      fn = context[fn];
+    }
+
+    this.subs[type].push({
+      fn,
+      context: context || this,
+    });
+  }
+
+  /**
+   * Рассылает событие указанного типа всем подписчикам.
+   * @param {string} type - Тип события.
+   * @param {*} data - Данные, которые передаются подписчикам.
+   */
+  emit(type, data) {
+    const subscribers = this.subs[type] || [];
+    subscribers.forEach(({ fn, context }) => fn.call(context, data));
+  }
+}
+
+export default Publisher;

package/src/lib/applyRoomOverrides.js

@@ -0,0 +1,48 @@
+// Собирает конфиг игры (движковые дефолты + игровая половина) и применяет
+// пользовательские настройки комнаты. Используется host.worker.js; вынесено
+// в lib для тестируемости (worker вешает self.onmessage при импорте)
+import hostDefaults from '../config/hostDefaults.js';
+
+export function applyRoomOverrides(room = {}, plugin) {
+  const game = structuredClone({ ...hostDefaults, ...plugin.gameConfig });
+
+  // Этап 5.1: актуальные карты мастера (фетчит главный поток) вместо бандла
+  if (room.maps && Object.keys(room.maps).length) {
+    game.maps = room.maps;
+
+    // дефолтная карта бандла могла уйти из каталога мастера
+    if (!game.maps[game.currentMap]) {
+      game.currentMap = Object.keys(game.maps)[0];
+    }
+  }
+
+  if (Number.isFinite(room.maxPlayers)) {
+    game.maxPlayers = Math.max(
+      1,
+      Math.min(game.roomDefaults.maxPlayers, room.maxPlayers),
+    );
+  }
+
+  if (room.map && game.maps[room.map]) {
+    game.currentMap = room.map;
+  }
+
+  // форма лобби — не серверная граница: клампим здесь
+  const { roomTimeMin, roomTimeMax } = game.timers;
+  const clampTime = ms =>
+    Math.min(roomTimeMax, Math.max(roomTimeMin, Math.floor(ms)));
+
+  if (Number.isFinite(room.roundTime)) {
+    game.timers.roundTime = clampTime(room.roundTime);
+  }
+
+  if (Number.isFinite(room.mapTime)) {
+    game.timers.mapTime = clampTime(room.mapTime);
+  }
+
+  if (typeof room.friendlyFire === 'boolean') {
+    game.parts.friendlyFire = room.friendlyFire;
+  }
+
+  return game;
+}

package/src/lib/buildClientConfig.js

@@ -0,0 +1,48 @@
+// Сборка клиентского CONFIG_DATA (порт 0): merge движковых дефолтов
+// (src/config/clientDefaults.js) с игровым client-конфигом
+// (@vimp/tanks/config/client.js) + время голосования и данные client-side
+// prediction из game-конфига. Используется Worker'ом хоста
+// (src/host/host.worker.js).
+
+const isPlainObject = value =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// рекурсивный merge: объекты сливаются, массивы и скаляры заменяются
+const deepMerge = (base, extra) => {
+  const result = { ...base };
+
+  for (const [key, value] of Object.entries(extra)) {
+    result[key] =
+      isPlainObject(result[key]) && isPlainObject(value)
+        ? deepMerge(result[key], value)
+        : value;
+  }
+
+  return result;
+};
+
+// Возвращает новый объект, не мутируя переданные конфиги.
+export const buildClientConfig = (game, defaults, gameClient) => {
+  const config = deepMerge(
+    structuredClone(defaults),
+    structuredClone(gameClient),
+  );
+
+  // время ожидания vote-модуля
+  config.modules.vote.params.time = game.timers.voteTime;
+
+  // данные для client-side prediction (реплика движения своего танка
+  // и визуального спавна его снарядов)
+  config.prediction = {
+    timeStep: game.timers.timeStep,
+    playerKeys: game.playerKeys,
+    models: game.parts.models,
+    weapons: game.parts.weapons,
+  };
+
+  // снапшот-схема игры: клиент собирает по ней конфиг клиентского ядра и
+  // читает hot-буфер — бандл клиента не обязан совпадать с бандлом хоста
+  config.snapshot = game.snapshot;
+
+  return config;
+};

package/src/lib/clientCoreConfig.js

@@ -0,0 +1,59 @@
+import { SNAPSHOT_FORMAT_VERSION } from '../config/opcodes.js';
+import wsports from '../config/wsports.js';
+
+// Сборка JSON-конфига клиентского ядра (ClientCore, срез 2.6): данные
+// prediction/interpolation из CONFIG_DATA хоста + бандловый реестр
+// снапшот-ключей. Отдельный модуль (не coreConfig.js): тот тянет
+// game.js/models.js/weapons.js, которым не место в клиентском бандле —
+// клиент получает параметры по порту 0.
+
+/**
+ * Собирает объект конфигурации клиентского ядра — форма {engine, game}
+ * (PLAN.md §3.4): движковая половина (timeStepMs/snapshot/interpolation) +
+ * игровая (models/weapons/playerKeys/seed трассеров).
+ * @param {Object} options
+ * @param {Object} options.prediction - Секция prediction CONFIG_DATA
+ *   (timeStep в мс, playerKeys, models, weapons).
+ * @param {Object} options.interpolation - Секция interpolation CONFIG_DATA
+ *   (delay, maxFrameAge в мс).
+ * @param {Object} options.snapshot - Секция snapshot CONFIG_DATA —
+ *   игровая схема ключей (гоняется хостом, не из бандла клиента).
+ * @param {Object} [overrides] - Переопределения плоским объектом (например,
+ *   seed для воспроизводимых прогонов) — распределяются автоматически.
+ * @returns {Object} Конфиг для `new ClientCore(JSON.stringify(config))`.
+ */
+export const buildClientCoreConfig = (
+  { prediction, interpolation, snapshot },
+  overrides = {},
+) => {
+  const flat = {
+    // имя поля фиксирует единицы: prediction.timeStep приходит в мс
+    timeStepMs: prediction.timeStep,
+    playerKeys: prediction.playerKeys,
+    models: prediction.models,
+    weapons: prediction.weapons,
+    // keys — игровая схема из CONFIG_DATA; version/port — движковые
+    snapshot: {
+      version: SNAPSHOT_FORMAT_VERSION,
+      port: wsports.server.SHOT_DATA,
+      keys: snapshot,
+    },
+    interpolation,
+    seed: undefined,
+    ...overrides,
+  };
+
+  return {
+    engine: {
+      timeStepMs: flat.timeStepMs,
+      snapshot: flat.snapshot,
+      interpolation: flat.interpolation,
+    },
+    game: {
+      playerKeys: flat.playerKeys,
+      models: flat.models,
+      weapons: flat.weapons,
+      seed: flat.seed,
+    },
+  };
+};

package/src/lib/config.js

@@ -0,0 +1,83 @@
+const config = {};
+
+// добавляет новое значение в config
+//
+// keys - может иметь несколько вложенностей,
+// вложенности разделены ':', например:
+// key1:key2:key3 будет значением config[key1][key2][key3]
+//
+// если структура вложенностей изменилась,
+// новые пути перезапишут старый вариант
+//
+// value - может быть значением любого типа
+function set(keys, value) {
+  if (!keys) {
+    console.error(`Error: The "keys" argument cannot be empty.`);
+    return;
+  }
+
+  const arr = keys.split(':');
+
+  // проверка на пустые сегменты
+  if (arr.includes('')) {
+    console.error(
+      `Error: The path '${keys}' is invalid (contains empty segments).`,
+    );
+    return;
+  }
+
+  const lastKey = arr.pop(); // последний ключ для записи значения
+  let currentLevel = config;
+
+  for (const key of arr) {
+    // если не является объектом, создание пустого объекта,
+    // стирая вложенность, если она была
+    if (typeof currentLevel[key] !== 'object' || currentLevel[key] === null) {
+      currentLevel[key] = {};
+    }
+
+    currentLevel = currentLevel[key];
+  }
+
+  // запись финального значения
+  currentLevel[lastKey] = value;
+}
+
+// возвращает значение по ключу или undefined
+// ключ может иметь несколько вложенностей
+// вложенности разделены ':',
+// например: key1:key2:key3 вернет значение config[key1][key2][key3]
+// вызов без аргументов вернет весь конфиг
+function get(keys) {
+  if (!keys) {
+    return config;
+  }
+
+  const arr = keys.split(':');
+  let currentLevel = config;
+
+  for (let i = 0, len = arr.length; i < len; i += 1) {
+    const key = arr[i];
+
+    // если поиск свойства не в объекте
+    if (typeof currentLevel !== 'object' || currentLevel === null) {
+      console.error(keys, `${currentLevel} is not object`);
+      return;
+    }
+
+    // если свойство есть в объекте
+    if (key in currentLevel) {
+      currentLevel = currentLevel[key];
+    } else {
+      console.error(keys, `${key} is not property`);
+      return;
+    }
+  }
+
+  return currentLevel;
+}
+
+export default {
+  set,
+  get,
+};

package/src/lib/coreConfig.js

@@ -0,0 +1,60 @@
+import { SNAPSHOT_FORMAT_VERSION } from '../config/opcodes.js';
+import hostDefaults from '../config/hostDefaults.js';
+import wsports from '../config/wsports.js';
+
+// Сборка JSON-конфига Rust-ядра (packages/engine/core + core/ в репозитории
+// игры, например vimp-tanks): движковая половина
+// (timeStep/mapScale/mapSetId/snapshot/seed) + игровая
+// (models/weapons/playerKeys/panel/friendlyFire) — форма {engine, game} из
+// PLAN.md §3.4. Единственная точка соответствия JS-конфигов и ABI ядра
+// (см. docs/core.md).
+
+/**
+ * Собирает объект конфигурации ядра.
+ * @param {Object} gameConfig - HostPlugin.gameConfig игры, загруженной
+ *   динамически по GameManifest (Этап 6.4) — движок больше не знает игру
+ *   статически.
+ * @param {Object} [overrides] - Переопределения плоским объектом (например,
+ *   seed для воспроизводимых прогонов или friendlyFire) — распределяются
+ *   по движковой/игровой половине автоматически.
+ * @returns {Object} Конфиг для `hostPlugin.createCore(JSON.stringify(config))`.
+ */
+export const buildCoreConfig = (gameConfig, overrides = {}) => {
+  const { models, weapons } = gameConfig.parts;
+
+  const flat = {
+    timeStep: hostDefaults.timers.timeStep / 1000,
+    friendlyFire: gameConfig.parts.friendlyFire,
+    mapScale: gameConfig.mapScale,
+    mapSetId: gameConfig.mapSetId,
+    models,
+    weapons,
+    playerKeys: gameConfig.playerKeys,
+    panel: gameConfig.panel.fields,
+    // keys — игровая схема (gameConfig.snapshot); version/port — движковые
+    snapshot: {
+      version: SNAPSHOT_FORMAT_VERSION,
+      port: wsports.server.SHOT_DATA,
+      keys: gameConfig.snapshot,
+    },
+    seed: undefined,
+    ...overrides,
+  };
+
+  return {
+    engine: {
+      timeStep: flat.timeStep,
+      mapScale: flat.mapScale,
+      mapSetId: flat.mapSetId,
+      snapshot: flat.snapshot,
+      seed: flat.seed,
+    },
+    game: {
+      friendlyFire: flat.friendlyFire,
+      models: flat.models,
+      weapons: flat.weapons,
+      playerKeys: flat.playerKeys,
+      panel: flat.panel,
+    },
+  };
+};

package/src/lib/factory.js

@@ -0,0 +1,21 @@
+// фабрика для строительства объектов игры
+// создает объект игры указанного типа
+// по заданным параметрам
+const Factory = (name, ...args) => {
+  const Constructor = Factory.constructors[name];
+
+  if (typeof Constructor !== 'function') {
+    throw new Error(`Constructor for ${name} not found.`);
+  }
+
+  return new Constructor(...args);
+};
+
+Factory.constructors = {};
+
+// добавление конструкторов
+Factory.add = data => {
+  Object.assign(Factory.constructors, data);
+};
+
+export default Factory;

package/src/lib/formatters.js

@@ -0,0 +1,33 @@
+/**
+ * Заменяет плейсхолдеры в строке на значения из массива.
+ * Плейсхолдеры имеют вид `{0}`, `{1}` и т.д.
+ * @param {string} [message=''] - Исходное сообщение с плейсхолдерами.
+ * @param {string[]} [arr=[]] - Массив значений для подстановки.
+ * @returns {string} Сообщение с подставленными значениями.
+ * @example
+ * formatMessage('Hello, {0} {1}!', ['John', 'Doe']);
+ * // возвращает "Hello, John Doe!"
+ */
+export const formatMessage = (message = '', arr = []) => {
+  if (!message || !arr.length) {
+    return message;
+  }
+
+  // замена плейсхолдеров
+  return message.replace(/\{(\d+)\}/g, (match, index) => {
+    // index — это номер, захваченный из скобок в RegExp
+    const value = arr[index];
+    // если значение для индекса существует, подставляем его.
+    return typeof value !== 'undefined' ? value : match;
+  });
+};
+
+/**
+ * Округляет число до 2-х знаков после запятой.
+ * @param {number} value - Число для округления.
+ * @returns {number}
+ * @example
+ * round(10.567);      // 10.57
+ * round(10.567, 1);  // 10.6
+ */
+export const roundTo2Decimals = value => Math.round(value * 100) / 100;

package/src/lib/gamePlugin.js

@@ -0,0 +1,95 @@
+import { ENGINE_API_VERSION } from '../config/opcodes.js';
+
+// Динамическая загрузка игры по GameManifest мастера (Этап 6.3): клиент
+// больше не импортирует игру статически (gameRegistry.static.js) — вместо
+// этого он читает каталог игр мастера и подгружает ClientPlugin по
+// entries.client из манифеста.
+
+// каталог всех игр мастера (GameCatalog, см. Этап 6.2) — массив манифестов
+export async function fetchGamesManifest(url = '/games/manifest.json') {
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    throw new Error(`games manifest: HTTP ${res.status}`);
+  }
+
+  return res.json();
+}
+
+// манифест одной игры (GameCatalog::getManifest, см. Этап 6.2) — объект,
+// не массив; используется при повторном фетче активной игры (Этап 6.5)
+export async function fetchGameManifest(url) {
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    throw new Error(`game manifest: HTTP ${res.status}`);
+  }
+
+  return res.json();
+}
+
+// несовпадение engineApi — плагин собран под другую версию контрактов
+// движка (§3.7 PLAN.md); загружать его небезопасно
+export function assertEngineApiCompatible(manifest) {
+  if (manifest.engineApi !== ENGINE_API_VERSION) {
+    throw new Error(
+      `game "${manifest.id}" requires engine API v${manifest.engineApi}, ` +
+        `this engine build is v${ENGINE_API_VERSION}`,
+    );
+  }
+}
+
+// поля gameConfig, которые движок читает до какой-либо игровой логики
+// (applyRoomOverrides/coreConfig/buildClientConfig) — недостающее валится
+// непрозрачной ошибкой глубоко в onInit; проверяем контракт §HostPlugin API
+// (docs/en/plugin-api.md) сразу после import, рядом с engineApi-гейтом
+const REQUIRED_GAME_CONFIG_PATHS = [
+  'roomDefaults.maxPlayers',
+  'snapshot',
+  'parts.models',
+  'parts.weapons',
+  'parts.friendlyFire',
+  'panel.fields',
+  'playerKeys',
+];
+
+function getPath(obj, dottedPath) {
+  return dottedPath
+    .split('.')
+    .reduce((value, key) => value?.[key], obj);
+}
+
+// бросает при отсутствии обязательных полей HostPlugin.gameConfig
+export function assertGameConfigShape(hostPlugin) {
+  const missing = REQUIRED_GAME_CONFIG_PATHS.filter(
+    p => getPath(hostPlugin.gameConfig, p) === undefined,
+  );
+
+  if (missing.length > 0) {
+    throw new Error(
+      `game "${hostPlugin.id}": gameConfig is missing required field(s): ` +
+        missing.join(', '),
+    );
+  }
+}
+
+// динамический import ClientPlugin игры (client-entry её сборки). Манифест и
+// плагин собираются одной сборкой (build-game-manifest.js читает то же
+// entries.client) и их engineApi всегда совпадает — проверяем только
+// манифест (дешевле: до сетевого import), плагин сверяем после загрузки как
+// защиту от рассинхрона сборки, а не как отдельный путь отказа
+export async function loadClientPlugin(manifest) {
+  assertEngineApiCompatible(manifest);
+
+  const module = await import(/* @vite-ignore */ manifest.entries.client);
+  const plugin = module.default;
+
+  if (plugin.engineApi !== manifest.engineApi) {
+    throw new Error(
+      `game "${manifest.id}": plugin engineApi v${plugin.engineApi} ` +
+        `does not match manifest engineApi v${manifest.engineApi}`,
+    );
+  }
+
+  return plugin;
+}

package/src/lib/jwt.js

@@ -0,0 +1,103 @@
+// декодирует base64url-сегмент JWT в строку (без проверки подписи)
+function base64UrlToString(segment) {
+  const base64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+
+  return atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='));
+}
+
+// декодирует base64url-сегмент JWT в байты (подпись — для crypto.subtle.verify)
+function base64UrlToBytes(segment) {
+  const binary = base64UrlToString(segment);
+  const bytes = new Uint8Array(binary.length);
+
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+
+  return bytes;
+}
+
+// Разбор payload JWT без проверки подписи — только для чтения claims на
+// клиенте (отображение ника в лобби). Подпись авторитетно проверяет хост по
+// /jwks (Этап B3); эта функция не является средством аутентификации.
+export function decodeJwtPayload(token) {
+  if (typeof token !== 'string') {
+    return null;
+  }
+
+  const parts = token.split('.');
+
+  if (parts.length !== 3) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(base64UrlToString(parts[1]));
+  } catch {
+    return null;
+  }
+}
+
+// Авторитетная проверка identity-токена (Этап B3): подпись RS256 по JWKS
+// central auth-сервиса (packages/auth), issuer и срок годности. Работает через
+// Web Crypto API (crypto.subtle) — доступен в браузере, Worker'е хоста и в
+// Node ≥19 глобально, отдельной JWT-библиотеки не требует. Возвращает
+// проверенный payload ({ sub, nick, iss, exp, ... }) или бросает исключение.
+export async function verifyIdentityToken(token, { jwks, issuer } = {}) {
+  if (typeof token !== 'string') {
+    throw new Error('token must be a string');
+  }
+
+  const parts = token.split('.');
+
+  if (parts.length !== 3) {
+    throw new Error('malformed token');
+  }
+
+  const [headerSeg, payloadSeg, signatureSeg] = parts;
+  const header = JSON.parse(base64UrlToString(headerSeg));
+  const payload = JSON.parse(base64UrlToString(payloadSeg));
+
+  if (header.alg !== 'RS256') {
+    throw new Error(`unsupported alg: ${header.alg}`);
+  }
+
+  if (issuer && payload.iss !== issuer) {
+    throw new Error('unknown issuer');
+  }
+
+  if (typeof payload.exp !== 'number' || Date.now() >= payload.exp * 1000) {
+    throw new Error('token expired');
+  }
+
+  if (typeof payload.nick !== 'string' || !payload.nick) {
+    throw new Error('token has no nick');
+  }
+
+  const jwk = jwks?.keys?.find(k => k.kid === header.kid);
+
+  if (!jwk) {
+    throw new Error('unknown key id');
+  }
+
+  const key = await crypto.subtle.importKey(
+    'jwk',
+    jwk,
+    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    false,
+    ['verify'],
+  );
+
+  const valid = await crypto.subtle.verify(
+    'RSASSA-PKCS1-v1_5',
+    key,
+    base64UrlToBytes(signatureSeg),
+    new TextEncoder().encode(`${headerSeg}.${payloadSeg}`),
+  );
+
+  if (!valid) {
+    throw new Error('invalid signature');
+  }
+
+  return payload;
+}