vimp-engine 0.38.2 → 0.39.0

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;
+}

package/src/standalone/index.js

@@ -10,7 +10,7 @@ import { ensureGameShell } from '../client/views/gameShell.js';
 // репозитория игры — `npm run dev` открывает вкладку с работающим матчем без
 // мастера, без входа и без экрана лобби.
 //
-// Отличия от прода (осознанные, см. plan/standalone-sdk/README.md):
+// Отличия от прода (осознанные):
 //   - хост крутится в главном потоке (inline), а не в Worker'е: HostPlugin
 //     непередаваем постмесседжем, а SDK получает живой объект плагина;
 //   - личность гостевая (ник из формы или из playerName), рейтинг и

package/tests/fixtures/generations/gen-api3/README.md

@@ -1,7 +1,7 @@
 # gen-api3 — ЗАМОРОЖЕНО
 
 Снимок плагина 2026-08-29, поколение `engineApi: 3`.
-Не править: правка фикстуры маскирует слом совместимости
-(этап 1 плана `plan/plugin-forward-compat`). Новое поколение
+Не править: правка фикстуры маскирует слом совместимости.
+Новое поколение
 добавляется копированием текущего `../../miniGame`, а не правкой
 этого каталога.

package/tests/fixtures/generations/gen-api4/README.md

@@ -1,7 +1,7 @@
 # gen-api4 — ЗАМОРОЖЕНО
 
 Снимок плагина 2026-08-29, поколение `engineApi: 4`.
-Не править: правка фикстуры маскирует слом совместимости
-(этап 1 плана `plan/plugin-forward-compat`). Новое поколение
+Не править: правка фикстуры маскирует слом совместимости.
+Новое поколение
 добавляется копированием текущего `../../miniGame`, а не правкой
 этого каталога.

package/src/devtools/surface/abiParse.js

@@ -1,175 +0,0 @@
-// Разбор `core/src/abi.rs` — единственный раздел слепка плагинной
-// поверхности, который нельзя собрать импортом: методы wasm-ABI живут внутри
-// `macro_rules!`, раскрывающихся уже в крейте игры. Слепок читает файл как
-// текст и вытаскивает имена и нормализованные сигнатуры `pub fn`.
-//
-// Разбор обязан ПАДАТЬ, а не возвращать пустоту: молчаливо пустой раздел
-// слепка пропустит любое нарушение И1/И3 (plan/plugin-forward-compat).
-
-// имя макроса → раздел слепка (`abi.game` / `abi.client`)
-const MACRO_SECTIONS = {
-  // имена макросов Rust — строками: camelCase к ним неприменим
-  'export_game_core_abi': 'game',
-  'export_client_core_abi': 'client',
-};
-
-/**
- * @param {string} source - Содержимое `core/src/abi.rs`.
- * @returns {{game: Object[], client: Object[]}} Методы ABI по разделам,
- *   каждый — { name, args, ret }, отсортированные по имени.
- */
-export function parseAbi(source) {
-  const blocks = splitMacros(source);
-
-  if (blocks.length === 0) {
-    throw new Error(
-      'abiParse: no macro_rules! block found in core/src/abi.rs — the file ' +
-        'was restructured; fix the parser instead of letting the surface ' +
-        'snapshot go silently empty',
-    );
-  }
-
-  const sections = {};
-
-  for (const block of blocks) {
-    const section = MACRO_SECTIONS[block.macro];
-
-    if (!section) {
-      continue; // макрос вне ABI плагина — не часть поверхности
-    }
-
-    const methods = parseMethods(block.body);
-
-    if (methods.length === 0) {
-      throw new Error(
-        `abiParse: macro_rules! ${block.macro} yielded no "pub fn" — the ` +
-          'file was restructured; fix the parser',
-      );
-    }
-
-    sections[section] = methods.sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  for (const [macro, section] of Object.entries(MACRO_SECTIONS)) {
-    if (!sections[section]) {
-      throw new Error(
-        `abiParse: macro_rules! ${macro} not found in core/src/abi.rs`,
-      );
-    }
-  }
-
-  return sections;
-}
-
-// тело каждого `macro_rules! <name> { … }` — от имени до парной скобке
-function splitMacros(source) {
-  const re = /macro_rules!\s+([a-z_0-9]+)\s*\{/g;
-  const blocks = [];
-  let match;
-
-  while ((match = re.exec(source)) !== null) {
-    const open = re.lastIndex - 1;
-    const close = matchBrace(source, open, '{', '}');
-
-    blocks.push({
-      macro: match[1],
-      body: source.slice(open + 1, close),
-    });
-  }
-
-  return blocks;
-}
-
-// `pub fn name(args) -> ret` внутри тела макроса; тело метода пропускается
-function parseMethods(body) {
-  const re = /pub\s+fn\s+([a-z_0-9]+)\s*\(/g;
-  const methods = [];
-  let match;
-
-  while ((match = re.exec(body)) !== null) {
-    const open = re.lastIndex - 1;
-    const close = matchBrace(body, open, '(', ')');
-    const tail = body.slice(close + 1);
-    const arrow = /^\s*->([^{;]+)/.exec(tail);
-
-    methods.push({
-      name: match[1],
-      args: splitArgs(body.slice(open + 1, close)).map(normalizeType),
-      ret: arrow ? normalizeType(arrow[1]) : '()',
-    });
-  }
-
-  return methods;
-}
-
-// индекс скобки, парной открывающей на позиции `open`
-function matchBrace(source, open, openChar, closeChar) {
-  let depth = 0;
-
-  for (let i = open; i < source.length; i += 1) {
-    if (source[i] === openChar) {
-      depth += 1;
-    } else if (source[i] === closeChar) {
-      depth -= 1;
-
-      if (depth === 0) {
-        return i;
-      }
-    }
-  }
-
-  throw new Error(`abiParse: unbalanced ${openChar} at offset ${open}`);
-}
-
-// список аргументов по запятым верхнего уровня; получатель (`&self`,
-// `&mut self`) в сигнатуру не входит — он не часть бинарного контракта
-function splitArgs(list) {
-  const args = [];
-  let depth = 0;
-  let current = '';
-
-  for (const ch of list) {
-    if (ch === '<' || ch === '(' || ch === '[') {
-      depth += 1;
-    } else if (ch === '>' || ch === ')' || ch === ']') {
-      depth -= 1;
-    }
-
-    if (ch === ',' && depth === 0) {
-      args.push(current);
-      current = '';
-      continue;
-    }
-
-    current += ch;
-  }
-
-  args.push(current);
-
-  return args
-    .map(arg => arg.trim())
-    .filter(arg => arg.length > 0 && !/^&?\s*(mut\s+)?self$/.test(arg))
-    .map(arg => {
-      const colon = arg.indexOf(':');
-
-      // аргумент без имени в этих макросах не встречается: имя есть всегда
-      return colon === -1 ? arg : arg.slice(colon + 1);
-    });
-}
-
-// Стабильная строка типа: меняется тогда и только тогда, когда меняется
-// бинарный контракт. Ссылка/`mut`/пробелы/путь до wasm-bindgen на него не
-// влияют; `Result<T, JsError>` сворачивается в `Result<T>` — вариант ошибки
-// у всех методов один.
-function normalizeType(type) {
-  const flat = type
-    .replaceAll('::wasm_bindgen::', '')
-    .replaceAll('wasm_bindgen::', '')
-    .replace(/\bmut\b/g, '')
-    .replaceAll('&', '')
-    .replace(/\s+/g, '');
-
-  return flat.replace(/^Result<(.*),JsError>$/, 'Result<$1>');
-}
-
-export default parseAbi;