Files
Neutron/docs/debug-menu.md
T

6.8 KiB

Debug menu and live overlay

User-requested modern investigation tools, separate from recovered original UI. F1 works in the game, during cutscenes and practice prompts, and in scene inspection. Opening the menu pauses player simulation, actors, mechanisms, cutscene clocks and audio. Closing resumes the previous mode. No new assets or dependencies are needed.

Key Action
F1 Open/close
F2 Toggle live diagnostics without pausing
Up/Down Select a row
Left/Right Change selected level, startpoint or staged SCENE task value
Page Up/Down Change staged SCENE value by10
Enter / numpad Enter Apply the selected action
Escape Close the menu

Actions: resume, switch gameplay/orbit camera, skip the current cutscene, refill energy to100, give/select the jet pack, apply SCENE, load selected level/start and reset the current start. SCENE is staged until Enter, bounded0..999; it updates the existing task system and its callbacks. Inventory/energy/task actions affect current runtime state and its normal checkpoint snapshots; they do not write files by themselves. Debug tools do not imply reconstructed progression or full gameplay.

Force Control toggles a persistent debug override. Set it to TRUE and close the menu to let Jimmy move even while a cutscene or scripted control lock is active. Subsequent camera shots cannot clear the override. The cutscene, camera and audio continue normally; Skip Current Cutscene remains available separately. Toggling back to FALSE exposes the current scripted ownership. Reset or loading another scene clears the override; it is not written into original TSK saves.

The level picker offers only supplied GAMs with prepared geometry, a player and original STRT records. It currently offers33 scenes; Level3B/E are absent because their registered geometry is unavailable. No substitute geometry is supplied. Load checks terrain support at the chosen start before requesting a scene rebuild. Task/inventory/score state carries through the existing transition path. Source start triggers run normally; use Skip Current Cutscene when needed. Unsupported scene classes and remaining physics/render limitations are unchanged.

Diagnostics show level/start, original actor root XYZ, yaw, speed, grounded state, energy, score, SCENE, control, current cutscene, director issue count, far plane and camera mode. Values describe the paused live scene, independently of staged level/start/task choices.

The menu captures keyboard and mouse input before gameplay/practice handling. Held keys stay captured until release after closing; repeated Escape cannot quit the game through the menu. F1 repeats do not toggle it repeatedly. Input clocks reset at both boundaries so paused wall time does not become simulation backlog.

Implementation: Application/DebugMenu.cs owns selection/staged values; DebugMenuOverlay.cs appends bounded screen-space glyph quads after the HUD. The generated5x7 font uses the existing Vulkan overlay pipeline and fixed buffers. SdlAudio/SceneAudio pause all stream categories, including replacements created while paused. The original assets and original HUD extraction are unchanged.

Checks: DebugMenuTests covers navigation/repeat/staged edits and original scene coverage; DebugOverlayTests covers composition/visibility/bounds; AudioPauseTests uses actual SDL dummy-device queues to verify freeze/resume for all stream types. --debug-menu opens the menu immediately, including headless captures. --smoke-debug-menu runs a16-frame window test: open during a source MCA, pause, skip/refill/grant/apply task, close with held/repeated input, resume and resize. It also enables Force Control through the menu and verifies actual movement while Carl's MCA is still playing. Director checks cover disabling the override, shot changes, scene reset and the normal completion music handoff.

Live diagnostics (F2)

F2 toggles a compact panel in the upper-left corner while gameplay, cutscenes and audio continue. The F1 menu also offers Live Overlay; opening F1 replaces the live panel temporarily, preserving its setting. F2 works while F1 or practice is open without changing their pause state. Visibility persists through resets and scene loads within the process; it is not stored in TSK. --debug-overlay starts enabled.

Twelve bounded rows show measured FPS/frame milliseconds; level/start; root XYZ; velocity XYZ; yaw/speed/turn rate; ground/pose/energy; control/force/pause; SCENE/ score/jetpack state and burst timer; actual camera mode/far plane; cutscene/shot/ blocked state; movement counters; and reported issue/Vulkan-error/frame counts. STRT, orbit, gameplay and cutscene modes use the actual rendered view selection; orbit reports its own radius-derived far plane. A paused player/control lock is separate from pausing the whole simulation.

Timing measures rendered-loop wall intervals, including rendering/presentation, independently of the simulation clock. It shows an initial running mean, then publishes half-second window averages. Text uses the preceding timing sample; the first frame has no measurement yet. This is frame timing, not GPU profiling. Timing continues while hidden so enabling the panel has current samples. Motion fields describe the player simulation; standalone mesh inspection has no running player and displays zero/default motion values.

DebugDiagnostics is read-only and retains timing/visibility across scene rebuilds. DebugMenuOverlay reuses the existing font and fixed vertex ranges with a smaller, content-sized panel. Gameplay state, pause policy and original HUD stay separate. There are no added assets or dependencies.

DebugDiagnosticsTests verifies timing, finite zero/invalid cases, live snapshots, camera selection, culture-independent formatting and label bounds. The24-frame --smoke-debug-overlay SDL check verifies F2/repeat handling, movement without pause, hide/show, F1 priority, visibility preference, menu action and800x600 resize. Native Linux evidence: artifacts/live-debug-window.log; zero Vulkan validation errors. The existing F1/force-control SDL check also passes. Full regression and cross-scene results are in progress.md; no new Windows runtime check is claimed. The headless lab/VR04/lab check preserves enabled state and frame samples1/2/3, with zero Vulkan errors (artifacts/live-debug-return.log).

Native Linux GTX1070 window test passes with zero Vulkan validation errors: artifacts/debug-window.log. GPU screenshots debug-menu.png and debug-window.open.ppm show the menu. Source/build/regression evidence does not constitute new native Windows verification. Full regression and package status is in progress.md.

Debug text scales uniformly with resolution. F1 uses a centered authored canvas on widescreen; F2 stays top-left. The window/device survive level changes. See presentation-and-ui.md for lifecycle, ultrawide and high-DPI pointer checks.