vimp-engine 0.32.3 → 0.33.1

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vimp-engine-core"
-version = "0.15.0"
+version = "0.18.0"
 edition = "2024"
 description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.32.3",
+  "version": "0.33.1",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/client/SoundManager.js

@@ -1,26 +1,88 @@
 import { Howl, Howler } from 'howler';
 
+import {
+  SPATIAL_DEFAULTS,
+  SPATIAL_NUMERIC,
+  SPATIAL_MODES,
+  PANNING_MODELS,
+  DISTANCE_MODELS,
+} from '../config/spatialDefaults.js';
+
 // глобальный лимит звуков
 const WORLD_VOICE_LIMIT = 30;
 
-// дед-зона панорамирования, в мировых пикселях (порядка половины тайла).
-// Порог по НАПРАВЛЕНИЮ, а не по громкости: азимут в Web Audio зависит от
-// вектора на источник, а не от расстояния до него, поэтому расхождение
-// камеры и источника в пару пикселей давало полную панораму и её рывки
-const MIN_SPATIAL_DISTANCE = 16;
-
-// настройки пространственного звука
-const PANNER_SETTINGS = {
-  panningModel: 'HRTF', // модель панорамирования
-  distanceModel: 'inverse', // модель затухания звука с расстоянием
-  refDistance: 150, // расстояние (в px), на котором громкость равна 100%
-  maxDistance: 1000, // расстояние, дальше которого звук не слышен
-  rolloffFactor: 1, // коэффициент затухания (больше - быстрее затухает)
-  coneInnerAngle: 360, // звук распространяется во все стороны одинаково
+// Позиция паннера переписывается не чаще 30 Гц. Каждый pos() внутри
+// Howler — это три setValueAtTime на positionX/Y/Z плюс событие 'pos'; на
+// 60 Гц и лимите в WORLD_VOICE_LIMIT голосов это тысячи записей
+// автоматизации в секунду. WebKit отвечает на такой поток артефактами,
+// клиппингом и обрывами (HRTF там — настоящая свёртка на каждый узел, а
+// не дешёвая аппроксимация), а на слух панорама между 30 и 60 Гц не
+// различается: 30 Гц — обычный темп обновления позиций в игровом звуке
+const POSITION_UPDATE_INTERVAL = 1000 / 30;
+
+// Допуск к границе интервала. Кадр 60 Гц приходит каждые ~16.7 мс, и без
+// допуска кадр, опоздавший к границе на доли миллисекунды, уезжает на
+// следующий: такт скачет между 30 и 20 Гц, а шаг панорамы становится
+// неравномерным — ровно то, ради чего гейт и ставился
+const POSITION_UPDATE_TOLERANCE = 2;
+
+// Порог смещения, ниже которого позиция не переписывается. Снимает поток
+// pos() с неподвижных источников — их большинство: горящий остов,
+// эмбиент, подобранный предмет
+const POSITION_EPSILON = 0.01;
+
+// Конусные атрибуты узла: звук распространяется во все стороны одинаково.
+// Игрой не настраиваются — направленных источников в 2D нет
+const CONE_SETTINGS = {
+  coneInnerAngle: 360,
   coneOuterAngle: 0,
   coneOuterGain: 0,
 };
 
+// Профиль проекции: как мировой вектор (sx, sy) и высота слушателя H
+// ложатся на оси Web Audio. Слушатель смотрит в -Z (верх экрана), его
+// «вверх» — +Y, поэтому мировой y (растёт вниз) входит со знаком минус
+// везде, где попадает на ось Y.
+export const SPATIAL_PROFILES = {
+  // вид сверху 360°: уши над полем боя, источник под ними
+  topDown: {
+    panningModel: 'HRTF',
+    mapCoords: (sx, sy, h) => [sx, -h, sy],
+  },
+
+  // вид сбоку: слышимость лево/право, вертикаль занижена, глубина фиксирована
+  sideScroller: {
+    panningModel: 'equalpower',
+    mapCoords: (sx, sy, h, cfg) => [sx, -sy * cfg.verticalFactor, -h],
+  },
+
+  // вид из кабины: сфера перед глазами, глубина фиксирована
+  cockpit: {
+    panningModel: 'HRTF',
+    mapCoords: (sx, sy, h) => [sx, -sy, -h],
+  },
+};
+
+/**
+ * Кубическая интерполяция Эрмита: 0 при value <= min, 1 при value >= max,
+ * гладкая (вместе с первой производной) между ними. Гладкость здесь и есть
+ * смысл: любой порог с разрывом слышен как щелчок.
+ * @param {number} min
+ * @param {number} max
+ * @param {number} value
+ * @returns {number} Значение в [0, 1].
+ */
+function smoothstep(min, max, value) {
+  // вырожденный интервал (innerRadius: 0) — деления не делаем
+  if (max <= min) {
+    return value > min ? 1 : 0;
+  }
+
+  const x = Math.max(0, Math.min(1, (value - min) / (max - min)));
+
+  return x * x * (3 - 2 * x);
+}
+
 /**
  * @class SoundManager
  * @description Централизованный "режиссёр звука". Управляет загрузкой,
@@ -43,13 +105,31 @@ export default class SoundManager {
     // pannerAttr ставится один раз на экземпляр, а не каждый кадр
     this._equalPowerIds = new Set();
 
-    // экземпляры, у которых PannerNode УЖЕ создан. Howler создаёт узел
-    // лениво — на первом pos()/pannerAttr(id) — и заканчивает создание
-    // парой pause()/play() (setupPanner в howler.js), то есть щелчком.
-    // Пока источник стоит в точке слушателя, паннер не нужен вовсе:
-    // сигнал идёт прямо в gain, сохраняя стерео сэмпла
+    // экземпляры, у которых PannerNode УЖЕ создан. Множество обслуживает
+    // только возврат в центр для spatial: false — мировой источник
+    // получает узел сразу, на первом же кадре. Howler создаёт узел лениво
+    // — на первом pos()/pannerAttr(id) — и заканчивает создание парой
+    // pause()/play() (setupPanner в howler.js), то есть щелчком, поэтому
+    // источнику игрока узел не заводится вовсе: сигнал идёт прямо в gain,
+    // сохраняя стерео сэмпла
     this._pannedIds = new Set();
 
+    // последняя записанная в узел позиция: soundId -> [x, y, z]. Служит
+    // порогом POSITION_EPSILON — неподвижный источник не переписывает
+    // автоматизацию паннера впустую
+    this._pannerPos = new Map();
+
+    // время последней записи позиций (performance.now), общее на кадр:
+    // гейт POSITION_UPDATE_INTERVAL
+    this._lastPositionWrite = -Infinity;
+
+    // разрешённая геометрия пространственного звука: числа профиля + его
+    // mapCoords. Ставится в init(), между матчами (reset) не меняется
+    this._spatial = this._resolveSpatialConfig();
+
+    // множитель зума камеры: 1 — покой, < 1 — динамическое отдаление
+    this._listenerScale = 1;
+
     // позиция слушателя
     this._listenerX = 0;
     this._listenerY = 0;
@@ -65,10 +145,19 @@ export default class SoundManager {
    * @param {string} soundsConfig.path - Путь к директории со звуками.
    * @param {object} soundsConfig.sounds - Словарь, где ключ - имя звука,
    * а значение - объект конфигурации { file, priority, loop, volume }.
+   * @param {object} [soundsConfig.spatial] - Геометрия пространственного
+   * звука: mode ('topDown' | 'sideScroller' | 'cockpit'), virtualElevation,
+   * innerRadius, verticalFactor, panningModel ('HRTF' | 'equalpower'),
+   * distanceModel ('linear' | 'inverse' | 'exponential'), refDistance,
+   * maxDistance, rolloffFactor. Все ключи необязательны, отсутствующие
+   * берутся из движковых дефолтов.
    * @returns {Promise<void>} Promise, который разрешается после загрузки.
    */
   async init(soundsConfig) {
-    const { codecList, path, sounds } = soundsConfig;
+    const { codecList, path, sounds, spatial } = soundsConfig;
+
+    this._spatial = this._resolveSpatialConfig(spatial);
+
     const supportedCodec = codecList.find(codec => Howler.codecs(codec));
 
     Howler.usingWebAudio = true;
@@ -102,7 +191,14 @@ export default class SoundManager {
             volume,
             onload: () => {
               this._sounds.set(soundName, {
-                sound: soundInstance.pannerAttr(PANNER_SETTINGS),
+                sound: soundInstance.pannerAttr({
+                  panningModel: this._spatial.panningModel,
+                  distanceModel: this._spatial.distanceModel,
+                  refDistance: this._spatial.refDistance,
+                  maxDistance: this._spatial.maxDistance,
+                  rolloffFactor: this._spatial.rolloffFactor,
+                  ...CONE_SETTINGS,
+                }),
                 config: { ...soundData, priority: soundData.priority ?? 50 },
               });
 
@@ -140,14 +236,17 @@ export default class SoundManager {
   }
 
   /**
-   * Устанавливает позицию слушателя (игрока) в 2D-пространстве для
-   * корректного расчета 3D-звука.
-   * @param {number} x - Координата X слушателя.
-   * @param {number} y - Координата Y слушателя.
+   * Устанавливает позицию слушателя и текущий зум камеры.
+   * @param {number} x - Мировая координата X слушателя.
+   * @param {number} y - Мировая координата Y слушателя.
+   * @param {number} [scale=1] - Множитель зума камеры: 1 в покое, меньше
+   * единицы при динамическом отдалении. Вызов с двумя аргументами
+   * сохраняет прежнее поведение полностью.
    */
-  setListenerPosition(x, y) {
+  setListenerPosition(x, y, scale = 1) {
     this._listenerX = x;
     this._listenerY = y;
+    this._listenerScale = Number.isFinite(scale) && scale > 0 ? scale : 1;
   }
 
   /**
@@ -173,7 +272,10 @@ export default class SoundManager {
    *   стоит ровно на слушателе, и HRTF на нулевой дистанции сворачивается
    *   в гребенчатую окраску («гул»), а не в тишину панорамы. Такому звуку
    *   PannerNode не создаётся вовсе — он идёт прямо в gain и остаётся
-   *   стерео.
+   *   стерео. Флаг рассчитан на ОДНОКРАТНОЕ переключение (владелец
+   *   узнаёт, что танк локальный, уже после конструктора): экземпляр,
+   *   который успел побывать мировым, переводится на equalpower
+   *   необратимо — HRTF обратно не возвращается.
    * @param {function} [callback] - Функция, вызываемая по завершении.
    * @returns {symbol | null} Уникальный ID звука или null, если звук не найден.
    */
@@ -262,7 +364,7 @@ export default class SoundManager {
   processAudibility() {
     const candidates = [];
     const maxDistSquared =
-      PANNER_SETTINGS.maxDistance * PANNER_SETTINGS.maxDistance;
+      this._spatial.maxDistance * this._spatial.maxDistance;
     const { _listenerX: lx, _listenerY: ly } = this;
     const deleteList = [];
 
@@ -323,14 +425,30 @@ export default class SoundManager {
 
           if (newSoundId !== null) {
             candidate.activeSoundId = newSoundId;
-            this._updateSpatialSound(
-              this._activeInstances.get(newSoundId)?.sound,
-              newSoundId,
-              candidate.position.x,
-              candidate.position.y,
-              candidate.volume,
-              candidate.spatial,
-            );
+
+            const started = this._activeInstances.get(newSoundId)?.sound;
+            const { x, y } = candidate.position;
+
+            // на старте звука гейт частоты не применяется: позиция обязана
+            // попасть в узел сразу, иначе первый кадр сэмпла звучит из центра
+            if (
+              this._applyVolume(
+                started,
+                newSoundId,
+                x,
+                y,
+                candidate.volume,
+                candidate.spatial,
+              )
+            ) {
+              this._updateSpatialSound(
+                started,
+                newSoundId,
+                x,
+                y,
+                candidate.spatial,
+              );
+            }
           }
         }
       }
@@ -345,6 +463,20 @@ export default class SoundManager {
    * Вызывается каждый кадр после `processAudibility`.
    */
   updateActiveSounds() {
+    // гейт частоты: под него попадает ТОЛЬКО запись позиции в паннер.
+    // Громкость, уборка мёртвых экземпляров и rate идут каждый кадр —
+    // громкость игра ведёт от скорости (двигатель), и ступенька в 30 Гц
+    // была бы слышна, а глушение за maxDistance обязано срабатывать в том
+    // же кадре, в котором источник ушёл за радиус
+    const now = performance.now();
+    const writePosition =
+      now - this._lastPositionWrite >=
+      POSITION_UPDATE_INTERVAL - POSITION_UPDATE_TOLERANCE;
+
+    if (writePosition) {
+      this._lastPositionWrite = now;
+    }
+
     for (const [soundId, activeInstance] of this._activeInstances.entries()) {
       if (!activeInstance.loop) {
         continue;
@@ -355,15 +487,12 @@ export default class SoundManager {
 
       if (!regSound) {
         sound.stop(soundId);
-        this._activeInstances.delete(soundId);
-        this._equalPowerIds.delete(soundId);
-        this._pannedIds.delete(soundId);
+        this._forgetInstance(soundId);
         continue;
       }
 
       const { position, volume, rate, spatial } = regSound;
-
-      this._updateSpatialSound(
+      const audible = this._applyVolume(
         sound,
         soundId,
         position.x,
@@ -372,6 +501,16 @@ export default class SoundManager {
         spatial,
       );
 
+      if (audible && writePosition) {
+        this._updateSpatialSound(
+          sound,
+          soundId,
+          position.x,
+          position.y,
+          spatial,
+        );
+      }
+
       // rate только на изменение: Howler на каждый вызов делает два seek(),
       // переписывает _rateSeek/_playStart и пересоздаёт таймер конца петли
       // — на 60 Гц это лишняя нагрузка и лишние события 'end' на каждом
@@ -415,9 +554,7 @@ export default class SoundManager {
             this._registeredSounds.delete(id);
           }
 
-          this._activeInstances.delete(soundId);
-          this._equalPowerIds.delete(soundId);
-          this._pannedIds.delete(soundId);
+          this._forgetInstance(soundId);
         },
         soundId,
       );
@@ -434,23 +571,180 @@ export default class SoundManager {
 
     if (instanceData) {
       instanceData.sound.stop(soundId);
-      this._activeInstances.delete(soundId);
-      this._equalPowerIds.delete(soundId);
-      this._pannedIds.delete(soundId);
+      this._forgetInstance(soundId);
+    }
+  }
+
+  /**
+   * @private Забывает всё, что менеджер помнил про экземпляр Howler.
+   * Единственная точка уборки: набор коллекций растёт, а пропущенная точка
+   * — это утечка, которую видно только по памяти, ни один тест её не
+   * поймает.
+   * @param {number} soundId - ID экземпляра от Howler.
+   */
+  _forgetInstance(soundId) {
+    this._activeInstances.delete(soundId);
+    this._equalPowerIds.delete(soundId);
+    this._pannedIds.delete(soundId);
+    this._pannerPos.delete(soundId);
+  }
+
+  /**
+   * @private Сводит объявленную игрой геометрию с движковыми дефолтами.
+   * Плагин объявляет её в parts.sounds.spatial; неверное значение не
+   * должно ломать аудиоконтекст, поэтому каждый ключ проверяется отдельно
+   * и по одному падает на дефолт с предупреждением в консоль. Статически
+   * то же самое ловит правило контракта E6 — здесь страховка на прод.
+   * @param {object} [custom] - Блок parts.sounds.spatial из конфига игры.
+   * @returns {object} Числа геометрии + panningModel + mapCoords профиля.
+   */
+  _resolveSpatialConfig(custom = {}) {
+    const source = custom && typeof custom === 'object' ? custom : {};
+    const warn = (key, value, fallback) =>
+      console.warn(
+        `[SoundManager] spatial.${key}: invalid value ${JSON.stringify(
+          value,
+        )}, using ${JSON.stringify(fallback)}`,
+      );
+
+    // число нужного знака, иначе дефолт. Знак объявлен в SPATIAL_NUMERIC —
+    // там же, откуда его читает правило контракта E6
+    const num = key => {
+      const value = source[key];
+      const fallback = SPATIAL_DEFAULTS[key];
+
+      if (value === undefined) {
+        return fallback;
+      }
+
+      const ok =
+        Number.isFinite(value) &&
+        (SPATIAL_NUMERIC[key] === 'positive' ? value > 0 : value >= 0);
+
+      if (!ok) {
+        warn(key, value, fallback);
+      }
+
+      return ok ? value : fallback;
+    };
+
+    // значение из закрытого списка, иначе дефолт
+    const pick = (key, list, fallback) => {
+      const value = source[key];
+
+      if (value === undefined) {
+        return fallback;
+      }
+
+      if (!list.includes(value)) {
+        warn(key, value, fallback);
+
+        return fallback;
+      }
+
+      return value;
+    };
+
+    const mode = pick('mode', SPATIAL_MODES, SPATIAL_DEFAULTS.mode);
+    const profile = SPATIAL_PROFILES[mode];
+
+    let refDistance = num('refDistance');
+    let maxDistance = num('maxDistance');
+
+    // PannerNode с maxDistance <= refDistance ведёт себя неопределённо.
+    // Откатываются ОБА ключа: пара обязана остаться согласованной, а
+    // починка одной половины дала бы геометрию, которую не просил никто.
+    // Сравниваются разрешённые значения, поэтому объявить одну дистанцию
+    // против дефолта второй тоже нарушение — то же условие проверяет
+    // статически правило контракта E6
+    if (maxDistance <= refDistance) {
+      console.warn(
+        `[SoundManager] spatial.maxDistance (${maxDistance}) must exceed ` +
+          `spatial.refDistance (${refDistance}); both fall back to ` +
+          `${SPATIAL_DEFAULTS.refDistance}/${SPATIAL_DEFAULTS.maxDistance}`,
+      );
+      refDistance = SPATIAL_DEFAULTS.refDistance;
+      maxDistance = SPATIAL_DEFAULTS.maxDistance;
     }
+
+    return {
+      mode,
+      virtualElevation: num('virtualElevation'),
+      innerRadius: num('innerRadius'),
+      verticalFactor: num('verticalFactor'),
+      distanceModel: pick(
+        'distanceModel',
+        DISTANCE_MODELS,
+        SPATIAL_DEFAULTS.distanceModel,
+      ),
+      panningModel: pick('panningModel', PANNING_MODELS, profile.panningModel),
+      refDistance,
+      maxDistance,
+      rolloffFactor: num('rolloffFactor'),
+      mapCoords: profile.mapCoords,
+    };
   }
 
   /**
-   * Обновляет громкость и 3D-позицию/панораму.
+   * @private Применяет громкость и решает, слышим ли источник. Отделено от
+   * записи позиции нарочно: позиция пишется под гейтом 30 Гц, а громкость
+   * обязана идти каждый кадр — игра ведёт её от скорости (двигатель), и
+   * ступенька в 30 Гц слышна, а глушение за maxDistance должно срабатывать
+   * в том же кадре, в котором источник ушёл за радиус.
+   * @param {Howl} sound - Экземпляр Howl.
+   * @param {number} soundId - ID конкретного проигрываемого экземпляра.
+   * @param {number} x - Мировая координата X источника.
+   * @param {number} y - Мировая координата Y источника.
+   * @param {number} volume - Громкость.
+   * @param {boolean} [spatial=true] - Принадлежит ли звук миру.
+   * @returns {boolean} `false`, если источник заглушен и позицию писать
+   * незачем.
+   */
+  _applyVolume(sound, soundId, x, y, volume, spatial = true) {
+    if (!sound || typeof soundId !== 'number') {
+      return false;
+    }
+
+    if (spatial === false) {
+      sound.volume(volume, soundId);
+
+      return true;
+    }
+
+    const dx = x - this._listenerX;
+    const dy = y - this._listenerY;
+
+    // отсечка в мировых координатах: она обязана совпадать с maxDistance
+    // самого PannerNode, поэтому зумом НЕ масштабируется — иначе движок
+    // считал бы источник слышимым там, где узел уже отдал тишину
+    if (Math.hypot(dx, dy) >= this._spatial.maxDistance) {
+      sound.volume(0, soundId);
+
+      return false;
+    }
+
+    sound.volume(volume, soundId);
+
+    return true;
+  }
+
+  /**
+   * Обновляет 3D-позицию источника. Позиция считается ОДНОЙ непрерывной
+   * формулой на каждом кадре: слушатель поднят над плоскостью игры на
+   * virtualElevation, а внутри innerRadius вектор на источник плавно
+   * гасится к нулю (smoothstep). Прежняя дед-зона по направлению
+   * (MIN_SPATIAL_DISTANCE) убрана: она переключала источник между двумя
+   * разными состояниями — «узла нет, сухое стерео» и «HRTF в крайнем ухе»
+   * — и этот разрыв тембра был слышен на дистанции в пару единиц.
+   * Громкость здесь не трогается — ей занимается `_applyVolume`.
    * @private
    * @param {Howl} sound - Экземпляр Howl.
-   * @param {number} soundId - ID конкретного проигрываемого звука.
-   * @param {number} x - Координата X источника звука.
-   * @param {number} y - Координата Y источника звука.
-   * @param {number} volume - Громкость звука.
+   * @param {number} soundId - ID конкретного проигрываемого экземпляра.
+   * @param {number} x - Мировая координата X источника.
+   * @param {number} y - Мировая координата Y источника.
    * @param {boolean} [spatial=true] - Принадлежит ли звук миру.
    */
-  _updateSpatialSound(sound, soundId, x, y, volume, spatial = true) {
+  _updateSpatialSound(sound, soundId, x, y, spatial = true) {
     if (!sound || typeof soundId !== 'number') {
       return;
     }
@@ -463,32 +757,66 @@ export default class SoundManager {
       // equalpower (тот схлопывает стерео сэмпла в моно). Пока узла нет,
       // pos() не зовётся вовсе: Howler создал бы паннер и щёлкнул
       // pause()/play()
-      sound.volume(volume, soundId);
       this._recenterIfPanned(sound, soundId, true);
 
       return;
     }
 
-    const distance = Math.hypot(x - this._listenerX, y - this._listenerY);
-
-    if (distance >= PANNER_SETTINGS.maxDistance) {
-      sound.volume(0, soundId);
+    const dx = x - this._listenerX;
+    const dy = y - this._listenerY;
+    const distance = Math.hypot(dx, dy);
+
+    // зум камеры поднимает уши вместе с камерой: при отдалении картинка
+    // сжимается, и стереобаза обязана сжаться так же, иначе звук шире
+    // того, что видит глаз
+    const zoom = this._listenerScale;
+    const elevation = this._spatial.virtualElevation / zoom;
+    const spread = smoothstep(0, this._spatial.innerRadius / zoom, distance);
+
+    const [px, py, pz] = this._spatial.mapCoords(
+      dx * spread,
+      dy * spread,
+      elevation,
+      this._spatial,
+    );
 
-      return;
-    }
+    this._writePos(sound, soundId, px, py, pz);
+  }
 
-    sound.volume(volume, soundId);
+  /**
+   * @private Пишет позицию в паннер, если она изменилась заметнее
+   * POSITION_EPSILON. Единственная точка записи: у неподвижного источника
+   * позиция уже в узле, и повторная запись — только лишняя автоматизация,
+   * а именно её поток WebKit и не переносит.
+   * @param {Howl} sound - Экземпляр Howl.
+   * @param {number} soundId - ID конкретного проигрываемого экземпляра.
+   * @param {number} px - Координата X в осях Web Audio.
+   * @param {number} py - Координата Y в осях Web Audio.
+   * @param {number} pz - Координата Z в осях Web Audio.
+   */
+  _writePos(sound, soundId, px, py, pz) {
+    const written = this._pannerPos.get(soundId);
+
+    if (written !== undefined) {
+      if (
+        Math.abs(written[0] - px) < POSITION_EPSILON &&
+        Math.abs(written[1] - py) < POSITION_EPSILON &&
+        Math.abs(written[2] - pz) < POSITION_EPSILON
+      ) {
+        return;
+      }
 
-    // если дистанция позволяет панорамировать звук
-    if (distance > MIN_SPATIAL_DISTANCE) {
-      sound.pos(x - this._listenerX, 0, y - this._listenerY, soundId);
-      this._pannedIds.add(soundId);
+      // массив переиспользуется: до WORLD_VOICE_LIMIT записей в 33 мс —
+      // это сотни лишних аллокаций в секунду на ровном месте
+      written[0] = px;
+      written[1] = py;
+      written[2] = pz;
     } else {
-      // внутри дед-зоны звук идёт по центру. Экземпляру, у которого паннер
-      // ещё не создан, здесь не место его заводить: узел появится на
-      // первом же выходе из дед-зоны
-      this._recenterIfPanned(sound, soundId);
+      this._pannerPos.set(soundId, [px, py, pz]);
     }
+
+    sound.pos(px, py, pz, soundId);
+    this._pannedIds.add(soundId);
   }
 
   /**
@@ -496,9 +824,12 @@ export default class SoundManager {
    * (источник успел побывать в стороне от слушателя). Экземпляр без узла
    * не трогается: создание паннера — это лишний узел в цепочке, потеря
    * стерео и щелчок от pause()/play() внутри setupPanner Howler'а.
-   * @param {boolean} [equalPower=false] - Перевести узел на equalpower:
-   *   так делается только для источника игрока, миру HRTF сохраняется —
-   *   он снова понадобится, как только источник выйдет из дед-зоны.
+   * @param {boolean} [equalPower=false] - Перевести узел на equalpower.
+   *   Так делается только для источника игрока, и перевод ОДНОСТОРОННИЙ:
+   *   HRTF обратно не возвращается. Рассчитано на однократное
+   *   переключение флага `spatial` (владелец узнаёт, что танк локальный,
+   *   уже после конструктора); обратный переход потребовал бы явного
+   *   восстановления HRTF.
    */
   _recenterIfPanned(sound, soundId, equalPower = false) {
     if (!this._pannedIds.has(soundId)) {
@@ -509,7 +840,10 @@ export default class SoundManager {
       this._applyEqualPower(sound, soundId);
     }
 
-    sound.pos(0, 0, 0, soundId);
+    // через тот же порог: собственный двигатель игрока звучит непрерывно и
+    // всегда, и переписывать ему центр каждый кадр — последнее, что стоит
+    // оставлять в потоке, который чинится ради WebKit
+    this._writePos(sound, soundId, 0, 0, 0);
   }
 
   /**
@@ -562,6 +896,8 @@ export default class SoundManager {
     this._activeInstances.clear();
     this._equalPowerIds.clear();
     this._pannedIds.clear();
+    this._pannerPos.clear();
+    this._lastPositionWrite = -Infinity;
 
     // луп переживает reset: его владелец жив, и ближайший
     // processAudibility() запустит звук заново. Одноразовый — нет:
@@ -577,6 +913,7 @@ export default class SoundManager {
 
     this._listenerX = 0;
     this._listenerY = 0;
+    this._listenerScale = 1;
   }
 
   /**

package/src/client/components/controller/CanvasManager.js

@@ -19,6 +19,11 @@ export default class CanvasManagerCtrl {
     this._model.updateCoords(x, y, cameraReset, shakeData);
   }
 
+  // текущий множитель зума камеры (для позиции слушателя звука)
+  getCameraZoom() {
+    return this._model.getCameraZoom();
+  }
+
   // экранная точка указателя -> мировая (в координатах игрового полотна)
   toWorld(clientX, clientY) {
     return this._view.toWorld(this._model.pointerCanvasId, clientX, clientY);

package/src/client/components/model/CanvasManager.js

@@ -14,6 +14,8 @@ export default class CanvasManagerModel {
     canvasManagerModel = this;
 
     this._data = {};
+    // хотя бы одно полотно с динамической камерой
+    this._hasDynamicCamera = false;
     this._coordX = 0; // текущая координата X игрока
     this._coordY = 0; // текущая координата Y игрока
 
@@ -79,6 +81,8 @@ export default class CanvasManagerModel {
           dynamicCamera: !!canvasData.dynamicCamera,
           shakeCamera: !!canvasData.shakeCamera,
         };
+
+        this._hasDynamicCamera ||= !!canvasData.dynamicCamera;
       }
     }
 
@@ -89,6 +93,32 @@ export default class CanvasManagerModel {
     return this._pointerCanvasId;
   }
 
+  // Множитель масштаба сцены для позиции слушателя звука: размер полотна
+  // (currentScale) И динамический зум. Звук обязан сжиматься вместе с
+  // картинкой — иначе стереобаза шире того, что видит глаз, — а сжимают её
+  // оба множителя: finalScale полотна это ровно их произведение.
+  // Отношение currentScale/baseScale — это доля расчётной ширины 1920
+  // (_designWidth), записанная через уже посчитанные поля, чтобы геттер не
+  // отстал, если формула масштаба изменится. Эталон — полотно указателя: у
+  // игры оно, как правило, одно и именно оно игровое.
+  // Если ни одно полотно динамическую камеру не использует, её множитель
+  // обязан быть 1: сам модификатор считается всегда, и звук «отъезжал» бы
+  // там, где картинка стоит на месте
+  getCameraZoom() {
+    const canvas = this._data[this._pointerCanvasId];
+
+    // до первого resize (и у полотна с fixSize) currentScale равен
+    // baseScale, то есть множитель ровно 1
+    if (!canvas || !canvas.baseScale) {
+      return 1;
+    }
+
+    const canvasScale = canvas.currentScale / canvas.baseScale;
+    const zoom = this._hasDynamicCamera ? this._camZoomModifier : 1;
+
+    return canvasScale * zoom;
+  }
+
   // рассчитывает размеры элементов с учетом пропорций
   resize(data) {
     const screenWidth = data.width;

package/src/client/lib/applyCamera.js

@@ -0,0 +1,29 @@
+// Применение данных камеры: позиция слушателя звука + полотно. Вынесено из
+// main.js отдельным модулем ради одной вещи — порядка вызовов, который
+// ничем больше не защищён: main.js целиком поднять в тесте нельзя, у него
+// побочные эффекты уровня приложения.
+
+/**
+ * Применяет кадр камеры: сначала полотно, затем слушатель звука.
+ *
+ * Порядок обязателен. Множитель зума пересчитывается внутри
+ * `updateCoords`, и слушателю нужен зум ЭТОГО кадра, а не прошлого: при
+ * обратном порядке стереобаза отстаёт от картинки на кадр, и на разгоне
+ * (когда зум как раз и меняется) это слышно как запаздывающую панораму.
+ * @param {object} canvasManager - Контроллер CanvasManager.
+ * @param {object} soundManager - Экземпляр SoundManager.
+ * @param {Array | number} camera - `[x, y, cameraReset, shakeData]` из
+ * горячего буфера ядра; `0` или пустое значение — кадра камеры нет.
+ */
+export default function applyCamera(canvasManager, soundManager, camera) {
+  if (!camera || camera === 0) {
+    return;
+  }
+
+  canvasManager.updateCoords(camera);
+  soundManager.setListenerPosition(
+    camera[0],
+    camera[1],
+    canvasManager.getCameraZoom(),
+  );
+}

package/src/client/main.js

@@ -94,6 +94,7 @@ import {
 import lobbyConfig from '../config/lobby.js';
 import authClientConfig from '../config/authClient.js';
 import clientDefaults from '../config/clientDefaults.js';
+import applyCamera from './lib/applyCamera.js';
 
 // Динамическая загрузка игры по каталогу мастера (Этап 6.3): ClientPlugin
 // (parts, bakers, игровой CSS, хуки ядра) грузится по entries.client манифеста
@@ -641,8 +642,12 @@ function applyMapData(data, { notifyHost = true } = {}) {
   const staticData = {};
   let staticIndex = 0;
 
-  // мировых единиц на уровень: партам нужен для параллакса слоёв и
-  // экструзии объёмов. 0/undefined — движок подставил размер тайла
+  // мировых единиц на уровень — величина ФИЗИКИ: по ней ядро считает
+  // уклон рампы и падение. Вертикальный масштаб КАРТИНКИ задаёт игра
+  // (у танков — `parallax.shear`) и намеренно не зависит от карты, иначе
+  // слои разных карт разъезжались бы по виду. Поле едет в парт как есть —
+  // партам, которые мерят высоту в мировых единицах.
+  // 0/undefined — движок подставил размер тайла
   const levelHeight = (Number(data.levelHeight) || step) * scale;
 
   const pushLayers = (levelLayers, levelMap, level, solid, floor, volumes) => {
@@ -900,18 +905,10 @@ function applyGameData(game) {
   });
 }
 
-// применяет данные камеры (позиция слушателя звука + полотно)
-function applyCamera(camera) {
-  if (camera && camera !== 0) {
-    soundManager.setListenerPosition(camera[0], camera[1]);
-    modules.canvasManager.updateCoords(camera);
-  }
-}
-
 // применяет кадр целиком (первый кадр и дискретные кадры интерполяции)
 function applyShot(game, camera) {
   applyGameData(game);
-  applyCamera(camera);
+  applyCamera(modules.canvasManager, soundManager, camera);
 }
 
 // рендер-тик: ядро выдаёт пересечённые кадры (события, создания/удаления)
@@ -949,7 +946,7 @@ function renderTick() {
 
   if (flags & HOT_FLAGS.CAMERA) {
     // камера уже разрешена ядром: предсказанная позиция либо интерполированная
-    applyCamera([hot[1], hot[2]]);
+    applyCamera(modules.canvasManager, soundManager, [hot[1], hot[2]]);
   }
 
   soundManager.processAudibility();

package/src/config/clientDefaults.js

@@ -1,3 +1,5 @@
+import { SPATIAL_DEFAULTS } from './spatialDefaults.js';
+
 // Движковые дефолты клиентского CONFIG_DATA (порт 0): интерполяция,
 // режимы/служебные клавиши, DOM-структуры движковых модулей, технические
 // сообщения. Игровая половина бывшего config/client.js — src/config/client.js
@@ -11,6 +13,17 @@ export default {
     maxFrameAge: 1000, // мс; страховочная очистка старых кадров буфера
   },
 
+  // ***** parts ***** //
+  // Геометрия пространственного звука. Значения, их единицы измерения и
+  // причина, по которой здесь нет panningModel — в
+  // src/config/spatialDefaults.js: этот же объект читают SoundManager и
+  // правило контракта E6, поэтому дефолт объявлен один раз там.
+  parts: {
+    sounds: {
+      spatial: { ...SPATIAL_DEFAULTS },
+    },
+  },
+
   // ***** modules ***** //
   modules: {
     canvasManager: {

package/src/config/spatialDefaults.js

@@ -0,0 +1,54 @@
+// Дефолты и словарь допустимых значений пространственного звука.
+// Единственный источник для трёх потребителей: clientDefaults.js (движковый
+// конфиг игры), SoundManager (страховка на пустой или битый конфиг) и
+// правило контракта E6 (статическая проверка). Держать их синхронными
+// «по договорённости» не получается: расхождение проявляется только на
+// слух и неотличимо от «звук просто другой».
+//
+// Числа — в МИРОВЫХ единицах игры, не в экранных пикселях: у игры с
+// mapScale 0.3 и baseScale 5 мировая единица впятеро меньше пикселя.
+// Дефолты рассчитаны на масштаб 1:1, игра со своим масштабом объявляет
+// parts.sounds.spatial сама.
+//
+// panningModel здесь НЕТ намеренно: его приносит профиль проекции
+// (SPATIAL_PROFILES в SoundManager.js), иначе sideScroller потерял бы свой
+// equalpower — жёсткий дефолт перекрыл бы профиль на уровне слияния
+// конфигов.
+export const SPATIAL_DEFAULTS = {
+  mode: 'topDown',
+  virtualElevation: 180,
+  innerRadius: 40,
+  verticalFactor: 0.2,
+  distanceModel: 'inverse',
+  refDistance: 200,
+  maxDistance: 1200,
+  rolloffFactor: 0.9,
+};
+
+// Требуемый знак каждого числового поля. Список закрыт: лишний ключ в
+// spatial — всегда опечатка, deepMerge молча положит его в конфиг, а
+// SoundManager молча проигнорирует
+export const SPATIAL_NUMERIC = {
+  virtualElevation: 'positive',
+  innerRadius: 'non-negative',
+  verticalFactor: 'non-negative',
+  refDistance: 'positive',
+  maxDistance: 'positive',
+  rolloffFactor: 'non-negative',
+};
+
+// Профили проекции; геометрия каждого живёт в SPATIAL_PROFILES
+// (SoundManager.js), здесь — только имена для валидации
+export const SPATIAL_MODES = ['topDown', 'sideScroller', 'cockpit'];
+
+export const PANNING_MODELS = ['HRTF', 'equalpower'];
+
+export const DISTANCE_MODELS = ['linear', 'inverse', 'exponential'];
+
+// Все ключи, которые SoundManager читает из блока spatial
+export const SPATIAL_KEYS = [
+  'mode',
+  'panningModel',
+  'distanceModel',
+  ...Object.keys(SPATIAL_NUMERIC),
+];

package/src/devtools/contract/rules/e6-sound-spatial.js

@@ -0,0 +1,115 @@
+import {
+  SPATIAL_DEFAULTS,
+  SPATIAL_NUMERIC,
+  SPATIAL_MODES,
+  SPATIAL_KEYS,
+  PANNING_MODELS,
+  DISTANCE_MODELS,
+} from '../../../config/spatialDefaults.js';
+import { WARN, skip, verdict } from '../result.js';
+
+// verticalFactor, объявленный не при sideScroller, здесь НЕ отмечается: он
+// входит в полный блок дефолтов, который документация показывает как
+// образец, и правило кричало бы на честный копипаст из неё. Лишний ключ
+// безвреден, а неверное число ловится проверкой знака.
+//
+// Блок spatial необязателен: игра без него получает движковые дефолты и
+// звучит правильно. Но объявленный блок с опечаткой — это тихий отказ:
+// движок падает на дефолт и ничего не говорит. Списки допустимых значений,
+// знаки чисел и сами дефолты берутся из src/config/spatialDefaults.js —
+// того же модуля, что читает SoundManager, иначе правило и рантайм
+// разошлись бы и проверка пропускала бы то, что движок молча откатывает.
+export default {
+  id: 'E6',
+  name: 'soundSpatial',
+  level: WARN,
+  title: 'the spatial sound block is well-formed',
+
+  check(ctx) {
+    const sounds = ctx.clientConfig?.parts?.sounds;
+
+    if (!sounds) {
+      return skip('no client sound config');
+    }
+
+    const spatial = sounds.spatial;
+
+    if (spatial === undefined) {
+      return skip('no spatial block — engine defaults apply');
+    }
+
+    if (!spatial || typeof spatial !== 'object' || Array.isArray(spatial)) {
+      return verdict(['parts.sounds.spatial must be a plain object']);
+    }
+
+    const violations = [];
+
+    for (const key of Object.keys(spatial)) {
+      if (!SPATIAL_KEYS.includes(key)) {
+        violations.push(
+          `unknown key "${key}": valid keys are ${SPATIAL_KEYS.join(', ')}`,
+        );
+      }
+    }
+
+    if (spatial.mode !== undefined && !SPATIAL_MODES.includes(spatial.mode)) {
+      violations.push(
+        `mode "${spatial.mode}" is unknown: valid modes are ${SPATIAL_MODES.join(', ')}`,
+      );
+    }
+
+    if (
+      spatial.panningModel !== undefined &&
+      !PANNING_MODELS.includes(spatial.panningModel)
+    ) {
+      violations.push(
+        `panningModel "${spatial.panningModel}" is unknown: valid models are ${PANNING_MODELS.join(', ')}`,
+      );
+    }
+
+    if (
+      spatial.distanceModel !== undefined &&
+      !DISTANCE_MODELS.includes(spatial.distanceModel)
+    ) {
+      violations.push(
+        `distanceModel "${spatial.distanceModel}" is unknown: valid models are ${DISTANCE_MODELS.join(', ')}`,
+      );
+    }
+
+    for (const [key, sign] of Object.entries(SPATIAL_NUMERIC)) {
+      const value = spatial[key];
+
+      if (value === undefined) {
+        continue;
+      }
+
+      const ok =
+        Number.isFinite(value) &&
+        (sign === 'positive' ? value > 0 : value >= 0);
+
+      if (!ok) {
+        violations.push(`${key} must be a ${sign} number, got ${value}`);
+      }
+    }
+
+    // Сравниваются РАЗРЕШЁННЫЕ значения, как в
+    // SoundManager._resolveSpatialConfig: объявить одну дистанцию против
+    // дефолта второй — то же нарушение, и рантайм откатит обе молча
+    const refDistance = Number.isFinite(spatial.refDistance)
+      ? spatial.refDistance
+      : SPATIAL_DEFAULTS.refDistance;
+    const maxDistance = Number.isFinite(spatial.maxDistance)
+      ? spatial.maxDistance
+      : SPATIAL_DEFAULTS.maxDistance;
+
+    if (maxDistance <= refDistance) {
+      violations.push(
+        `maxDistance (${maxDistance}) must be greater than refDistance ` +
+          `(${refDistance}); an undeclared distance falls back to the ` +
+          `engine default, and the engine resets both at runtime`,
+      );
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/index.js

@@ -34,6 +34,7 @@ import e2 from './e2-map-images.js';
 import e3 from './e3-sound-registry.js';
 import e4 from './e4-map-layers.js';
 import e5 from './e5-map-radar-walls.js';
+import e6 from './e6-sound-spatial.js';
 
 // Порядок групп — порядок отчёта: A пакет и сборка, B host, C client,
 // D снапшот, E ассеты (plan/create-vimp-game/stage_1.md).
@@ -42,7 +43,7 @@ export const rules = [
   b1, b2, b3, b4, b5, b6, b7, b8, b9, b10,
   c1, c2, c3, c4, c5, c6, c7, c8, c9, c10, c11,
   d1, d2, d3,
-  e1, e2, e3, e4, e5,
+  e1, e2, e3, e4, e5, e6,
 ];
 
 export default rules;