@auraindustry/aurajs 0.1.1 → 0.1.3

package/templates/create/3d-collectathon/src/runtime/app.js

@@ -1,6 +1,7 @@
 import { createSceneRegistry } from './scene-registry.js';
 import { createProjectInspector } from './project-inspector.js';
 import { assertRuntimeCapabilities } from './capabilities.js';
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './splash.js';
 
 export function createApp() {
   const sceneRegistry = createSceneRegistry({
@@ -26,13 +27,16 @@ export function createApp() {
     },
     setup() {
       assertRuntimeCapabilities();
+      initSplash();
       activeScene()?.setup?.();
     },
     update(dt) {
+      if (isSplashActive()) { updateSplash(dt); return; }
       projectInspector.syncInput(globalThis.aura?.input || null);
       activeScene()?.update?.(dt);
     },
     draw() {
+      if (isSplashActive()) { drawSplash(); return; }
       activeScene()?.draw?.();
       projectInspector.draw({ activeSceneId });
     },

package/templates/create/blank/src/main.js

@@ -1,4 +1,5 @@
 // {{PROJECT_TITLE}} — AuraJS blank starter
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './runtime/splash.js';
 
 function hasMethod(obj, method) {
   return Boolean(obj) && typeof obj[method] === 'function';
@@ -16,13 +17,16 @@ function assertRuntimeCapabilities() {
 
 aura.setup = function () {
   assertRuntimeCapabilities();
+  initSplash();
   console.log('{{PROJECT_TITLE}} ready');
 };
 
-aura.update = function (_dt) {
+aura.update = function (dt) {
+  if (isSplashActive()) { updateSplash(dt); return; }
   // game logic
 };
 
 aura.draw = function () {
+  if (isSplashActive()) { drawSplash(); return; }
   aura.draw2d.clear(aura.rgba(0.06, 0.06, 0.08, 1.0));
 };

package/templates/create/blank/src/runtime/splash.js

@@ -0,0 +1,305 @@
+// AuraJS Splash — unified retro paper-card boot screen.
+// Auto-wired by createApp(). Shows once on launch, then hands off to the game.
+
+const FADE_IN = 0.7;
+const HOLD = 1.8;
+const FADE_OUT = 0.7;
+const TOTAL = FADE_IN + HOLD + FADE_OUT;
+
+const PAPER = [0.89, 0.89, 0.89];
+const PAPER_SHADOW = [0.80, 0.80, 0.80];
+const PAPER_EDGE = [0.41, 0.41, 0.41];
+const INK = [0.1, 0.1, 0.1];
+const INK_MUTED = [0.42, 0.42, 0.42];
+const MASCOT_FRAME_W = 64;
+const MASCOT_FRAME_H = 84;
+const MASCOT_SEQUENCE = Object.freeze([0, 1, 2, 1]);
+const SPLASH_STING_PATH = 'splash/boot-sting.wav';
+const SPLASH_LOOP_PATH = 'splash/boot-loop.wav';
+const SPLASH_BUS = 'splash';
+const QUIET_BUSES = Object.freeze(['default', 'music', 'sfx']);
+
+let state = null;
+
+function has(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function color(rgb, alpha = 1) {
+  return aura.rgba(rgb[0], rgb[1], rgb[2], alpha);
+}
+
+function drawShadowText(text, x, y, options = {}) {
+  const {
+    shadowOffset = 2,
+    shadowColor = color(INK_MUTED, 0.3),
+    ...rest
+  } = options;
+  aura.draw2d.text(text, x + shadowOffset, y + shadowOffset, {
+    ...rest,
+    color: shadowColor,
+  });
+  aura.draw2d.text(text, x, y, rest);
+}
+
+export function initSplash() {
+  state = {
+    t: 0,
+    logo: null,
+    mascot: null,
+    wordmark: null,
+    font: null,
+    stingHandle: null,
+    loopHandle: null,
+    busVolumes: null,
+    pausedHandles: [],
+  };
+  try { if (has(aura.assets, 'load')) state.logo = aura.assets.load('splash/logoholo.webp'); } catch (_) {}
+  try { if (has(aura.assets, 'load')) state.mascot = aura.assets.load('splash/logo-mascot-sheet.webp'); } catch (_) {}
+  try { if (has(aura.assets, 'load')) state.wordmark = aura.assets.load('splash/aurajs-gg-wordmark.webp'); } catch (_) {}
+  try {
+    if (has(aura.assets, 'loadBitmapFont')) {
+      const result = aura.assets.loadBitmapFont();
+      if (result && result.ok && result.font) state.font = result.font;
+    }
+  } catch (_) {}
+  captureBusVolumes();
+  applySplashBusIsolation();
+  try {
+    if (aura.audio && aura.audio.supported !== false && typeof aura.audio.play === 'function') {
+      state.loopHandle = aura.audio.play(SPLASH_LOOP_PATH, {
+        loop: true,
+        volume: 0.22,
+        bus: SPLASH_BUS,
+      });
+      state.stingHandle = aura.audio.play(SPLASH_STING_PATH, {
+        loop: false,
+        volume: 0.54,
+        bus: SPLASH_BUS,
+      });
+    }
+  } catch (_) {}
+}
+
+export function isSplashActive() {
+  return state !== null;
+}
+
+export function updateSplash(dt) {
+  if (!state) return;
+  syncPausedTracks();
+  try {
+    if (aura.audio && typeof aura.audio.update === 'function') {
+      aura.audio.update(Number(dt) > 0 ? Number(dt) : (1 / 60));
+    }
+  } catch (_) {}
+  state.t += dt;
+  if (state.t >= TOTAL) {
+    stopSplashAudio();
+    state = null;
+  }
+}
+
+export function drawSplash() {
+  if (!state) return;
+  const { width: w, height: h } = has(aura.window, 'getSize')
+    ? aura.window.getSize()
+    : { width: 640, height: 480 };
+  const t = state.t;
+  const cx = w / 2;
+  const cy = h / 2;
+
+  let a = 1;
+  if (t < FADE_IN) a = easeOut(t / FADE_IN);
+  else if (t > FADE_IN + HOLD) a = 1 - easeIn((t - FADE_IN - HOLD) / FADE_OUT);
+
+  aura.draw2d.clear(color(PAPER));
+
+  const panelW = Math.min(Math.floor(w * 0.48), 580);
+  const panelH = Math.min(Math.floor(h * 0.72), 620);
+  const panelX = Math.floor(cx - (panelW * 0.5));
+  const panelY = Math.floor(cy - (panelH * 0.5));
+
+  aura.draw2d.rectFill(panelX + 6, panelY + 6, panelW, panelH, color(INK, 0.08 * a));
+  aura.draw2d.rectFill(panelX, panelY, panelW, panelH, color(PAPER_EDGE, a));
+  aura.draw2d.rectFill(panelX + 6, panelY + 6, panelW - 12, panelH - 12, color(PAPER, a));
+  aura.draw2d.rectFill(panelX + 12, panelY + 12, panelW - 24, panelH - 24, color(PAPER, a * 0.96));
+
+  const floatY = Math.sin(t * 1.4 * Math.PI * 2) * 2;
+  const breathe = 0.985 + 0.015 * (0.5 + 0.5 * Math.sin(t * Math.PI * 2));
+  const mascotScale = Math.max(1, Math.min(Math.floor(Math.min(w, h) / 260), 2));
+  const mascotW = Math.floor(MASCOT_FRAME_W * mascotScale * breathe);
+  const mascotH = Math.floor(MASCOT_FRAME_H * mascotScale * breathe);
+  const mascotX = Math.floor(cx - (mascotW * 0.5));
+  const mascotY = Math.floor(panelY + panelH * 0.40 + floatY);
+  const mascotFrame = MASCOT_SEQUENCE[Math.floor(t * 7.5) % MASCOT_SEQUENCE.length] || 0;
+
+  aura.draw2d.rectFill(
+    mascotX + Math.floor(mascotW * 0.18),
+    mascotY + mascotH - 8,
+    Math.floor(mascotW * 0.64),
+    6,
+    color(INK, a * 0.08),
+  );
+
+  if (state.mascot) {
+    aura.draw2d.sprite(state.mascot, mascotX, mascotY, {
+      width: mascotW,
+      height: mascotH,
+      frameX: mascotFrame * MASCOT_FRAME_W,
+      frameY: 0,
+      frameW: MASCOT_FRAME_W,
+      frameH: MASCOT_FRAME_H,
+      alpha: a,
+    });
+  } else if (state.logo) {
+    const sz = Math.min(Math.floor(panelW * 0.24), Math.floor(h * 0.14)) * breathe;
+    aura.draw2d.sprite(state.logo, Math.floor(cx - sz / 2), Math.floor(mascotY + 6), {
+      width: sz,
+      height: sz,
+      alpha: a,
+    });
+  }
+
+  const ta = clamp(a * easeOut(clamp((t - 0.2) / (FADE_IN * 0.6))));
+  const sa = clamp(a * easeOut(clamp((t - 0.4) / (FADE_IN * 0.6))));
+  const scale = Math.min(w, h) / 480;
+  const tsz = Math.max(24, Math.round(scale * 28));
+  const ssz = Math.max(11, Math.round(scale * 12));
+  const wordmarkW = Math.min(Math.floor(panelW * 0.52), 290);
+  const wordmarkH = Math.floor(wordmarkW * (768 / 1408));
+  const wordmarkX = Math.floor(cx - (wordmarkW * 0.5));
+  const wordmarkY = Math.floor(panelY + 36);
+  const sY = Math.floor(panelY + panelH - 108);
+  const fo = state.font ? { font: state.font } : {};
+
+  if (state.wordmark) {
+    aura.draw2d.sprite(state.wordmark, wordmarkX, wordmarkY, {
+      width: wordmarkW,
+      height: wordmarkH,
+      alpha: ta,
+      tint: color(INK, ta),
+    });
+  } else {
+    drawShadowText('AuraJS.gg', cx, wordmarkY + Math.floor(wordmarkH * 0.55), {
+      ...fo,
+      size: tsz,
+      color: color(INK, ta),
+      shadowColor: color(INK_MUTED, ta * 0.28),
+      align: 'center',
+    });
+  }
+
+  drawShadowText('Open-Source. MIT.', cx, sY, {
+    ...fo,
+    size: ssz,
+    color: color(INK_MUTED, sa),
+    shadowColor: color(PAPER_EDGE, sa * 0.18),
+    shadowOffset: 1,
+    align: 'center',
+  });
+  drawShadowText('Who needs publishers?', cx, sY + Math.max(16, Math.round(ssz * 1.45)), {
+    ...fo,
+    size: ssz,
+    color: color(INK_MUTED, sa),
+    shadowColor: color(PAPER_EDGE, sa * 0.18),
+    shadowOffset: 1,
+    align: 'center',
+  });
+
+  const rw = Math.min(panelW - 140, 240);
+  aura.draw2d.rectFill(Math.floor(cx - rw / 2), Math.floor(sY + Math.max(34, ssz * 3.2)), rw, 2, color(PAPER_EDGE, sa * 0.38));
+}
+
+function easeOut(t) {
+  const u = 1 - clamp(t);
+  return 1 - (u * u * u);
+}
+
+function easeIn(t) {
+  const c = clamp(t);
+  return c * c * c;
+}
+
+function clamp(v) {
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function stopSplashAudio() {
+  if (!state || !aura.audio || typeof aura.audio.stop !== 'function') return;
+  try {
+    if (state.stingHandle != null) aura.audio.stop(state.stingHandle);
+  } catch (_) {}
+  try {
+    if (state.loopHandle != null) aura.audio.stop(state.loopHandle);
+  } catch (_) {}
+  restoreAudioState();
+  state.stingHandle = null;
+  state.loopHandle = null;
+}
+
+function captureBusVolumes() {
+  if (!state || !aura.audio || typeof aura.audio.getMixerState !== 'function') return;
+  try {
+    const mixer = aura.audio.getMixerState();
+    const buses = Array.isArray(mixer?.buses) ? mixer.buses : [];
+    state.busVolumes = buses.reduce((acc, entry) => {
+      const bus = String(entry?.bus || '').trim();
+      if (!bus) return acc;
+      acc[bus] = Number(entry?.volume);
+      return acc;
+    }, {});
+  } catch (_) {}
+}
+
+function applySplashBusIsolation() {
+  if (!state || !aura.audio || typeof aura.audio.setBusVolume !== 'function') return;
+  try { aura.audio.setBusVolume(SPLASH_BUS, 1); } catch (_) {}
+  for (const bus of QUIET_BUSES) {
+    try { aura.audio.setBusVolume(bus, 0); } catch (_) {}
+  }
+}
+
+function syncPausedTracks() {
+  if (!state || !aura.audio || typeof aura.audio.getMixerState !== 'function' || typeof aura.audio.pause !== 'function') return;
+  try {
+    const mixer = aura.audio.getMixerState();
+    const tracks = Array.isArray(mixer?.tracks) ? mixer.tracks : [];
+    const splashHandles = [state.stingHandle, state.loopHandle].filter((handle) => handle != null);
+    const pausedHandles = new Set(Array.isArray(state.pausedHandles) ? state.pausedHandles : []);
+    for (const track of tracks) {
+      const handle = Number(track?.handle);
+      if (!Number.isInteger(handle) || handle <= 0) continue;
+      if (splashHandles.includes(handle)) continue;
+      if (track?.paused === true || pausedHandles.has(handle)) continue;
+      try {
+        aura.audio.pause(handle);
+        pausedHandles.add(handle);
+      } catch (_) {}
+    }
+    state.pausedHandles = Array.from(pausedHandles);
+  } catch (_) {}
+}
+
+function restoreAudioState() {
+  if (!state || !aura.audio) return;
+  if (typeof aura.audio.setBusVolume === 'function') {
+    const snapshot = state.busVolumes && typeof state.busVolumes === 'object' ? state.busVolumes : null;
+    if (snapshot) {
+      for (const [bus, volume] of Object.entries(snapshot)) {
+        try { aura.audio.setBusVolume(bus, Number(volume)); } catch (_) {}
+      }
+    } else {
+      for (const bus of QUIET_BUSES) {
+        try { aura.audio.setBusVolume(bus, 1); } catch (_) {}
+      }
+    }
+    try { aura.audio.setBusVolume(SPLASH_BUS, 1); } catch (_) {}
+  }
+  if (typeof aura.audio.resume === 'function') {
+    for (const handle of Array.isArray(state.pausedHandles) ? state.pausedHandles : []) {
+      try { aura.audio.resume(handle); } catch (_) {}
+    }
+  }
+  state.pausedHandles = [];
+}

package/templates/create/local-multiplayer/scenes/gameplay.scene.js

@@ -178,13 +178,20 @@ function assertLocalMultiplayerCapabilities() {
   if (!hasMethod(aura.draw2d, 'text')) missing.push('aura.draw2d.text');
   if (typeof aura.rgb !== 'function') missing.push('aura.rgb');
   if (!hasMethod(aura.multiplayer, 'configure')) missing.push('aura.multiplayer.configure');
+  if (!hasMethod(aura.multiplayer, 'configureRollbackLane')) missing.push('aura.multiplayer.configureRollbackLane');
+  if (!hasMethod(aura.multiplayer, 'clearRollbackLane')) missing.push('aura.multiplayer.clearRollbackLane');
   if (!hasMethod(aura.multiplayer, 'getAllPlayerInputs')) missing.push('aura.multiplayer.getAllPlayerInputs');
-  if (!hasMethod(aura.multiplayer, 'getAllState')) missing.push('aura.multiplayer.getAllState');
+  if (!hasMethod(aura.multiplayer, 'getInterpolatedAllState')) missing.push('aura.multiplayer.getInterpolatedAllState');
+  if (!hasMethod(aura.multiplayer, 'getLocalId')) missing.push('aura.multiplayer.getLocalId');
+  if (!hasMethod(aura.multiplayer, 'getNetworkDiagnostics')) missing.push('aura.multiplayer.getNetworkDiagnostics');
   if (!hasMethod(aura.multiplayer, 'getPlayerCount')) missing.push('aura.multiplayer.getPlayerCount');
+  if (!hasMethod(aura.multiplayer, 'getRollbackDiagnostics')) missing.push('aura.multiplayer.getRollbackDiagnostics');
+  if (!hasMethod(aura.multiplayer, 'getRollbackState')) missing.push('aura.multiplayer.getRollbackState');
   if (!hasMethod(aura.multiplayer, 'getRoomInfo')) missing.push('aura.multiplayer.getRoomInfo');
   if (!hasMethod(aura.multiplayer, 'getState')) missing.push('aura.multiplayer.getState');
   if (!hasMethod(aura.multiplayer, 'host')) missing.push('aura.multiplayer.host');
   if (!hasMethod(aura.multiplayer, 'isConnected')) missing.push('aura.multiplayer.isConnected');
+  if (!hasMethod(aura.multiplayer, 'onStateUpdate')) missing.push('aura.multiplayer.onStateUpdate');
   if (!hasMethod(aura.multiplayer, 'onPlayerJoin')) missing.push('aura.multiplayer.onPlayerJoin');
   if (!hasMethod(aura.multiplayer, 'onPlayerLeave')) missing.push('aura.multiplayer.onPlayerLeave');
   if (!hasMethod(aura.multiplayer, 'sendInput')) missing.push('aura.multiplayer.sendInput');
@@ -219,6 +226,24 @@ function createSceneState() {
     hostedRoom: null,
     pendingElapsed: 0,
     registeredHostCallbacks: false,
+    registeredRuntimeCallbacks: false,
+    rollbackKey: null,
+    stateUpdateMeta: null,
+  };
+}
+
+function resolveDrawStates(sceneState) {
+  const drawState = aura.multiplayer.getInterpolatedAllState() || {};
+  if (sceneState.role !== 'client' || !sceneState.rollbackKey) {
+    return drawState;
+  }
+  const rollbackState = aura.multiplayer.getRollbackState?.(sceneState.rollbackKey);
+  if (!rollbackState || typeof rollbackState !== 'object') {
+    return drawState;
+  }
+  return {
+    ...drawState,
+    [sceneState.rollbackKey]: rollbackState,
   };
 }
 
@@ -244,6 +269,55 @@ function readInput() {
   };
 }
 
+function readFiniteNumber(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function formatDiagnosticNumber(value, suffix = '') {
+  const numeric = readFiniteNumber(value);
+  return numeric === null ? '-' : `${Math.round(numeric)}${suffix}`;
+}
+
+function readLocalPlayerId(fallback = null) {
+  const localId = Number(aura.multiplayer.getLocalId?.());
+  return Number.isInteger(localId) && localId >= 0 ? localId : fallback;
+}
+
+function localPlayerStateKey(playerId) {
+  return Number.isInteger(playerId) && playerId >= 0 ? `player_${playerId}` : null;
+}
+
+function defaultLocalPlayerLabel(playerId, role = 'client') {
+  if (!Number.isInteger(playerId) || playerId < 0) {
+    return 'player';
+  }
+  if (role === 'host' && playerId === 0) {
+    return 'host';
+  }
+  return `p${playerId}`;
+}
+
+function createFallbackPlayerState(playerId, role = 'client') {
+  return createLocalPlayerState(playerId, defaultLocalPlayerLabel(playerId, role));
+}
+
+function normalizeStateUpdateMetadata(metadata) {
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+  return {
+    source: typeof metadata.source === 'string' && metadata.source.trim() ? metadata.source.trim() : null,
+    sequence: readFiniteNumber(metadata.sequence),
+    serverTimeMs: readFiniteNumber(metadata.serverTimeMs),
+    tickIntervalMs: readFiniteNumber(metadata.tickIntervalMs),
+    jitterMs: readFiniteNumber(metadata.jitterMs),
+    bufferDelayMs: readFiniteNumber(metadata.bufferDelayMs),
+    historyDepth: readFiniteNumber(metadata.historyDepth),
+    bufferedServerTimeMs: readFiniteNumber(metadata.bufferedServerTimeMs),
+  };
+}
+
 function currentStatusLine(sceneState, roomCode) {
   const shareLink = currentLauncherJoinLink(sceneState);
   if (sceneState.role === 'pending') {
@@ -300,15 +374,38 @@ export function createGameplayScene(context = {}) {
     const roomInfo = currentRoomInfo(sceneState);
     const roomCode = currentRoomCode(sceneState);
     const shareLink = currentLauncherJoinLink(sceneState);
+    const network = aura.multiplayer.getNetworkDiagnostics?.() || {};
+    const rollback = aura.multiplayer.getRollbackDiagnostics?.(sceneState.rollbackKey || undefined) || {};
+    const stateUpdateMeta = sceneState.stateUpdateMeta || {};
+    const transportPath = network.transportPath || roomInfo?.transportPath || (usesInternetBackedHosting() ? 'internet_pending' : 'local_room');
+    const transportStatus = network.transportStatus || roomInfo?.transportStatus || (aura.multiplayer.isConnected() ? 'connected' : 'waiting');
+    const joinPath = roomInfo?.joinPath || (usesInternetBackedHosting() ? 'internet_fallback' : 'local');
+    const roomReason = roomInfo?.lastReasonCode || network.lastReasonCode || null;
     const diagnostics = DIAGNOSTICS_CONFIG.enabled
       ? {
-          mode: roomInfo?.requestedMode || CONNECTIVITY_CONFIG.mode,
-          scope: roomInfo?.scope || (usesInternetBackedHosting() ? 'internet' : 'local'),
-          transportPath: roomInfo?.transportPath || (usesInternetBackedHosting() ? 'internet_pending' : 'local_room'),
-          transportStatus: roomInfo?.transportStatus || (aura.multiplayer.isConnected() ? 'connected' : 'waiting'),
-          joinPath: roomInfo?.joinPath || (usesInternetBackedHosting() ? 'internet_fallback' : 'local'),
-          lastReasonCode: roomInfo?.lastReasonCode || null,
+          mode: `${network.requestedMode || roomInfo?.requestedMode || CONNECTIVITY_CONFIG.mode}${rollback.enabled ? ' / rollback on' : ' / rollback off'}`,
+          scope: network.scope || roomInfo?.scope || (usesInternetBackedHosting() ? 'internet' : 'local'),
+          transportPath: `${transportPath}${stateUpdateMeta.source ? ` / ${stateUpdateMeta.source}` : ''}`,
+          transportStatus: `${transportStatus} / seq ${formatDiagnosticNumber(network.lastSequence ?? stateUpdateMeta.sequence)} / gap ${formatDiagnosticNumber(network.sequenceGapCount)}`,
+          joinPath: `${joinPath} / buf ${formatDiagnosticNumber(network.bufferDelayMs ?? stateUpdateMeta.bufferDelayMs, 'ms')} / jit ${formatDiagnosticNumber(network.jitterMs ?? stateUpdateMeta.jitterMs, 'ms')} / q ${formatDiagnosticNumber(network.queuedEventCount)}`,
+          lastReasonCode: `${roomReason || rollback.lastReasonCode || '-'} / rb ${formatDiagnosticNumber(rollback.rollbackCount)} rp ${formatDiagnosticNumber(rollback.replayCount)}`,
           pingMs: Number(aura.multiplayer.getPing?.()),
+          source: stateUpdateMeta.source || null,
+          sequence: network.lastSequence ?? stateUpdateMeta.sequence,
+          serverTimeMs: network.lastSnapshotServerTimeMs ?? stateUpdateMeta.serverTimeMs,
+          tickIntervalMs: network.lastSnapshotTickIntervalMs ?? stateUpdateMeta.tickIntervalMs,
+          jitterMs: network.jitterMs ?? stateUpdateMeta.jitterMs,
+          bufferDelayMs: network.bufferDelayMs ?? stateUpdateMeta.bufferDelayMs,
+          historyDepth: network.historyDepth ?? stateUpdateMeta.historyDepth,
+          bufferedServerTimeMs: network.bufferedServerTimeMs ?? stateUpdateMeta.bufferedServerTimeMs,
+          rollbackEnabled: rollback.enabled === true,
+          rollbackKey: rollback.key || sceneState.rollbackKey || null,
+          rollbackCount: readFiniteNumber(rollback.rollbackCount),
+          replayCount: readFiniteNumber(rollback.replayCount),
+          continuityResetCount: readFiniteNumber(rollback.continuityResetCount),
+          lastCorrectionMagnitude: readFiniteNumber(rollback.lastCorrectionMagnitude),
+          lastAuthoritativeServerTick: readFiniteNumber(rollback.lastAuthoritativeServerTick),
+          lastAckInputTick: readFiniteNumber(rollback.lastAckInputTick),
         }
       : null;
     context.setHudScreen?.('hud', {
@@ -341,6 +438,68 @@ export function createGameplayScene(context = {}) {
     });
   }
 
+  function ensureRuntimeCallbacks() {
+    if (sceneState.registeredRuntimeCallbacks) return;
+    sceneState.registeredRuntimeCallbacks = true;
+    aura.multiplayer.onStateUpdate((_snapshot, metadata) => {
+      sceneState.stateUpdateMeta = normalizeStateUpdateMetadata(metadata);
+    });
+  }
+
+  function clearClientRollback() {
+    if (sceneState.rollbackKey) {
+      aura.multiplayer.clearRollbackLane(sceneState.rollbackKey);
+    } else if (aura.multiplayer.getRollbackDiagnostics?.()?.enabled) {
+      aura.multiplayer.clearRollbackLane();
+    }
+    sceneState.rollbackKey = null;
+  }
+
+  function syncRoleFromRuntime() {
+    const runtimeRole = aura.multiplayer.getRoomInfo?.()?.role;
+    if (runtimeRole === 'host' && sceneState.role !== 'host') {
+      sceneState.role = 'host';
+      ensureHostCallbacks();
+    } else if (runtimeRole === 'client' && sceneState.role !== 'client') {
+      sceneState.role = 'client';
+    }
+  }
+
+  function ensureClientRollback() {
+    const connected = aura.multiplayer.isConnected() === true;
+    const roomRole = aura.multiplayer.getRoomInfo?.()?.role || sceneState.role;
+    if (!connected || roomRole !== 'client') {
+      clearClientRollback();
+      return null;
+    }
+    const localId = readLocalPlayerId();
+    const rollbackKey = localPlayerStateKey(localId);
+    if (!rollbackKey) {
+      clearClientRollback();
+      return null;
+    }
+    const diagnostics = aura.multiplayer.getRollbackDiagnostics?.(rollbackKey) || {};
+    if (sceneState.rollbackKey !== rollbackKey || diagnostics?.enabled !== true || diagnostics?.key !== rollbackKey) {
+      if (sceneState.rollbackKey && sceneState.rollbackKey !== rollbackKey) {
+        aura.multiplayer.clearRollbackLane(sceneState.rollbackKey);
+      }
+      aura.multiplayer.configureRollbackLane({
+        key: rollbackKey,
+        playerId: localId,
+        speed: LOCAL_MULTIPLAYER_CONFIG.playerSpeed,
+        historyLimit: 12,
+        bounds: {
+          minX: 24,
+          maxX: LOCAL_MULTIPLAYER_CONFIG.width - LOCAL_MULTIPLAYER_CONFIG.playerWidth - 24,
+          minY: 96,
+          maxY: LOCAL_MULTIPLAYER_CONFIG.height - LOCAL_MULTIPLAYER_CONFIG.playerHeight - 28,
+        },
+      });
+      sceneState.rollbackKey = rollbackKey;
+    }
+    return { key: rollbackKey, playerId: localId };
+  }
+
   function activateHost() {
     if (sceneState.role === 'host') return;
     const hostOptions = {
@@ -361,15 +520,20 @@ export function createGameplayScene(context = {}) {
     }
     sceneState.hostedRoom = aura.multiplayer.host(hostOptions);
     sceneState.role = 'host';
+    clearClientRollback();
     ensureHostCallbacks();
-    aura.multiplayer.setState('player_0', createLocalPlayerState(0, 'host'));
+    const hostPlayerId = readLocalPlayerId(0);
+    const hostKey = localPlayerStateKey(hostPlayerId) || 'player_0';
+    aura.multiplayer.setState(hostKey, createFallbackPlayerState(hostPlayerId, 'host'));
   }
 
   function resetRun() {
+    clearClientRollback();
     sceneState.role = 'pending';
     sceneState.hostedRoom = null;
     sceneState.pendingElapsed = 0;
     sceneState.registeredHostCallbacks = false;
+    sceneState.stateUpdateMeta = null;
     multiplayerSession.runsStarted += 1;
     multiplayerUi.showControlsHint = true;
     syncSessionState();
@@ -385,10 +549,11 @@ export function createGameplayScene(context = {}) {
       'config/gameplay/local-multiplayer.config.js',
       'content/gameplay/room-layout.js',
     ],
-    summary: 'Room-code multiplayer starter. `npm run dev` hosts, `npm run join -- CODE` joins, `aura.config.json -> multiplayer` owns room/connectivity defaults, and the HUD surfaces live transport diagnostics.',
+    summary: 'Room-code multiplayer starter. `npm run dev` hosts, `npm run join -- CODE` joins, `aura.config.json -> multiplayer` owns room/connectivity defaults, and the HUD surfaces live transport plus rollback diagnostics.',
 
     setup() {
       assertLocalMultiplayerCapabilities();
+      ensureRuntimeCallbacks();
       aura.multiplayer.configure({
         maxPlayers: LOCAL_MULTIPLAYER_CONFIG.maxPlayers,
         tickRate: LOCAL_MULTIPLAYER_CONFIG.tickRate,
@@ -414,9 +579,14 @@ export function createGameplayScene(context = {}) {
         }
       }
 
+      syncRoleFromRuntime();
+
       if (sceneState.role === 'host') {
-        const hostState = aura.multiplayer.getState('player_0') || createLocalPlayerState(0, 'host');
-        aura.multiplayer.setState('player_0', applyLocalPlayerMovement(hostState, input, frameDt));
+        clearClientRollback();
+        const hostPlayerId = readLocalPlayerId(0);
+        const hostKey = localPlayerStateKey(hostPlayerId) || 'player_0';
+        const hostState = aura.multiplayer.getState(hostKey) || createFallbackPlayerState(hostPlayerId, 'host');
+        aura.multiplayer.setState(hostKey, applyLocalPlayerMovement(hostState, input, frameDt));
 
         const inputs = aura.multiplayer.getAllPlayerInputs() || {};
         for (const [playerId, playerInput] of Object.entries(inputs)) {
@@ -426,7 +596,10 @@ export function createGameplayScene(context = {}) {
           aura.multiplayer.setState(key, applyLocalPlayerMovement(current, playerInput, frameDt));
         }
       } else if (sceneState.role === 'client' && aura.multiplayer.isConnected()) {
+        ensureClientRollback();
         aura.multiplayer.sendInput(input);
+      } else {
+        clearClientRollback();
       }
 
       syncSessionState();
@@ -434,13 +607,14 @@ export function createGameplayScene(context = {}) {
     },
 
     onExit() {
+      clearClientRollback();
       context.clearHudScreen?.();
     },
 
     draw() {
       aura.draw2d.clear(aura.rgb(0.07, 0.09, 0.13));
 
-      const allState = aura.multiplayer.getAllState() || {};
+      const allState = resolveDrawStates(sceneState);
       for (const key of Object.keys(allState).sort()) {
         drawLocalPlayerState(allState[key], key);
       }