vimp-engine 0.33.2 → 0.34.1

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vimp-engine-core"
-version = "0.19.0"
+version = "0.21.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.33.2",
+  "version": "0.34.1",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/client/main.js

@@ -596,6 +596,8 @@ function applyMapData(data, { notifyHost = true } = {}) {
         // значит и предсказание подъёма. Не доехав до клиентской `MapLevels`,
         // она дала бы другой уклон, чем у хоста, — расхождение молчаливое
         levelHeight: data.levelHeight,
+        // непрозрачные данные игры: движок их не читает и не масштабирует
+        game: data.game,
       }),
     );
   } catch (e) {
@@ -673,6 +675,9 @@ function applyMapData(data, { notifyHost = true } = {}) {
         // прежнее имя оставлено для парта, который его уже читает
         physicsStatic,
         scale,
+        // непрозрачные данные игры (`map.game`) как объявлены в карте: без
+        // масштабирования. `physicsDynamic[i].game` доезжает до `d{i}` сам
+        game: data.game,
       };
 
       staticIndex += 1;

package/src/devtools/ScenarioRunner.js

@@ -32,6 +32,10 @@ const RECORDED_PORTS = {
   sendTechInform: 'techInform',
 };
 
+// Сообщения, перед которыми отложенные кадры клиента доставляются сразу:
+// они сбрасывают или заменяют его мир (см. routeFrame).
+const FLUSHING_METHODS = new Set(['sendClear', 'sendMap', 'sendFirstShot']);
+
 // В headless-контуре нет ни мастера, ни auth-сервиса — участник стартует с
 // пустым профилем (lib/offlinePlayerData.js, общее со standalone/dedicated).
 const emptyProfileFetch = offlinePlayerData();
@@ -133,6 +137,12 @@ export async function runScenario(rawScenario, options = {}) {
 
 async function execute(scenario, plugin, virtualClock, { captureFrames }) {
   const clients = new Map(); // socketId → VirtualClient
+  // sendShot не вталкивается в клиента сразу: кадр момента T, доставленный
+  // до render(T), сравнивался бы детектором рассинхрона с репликой на
+  // T − timeStep — ложный дрейф v · timeStep. Кадры копятся здесь и
+  // доставляются после рендер-тика (docs/*/debugging.md, «Prediction
+  // divergence detector»)
+  const pendingShots = new Map(); // socketId → [bytes]
   const byParticipant = new Map(); // id сценария → { socketId, gameId }
   const participantLog = []; // [{ who, socketId, gameId, joinTick, leaveTick }]
   const mapChanges = [];
@@ -165,7 +175,8 @@ async function execute(scenario, plugin, virtualClock, { captureFrames }) {
     // получить те же порты и ту же игровую параметризацию
     createSocketManager: (ports, gameOpts) => {
       socketManager = new RecordingSocketManager(ports, gameOpts, {
-        onFrame: frame => routeFrame(frame, clients, virtualClock, host),
+        onFrame: frame =>
+          routeFrame(frame, clients, pendingShots, virtualClock, host),
       });
 
       return socketManager;
@@ -211,6 +222,7 @@ async function execute(scenario, plugin, virtualClock, { captureFrames }) {
         clientCfg,
         plugin,
         clients,
+        pendingShots,
         byParticipant,
         participantLog,
         inputSeq,
@@ -224,8 +236,9 @@ async function execute(scenario, plugin, virtualClock, { captureFrames }) {
       await virtualClock.advance(stepMs);
     }
 
-    for (const client of clients.values()) {
+    for (const [socketId, client] of clients) {
       client.render(virtualClock.monotonic());
+      deliverShots(socketId, clients, pendingShots, virtualClock);
     }
 
     if (dumpTicks.has(tick)) {
@@ -240,6 +253,16 @@ async function execute(scenario, plugin, virtualClock, { captureFrames }) {
     }
   }
 
+  // кадры последнего advance доставляются уже после финального дампа (срез
+  // сцены не меняется), но ещё раз проходят рендер: без него проверки
+  // finiteValues/hotLayout/renderCoverage не видели бы последнего тика, а
+  // агрегаты детектора (render вычерпывает их первым делом) — его кадров.
+  // Время то же — реплика не шагает повторно
+  for (const [socketId, client] of clients) {
+    deliverShots(socketId, clients, pendingShots, virtualClock);
+    client.render(virtualClock.monotonic());
+  }
+
   return buildReport({
     scenario,
     plugin,
@@ -261,13 +284,31 @@ async function execute(scenario, plugin, virtualClock, { captureFrames }) {
 
 // исходящий кадр хоста → клиент-получатель. sendShot несёт байты, которые в
 // проде ушли бы в data channel — их и скармливаем клиентскому ядру
-function routeFrame(frame, clients, virtualClock, host) {
+function routeFrame(frame, clients, pendingShots, virtualClock, host) {
   const client = clients.get(frame.socketId);
 
   if (!client) {
     return;
   }
 
+  // кадр ждёт рендер-тика своего момента (см. pendingShots в runScenario)
+  if (frame.method === 'sendShot') {
+    if (!pendingShots.has(frame.socketId)) {
+      pendingShots.set(frame.socketId, []);
+    }
+
+    pendingShots.get(frame.socketId).push(frame.args[0]);
+    return;
+  }
+
+  // отложенные кадры выпускают только сообщения, меняющие мир клиента: кадр
+  // старой карты не должен доехать после CLEAR/MAP/первого снапшота. Пинг
+  // (каждые rttPingInterval), панель и прочие очередь не трогают — иначе
+  // кадр их тика доставлялся бы до рендера, на шаг раньше реплики
+  if (FLUSHING_METHODS.has(frame.method)) {
+    deliverShots(frame.socketId, clients, pendingShots, virtualClock);
+  }
+
   // pong отвечается мгновенно: латентность headless-прогона равна нулю, и
   // это единственная честная её модель
   if (frame.method === 'sendPing') {
@@ -275,11 +316,6 @@ function routeFrame(frame, clients, virtualClock, host) {
     return;
   }
 
-  if (frame.method === 'sendShot') {
-    client.pushFrame(frame.args[0], virtualClock.monotonic());
-    return;
-  }
-
   // первый снапшот мира: в браузере он применяется сразу (applyShot), а не
   // едет через буфер интерполяции — сущность, доехавшая только им, иначе не
   // попадёт ни в сцену, ни в проверки
@@ -307,10 +343,27 @@ function routeFrame(frame, clients, virtualClock, host) {
   }
 }
 
+function deliverShots(socketId, clients, pendingShots, virtualClock) {
+  const queue = pendingShots.get(socketId);
+
+  if (!queue?.length) {
+    return;
+  }
+
+  pendingShots.delete(socketId);
+
+  const client = clients.get(socketId);
+
+  for (const bytes of queue) {
+    client?.pushFrame(bytes, virtualClock.monotonic());
+  }
+}
+
 async function applyOp(op, ctx) {
   const {
     host,
     clients,
+    pendingShots,
     byParticipant,
     participantLog,
     inputSeq,
@@ -333,6 +386,7 @@ async function applyOp(op, ctx) {
         // текучкой участников растит процесс
         clients.get(entry.socketId)?.destroy();
         clients.delete(entry.socketId);
+        pendingShots.delete(entry.socketId);
         byParticipant.delete(op.who);
 
         const logged = participantLog.find(

package/src/devtools/VirtualClient.js

@@ -206,6 +206,8 @@ class VirtualClient {
           // разъедется с авторитетным молча
           levels: data.levels,
           ramps: data.ramps,
+          // непрозрачные данные игры — как в main.js
+          game: data.game,
         }),
       );
     } catch (e) {
@@ -220,7 +222,7 @@ class VirtualClient {
   render(localNow) {
     // записи копятся в ядре на push_frame, поэтому вычерпываются до sample —
     // иначе тик с пустым hot-буфером (ранний выход ниже) их бы потерял
-    this._drainDivergence();
+    this.drainDivergence();
 
     const len = this.core.sample(localNow);
 
@@ -297,8 +299,9 @@ class VirtualClient {
   }
 
   // Записи детектора рассинхрона предикта из ядра. Агрегаты накопительные,
-  // поэтому просто перезаписываются; записи — вычерпываются.
-  _drainDivergence() {
+  // поэтому просто перезаписываются; записи — вычерпываются. Публичный:
+  // раннер вычерпывает кадры, доставленные после последнего рендер-тика.
+  drainDivergence() {
     if (typeof this.core.take_divergence !== 'function') {
       return;
     }

package/src/devtools/contract/rules/d3-snapshot-interp.js

@@ -3,11 +3,16 @@ import { ERROR, skip, verdict } from '../result.js';
 // Интерполируются только f32 и только в горячих блоках. interp на u8 или
 // в event-блоке не ошибка сборки — он просто не исполняется, и поле
 // дёргается вместо плавного движения.
+//
+// Там же — роль `state` (байт состояния тела карты): u8 сразу за головой
+// строки динамики (позиция 5 у слоёной строки, 3 — у плоской) и до
+// опционального хвоста. Ядро отвергает иное при загрузке карты, то есть
+// уже в запущенном матче (зеркало `BlockSchema::validate_roles`).
 export default {
   id: 'D3',
   name: 'snapshotInterp',
   level: ERROR,
-  title: "interp only on f32 fields of class 'hot' blocks",
+  title: "interp only on f32 fields of class 'hot' blocks; role 'state' is a u8 right after the row head",
 
   check(ctx) {
     const snapshot = ctx.gameConfig?.snapshot;
@@ -19,6 +24,8 @@ export default {
     const violations = [];
 
     for (const [key, block] of Object.entries(snapshot)) {
+      checkStateRole(key, block, violations);
+
       for (const field of block.fields ?? []) {
         if (field.interp === undefined) {
           continue;
@@ -43,3 +50,39 @@ export default {
     return verdict(violations);
   },
 };
+
+// позиции зафиксированы движком (`GameMap::dynamic_map_data_with_state`)
+const STATE_INDEX_FLAT = 3;
+const STATE_INDEX_LAYERED = 5;
+
+function checkStateRole(key, block, violations) {
+  const fields = block.fields ?? [];
+  const layered = fields[3]?.role === 'z' && fields[4]?.role === 'level';
+  const expected = layered ? STATE_INDEX_LAYERED : STATE_INDEX_FLAT;
+
+  fields.forEach((field, index) => {
+    if (field.role !== 'state') {
+      return;
+    }
+
+    const at = `snapshot "${key}".${field.name}`;
+
+    if (index !== expected) {
+      violations.push(
+        `${at}: role 'state' at index ${index}, the engine writes it at ` +
+          `${expected} (right after the ${layered ? 'layered' : 'flat'} row head)`,
+      );
+    }
+
+    if (field.ty !== 'u8') {
+      violations.push(`${at}: role 'state' must be ty "u8", got "${field.ty}"`);
+    }
+
+    if (block.optionalFrom !== undefined && block.optionalFrom <= index) {
+      violations.push(
+        `${at}: role 'state' at index ${index} lies inside the optional tail ` +
+          `(optionalFrom ${block.optionalFrom}) — a resting body would lose it`,
+      );
+    }
+  });
+}

package/src/devtools/contract/rules/e7-map-game-field.js

@@ -0,0 +1,58 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Поле карты `game` (и `physicsDynamic[i].game`) — пространство игры:
+// движок его не читает и не масштабирует, но фиксирует форму. Ядро
+// (`MapConfig::validate`) отвергает не-объект при загрузке карты, то есть в
+// уже запущенном матче; здесь то же ловится до сборки.
+export default {
+  id: 'E7',
+  name: 'mapGameField',
+  level: ERROR,
+  title: 'map game field is a plain object',
+
+  check(ctx) {
+    const maps = ctx.gameConfig?.maps;
+
+    if (!maps) {
+      return skip('no gameConfig.maps');
+    }
+
+    const declared = Object.entries(maps).filter(
+      ([, map]) =>
+        map?.game !== undefined ||
+        (map?.physicsDynamic ?? []).some(object => object?.game !== undefined),
+    );
+
+    if (!declared.length) {
+      return skip('no map declares game');
+    }
+
+    const violations = [];
+
+    for (const [name, map] of declared) {
+      if (map.game !== undefined && !isPlainObject(map.game)) {
+        violations.push(`map "${name}": game is not a plain object`);
+      }
+
+      for (const [index, object] of (map.physicsDynamic ?? []).entries()) {
+        if (object?.game !== undefined && !isPlainObject(object.game)) {
+          violations.push(
+            `map "${name}": physicsDynamic ${index} game is not a plain object`,
+          );
+        }
+      }
+    }
+
+    return verdict(violations);
+  },
+};
+
+// `null` ядро принимает как «не объявлено», но в исходнике карты это почти
+// всегда опечатка — правило требует либо объект, либо отсутствие поля
+function isPlainObject(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}

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

@@ -35,6 +35,7 @@ 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';
+import e7 from './e7-map-game-field.js';
 
 // Порядок групп — порядок отчёта: A пакет и сборка, B host, C client,
 // D снапшот, E ассеты (plan/create-vimp-game/stage_1.md).
@@ -43,7 +44,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, e6,
+  e1, e2, e3, e4, e5, e6, e7,
 ];
 
 export default rules;

package/src/lib/capabilities.js

@@ -35,6 +35,14 @@ export const ENGINE_CAPABILITIES = createRegistry('engine-capabilities', [
   // уклон рампы в ядре, поле `levelHeight` в контексте статического парта,
   // прогоны рамп уровня (`ramps`) там же, коллайдеры-стражи прогона
   { value: 'map.levelHeight', since: '0.32.0' },
+  // непрозрачное поле карты `game` (и `physicsDynamic[i].game`): до
+  // игрового ядра хоста, `ClientCore.set_map` и партов карты; хук ядра
+  // `GameSim::on_map_loaded`
+  { value: 'map.gameData', since: '0.34.0' },
+  // байт состояния тела карты (роль `state` в строке динамики,
+  // `SimCtx::map_body_state`) и доступ игры к телам карты по индексу
+  // (хэндл, индекс по хэндлу, отключение тела)
+  { value: 'map.bodyState', since: '0.34.0' },
 ]);
 
 // плоский список имён — то, чем правило контракта B2 проверяет `requires`

package/tests/fixtures/miniGame/client/fakeClientCore.js

@@ -40,6 +40,10 @@ export default class FakeClientCore {
     this._inputs = []; // [{ time, vy }] в локальном времени
     this._base = null; // { x, y, time, vy } — последнее авторитетное, в серверном
     this._offset = 0;
+    // локальное время последнего sample(): реплика Rust-ядра шагает только
+    // в нём, и predicted_state() отдаёт состояние на этот момент, а не на
+    // момент кадра — фикстура сравнивает так же, чтобы сдвиг был виден
+    this._sampledAt = null;
   }
 
   push_frame(data, localNow = 0) {
@@ -66,7 +70,9 @@ export default class FakeClientCore {
     return 0;
   }
 
-  sample() {
+  sample(localNow = 0) {
+    this._sampledAt = localNow;
+
     if (!this._frame || !this._hotKey) {
       this._hot = new Float32Array(0);
 
@@ -157,7 +163,11 @@ export default class FakeClientCore {
     const time = frame.serverTime;
 
     if (this._base) {
-      const predicted = this._predictAt(time);
+      // до первого sample() момента реплики ещё нет — сравнение на момент
+      // кадра, как было до учёта sample (сдвига в этот момент нет)
+      const predicted = this._predictAt(
+        this._sampledAt === null ? time : this._sampledAt + this._offset,
+      );
 
       this._compare(predicted, authoritative, frame);
     }
@@ -273,6 +283,7 @@ export default class FakeClientCore {
     this._hot = new Float32Array(0);
     this._base = null;
     this._inputs = [];
+    this._sampledAt = null;
   }
 
   // зеркало ClientState::debug_json; у фикстуры буфер — один последний