Add gameplay-safe overlay interaction controls.

DavidQ · DavidQ · commit e86560ad6f91 · 2026-04-16T17:29:24.000-04:00
PR Details:
- Enables show/hide/cycle controls for gameplay overlays
- Preserves shared non-Tab input mapping
- Adds focused validation for non-interference with gameplay controls
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,10 +1,15 @@
-MODEL: GPT-5.4-codex
+MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Integrate overlay system into gameplay runtime:
-- Allow overlays to run during gameplay
-- Ensure no interference with controls/rendering
-- Preserve debug overlay behavior
+Create BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS as the next smallest executable/testable PR.
 
-Package ZIP to <project folder>/tmp/
+Requirements:
+- Add gameplay-safe interaction controls for overlays introduced by Level 19.2
+- Support show/hide and cycle behavior in gameplay runtime
+- Reuse the shared overlay/input mapping; do not reintroduce hardcoded Tab behavior
+- Preserve existing debug overlay behavior
+- Add or update focused tests proving overlay controls do not interfere with gameplay controls
+- Keep scope narrow and testable
+- Do not modify start_of_day folders
+- Package the repo-structured ZIP to <project folder>/tmp/BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,6 @@
-Level 19.2 gameplay overlay integration.
-Enable overlays during gameplay runtime without interference.
+Add gameplay-safe overlay interaction controls.
+
+PR Details:
+- Enables show/hide/cycle controls for gameplay overlays
+- Preserves shared non-Tab input mapping
+- Adds focused validation for non-interference with gameplay controls
diff --git a/docs/dev/reports/BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS_report.md b/docs/dev/reports/BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS_report.md
@@ -0,0 +1,29 @@
+# BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS Report
+
+## Purpose
+Add gameplay-safe overlay interaction controls for Level 19 runtime overlay extensions.
+
+## Scope Applied
+- Added shared runtime interaction input mapping (no Tab usage).
+- Added overlay gameplay runtime controls for:
+  - show/hide (`Ctrl+G`)
+  - cycle active runtime extension (`G`, reverse with `Shift+G`)
+- Integrated controls into gameplay runtime scenes (`1708`, `1710`), preserving existing debug overlay cycle behavior.
+- Kept control execution non-blocking so overlay runtime hooks cannot break gameplay step/render.
+
+## Behavior Safety
+- Existing debug overlay stack and cycle behavior remain unchanged.
+- Gameplay controls (movement/camera) continue to work while overlay controls are used.
+- Runtime overlay hooks are hidden/shown without affecting gameplay loop integrity.
+
+## Validation
+- `tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs` PASS
+- `tests/runtime/Phase17OverlayExpansionFramework.test.mjs` PASS
+- `tests/runtime/Phase17RealGameplaySample.test.mjs` PASS
+- `tests/runtime/Phase17Sample1712GameplayMetricsTelemetry.test.mjs` PASS
+- `tests/runtime/Phase17Sample1713FinalReferenceGame.test.mjs` PASS
+- `tests/runtime/Phase17TabDebugOverlayCycle1707Plus.test.mjs` PASS
+- `tests/runtime/Phase17DebugOverlayBottomRightPosition.test.mjs` PASS
+- `tests/runtime/Phase18RuntimeLayerScaffold.test.mjs` PASS
+- `tests/runtime/Phase18IntegrationFlowPass.test.mjs` PASS
+- `tests/runtime/Phase18CoreServicesSkeleton.test.mjs` PASS
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,7 +1,7 @@
-Final validation pass for overlay system after full Level 18 integration.
+Summary:
+This PR follows Level 19.2 by adding interaction controls for gameplay overlays.
+It keeps scope limited to a testable control layer so overlays can be shown, hidden, and cycled during gameplay without interfering with core player input.
 
-Confirms:
-- Stability
-- Performance
-- Integration completeness
-- Production readiness
+Roadmap Improvement:
+- Advances Level 19 from gameplay overlay availability to gameplay-safe overlay usability
+- Keeps the change executable and validation-backed
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,6 @@
-[ ] Gameplay runs normally
-[ ] Overlays visible in gameplay
-[ ] No input conflicts
-[ ] No render issues
+[ ] Gameplay sample with overlays loads
+[ ] Overlay show/hide control works
+[ ] Overlay cycle control works
+[ ] Gameplay controls remain responsive while using overlay controls
+[ ] No Tab-based overlay interaction is introduced
+[ ] Debug overlay behavior remains unchanged
diff --git a/docs/pr/BUILD_PR.md b/docs/pr/BUILD_PR.md
@@ -1,31 +1,40 @@
-# BUILD_PR_LEVEL_19_2_GAMEPLAY_OVERLAY_INTEGRATION
-
-## PLAN
-
-### Purpose
-Integrate overlay system into gameplay layer so overlays can be used during active gameplay, not just debug/testing.
-
-### Goals
-- Enable overlays in gameplay runtime
-- Maintain separation from debug overlays
-- Ensure no gameplay interference
-
----
-
-## BUILD
-
-### Scope
-- 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. Run gameplay sample
-2. Enable overlays
-3. Verify gameplay unaffected
-4. Cycle overlays
-
-### Expected
-- Overlays work during gameplay
-- No input or render conflicts
+# BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS
+
+## Purpose
+Add testable interaction controls for gameplay-safe overlays introduced in Level 19.2 so overlays can be shown, hidden, and cycled without interfering with gameplay input.
+
+## Scope
+- Define gameplay-safe overlay interaction controls
+- Keep debug-overlay behavior intact
+- Ensure overlay interaction does not steal or block primary gameplay controls
+- Validate control behavior in at least one gameplay-active sample
+
+## Included
+- Interaction control contract for gameplay overlays
+- Runtime hookup for overlay show/hide/cycle actions in gameplay context
+- Tests covering non-interference with gameplay controls
+- Validation notes for control behavior
+
+## Excluded
+- New overlay types
+- Overlay visual redesign
+- Mission or telemetry feature expansion
+- Repo-wide input cleanup
+
+## Execution Notes
+- Use the shared input mapping established by prior overlay/input consolidation work
+- Preserve current non-Tab overlay cycle behavior
+- Keep scope to the smallest executable/testable change
+- Do not modify start_of_day folders
+
+## Test Steps
+1. Load a gameplay-active sample with overlays enabled
+2. Trigger overlay show/hide control
+3. Trigger overlay cycle control
+4. Confirm gameplay movement/actions still work while overlay controls are used
+5. Confirm debug overlay behavior remains unchanged where applicable
+
+## Expected Result
+- Gameplay overlays can be interacted with safely
+- Overlay controls do not interfere with core gameplay input
+- Existing debug overlay behavior remains stable
diff --git a/samples/phase-17/1708/RealGameplayMiniGameScene.js b/samples/phase-17/1708/RealGameplayMiniGameScene.js
@@ -41,6 +41,7 @@ import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/o
 import {
   createOverlayGameplayRuntime,
   renderOverlayGameplayRuntime,
+  stepOverlayGameplayRuntimeControls,
   setOverlayGameplayRuntimeExtensions,
   stepOverlayGameplayRuntime,
 } from '/samples/phase-17/shared/overlayGameplayRuntime.js';
@@ -486,6 +487,7 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.lastCollisionCount = this.debugCollisionRows.length;
     this.updateFeedback(dt);
     this.refreshMissionFeedState();
+    stepOverlayGameplayRuntimeControls(this.overlayGameplayRuntime, input);
     stepOverlayGameplayRuntime(this.overlayGameplayRuntime, {
       scene: this,
       engine,
diff --git a/samples/phase-17/1710/RealGameplayMiniGameScene.js b/samples/phase-17/1710/RealGameplayMiniGameScene.js
@@ -41,6 +41,7 @@ import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/o
 import {
   createOverlayGameplayRuntime,
   renderOverlayGameplayRuntime,
+  stepOverlayGameplayRuntimeControls,
   setOverlayGameplayRuntimeExtensions,
   stepOverlayGameplayRuntime,
 } from '/samples/phase-17/shared/overlayGameplayRuntime.js';
@@ -486,6 +487,7 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.lastCollisionCount = this.debugCollisionRows.length;
     this.updateFeedback(dt);
     this.refreshMissionFeedState();
+    stepOverlayGameplayRuntimeControls(this.overlayGameplayRuntime, input);
     stepOverlayGameplayRuntime(this.overlayGameplayRuntime, {
       scene: this,
       engine,
diff --git a/samples/phase-17/shared/overlayCycleInput.js b/samples/phase-17/shared/overlayCycleInput.js
@@ -6,6 +6,7 @@ overlayCycleInput.js
 */
 export const LEVEL17_OVERLAY_CYCLE_KEY = 'KeyG';
 export const LEVEL17_OVERLAY_REVERSE_MODIFIERS = Object.freeze(['ShiftLeft', 'ShiftRight']);
+export const LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS = Object.freeze(['ControlLeft', 'ControlRight']);
 export const LEVEL17_OVERLAY_CYCLE_LABEL = 'G/Shift+G';
 
 export function isOverlayCycleReverseModifierActive(input) {
@@ -23,3 +24,16 @@ export function getOverlayCycleInputCodes({ reverse = false } = {}) {
   }
   return [LEVEL17_OVERLAY_CYCLE_KEY, LEVEL17_OVERLAY_REVERSE_MODIFIERS[0]];
 }
+
+export function isOverlayRuntimeToggleModifierActive(input) {
+  for (let i = 0; i < LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS.length; i += 1) {
+    if (input?.isDown(LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS[i]) === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function getOverlayRuntimeToggleInputCodes() {
+  return [LEVEL17_OVERLAY_CYCLE_KEY, LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS[0]];
+}
diff --git a/samples/phase-17/shared/overlayGameplayRuntime.js b/samples/phase-17/shared/overlayGameplayRuntime.js
diff --git a/tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs b/tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs
