186 lines
11 KiB
Markdown
186 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, 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.
|
|
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.
|