vimp-engine 0.38.3 → 0.39.0

package/src/lib/capabilities.js

@@ -51,6 +51,10 @@ export const ENGINE_CAPABILITIES = createRegistry('engine-capabilities', [
   // Писать в `requires` не нужно: старый движок флаг просто игнорирует, и
   // игра на нём мигрирует мягко
   { value: 'host.migration', since: '0.36.0' },
+  // голосовая связь (gameConfig.voice, порты VOICE_*, сервис пула `voice`,
+  // хуки `hooks.voiceSounds`/`hooks.voiceFilter`); опциональна — игра не
+  // пишет её в `requires`
+  { value: 'voice', since: '0.39.0' },
 ]);
 
 // плоский список имён — то, чем правило контракта B2 проверяет `requires`

package/src/lib/createHostRuntime.js

@@ -29,6 +29,9 @@ import HostGame from '../host/HostGame.js';
  * @param {Function} [options.overrideGameConfig] - Правка собранного конфига
  *   игры перед созданием ядра; в проде не задаётся, нужна отладочному
  *   прогону (сценарий подкручивает networkSendRate и таймеры).
+ * @param {boolean} [options.voiceRelay] - У контура есть ретранслятор голоса
+ *   на транспортном уровне (браузерный хост лобби); без него связь
+ *   выключается, даже если игра её объявила (standalone, headless, dedicated).
  * @returns {Promise<Object>} { hostPlugin, game, seed, core, clientCfg,
  *   socketManager, host }.
  */
@@ -38,6 +41,7 @@ export async function createHostRuntime(room, options = {}) {
     createSocketManager = defaultCreateSocketManager,
     hostOptions = {},
     overrideGameConfig = null,
+    voiceRelay = false,
   } = options;
 
   const hostPlugin = await loadHostPlugin(room);
@@ -52,6 +56,10 @@ export async function createHostRuntime(room, options = {}) {
     overrideGameConfig(game);
   }
 
+  if (!voiceRelay && game.voice?.enabled) {
+    game.voice = Object.freeze({ ...game.voice, enabled: false });
+  }
+
   // seed уезжает наружу вызывающему: без него прогон матча невоспроизводим
   // (реплей задаёт room.seed и получает тот же мир)
   const seed =

package/src/lib/gameConfigView.js

@@ -1,4 +1,6 @@
 import hostDefaults from '../config/hostDefaults.js';
+import { VOICE_CONFIG_PATHS } from '../config/voiceDefaults.js';
+import { normalizeVoiceConfig } from './voiceConfig.js';
 
 // Единственная точка чтения HostPlugin.gameConfig движком (этап 2 плана
 // plugin-forward-compat). До неё движок разыменовывал конфиг игры россыпью
@@ -77,7 +79,11 @@ const FIELDS = {
 // те, за которые он подставляет умолчание. Раздел слепка поверхности
 // (contract/surface.json → gameConfigFields): исчезнувший отсюда путь —
 // нарушение И1, потому что игра могла его написать.
-export const KNOWN_GAME_CONFIG_PATHS = Object.keys(FIELDS);
+// Пути связи живут в config/voiceDefaults.js.
+export const KNOWN_GAME_CONFIG_PATHS = [
+  ...Object.keys(FIELDS),
+  ...VOICE_CONFIG_PATHS,
+];
 
 // ЗАМОРОЖЕНО (И2). Этот список может только СОКРАЩАТЬСЯ.
 // Добавление сюда отвергнет все ранее опубликованные игры — вместо этого
@@ -182,6 +188,10 @@ export function createGameConfigView(gameConfig, gameId = 'unknown') {
     );
   }
 
+  // блок связи нормализуется целиком (а не по путям FIELDS): неверное
+  // значение тоже должно получить дефолт, а не только отсутствующее
+  view.voice = normalizeVoiceConfig(source.voice, { gameId });
+
   assertConsistent(view, source, gameId);
 
   return Object.freeze(view);

package/src/lib/voiceConfig.js

@@ -0,0 +1,136 @@
+import {
+  VOICE_DEFAULTS,
+  VOICE_HOTKEY_RANGE,
+  VOICE_KEYS,
+  VOICE_RANGES,
+  VOICE_SCOPES,
+  VOICE_TEXT_KEYS,
+  VOICE_TEXT_MAX_LENGTH,
+} from '../config/voiceDefaults.js';
+
+const isPlainObject = value =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Разбирает блок gameConfig.voice. Конфиг не отвергается никогда: плохое
+ * значение заменяется дефолтом (числа вне диапазона — зажимом) и попадает в
+ * problems. Одна функция на два потребителя: рантайм предупреждает, правило
+ * контракта B11 отчитывается.
+ * @param {*} raw - Что написала игра (undefined/null — блока нет).
+ * @returns {{ config: Object, problems: string[] }} config — полный блок
+ *   (все ключи, вложенный texts); problems — описания на английском.
+ */
+export function inspectVoiceConfig(raw) {
+  const problems = [];
+  const config = { ...VOICE_DEFAULTS, texts: { ...VOICE_DEFAULTS.texts } };
+
+  if (raw === undefined || raw === null) {
+    return { config, problems };
+  }
+
+  if (!isPlainObject(raw)) {
+    problems.push('voice must be a plain object');
+
+    return { config, problems };
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!VOICE_KEYS.includes(key)) {
+      problems.push(`unknown key "voice.${key}"`);
+    }
+  }
+
+  if (raw.enabled !== undefined) {
+    if (typeof raw.enabled === 'boolean') {
+      config.enabled = raw.enabled;
+    } else {
+      problems.push('voice.enabled must be a boolean');
+    }
+  }
+
+  if (raw.scope !== undefined) {
+    if (VOICE_SCOPES.includes(raw.scope)) {
+      config.scope = raw.scope;
+    } else {
+      problems.push(`voice.scope must be one of ${VOICE_SCOPES.join(', ')}`);
+    }
+  }
+
+  if (raw.hotkey !== undefined) {
+    const [min, max] = VOICE_HOTKEY_RANGE;
+
+    if (
+      Number.isInteger(raw.hotkey) &&
+      raw.hotkey >= min &&
+      raw.hotkey <= max
+    ) {
+      config.hotkey = raw.hotkey;
+    } else {
+      problems.push(`voice.hotkey must be an integer keyCode ${min}..${max}`);
+    }
+  }
+
+  for (const [key, [min, max]] of Object.entries(VOICE_RANGES)) {
+    const value = raw[key];
+
+    if (value === undefined) {
+      continue;
+    }
+
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      problems.push(`voice.${key} must be a finite number`);
+    } else if (value < min || value > max) {
+      config[key] = Math.min(max, Math.max(min, value));
+      problems.push(`voice.${key} must be within ${min}..${max}, clamped`);
+    } else {
+      config[key] = value;
+    }
+  }
+
+  if (raw.texts !== undefined) {
+    if (!isPlainObject(raw.texts)) {
+      problems.push('voice.texts must be a plain object');
+    } else {
+      for (const [key, value] of Object.entries(raw.texts)) {
+        if (!VOICE_TEXT_KEYS.includes(key)) {
+          problems.push(`unknown key "voice.texts.${key}"`);
+        } else if (
+          typeof value !== 'string' ||
+          value.length > VOICE_TEXT_MAX_LENGTH
+        ) {
+          problems.push(
+            `voice.texts.${key} must be a string up to ` +
+              `${VOICE_TEXT_MAX_LENGTH} characters`,
+          );
+        } else {
+          config.texts[key] = value;
+        }
+      }
+    }
+  }
+
+  return { config, problems };
+}
+
+/**
+ * Рантайм-обёртка: каждая проблема уходит в warn.
+ * @param {*} raw - gameConfig.voice как есть.
+ * @param {Object} [options]
+ * @param {string} [options.gameId]
+ * @param {Function} [options.warn]
+ * @returns {Object} Замороженный полный блок (texts тоже заморожен).
+ */
+export function normalizeVoiceConfig(
+  raw,
+  { gameId = 'unknown', warn = console.warn } = {},
+) {
+  const { config, problems } = inspectVoiceConfig(raw);
+
+  for (const problem of problems) {
+    warn(`game "${gameId}": voice: ${problem}`);
+  }
+
+  config.texts = Object.freeze(config.texts);
+
+  return Object.freeze(config);
+}

package/src/lib/voiceMessages.js

@@ -0,0 +1,172 @@
+import {
+  VOICE_DENY,
+  VOICE_END,
+  VOICE_FLOOR_OP,
+  VOICE_MAX_TALK_ID,
+  VOICE_MSG,
+  VOICE_NAME_MAX_LENGTH,
+} from '../config/voiceProtocol.js';
+import { VOICE_RANGES } from '../config/voiceDefaults.js';
+import { isVoiceSpeakerId } from './voicePacket.js';
+
+// Единственное место, где описана раскладка кортежей VOICE_DATA и
+// VOICE_FLOOR: хост собирает ими, клиент и хост разбирают. Изоморфный.
+
+const COLOR_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const DENY_REASONS = new Set(Object.values(VOICE_DENY));
+const END_REASONS = new Set(Object.values(VOICE_END));
+
+const isTalkId = value =>
+  Number.isInteger(value) && value >= 1 && value <= VOICE_MAX_TALK_ID;
+
+const clampMs = (value, max) => Math.min(max, Math.max(0, Math.round(value)));
+
+// хост → клиент (собирает модуль Voice)
+export const grantMessage = (talkId, maxDurationMs) => [
+  VOICE_MSG.GRANT,
+  talkId,
+  maxDurationMs,
+];
+
+export const denyMessage = (reason, retryAfterMs) => [
+  VOICE_MSG.DENY,
+  reason,
+  retryAfterMs,
+];
+
+export const endMessage = (talkId, reason) => [VOICE_MSG.END, talkId, reason];
+
+export const startMessage = ({
+  speakerId,
+  talkId,
+  name,
+  teamId,
+  chatColor,
+}) => [
+  VOICE_MSG.START,
+  speakerId,
+  talkId,
+  name,
+  teamId ?? null,
+  chatColor ?? null,
+];
+
+export const stopMessage = (speakerId, talkId) => [
+  VOICE_MSG.STOP,
+  speakerId,
+  talkId,
+];
+
+// клиент → хост (собирает VoiceClient)
+export const floorRequestMessage = () => [VOICE_FLOOR_OP.REQUEST];
+
+export const floorReleaseMessage = talkId => [VOICE_FLOOR_OP.RELEASE, talkId];
+
+/**
+ * Разбор VOICE_DATA на клиенте. Хост в P2P — браузер другого игрока:
+ * принимается только кортеж, прошедший все проверки.
+ * @param {*} data
+ * @returns {{ type: 'grant', talkId: number, maxDurationMs: number }
+ *   | { type: 'deny', reason: number, retryAfterMs: number }
+ *   | { type: 'end', talkId: number, reason: number }
+ *   | { type: 'start', speakerId: number, talkId: number, name: string,
+ *       teamId: number|null, color: string|null }
+ *   | { type: 'stop', speakerId: number, talkId: number }|null}
+ */
+export function parseVoiceMessage(data) {
+  if (!Array.isArray(data)) {
+    return null;
+  }
+
+  switch (data[0]) {
+    case VOICE_MSG.GRANT: {
+      const [, talkId, maxDurationMs] = data;
+
+      if (!isTalkId(talkId) || !Number.isFinite(maxDurationMs)) {
+        return null;
+      }
+
+      return {
+        type: 'grant',
+        talkId,
+        maxDurationMs: clampMs(maxDurationMs, VOICE_RANGES.maxDurationMs[1]),
+      };
+    }
+
+    case VOICE_MSG.DENY: {
+      const [, reason, retryAfterMs] = data;
+
+      if (!DENY_REASONS.has(reason) || !Number.isFinite(retryAfterMs)) {
+        return null;
+      }
+
+      return {
+        type: 'deny',
+        reason,
+        retryAfterMs: clampMs(retryAfterMs, VOICE_RANGES.cooldownMs[1]),
+      };
+    }
+
+    case VOICE_MSG.END: {
+      const [, talkId, reason] = data;
+
+      if (!isTalkId(talkId) || !END_REASONS.has(reason)) {
+        return null;
+      }
+
+      return { type: 'end', talkId, reason };
+    }
+
+    case VOICE_MSG.START: {
+      const [, speakerId, talkId, name, teamId, color] = data;
+
+      if (!isVoiceSpeakerId(speakerId) || !isTalkId(talkId)) {
+        return null;
+      }
+
+      return {
+        type: 'start',
+        speakerId,
+        talkId,
+        name:
+          typeof name === 'string' ? name.slice(0, VOICE_NAME_MAX_LENGTH) : '',
+        teamId: Number.isInteger(teamId) ? teamId : null,
+        color: typeof color === 'string' && COLOR_RE.test(color) ? color : null,
+      };
+    }
+
+    case VOICE_MSG.STOP: {
+      const [, speakerId, talkId] = data;
+
+      if (!isVoiceSpeakerId(speakerId) || !isTalkId(talkId)) {
+        return null;
+      }
+
+      return { type: 'stop', speakerId, talkId };
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Разбор VOICE_FLOOR на хосте.
+ * @param {*} data
+ * @returns {{ op: 'request' } | { op: 'release', talkId: number }|null}
+ */
+export function parseFloorMessage(data) {
+  if (!Array.isArray(data)) {
+    return null;
+  }
+
+  if (data[0] === VOICE_FLOOR_OP.REQUEST) {
+    return { op: 'request' };
+  }
+
+  if (data[0] === VOICE_FLOOR_OP.RELEASE && isTalkId(data[1])) {
+    return { op: 'release', talkId: data[1] };
+  }
+
+  return null;
+}

package/src/lib/voicePacket.js

@@ -0,0 +1,142 @@
+import wsports from '../config/wsports.js';
+import {
+  VOICE_HEADER_BYTES,
+  VOICE_MAX_PACKET_BYTES,
+  VOICE_MAX_SPEAKER_ID,
+  VOICE_PACKET_VERSION,
+} from '../config/voiceProtocol.js';
+
+// Кодек голосового пакета (раскладка — config/voiceProtocol.js). Изоморфный:
+// им пользуются клиент и ретранслятор вкладки хоста (dedicated голоса не имеет).
+
+const isByte = value => Number.isInteger(value) && value >= 0 && value <= 0xff;
+
+/**
+ * id говорящего на проводе: целое 0..VOICE_MAX_SPEAKER_ID.
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isVoiceSpeakerId(value) {
+  return Number.isInteger(value) && value >= 0 && value <= VOICE_MAX_SPEAKER_ID;
+}
+
+/**
+ * Нормализует вход к Uint8Array без копии: ArrayBuffer, любой
+ * ArrayBufferView (в т.ч. Node Buffer — он и есть Uint8Array).
+ * @param {*} data
+ * @returns {Uint8Array|null} null — не бинарные данные.
+ */
+export function toBytes(data) {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+
+  return null;
+}
+
+/**
+ * Собирает пакет: новый Uint8Array(VOICE_HEADER_BYTES + payload.length).
+ * speakerId — 0 у клиента. seq обрезается до u16.
+ * @param {Object} packet
+ * @param {number} packet.port - Байт 0 (wsports.client/server.VOICE_AUDIO).
+ * @param {number} [packet.speakerId]
+ * @param {number} packet.talkId
+ * @param {number} packet.seq
+ * @param {Uint8Array} packet.payload - Opus-пакет.
+ * @returns {Uint8Array}
+ * @throws {RangeError} port/speakerId/talkId не целые 0..255.
+ */
+export function encodeVoicePacket({
+  port,
+  speakerId = 0,
+  talkId,
+  seq,
+  payload,
+}) {
+  if (!isByte(port) || !isByte(speakerId) || !isByte(talkId)) {
+    throw new RangeError('voice packet: port, speakerId, talkId must be u8');
+  }
+
+  const bytes = new Uint8Array(VOICE_HEADER_BYTES + payload.length);
+
+  bytes[0] = port;
+  bytes[1] = VOICE_PACKET_VERSION;
+  bytes[2] = speakerId;
+  bytes[3] = talkId;
+
+  new DataView(bytes.buffer).setUint16(4, seq & 0xffff);
+  bytes.set(payload, VOICE_HEADER_BYTES);
+
+  return bytes;
+}
+
+/**
+ * Читает и проверяет заголовок: длина в [VOICE_HEADER_BYTES + 1,
+ * VOICE_MAX_PACKET_BYTES], версия === VOICE_PACKET_VERSION.
+ * @param {Uint8Array} bytes
+ * @returns {{ port: number, version: number, speakerId: number,
+ *   talkId: number, seq: number }|null}
+ */
+export function readVoiceHeader(bytes) {
+  if (
+    !bytes ||
+    bytes.length <= VOICE_HEADER_BYTES ||
+    bytes.length > VOICE_MAX_PACKET_BYTES ||
+    bytes[1] !== VOICE_PACKET_VERSION
+  ) {
+    return null;
+  }
+
+  return {
+    port: bytes[0],
+    version: bytes[1],
+    speakerId: bytes[2],
+    talkId: bytes[3],
+    seq: new DataView(bytes.buffer, bytes.byteOffset).getUint16(4),
+  };
+}
+
+/**
+ * Готовит пакет клиента к раздаче: байт 0 ← server.VOICE_AUDIO, байт 2 ←
+ * speakerId. Правит буфер на месте (ретранслятор владеет им).
+ * @param {Uint8Array} bytes
+ * @param {number} speakerId - 0..VOICE_MAX_SPEAKER_ID.
+ * @returns {Uint8Array}
+ */
+export function stampForListeners(bytes, speakerId) {
+  if (!isVoiceSpeakerId(speakerId)) {
+    throw new RangeError('voice packet: speakerId out of range');
+  }
+
+  bytes[0] = wsports.server.VOICE_AUDIO;
+  bytes[2] = speakerId;
+
+  return bytes;
+}
+
+/**
+ * Полезная нагрузка (Opus) без копии.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function voicePayload(bytes) {
+  return bytes.subarray(VOICE_HEADER_BYTES);
+}
+
+/**
+ * Знаковая разность номеров u16 с переполнением: seqDiff(1, 65535) === 2.
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function seqDiff(a, b) {
+  return ((a - b + 32768) & 0xffff) - 32768;
+}