13 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 |
| 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
Give/Select Scooter grants item4 and summons the live vehicle at Goddard in VR05 or outside LEV1. Walk into it to mount; selecting alone leaves Jimmy free. The normal owned gadget tile works outside too. Header diagnostics report OFF/PARK/RIDE, speed and front/rear supported wheel counts. Tab/Space unequips; F3/reset releases vehicle control and sound. The Player page remains32 rows.
Player includes Give All Gadgets, which sets all eight gadget tiles to owned and available in the current scene. It preserves the equipped gadget and other inventory entries. Normal level-load availability rules still apply afterward. Give/Select Rocketship equips the live vehicle in VR02; elsewhere it grants the tile for Practice entry. Its speed, vertical velocity and contact count appear in the Player header. The complete page still fits32 rows and scales uniformly. While mounted, Enter/T turns180degrees and R barrel rolls; Tab/Space unequips. Force Control continues to drive the mounted pilot without changing authored ownership; enabling noclip releases the ship and engine before flying Jimmy.
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, energy refill, Give/Select Invisible and Unequip Current Gadget. Invisible obeys its source energy/recharge gates; a grant is not instant activation. The header shows remaining time, recharge and targetability. Full enemy sensing is not implied. Give/Select Bubble uses the implemented mode2 controller, while Unequip starts its original fade. Diagnostics show Bubble phase and source radius/factor. Give/Select Baseball grants item6 and shows aim/pending/throw diagnostics. Hold primary fire and use Up/Down to aim; release to throw. Cleanup preserves its source pending latch and existing flying balls. See gameplay/baseball-implementation.md. State0 means unowned,1 enabled and4 disabled by the level. The full availability action re-enables the matching VR practice gadget and applies LV1B restrictions on gadgets1/7 after the common prefix. Other level-specific tails remain incomplete. 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.