Level 19.2 gameplay overlay integration.

Enable overlays during gameplay runtime without interference.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,9 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Implement overlay expansion framework:
-- Define extension interfaces/contracts
-- Ensure compatibility with config-driven overlays
-- Do not change existing behavior
+Integrate overlay system into gameplay runtime:
+- Allow overlays to run during gameplay
+- Ensure no interference with controls/rendering
+- Preserve debug overlay behavior
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Level 19.1 overlay system expansion framework.
-Introduce extension points for future overlay types.
+Level 19.2 gameplay overlay integration.
+Enable overlays during gameplay runtime without interference.

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -99,7 +99,7 @@ Commit Comment:
 - Always proceed to the next logical step
 
 ### NO COMMIT-ONLY PRs
-- PRs must include something testable
+- PRs must include something testable and improve the Roadmap
 - If a PR is doc-only, bundle with next smallest executable/testable change
 
 ### ZIP IS ALWAYS REQUIRED

docs/dev/reports/BUILD_PR_LEVEL_19_2_OVERLAY_GAMEPLAY_RUNTIME_INTEGRATION_report.md

@@ -0,0 +1,24 @@
+# BUILD_PR_LEVEL_19_2_OVERLAY_GAMEPLAY_RUNTIME_INTEGRATION Report
+
+## Purpose
+Integrate overlay extension support into gameplay runtime without changing existing debug overlay behavior.
+
+## Scope Applied
+- Add optional runtime overlay extension hooks (`onStep`, `onRender`) to overlay contracts/config.
+- Add a shared gameplay runtime runner for overlay extension hooks.
+- Wire gameplay sample runtimes to execute overlay hooks safely (non-blocking).
+- Preserve existing input, rendering, and debug overlay behavior by default.
+
+## Files
+- `samples/phase-17/shared/overlayExpansionContracts.js`
+- `samples/phase-17/shared/overlayGameplayRuntime.js`
+- `samples/phase-17/shared/overlayStackBySampleConfig.js`
+- `samples/phase-17/1708/RealGameplayMiniGameScene.js`
+- `samples/phase-17/1710/RealGameplayMiniGameScene.js`
+- `tests/runtime/Phase17OverlayExpansionFramework.test.mjs`
+- `tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs`
+
+## Behavior Notes
+- Existing overlays keep the same stack order, cycle keys, persistence, and placement.
+- Runtime hooks are opt-in; current configs use empty runtime hook arrays.
+- Hook failures are contained and do not break gameplay step/render execution.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Existing overlays load
-[ ] Extension points defined
-[ ] No regression
-[ ] Config compatibility maintained
+[ ] Gameplay runs normally
+[ ] Overlays visible in gameplay
+[ ] No input conflicts
+[ ] No render issues

docs/pr/BUILD_PR.md

@@ -1,30 +1,31 @@
-# BUILD_PR_LEVEL_19_1_OVERLAY_SYSTEM_EXPANSION_FRAMEWORK
+# BUILD_PR_LEVEL_19_2_GAMEPLAY_OVERLAY_INTEGRATION
 
 ## PLAN
 
 ### Purpose
-Establish a framework for expanding the overlay system beyond debug use into reusable gameplay and tool overlays.
+Integrate overlay system into gameplay layer so overlays can be used during active gameplay, not just debug/testing.
 
 ### Goals
-- Define extension points for new overlays
-- Ensure compatibility with existing config-driven system
-- Maintain strict separation between debug and gameplay overlays
+- Enable overlays in gameplay runtime
+- Maintain separation from debug overlays
+- Ensure no gameplay interference
 
 ---
 
 ## BUILD
 
 ### Scope
-- Define overlay extension interface/contracts
-- Document integration pattern for new overlays
-- Ensure existing overlays conform to framework
-- No behavior change
+- Hook overlay system into gameplay runtime
+- Allow gameplay-safe overlays
+- Ensure overlays do not block input or rendering
+- No change to debug overlays
 
 ### Test Steps
-1. Validate existing overlays still load
-2. Confirm extension points available
-3. Verify no regression
+1. Run gameplay sample
+2. Enable overlays
+3. Verify gameplay unaffected
+4. Cycle overlays
 
 ### Expected
-- Overlay system ready for expansion
-- No impact to existing behavior
+- Overlays work during gameplay
+- No input or render conflicts

samples/phase-17/1708/RealGameplayMiniGameScene.js

@@ -38,6 +38,12 @@ import {
   OVERLAY_UI_LAYER,
 } from '/samples/phase-17/shared/miniGameOverlayStack.js';
 import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
+import {
+  createOverlayGameplayRuntime,
+  renderOverlayGameplayRuntime,
+  setOverlayGameplayRuntimeExtensions,
+  stepOverlayGameplayRuntime,
+} from '/samples/phase-17/shared/overlayGameplayRuntime.js';
 
 const theme = new Theme(ThemeTokens);
 
@@ -105,6 +111,9 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MINI_GAME_DEBUG_CYCLE_KEY);
     setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
     this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId);
+    this.overlayGameplayRuntime = createOverlayGameplayRuntime({
+      runtimeExtensions: DEBUG_OVERLAY_CONFIG.runtimeExtensions,
+    });
   }
 
   addEvent(text) {
@@ -202,6 +211,10 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, persistenceKey);
   }
 
+  setOverlayGameplayRuntimeExtensions(runtimeExtensions) {
+    return setOverlayGameplayRuntimeExtensions(this.overlayGameplayRuntime, runtimeExtensions);
+  }
+
   isDebugOverlayActive(overlayId) {
     return isTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
   }
@@ -473,6 +486,14 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.lastCollisionCount = this.debugCollisionRows.length;
     this.updateFeedback(dt);
     this.refreshMissionFeedState();
+    stepOverlayGameplayRuntime(this.overlayGameplayRuntime, {
+      scene: this,
+      engine,
+      input,
+      dtSeconds: dt,
+      gameState: this.gameState,
+      activeOverlayId: this.getActiveDebugOverlayId(),
+    });
     this.syncCamera();
   }
 
@@ -621,5 +642,11 @@ export default class RealGameplayMiniGameScene extends Scene {
         `Camera mode: ${this.viewState.cameraMode}`,
       ]);
     }
+    renderOverlayGameplayRuntime(this.overlayGameplayRuntime, {
+      scene: this,
+      renderer,
+      gameState: this.gameState,
+      activeOverlayId,
+    });
   }
 }

samples/phase-17/1710/RealGameplayMiniGameScene.js

@@ -38,6 +38,12 @@ import {
   OVERLAY_UI_LAYER,
 } from '/samples/phase-17/shared/miniGameOverlayStack.js';
 import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
+import {
+  createOverlayGameplayRuntime,
+  renderOverlayGameplayRuntime,
+  setOverlayGameplayRuntimeExtensions,
+  stepOverlayGameplayRuntime,
+} from '/samples/phase-17/shared/overlayGameplayRuntime.js';
 
 const theme = new Theme(ThemeTokens);
 
@@ -105,6 +111,9 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MINI_GAME_DEBUG_CYCLE_KEY);
     setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
     this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId);
+    this.overlayGameplayRuntime = createOverlayGameplayRuntime({
+      runtimeExtensions: DEBUG_OVERLAY_CONFIG.runtimeExtensions,
+    });
   }
 
   addEvent(text) {
@@ -202,6 +211,10 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, persistenceKey);
   }
 
+  setOverlayGameplayRuntimeExtensions(runtimeExtensions) {
+    return setOverlayGameplayRuntimeExtensions(this.overlayGameplayRuntime, runtimeExtensions);
+  }
+
   isDebugOverlayActive(overlayId) {
     return isTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
   }
@@ -473,6 +486,14 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.lastCollisionCount = this.debugCollisionRows.length;
     this.updateFeedback(dt);
     this.refreshMissionFeedState();
+    stepOverlayGameplayRuntime(this.overlayGameplayRuntime, {
+      scene: this,
+      engine,
+      input,
+      dtSeconds: dt,
+      gameState: this.gameState,
+      activeOverlayId: this.getActiveDebugOverlayId(),
+    });
     this.syncCamera();
   }
 
@@ -621,5 +642,11 @@ export default class RealGameplayMiniGameScene extends Scene {
         `Camera mode: ${this.viewState.cameraMode}`,
       ]);
     }
+    renderOverlayGameplayRuntime(this.overlayGameplayRuntime, {
+      scene: this,
+      renderer,
+      gameState: this.gameState,
+      activeOverlayId,
+    });
   }
 }

samples/phase-17/shared/overlayExpansionContracts.js

@@ -45,13 +45,49 @@ function resolveInitialOverlayId(overlays, initialOverlayId) {
   return exists ? requestedId : overlays[0].id;
 }
 
+function normalizeRuntimeExtensionEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const overlayId = String(entry.overlayId || '').trim();
+  const onStep = typeof entry.onStep === 'function' ? entry.onStep : null;
+  const onRender = typeof entry.onRender === 'function' ? entry.onRender : null;
+  if (!onStep && !onRender) {
+    return null;
+  }
+
+  return Object.freeze({
+    overlayId,
+    onStep,
+    onRender,
+  });
+}
+
+function normalizeRuntimeExtensions(runtimeExtensions) {
+  if (!Array.isArray(runtimeExtensions) || runtimeExtensions.length === 0) {
+    return Object.freeze([]);
+  }
+
+  const normalized = [];
+  for (let i = 0; i < runtimeExtensions.length; i += 1) {
+    const candidate = normalizeRuntimeExtensionEntry(runtimeExtensions[i]);
+    if (!candidate) {
+      continue;
+    }
+    normalized.push(candidate);
+  }
+  return Object.freeze(normalized);
+}
+
 export function defineOverlayExtensionContract({
   id = '',
   overlays = [],
   initialOverlayId = '',
   cycleKey = '',
   persistenceKey = '',
   channel = DEFAULT_CHANNEL,
+  runtimeExtensions = [],
   metadata = {},
 } = {}) {
   const normalizedId = String(id || '').trim();
@@ -68,6 +104,7 @@ export function defineOverlayExtensionContract({
   const normalizedPersistenceKey = String(persistenceKey || '').trim();
   const normalizedChannel = String(channel || DEFAULT_CHANNEL).trim() || DEFAULT_CHANNEL;
   const normalizedInitialOverlayId = resolveInitialOverlayId(normalizedOverlays, initialOverlayId);
+  const normalizedRuntimeExtensions = normalizeRuntimeExtensions(runtimeExtensions);
 
   return Object.freeze({
     id: normalizedId,
@@ -76,6 +113,7 @@ export function defineOverlayExtensionContract({
     initialOverlayId: normalizedInitialOverlayId,
     cycleKey: normalizedCycleKey,
     persistenceKey: normalizedPersistenceKey,
+    runtimeExtensions: normalizedRuntimeExtensions,
     metadata: Object.freeze({ ...(metadata || {}) }),
   });
 }
@@ -105,5 +143,6 @@ export function getOverlayControllerConfigFromContract(contract) {
     initialOverlayId: contract.initialOverlayId,
     cycleKey: contract.cycleKey,
     persistenceKey: contract.persistenceKey,
+    runtimeExtensions: contract.runtimeExtensions,
   });
 }