Files
Neutron/docs/debug-menu.md
T

69 lines
4.1 KiB
Markdown

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