Files
Neutron/docs/debug-menu.md
T

4.1 KiB

F1 debug menu

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
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.

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.