vimp-engine 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {
@@ -16,19 +16,26 @@
     "./lib/*": "./src/lib/*",
     "./config/*": "./src/config/*",
     "./host/*": "./src/host/*",
-    "./devtools/*": "./src/devtools/*"
+    "./client/*": "./src/client/*",
+    "./devtools/*": "./src/devtools/*",
+    "./standalone": "./src/standalone/index.js",
+    "./style.css": "./src/client/style.css"
   },
   "files": [
     "src/lib",
     "src/config",
     "src/host",
+    "src/client",
+    "!src/client/_*",
+    "src/standalone",
     "src/devtools",
     "tests/fixtures",
     "bin"
   ],
   "scripts": {
     "predev": "node scripts/sync-pixi-vendor.mjs",
-    "dev": "NODE_ENV=development nodemon src/master/main.js -w src/master -w src/lib -w src/config",
+    "dev": "NODE_ENV=development nodemon src/master/main.js -w src/master -w src/dedicated -w src/lib -w src/config",
+    "dedicated": "NODE_ENV=development nodemon src/master/main.js -w src/master -w src/dedicated -w src/host -w src/lib -w src/config",
     "start": "NODE_ENV=production node --env-file ../../.env src/master/main.js",
     "prebuild": "node scripts/sync-pixi-vendor.mjs",
     "build": "vite build",
@@ -36,6 +43,7 @@
   },
   "dependencies": {
     "express": "^5.1.0",
+    "howler": "^2.2.4",
     "pixi.js": "8.19.0",
     "uuid": "^13.0.0",
     "vite-express": "^0.21.1",
@@ -43,7 +51,6 @@
   },
   "devDependencies": {
     "esbuild": "0.27.7",
-    "howler": "^2.2.4",
     "nodemon": "^3.1.10",
     "vite": "^7.1.11",
     "vite-plugin-pug": "^0.4.1"

package/src/client/InputListener.js

@@ -0,0 +1,36 @@
+import Publisher from '../lib/Publisher.js';
+
+let inputListener;
+
+export default class InputListener {
+  constructor() {
+    if (inputListener) {
+      return inputListener;
+    }
+
+    inputListener = this;
+
+    this.publisher = new Publisher();
+
+    window.addEventListener('keydown', event =>
+      this.publisher.emit('keyDown', event),
+    );
+
+    window.addEventListener('keyup', event =>
+      this.publisher.emit('keyUp', event),
+    );
+
+    const emitMouse = () => this.publisher.emit('mouseAction');
+
+    window.addEventListener('mouseup', emitMouse);
+    window.addEventListener('mousedown', emitMouse);
+    window.addEventListener('mousemove', emitMouse);
+
+    window.addEventListener('resize', () =>
+      this.publisher.emit('resize', {
+        width: innerWidth,
+        height: innerHeight,
+      }),
+    );
+  }
+}

package/src/client/SoundManager.js

@@ -0,0 +1,498 @@
+import { Howl, Howler } from 'howler';
+
+// глобальный лимит звуков
+const WORLD_VOICE_LIMIT = 30;
+
+// минимальная дистанция для панорамирования
+const MIN_SPATIAL_DISTANCE = 1;
+
+// настройки пространственного звука
+const PANNER_SETTINGS = {
+  panningModel: 'HRTF', // модель панорамирования
+  distanceModel: 'inverse', // модель затухания звука с расстоянием
+  refDistance: 150, // расстояние (в px), на котором громкость равна 100%
+  maxDistance: 1000, // расстояние, дальше которого звук не слышен
+  rolloffFactor: 1, // коэффициент затухания (больше - быстрее затухает)
+  coneInnerAngle: 360, // звук распространяется во все стороны одинаково
+  coneOuterAngle: 0,
+  coneOuterGain: 0,
+};
+
+/**
+ * @class SoundManager
+ * @description Централизованный "режиссёр звука". Управляет загрузкой,
+ * виртуализацией и воспроизведением всех звуков в игре. Использует систему
+ * приоритетов и глобальный лимит голосов для предотвращения перегрузки
+ * аудио-движка и обеспечения того, чтобы самые важные звуки всегда были слышны.
+ */
+export default class SoundManager {
+  constructor() {
+    // хранение загруженных звуков { sound, config }
+    this._sounds = new Map();
+
+    // хранит соответствие soundId -> { sound, ownerId, loop }
+    this._activeInstances = new Map();
+
+    // реестр всех зарегистрированных звуковых источников
+    this._registeredSounds = new Map();
+
+    // позиция слушателя
+    this._listenerX = 0;
+    this._listenerY = 0;
+  }
+
+  /**
+   * Производит базовую настройку Howler, асинхронно загружает все звуки,
+   * определенные в конфигурации.
+   * Сохраняет как сам экземпляр Howl, так и его конфигурацию (приоритет).
+   * @param {object} soundsConfig - Объект конфигурации звуков.
+   * @param {string[]} soundsConfig.codecList - Список поддерживаемых кодеков
+   * (['webm', 'mp3']).
+   * @param {string} soundsConfig.path - Путь к директории со звуками.
+   * @param {object} soundsConfig.sounds - Словарь, где ключ - имя звука,
+   * а значение - объект конфигурации { file, priority, loop, volume }.
+   * @returns {Promise<void>} Promise, который разрешается после загрузки.
+   */
+  async init(soundsConfig) {
+    const { codecList, path, sounds } = soundsConfig;
+    const supportedCodec = codecList.find(codec => Howler.codecs(codec));
+
+    Howler.usingWebAudio = true;
+    Howler.autoSuspend = false;
+    Howler.pos(0, 0, 0);
+    Howler.volume(0.7);
+
+    // устанавливает ориентацию (направление взгляда) слушателя.
+    // вектор "вперед" (0, 0, -1) - соответствует верху экрана
+    // вектор "вверх" (0, 1, 0) - вектор "вверх" для аудиосистемы
+    Howler.orientation(0, 0, -1, 0, 1, 0);
+
+    if (!supportedCodec) {
+      console.error(`No supported audio codec found from: ${codecList}`);
+      return;
+    }
+
+    const loadingPromises = Object.entries(sounds).map(
+      ([soundName, soundData]) => {
+        const fileName = soundData.file;
+        const loop = !!soundData.loop;
+        const volume = soundData.volume ?? 0.5;
+        const url = `${path}${fileName}.${supportedCodec}`;
+
+        return new Promise((resolve, reject) => {
+          const soundInstance = new Howl({
+            src: [url],
+            preload: true,
+            html5: false,
+            loop,
+            volume,
+            onload: () => {
+              this._sounds.set(soundName, {
+                sound: soundInstance.pannerAttr(PANNER_SETTINGS),
+                config: { ...soundData, priority: soundData.priority ?? 50 },
+              });
+
+              resolve(soundName);
+            },
+            onloaderror: (_id, error) => {
+              reject({
+                message: `Error loading "${soundName}" from ${url}`,
+                error,
+              });
+            },
+          });
+        });
+      },
+    );
+
+    // Promise.allSettled, чтобы сбой загрузки одного файла
+    // не прерывал загрузку остальных
+    const results = await Promise.allSettled(loadingPromises);
+
+    results.forEach(result => {
+      if (result.status === 'rejected') {
+        console.error(result.reason.message, result.reason.error);
+      }
+    });
+  }
+
+  /**
+   * Возвращает конфигурацию для указанного звука.
+   * @param {string} soundName - Имя звука.
+   * @returns {object | undefined} Конфигурация звука или undefined.
+   */
+  getSoundConfig(soundName) {
+    return this._sounds.get(soundName)?.config;
+  }
+
+  /**
+   * Устанавливает позицию слушателя (игрока) в 2D-пространстве для
+   * корректного расчета 3D-звука.
+   * @param {number} x - Координата X слушателя.
+   * @param {number} y - Координата Y слушателя.
+   */
+  setListenerPosition(x, y) {
+    this._listenerX = x;
+    this._listenerY = y;
+  }
+
+  /**
+   * Воспроизводит системный/UI звук немедленно, в обход системы приоритетов.
+   * Следует использовать для критически важных звуков, не относящихся к
+   * игровому миру (например звук начала раунда).
+   * @param {string} soundName - Имя звука для воспроизведения.
+   */
+  playSystemSound(soundName) {
+    this._sounds.get(soundName)?.sound.play();
+  }
+
+  /**
+   * Регистрирует звук.
+   * Возвращает уникальный ID для управления этим источником.
+   * @param {string} soundName - Имя звука (ключ из файла sounds.js).
+   * @param {object} data - Начальные параметры звука.
+   * @param {object} data.position - { x: number, y: number }.
+   * @param {number} [data?.rate] - Скорость воспроизведения.
+   * @param {number} [data?.volume] - Громкость.
+   * @param {function} [callback] - Функция, вызываемая по завершении.
+   * @returns {symbol | null} Уникальный ID звука или null, если звук не найден.
+   */
+  registerSound(soundName, data, callback) {
+    const soundData = this._sounds.get(soundName);
+
+    if (!soundData) {
+      console.warn(`SoundManager: Sound "${soundName}" does not exist.`);
+
+      return null;
+    }
+
+    const id = Symbol(soundName);
+    const registration = {
+      ...soundData.config,
+      ...data,
+      sound: soundData.sound,
+      id,
+      activeSoundId: null, // ID от Howler, когда звук будет играть
+      callback,
+    };
+
+    this._registeredSounds.set(id, registration);
+
+    return id;
+  }
+
+  /**
+   * Снимает звук с регистрации. Если он играет, он будет остановлен.
+   * @param {symbol} id - ID, полученный от `registerSound`.
+   */
+  unregisterSound(id) {
+    const sound = this._registeredSounds.get(id);
+
+    if (sound && sound.activeSoundId !== null) {
+      this._internalStop(sound.activeSoundId);
+    }
+
+    this._registeredSounds.delete(id);
+  }
+
+  /**
+   * Снимает звук с регистрации, но даёт уже звучащему одноразовому сэмплу
+   * доиграть. Для сущностей, которые исчезают раньше своего звука
+   * (например, взорвавшаяся бомба).
+   * @param {symbol} id - ID, полученный от `registerSound`.
+   */
+  releaseSound(id) {
+    const sound = this._registeredSounds.get(id);
+
+    if (!sound) {
+      return;
+    }
+
+    // луп обязан замолчать вместе с владельцем, one-shot — доиграть:
+    // updateActiveSounds() не-лупы не трогает, а обработчик 'end' сам
+    // подчистит _activeInstances
+    if (sound.loop && sound.activeSoundId !== null) {
+      this._internalStop(sound.activeSoundId);
+    }
+
+    this._registeredSounds.delete(id);
+  }
+
+  /**
+   * Обновляет параметры зарегистрированного звука.
+   * @param {symbol} id - ID, полученный от `registerSound`.
+   * @param {object} data - Новые параметры.
+   */
+  updateSoundData(id, data) {
+    const sound = this._registeredSounds.get(id);
+
+    if (sound) {
+      Object.assign(sound, data);
+    }
+  }
+
+  /**
+   * Главный метод - "режиссёр", мозг всей звуковой системы.
+   * Анализирует все существующие и заявленные звуки, пересчитывает их важность
+   * на основе приоритета и расстояния, и решает, какие из них должны
+   * звучать в данный момент, соблюдая глобальный лимит голосов.
+   * Вызывается один раз за кадр.
+   */
+  processAudibility() {
+    const candidates = [];
+    const maxDistSquared =
+      PANNER_SETTINGS.maxDistance * PANNER_SETTINGS.maxDistance;
+    const { _listenerX: lx, _listenerY: ly } = this;
+    const deleteList = [];
+
+    // сбор и предварительный отсев кандидатов
+    for (const regSound of this._registeredSounds.values()) {
+      const dx = regSound.position.x - lx;
+      const dy = regSound.position.y - ly;
+      const distanceSquared = dx * dx + dy * dy;
+
+      // если звук слишком далеко и он одноразовый, то удаление
+      if (distanceSquared >= maxDistSquared && !regSound.loop) {
+        deleteList.push(regSound.id);
+        continue;
+      }
+
+      // расчет приоритета
+      const basePriority = regSound.priority;
+
+      // дистанция 1.0, если звук в той же точке,
+      // чтобы избежать деления на ноль
+      regSound.priorityScore =
+        (basePriority * basePriority) / Math.max(distanceSquared, 1.0);
+      regSound.isPlaying = regSound.activeSoundId !== null;
+
+      candidates.push(regSound);
+    }
+
+    deleteList.forEach(id => this._registeredSounds.delete(id));
+
+    // если кандидатов нет, то очистка одноразовых звуков и выход
+    if (candidates.length === 0) {
+      this._cleanupUnplayedOneShots();
+      return;
+    }
+
+    // сортировка кандидатов по убыванию очков приоритета
+    candidates.sort((a, b) => b.priorityScore - a.priorityScore);
+
+    const audibleCandidates =
+      candidates.length > WORLD_VOICE_LIMIT
+        ? candidates.slice(0, WORLD_VOICE_LIMIT)
+        : candidates;
+
+    const audibleSet = new Set(audibleCandidates);
+
+    // синхронизация и очистка
+    for (const candidate of candidates) {
+      const shouldBePlaying = audibleSet.has(candidate);
+
+      if (candidate.isPlaying) {
+        if (!shouldBePlaying) {
+          this._internalStop(candidate.activeSoundId);
+          candidate.activeSoundId = null;
+        }
+      } else {
+        if (shouldBePlaying) {
+          const newSoundId = this._internalPlay(candidate);
+
+          if (newSoundId !== null) {
+            candidate.activeSoundId = newSoundId;
+            this._updateSpatialSound(
+              this._activeInstances.get(newSoundId)?.sound,
+              newSoundId,
+              candidate.position.x,
+              candidate.position.y,
+              candidate.volume,
+            );
+          }
+        }
+      }
+    }
+
+    // очистка несыгравших одноразовых звуков
+    this._cleanupUnplayedOneShots();
+  }
+
+  /**
+   * Обновляет параметры всех активных зацикленных звуков.
+   * Вызывается каждый кадр после `processAudibility`.
+   */
+  updateActiveSounds() {
+    for (const [soundId, activeInstance] of this._activeInstances.entries()) {
+      if (!activeInstance.loop) {
+        continue;
+      }
+
+      const regSound = this._registeredSounds.get(activeInstance.ownerId);
+      const { sound } = activeInstance;
+
+      if (!regSound) {
+        sound.stop(soundId);
+        this._activeInstances.delete(soundId);
+        continue;
+      }
+
+      const { position, volume, rate } = regSound;
+
+      this._updateSpatialSound(sound, soundId, position.x, position.y, volume);
+
+      if (typeof rate === 'number') {
+        sound.rate(rate, soundId);
+      }
+    }
+  }
+
+  /**
+   * @private Внутренний метод для воспроизведения звука через Howler.
+   */
+  _internalPlay(candidate) {
+    const { sound, id, loop, callback } = candidate;
+    const soundId = sound.play();
+
+    if (typeof soundId !== 'number') {
+      return null;
+    }
+
+    this._activeInstances.set(soundId, {
+      sound,
+      ownerId: id,
+      loop,
+    });
+
+    if (!loop) {
+      sound.once(
+        'end',
+        () => {
+          if (typeof callback === 'function') {
+            callback();
+          }
+
+          // по завершению удаляем из активных инстансов и из реестра
+          const regSound = this._registeredSounds.get(id);
+
+          if (regSound && regSound.activeSoundId === soundId) {
+            this._registeredSounds.delete(id);
+          }
+
+          this._activeInstances.delete(soundId);
+        },
+        soundId,
+      );
+    }
+
+    return soundId;
+  }
+
+  /**
+   * @private Внутренний метод для остановки экземпляра звука.
+   */
+  _internalStop(soundId) {
+    const instanceData = this._activeInstances.get(soundId);
+
+    if (instanceData) {
+      instanceData.sound.stop(soundId);
+      this._activeInstances.delete(soundId);
+    }
+  }
+
+  /**
+   * Обновляет громкость и 3D-позицию/панораму.
+   * @private
+   * @param {Howl} sound - Экземпляр Howl.
+   * @param {number} soundId - ID конкретного проигрываемого звука.
+   * @param {number} x - Координата X источника звука.
+   * @param {number} y - Координата Y источника звука.
+   * @param {number} volume - Громкость звука.
+   */
+  _updateSpatialSound(sound, soundId, x, y, volume) {
+    if (!sound || typeof soundId !== 'number') {
+      return;
+    }
+
+    const distance = Math.hypot(x - this._listenerX, y - this._listenerY);
+
+    if (distance >= PANNER_SETTINGS.maxDistance) {
+      sound.volume(0, soundId);
+
+      return;
+    }
+
+    sound.volume(volume, soundId);
+
+    // если дистанция позволяет панорамировать звук
+    if (distance > MIN_SPATIAL_DISTANCE) {
+      sound.pos(x - this._listenerX, 0, y - this._listenerY, soundId);
+    } else {
+      sound.pos(0, 0, 0, soundId); // отключение панорамирования
+    }
+  }
+
+  /**
+   * @private
+   * Удаляет из реестра одноразовые звуки, которые были заявлены,
+   * но не попали в лимит воспроизведения в текущем кадре.
+   */
+  _cleanupUnplayedOneShots() {
+    for (const [id, regSound] of this._registeredSounds.entries()) {
+      if (!regSound.loop && regSound.activeSoundId === null) {
+        this._registeredSounds.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Выключает все звуки.
+   */
+  mute() {
+    Howler.mute(true);
+  }
+
+  /**
+   * Включает все звуки после выключения.
+   */
+  unmute() {
+    Howler.mute(false);
+  }
+
+  /**
+   * Останавливает все играющие звуки и
+   * сбрасывает внутреннее состояние "режиссёра".
+   * Используется при смене карты или полной перезагрузке.
+   */
+  reset() {
+    Howler.stop();
+    this._activeInstances.clear();
+
+    // луп переживает reset: его владелец жив, и ближайший
+    // processAudibility() запустит звук заново. Одноразовый — нет:
+    // Howler.stop() не шлёт 'end', регистрация сыгравшего сэмпла осталась
+    // бы в реестре и прозвучала бы второй раз с начала
+    for (const [id, regSound] of this._registeredSounds.entries()) {
+      if (regSound.loop) {
+        regSound.activeSoundId = null;
+      } else {
+        this._registeredSounds.delete(id);
+      }
+    }
+
+    this._listenerX = 0;
+    this._listenerY = 0;
+  }
+
+  /**
+   * Полностью выгружает все загруженные звуки из памяти.
+   * Следует вызывать при закрытии вкладки или
+   * полном завершении работы приложения.
+   */
+  destroy() {
+    this.reset();
+    this._registeredSounds.clear();
+    Howler.unload();
+    this._sounds.clear();
+  }
+}

package/src/client/boot.js

@@ -0,0 +1,113 @@
+// Режим загрузки клиента движка (Этап 2 плана standalone-sdk). Клиент один
+// на все контуры, а различает их этот модуль:
+//
+//   lobby      — прод: каталог игр и сигналинг мастера, лобби за OAuth-гейтом;
+//   solo       — standalone SDK: хост в этой же вкладке (inline, без Worker'а),
+//                мастера нет вовсе;
+//   dedicated  — Node-сервер: прямой WebSocket к игровому процессу.
+//
+// Канал передачи конфига от SDK к main.js — модульное состояние: и SDK, и
+// main.js резолвят этот модуль в один экземпляр графа бандлера. Глобалов на
+// window не вводим: они переживают перезагрузку бандла и ломают вторую
+// вкладку SDK в том же документе.
+
+// эндпоинт режима: его отдаёт dedicated-сервер, у мастера его нет —
+// 404/сеть/мусор означают прод-лобби (обратная совместимость)
+const CONFIG_URL = '/config';
+
+// умолчание игрового WS dedicated-сервера: тот же хост, путь /game
+const DEDICATED_WS_PATH = '/game';
+
+/**
+ * Конфиг загрузки:
+ * {
+ *   mode: 'lobby' | 'solo' | 'dedicated',
+ *   container,       // solo: точка монтирования каркаса и канвасов
+ *   manifest,        // solo: манифест-подобный объект в памяти
+ *   clientPlugin,    // solo: живой ClientPlugin (минуя dynamic import)
+ *   hostPlugin,      // solo: живой HostPlugin (для inline-хоста)
+ *   room,            // solo: переопределения комнаты (map/maxPlayers/seed/…)
+ *   autoAuth,        // solo: { name, model, … } → AUTH_RESPONSE без формы
+ *   startupVotes,    // solo: ответы на initialVote (выход из наблюдателей)
+ *   startupCommands, // solo: чат-команды игры (спавн ботов)
+ *   wsUrl,           // dedicated: адрес игрового WS
+ *   gameId,          // dedicated: какую игру каталога считать активной
+ * }
+ */
+let bootConfig = null;
+
+/**
+ * Задаёт конфиг загрузки. SDK вызывает его до import('./main.js') — main.js
+ * читает уже готовое состояние и сети не касается.
+ * @param {Object} cfg - Конфиг загрузки (см. выше).
+ */
+export function setBootConfig(cfg) {
+  bootConfig = cfg;
+}
+
+/**
+ * Текущий конфиг загрузки (null, пока не задан и не разрешён).
+ * @returns {Object|null}
+ */
+export function getBootConfig() {
+  return bootConfig;
+}
+
+/**
+ * Сбрасывает состояние модуля. Нужен тестам: модульный синглтон переживает
+ * отдельный it().
+ */
+export function resetBootConfig() {
+  bootConfig = null;
+}
+
+/**
+ * Разрешает режим загрузки: инъекция SDK → GET /config → лобби.
+ * @param {Function} [fetchImpl] - Реализация fetch (тесты подставляют свою).
+ * @returns {Promise<Object>} Конфиг загрузки.
+ */
+export async function resolveBootConfig(fetchImpl) {
+  if (bootConfig) {
+    return bootConfig;
+  }
+
+  const doFetch = fetchImpl ?? ((...args) => fetch(...args));
+
+  try {
+    const res = await doFetch(CONFIG_URL);
+
+    if (res.ok) {
+      bootConfig = normalize(await res.json());
+    }
+  } catch (e) {
+    // сети/эндпоинта нет — это и есть прод-лобби, шуметь не о чем
+  }
+
+  bootConfig = bootConfig ?? { mode: 'lobby' };
+
+  return bootConfig;
+}
+
+// приводит ответ /config к валидному конфигу; всё, что не dedicated, —
+// лобби: неизвестный режим не должен уронить клиент в чёрный экран
+function normalize(raw) {
+  if (!raw || typeof raw !== 'object' || raw.mode !== 'dedicated') {
+    return null;
+  }
+
+  return {
+    ...raw,
+    mode: 'dedicated',
+    // сервер объявляет свой путь в /config: константа — только умолчание
+    wsUrl: raw.wsUrl || defaultDedicatedWsUrl(raw.wsPath),
+  };
+}
+
+function defaultDedicatedWsUrl(wsPath) {
+  const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  // пустой или отсутствующий путь — это «умолчание», а не корень: `''` дал бы
+  // ws://host, null — ws://hostnull
+  const path = wsPath || DEDICATED_WS_PATH;
+
+  return `${protocol}//${location.host}${path}`;
+}