@fps-games/record-replay

Game-side recording, fixed replay, and autonomous done for Babylon.js games. The package is installed and initialized by the game. Bridge does not inject it and does not own its data.

Install it as a development dependency and import it only from the game's development entry. Production builds must exclude this package completely and fail artifact validation if @fps-games/record-replay or rReplay is present.

Game integration

Vite/Babylon projects can enable capture-only recording with one development plugin:

import rr from '@fps-games/record-replay/vite';

// Add only while serving:
rr()

The plugin injects a lightweight provider only in Vite serve. The provider does not poll for a Scene, attach frame observers, or install navigation guards until Runner or the user starts an operation. It never applies to vite build.

Runner chooses record, replay, or autonomous solving and passes Tape/Experience directly. No URL flag is required.

const { replay, yuka } = await import('@fps-games/record-replay');

replay({
  engine,
  scene,
  game,
  sources: entityManager
    ? [
        yuka({
          entityManager,
          controlEntity: () => player,
          controlMode: () => game.actor().mode,
        }),
      ]
    : [],
});

This installs one explicit game-owned automation surface:

window.rReplay

Runner controller

These calls remain available to Runner and tests. Entering Play only exposes the idle provider. The user starts recording explicitly; authoritative success or failure stops it, and the platform persists the Tape.

window.rReplay.record('baseline');
const tape = window.rReplay.stop();
window.rReplay.replay(tape);
window.rReplay.solve(experience);
await window.rReplay.run('fish.cast', args);
window.rReplay.state();

replay(tape) and solve(experience) load and start in one call. Runner begins performance measurement before invoking either method. state() returns the authoritative snapshot and currently available game actions. stop() is idempotent after an outcome-triggered automatic stop and returns the sealed Tape.

Ownership

This package owns:

• browser input, frame, camera, and optional node capture;
• generic opaque Source sampling;
• Yuka EntityManager state recording;
• Tape validation and Experience extraction;
• fixed replay and autonomous execution;
• the development-only browser controller.

The Yuka adapter uses a structural interface and does not install Yuka. Games that already use Yuka pass their existing EntityManager; other games incur no Yuka dependency.

Runner owns:

• passing Tape/Experience into the page;
• artifact upload and task identity;
• terminal-success verification;
• performance measurement and optimization.

Bridge owns neither recording nor replay; it may only forward controller commands and returned Tape bytes. Do not put platform WebSocket messages, task IDs, artifact paths, credentials, or forced game outcomes in this package.

game.outcome() must be read-only. Tape exhaustion and replay completion are diagnostic signals, not proof that the game reached its authoritative successful terminal state.