Files
Neutron/docs/debug-menu.md
T

181 lines
11 KiB
Markdown

# 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 |
| F3 | Toggle noclip |
| Tab | Cycle General, Player and Systems pages |
| Up/Down | Select a row |
| Left/Right | Change selected level, startpoint, staged SCENE, flight speed or jetpack state |
| 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.
## Player and Systems pages
The General page retains the existing actions. Player adds noclip, staged flight
speeds300/600/1200/2400 (Enter applies), clear motion/queued jump, reopen objective,
return to noclip entry, apply source level gadget availability, toggle input after
player, staged jetpack states0/1/4 with a separate Apply row, and energy refill.
State0 means unowned,1 enabled and4 disabled by the level. These controls expose
the current implementation; they are not proof of complete original behavior.
Systems adds the route static camera query toggle, independent music/speech/effects
mutes, restart selected music, stop all effects/loops, checkpoint save/load and the
practice prompt. Camera query control is available on LV1B/VR04/LEV1; elsewhere
it reports unavailable. Audio actions require scene audio (not headless/--mute).
Muting sets stream gain while playback clocks continue; new streams inherit mute.
F1 still pauses all stream clocks. Audio mute preferences reset with the scene.
Input-order override is for comparison; a new scene restores the continuation policy.
The practice action opens the existing prompt and closes F1.
Player diagnostics include velocity, pending impulse, movement mode/input order,
jump/hold/burst timers, jetpack state and objective time. Systems shows camera
polygon/query counts, category mute flags and queued audio bytes. Staged values
are separate from live values. `--debug-page general|player|systems` opens a page.
## Noclip (F3)
A modern investigation mode, enabled from F3 or Player/Noclip (`--noclip` at startup).
W/S or Up/Down move forward/back; A/D strafe; Left/Right turn. Space/E rises,
Ctrl/Q descends, Shift triples speed. Diagonal motion is normalized. Release stops
flight immediately. Gravity, body collision, camera obstruction, jetpack consumption
and contact-triggered script/pickup/mechanism/level actions are bypassed. Script,
actor and mechanism clocks still run; unrelated scripted transitions can still occur.
Flight uses the player camera during cutscenes without changing authored control
ownership. Space rises without skipping a cutscene while flying; Escape keeps its
normal skip action. F1 pauses flight. Toggle boundaries clear queued motion and
capture held input until release, so Space/Shift cannot become a jump on exit.
Reset and level changes clear noclip; it is never written into TSK saves.
Enabling remembers position/yaw. Return Noclip Entry restores them and clears
motion. Disabling retains the new position if the current static capsule adapter
accepts it, otherwise returns to entry. This checks static triangle proximity, not
full solid containment or moving objects; use Return Entry or reset if needed.
Normal gravity/collision resumes when disabled.
## Debug checkpoint
Save writes `debug-checkpoint.tsk` beside the executable using the existing original
TSK encoder and a temporary file replacement. It captures tasks, items, energy,
score, level/start and the existing RETURN departure vector; it does **not** capture
live Jimmy position, cutscene time, physics or debug preferences. Save errors appear
in the menu. Load validates the available prepared scene/start/support and uses the
normal scene rebuild, preserving the application window and renderer. Authored
start actions run normally. A load/reset clears force-control and noclip.
These are explicitly requested modern tools, a scoped exception to the gameplay
feature pause; no original debug-menu or noclip algorithm is claimed.
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/noclip; 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.
Expansion verification (2026-10-25): full `scripts/test.sh` passes, including70
Python checks,21 movement groups, debug pages and real SDL dummy pause/mute clocks;
539 originals remain unchanged. Native Linux GTX1070 at1920x1080 passes
`--smoke-debug-tools`: F1/Tab, cutscene flight without force-control, F3 repeats,
held-input capture, camera/audio actions, TSK save/load and retained window.
Validation enabled, zero errors. Headless Player1920x1080 and Systems2560x1080
captures fit the existing uniform canvas. Logs/captures: artifacts/debug-expansion/.
No new native Windows runtime verification is claimed.