diff --git a/README.md b/README.md
index bd4d047..d3e3a7a 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,13 @@ ordinary play. Use `--skip-intro` to begin with control or `--mute` for silent p
The lab camera sequence stops background music and DEFAULT restarts it when
control returns, including after skipping.
+**F1** opens the debug menu and pauses gameplay and audio. Use Up/Down to select,
+Left/Right to change values, Enter to apply, and F1/Escape to close. It includes
+live diagnostics, camera switching, cutscene skip, energy refill, jet-pack grant,
+SCENE task editing, all 33 prepared levels and their original startpoints, and
+reset. Page Up/Down changes the staged SCENE value by 10. See
+[debug menu controls](docs/debug-menu.md).
+
The original lab pickup is internally tagged `shrinkray`; the original objective
art identifies it as the **jet pack**. Its practice prompt accepts **Y** or a click
on Yes to enter VR04, and **N** or a click on No to resume. Enter selects the
diff --git a/docs/architecture.md b/docs/architecture.md
index 69b117f..3da15c1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -148,3 +148,11 @@ MeshPolygonSource obtains shape names from prepared mesh records. Its recovered
NC-prefix terrain eligibility is consumed by SceneCollision and OriginalScenePhysics
support/wall queries; rendering and raw source triangles remain unchanged. Other
collision masks and the modern narrowphase remain explicit fidelity limits.
+
+DebugMenu is an intentional modern tool, separate from original UI/gameplay.
+Its staged selection emits commands into the existing task/inventory/director/
+transition consumers. DebugMenuOverlay appends fixed glyph/batch ranges last;
+all composers still update the final mesh and the renderer uploads the changed
+vertices even in static inspection. F1 owns input before practice/gameplay, pauses
+simulation and all audio streams, resets the clock at both boundaries and retains
+captured keys until release. Audio streams created during pause inherit that state.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index e557b0b..d77c78f 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -23,6 +23,7 @@ separate evidence categories. **The game is not fully reconstructed/playable yet
| Null-material visibility | Binary rule implemented/tested | Original DX renderer skips null pointers; proxy geometry retained |
| SDL3 presentation/input | Linux Xvfb + GTX1070 | Six frames; injected keyboard event received |
| Swapchain resize | Linux tested | 960x720 ->800x600, zero validation errors |
+| F1 debug menu | Managed/SDL audio tests + native Linux GTX1070 window pass |Pause/actions/input capture/resume/800x600 resize, zero validation errors;33 prepared scene/start choices; intentional modern tools, no new Windows runtime claim |
| Focus / fullscreen | Code present, partial/unverified | Focus clears keys; fullscreen toggle not dynamically tested |
| Mouse/relative input/controller | Incomplete | SDL entry point declaration alone is not behavior |
| Audio stream | Linux dummy device | Original11025Hz mono WAV consumed10752bytes/500ms; speakers untested |
@@ -77,6 +78,12 @@ exclusion fixes the underground water-plane rise while retaining rendering.
Both Linux x64 and Windows x64 self-contained executables republish successfully.
No subsequent native Windows/Wine runtime check is claimed.
+F1 menu checkpoint: artifacts/debug-menu-full-tests.log passes the full suite,
+including actual SDL audio pause/resume and539 unchanged originals. Native Linux
+window/input/action/resize evidence is artifacts/debug-window.log; screenshots
+were visually inspected. Both Linux and Windows self-contained packages publish
+successfully. No new Windows/Wine runtime check was run for this addition.
+
Known visual/behavior limits include incomplete lighting/fog/blend/culling/material
mapping, inferred model/root pivot, provisional collision/cadence/animation timing,
close-wall camera clipping near Jimmy, incomplete class-specific triggers/interactions,
diff --git a/docs/debug-menu.md b/docs/debug-menu.md
new file mode 100644
index 0000000..ac2713a
--- /dev/null
+++ b/docs/debug-menu.md
@@ -0,0 +1,58 @@
+# 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.
+
+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.
+
+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.
diff --git a/docs/decisions.md b/docs/decisions.md
index a70a1be..6e6f416 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -79,3 +79,8 @@
NC-prefixed shape names. Use prepared shape metadata for player and actor
terrain queries; retain rendered geometry and null-material proxies. Do not
infer a generic water-material rule or full water gameplay from this finding.
+19. **Keep user-requested debug tools explicit.** F1 opens a modern diagnostic menu
+ with code-generated glyphs, separate from recovered UI assets. Pause gameplay
+ and audio together, capture held input until release and stage SCENE edits until
+ Enter. Invoke existing source-state consumers for actions; offer only prepared
+ geometry and source startpoints. No debug behavior is attributed to the original.
diff --git a/docs/progress.md b/docs/progress.md
index caafeda..e5186a2 100644
--- a/docs/progress.md
+++ b/docs/progress.md
@@ -4,6 +4,23 @@
user-verified Windows rendering checkpoint into an interactive original lab and
jet pack tutorial flow. This is not a verified faithful complete scene or release.
+## User-requested F1 debug menu
+
+F1 opens a modern debug overlay with live player/scene/task diagnostics. Keyboard
+actions cover camera, cutscene skip, energy refill, jet-pack grant, staged SCENE
+editing,33 prepared levels/original starts, reset and resume. Gameplay, cutscene
+clocks and SDL audio pause while open; input is captured through release after
+closing. No new asset/dependency or original-game behavior is claimed.
+
+Targeted menu/overlay and actual SDL pause tests pass. Native Linux GTX1070
+16-frame SDL test passes pause, actions, Escape/held-input capture, resume and
+800x600 resize with zero Vulkan validation errors (artifacts/debug-window.log).
+Headless menu GPU readback was visually inspected. Complete scripts/test.sh passes,
+including41 Python checks, all managed/gameplay/GPU/audio regressions and539
+unchanged original hashes (artifacts/debug-menu-full-tests.log). Both platform
+executables are republished successfully. No new Windows/Wine runtime check was run,
+consistent with the user's earlier preference. See debug-menu.md.
+
## RETURN placement and underground passage
Recovered and integrated the next lab checkpoint:
diff --git a/docs/tasks.md b/docs/tasks.md
index 02e8a2a..efd67e5 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -29,6 +29,8 @@ compile, runtime and original-fidelity verification are separate.
- [x] Source RETURN departure-root/TSK identity, player/companion restoration and
one-time STRT suppression; source NC-shape terrain exclusion; input-only
underground passage both ways from explicit riverlab/SCENE65 fixture.
+- [x] User-requested F1 debug menu with diagnostics, paused audio/gameplay,
+ camera/cutscene/energy/jetpack/task/scene/start/reset controls and input capture.
## Immediate continuation
diff --git a/scripts/package.sh b/scripts/package.sh
index c738760..fa729f6 100755
--- a/scripts/package.sh
+++ b/scripts/package.sh
@@ -46,6 +46,9 @@ to save GPU readback. A Vulkan 1.3 graphics driver/loader is required.
This package includes the .NET runtime, SDL3, shaders and local asset copies.
The default opens the controllable original lab. Arrows walk/backpedal/turn;
Shift, Insert, numpad 0 or right mouse jump. R resets to the original start area;
+F1 opens debug tools: arrows navigate/change, Enter applies, F1/Escape closes.
+The menu pauses gameplay/audio and provides diagnostics, camera/cutscene controls,
+energy/jetpack/task changes, level/start selection and reset.
C pauses into inspection and resumes the chase camera. F11 fullscreen, Escape quit.
Inspection: arrows/WASD orbit, +/- zoom, 1 idle, 2 run, 3 jump, 4 scratch preview.
Append --inspect to start directly in the old scene inspector.
diff --git a/scripts/test.sh b/scripts/test.sh
index b638c00..ad910a3 100755
--- a/scripts/test.sh
+++ b/scripts/test.sh
@@ -11,6 +11,9 @@ dotnet run --project tests/GamePort.PatrolTests -- ../Original
dotnet run --project tests/GamePort.SupportTests -- ../Original
dotnet run --project tests/GamePort.InteractionTests -- ../Original
dotnet run --project tests/GamePort.CheckpointTests -- ../Original
+dotnet run --project tests/GamePort.DebugMenuTests -- ../Original
+dotnet run --project tests/GamePort.DebugOverlayTests
+SDL_AUDIODRIVER=dummy dotnet run --project tests/GamePort.AudioPauseTests
dotnet run --project tests/GamePort.LabRouteTests -- ../Original
dotnet run --project tests/GamePort.UndergroundRouteTests -- ../Original
dotnet run --project tests/GamePort.DynamicCollisionTests -- ../Original
@@ -29,6 +32,7 @@ dotnet run --no-build -- --headless --story --story-time 12 --screenshot artifac
dotnet run --no-build -- --headless --story --smoke-practice-prompt --screenshot artifacts/test-practice.ppm
dotnet run --no-build -- --headless --story --smoke-practice-transition
dotnet run --no-build -- --headless --smoke-practice-return --screenshot artifacts/test-practice-return.ppm
+dotnet run --no-build -- --headless --debug-menu --screenshot artifacts/test-debug-menu.ppm
dotnet run --no-build -- --headless --story --smoke-lab-route
dotnet run --no-build -- --headless --smoke-carl-cutscene --frames 60 --screenshot artifacts/test-carl-cutscene.ppm
dotnet run --no-build -- --headless --smoke-objective-panel --story-time 1 --screenshot artifacts/test-objective-visible.ppm
@@ -50,6 +54,7 @@ SDL_AUDIODRIVER=dummy dotnet run --no-build -- --scene-audio-smoke artifacts/ext
SDL_AUDIODRIVER=dummy dotnet run --no-build -- --cutscene-audio-smoke artifacts/extracted/level1b/entities/entities.json
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
if [[ "${NEUTRON_WINDOW_TEST:-0}" == 1 ]]; then
+ dotnet run --no-build -- --smoke-debug-menu --screenshot artifacts/test-debug-window.ppm
dotnet run --no-build -- --smoke-objective-window --screenshot artifacts/test-objective-window.ppm
dotnet run --no-build -- --scene artifacts/extracted/VR04/scene.json --level gam/VR04.gam --smoke-jetpack --screenshot artifacts/test-jetpack-window.ppm
dotnet run --no-build -- --smoke-practice-window --frames 12 --screenshot artifacts/test-practice-window.ppm
diff --git a/src/GamePort/Application/DebugMenu.cs b/src/GamePort/Application/DebugMenu.cs
new file mode 100644
index 0000000..18912d5
--- /dev/null
+++ b/src/GamePort/Application/DebugMenu.cs
@@ -0,0 +1,120 @@
+using System.Globalization;
+using System.Numerics;
+using GamePort.Assets;
+
+namespace GamePort.Application;
+
+public sealed record DebugScene(string LevelFile, string Code, string[] Starts);
+public enum DebugAction { None, Resume, Camera, SkipCutscene, RefillEnergy, GiveJetpack, ApplySceneTask, LoadScene, Reset }
+public sealed record DebugMenuView(string[] Lines, int SelectedLine);
+public sealed record DebugStatus(string Level, string Start, Vector3 Root, float Yaw, float Speed,
+ bool Grounded, float Energy, int Score, int SceneTask, string Cutscene, bool Controlled,
+ int Issues, float FarPlane, bool Inspecting);
+
+/// Modern investigation tools, deliberately separate from recovered game UI.
+public sealed class DebugMenu
+{
+ public const uint ToggleKey = 58; // SDL scancode F1; F11 remains fullscreen.
+ public const int ItemCount = 10;
+ public bool Open { get; private set; }
+ public int Selected { get; private set; }
+ public int SceneTask { get; private set; }
+ public string Message { get; set; } = "";
+ private readonly DebugScene[] scenes;
+ private int sceneIndex, startIndex;
+ public DebugScene? Scene => scenes.Length == 0 ? null : scenes[sceneIndex];
+ public string? Start => Scene is { } scene ? scene.Starts[startIndex] : null;
+
+ public DebugMenu(IEnumerable scenes, string? currentLevel, string? currentStart)
+ {
+ this.scenes = scenes.ToArray();
+ if (this.scenes.Any(s => s.Starts.Length == 0)) throw new ArgumentException("Debug scenes require a startpoint");
+ sceneIndex = Math.Max(0, Array.FindIndex(this.scenes,
+ s => string.Equals(s.LevelFile, currentLevel, StringComparison.OrdinalIgnoreCase)));
+ if (Scene is { } selected)
+ startIndex = Math.Max(0, Array.FindIndex(selected.Starts,
+ s => string.Equals(s, currentStart, StringComparison.OrdinalIgnoreCase)));
+ }
+
+ public void Toggle(int currentSceneTask)
+ {
+ Open = !Open;
+ if (Open) { SceneTask = currentSceneTask; Message = ""; }
+ }
+ public void Close() => Open = false;
+
+ public DebugAction Key(uint scancode, bool repeat = false)
+ {
+ if (!Open) return DebugAction.None;
+ if (scancode == 41) { Close(); return DebugAction.None; }
+ if (scancode is 82 or 81)
+ Selected = (Selected + (scancode == 82 ? ItemCount - 1 : 1)) % ItemCount;
+ else if (scancode is 80 or 79 or 75 or 78)
+ {
+ var direction = scancode is 80 or 78 ? -1 : 1;
+ if (Selected == 5)
+ SceneTask = (int)Math.Clamp((long)SceneTask + direction * (scancode is 75 or 78 ? 10 : 1), 0, 999);
+ else if (Selected == 6 && scenes.Length > 0)
+ { sceneIndex = (sceneIndex + scenes.Length + direction) % scenes.Length; startIndex = 0; }
+ else if (Selected == 7 && Scene is { } scene)
+ startIndex = (startIndex + scene.Starts.Length + direction) % scene.Starts.Length;
+ }
+ else if (scancode is 40 or 88 && !repeat)
+ return Selected switch
+ {
+ 0 => DebugAction.Resume, 1 => DebugAction.Camera, 2 => DebugAction.SkipCutscene,
+ 3 => DebugAction.RefillEnergy, 4 => DebugAction.GiveJetpack, 5 => DebugAction.ApplySceneTask,
+ 8 => Scene == null ? DebugAction.None : DebugAction.LoadScene, 9 => DebugAction.Reset,
+ _ => DebugAction.None
+ };
+ return DebugAction.None;
+ }
+
+ public DebugMenuView View(DebugStatus status)
+ {
+ if (!Open) return new([], -1);
+ var c = CultureInfo.InvariantCulture;
+ string F(float value) => value.ToString("0.0", c);
+ return new([
+ "NEUTRON DEBUG MENU - F1",
+ "PAUSED - MODERN DEBUG TOOLS",
+ $"LEVEL {status.Level} / START {status.Start}",
+ $"ROOT X {F(status.Root.X)} Y {F(status.Root.Y)} Z {F(status.Root.Z)}",
+ $"YAW {F(status.Yaw)} SPEED {F(status.Speed)} GROUNDED {status.Grounded}",
+ $"ENERGY {F(status.Energy)} SCORE {status.Score} SCENE {status.SceneTask}",
+ $"CONTROL {status.Controlled} CUTSCENE {status.Cutscene}",
+ $"ISSUES {status.Issues} FAR {F(status.FarPlane)} CAMERA {(status.Inspecting ? "ORBIT" : "GAMEPLAY")}",
+ "",
+ "RESUME",
+ $"CAMERA: {(status.Inspecting ? "SWITCH TO GAMEPLAY" : "SWITCH TO ORBIT")}",
+ "SKIP CURRENT CUTSCENE",
+ "REFILL ENERGY TO 100",
+ "GIVE / SELECT JET PACK",
+ $"SCENE TASK: {SceneTask} (ENTER APPLIES)",
+ $"LEVEL: {Scene?.LevelFile ?? "UNAVAILABLE"}",
+ $"START: {Start ?? "UNAVAILABLE"}",
+ "LOAD SELECTED LEVEL / START",
+ "RESET CURRENT START",
+ "",
+ "UP/DOWN SELECT LEFT/RIGHT CHANGE ENTER APPLY",
+ "SCENE TASK: PAGE UP/DOWN CHANGES BY 10",
+ "F1 / ESC CLOSE - GAME INPUT IS CAPTURED WHILE OPEN",
+ Message
+ ], 9 + Selected);
+ }
+
+ public static DebugScene[] AvailableScenes(string assets, string prepared)
+ {
+ var scenes = new List();
+ foreach (var path in Directory.EnumerateFiles(AssetPath.Resolve(assets, "gam"))
+ .Where(p => p.EndsWith(".gam", StringComparison.OrdinalIgnoreCase)).OrderBy(Path.GetFileName, StringComparer.OrdinalIgnoreCase))
+ {
+ try { AssetPath.Resolve(prepared, Path.GetFileNameWithoutExtension(path) + "/scene.json"); }
+ catch (FileNotFoundException) { continue; }
+ var level = GamLevel.Load(path);
+ var starts = level.Entities.Where(e => e.Kind == "STRT" && e.Tag is { Length: > 0 }).Select(e => e.Tag!).ToArray();
+ if (level.Player != null && starts.Length > 0) scenes.Add(new(Path.GetFileName(path), level.Code, starts));
+ }
+ return scenes.ToArray();
+ }
+}
diff --git a/src/GamePort/Application/DebugMenuOverlay.cs b/src/GamePort/Application/DebugMenuOverlay.cs
new file mode 100644
index 0000000..c7970c2
--- /dev/null
+++ b/src/GamePort/Application/DebugMenuOverlay.cs
@@ -0,0 +1,164 @@
+using System.Numerics;
+using GamePort.Assets;
+
+namespace GamePort.Application;
+
+///
+/// Modern developer overlay, separate from recovered game UI. Uses a code-built
+/// 5x7 font and the existing alpha-tested screen-space pipeline; no asset files.
+/// Allocate once before renderer creation, then update the final merged mesh.
+///
+public sealed class DebugMenuOverlay
+{
+ public const int MaxLines = 32;
+ public const int MaxColumns = 76;
+ private const float LineHeight = 13;
+ private const float CharacterAdvance = 7.5f;
+ private const int AtlasWidth = 128, AtlasHeight = 64;
+ private readonly int firstVertex;
+ private readonly uint firstIndex;
+ private readonly int textureId;
+ public Mesh Mesh { get; }
+
+ public DebugMenuOverlay(Mesh combined)
+ {
+ ArgumentNullException.ThrowIfNull(combined);
+ firstVertex = combined.Vertices.Length;
+ firstIndex = (uint)combined.Indices.Length;
+ var vertices = combined.Vertices.ToList();
+ var indices = combined.Indices.ToList();
+ var draws = combined.Draws.ToList();
+ if (!combined.HasExplicitDraws && draws.Count == 0 && indices.Count > 0)
+ draws.Add(new(0, (uint)indices.Count, -1));
+ var textures = new Dictionary(combined.Textures);
+ textureId = int.MinValue;
+ while (textures.ContainsKey(textureId)) textureId++;
+ textures.Add(textureId, CreateFont());
+ // Two solid quads precede a fixed range for each text row. Keeping the
+ // ranges fixed means the Vulkan vertex/index buffers never need resizing.
+ AddRange(1);
+ AddRange(1);
+ for (var row = 0; row < MaxLines; row++) AddRange(MaxColumns);
+ Mesh = new(vertices.ToArray(), indices.ToArray())
+ {
+ Draws = draws.ToArray(), HasExplicitDraws = true,
+ Textures = textures, CollisionPolygons = combined.CollisionPolygons
+ };
+
+ void AddRange(int quads)
+ {
+ var start = (uint)indices.Count;
+ for (var i = 0; i < quads; i++)
+ {
+ var vertex = (uint)vertices.Count;
+ for (var corner = 0; corner < 4; corner++) vertices.Add(new(Vector3.Zero, Vector2.Zero, Vector3.One));
+ indices.AddRange([vertex, vertex + 1, vertex + 2, vertex, vertex + 2, vertex + 3]);
+ }
+ draws.Add(new(start, (uint)quads * 6, textureId) { ScreenSpace = true, Visible = false });
+ }
+ }
+
+ ///
+ /// Empty lines hide all overlay draws. Accepts at most32 lines; individual
+ /// lines clip at76 characters. selectedLine is -1 or an index into lines.
+ /// Lowercase renders as uppercase, unsupported characters as question marks.
+ /// Layout uses the same640x480 reference viewport as the original HUD.
+ ///
+ public void Update(Mesh destination, IReadOnlyList lines, int selectedLine = -1)
+ {
+ ArgumentNullException.ThrowIfNull(destination);
+ ArgumentNullException.ThrowIfNull(lines);
+ if (lines.Count > MaxLines) throw new ArgumentOutOfRangeException(nameof(lines));
+ if (selectedLine < -1 || selectedLine >= lines.Count) throw new ArgumentOutOfRangeException(nameof(selectedLine));
+ if (destination.Vertices.Length < Mesh.Vertices.Length || destination.Indices.Length < Mesh.Indices.Length)
+ throw new ArgumentException("Destination omits debug overlay ranges", nameof(destination));
+ var background = FindDraw(firstIndex, 6);
+ var highlight = FindDraw(firstIndex + 6, 6);
+ background.Visible = lines.Count > 0;
+ highlight.Visible = selectedLine >= 0;
+ var solid = new Vector2(127.5f / AtlasWidth, 63.5f / AtlasHeight);
+ Quad(firstVertex, 18, 18, 604, Math.Clamp(lines.Count * LineHeight + 24, 80, 444), solid, solid, new(.025f, .04f, .07f));
+ Quad(firstVertex + 4, 25, 27 + selectedLine * LineHeight, 590, LineHeight,
+ solid, solid, new(.07f, .24f, .33f));
+ for (var row = 0; row < MaxLines; row++)
+ {
+ var draw = FindDraw(firstIndex + 12 + (uint)(row * MaxColumns * 6), MaxColumns * 6);
+ draw.Visible = row < lines.Count;
+ if (!draw.Visible) continue;
+ var line = lines[row] ?? "";
+ var color = row == 0 ? new Vector3(1, .83f, .35f) : new(.85f, .93f, .98f);
+ for (var column = 0; column < MaxColumns; column++)
+ {
+ var character = column < line.Length ? char.ToUpperInvariant(line[column]) : ' ';
+ if (character is < ' ' or > '~') character = '?';
+ var cell = character - ' ';
+ var x = cell % 16 * 8 + 1;
+ var y = cell / 16 * 8;
+ Quad(firstVertex + 8 + (row * MaxColumns + column) * 4,
+ 30 + column * CharacterAdvance, 30 + row * LineHeight, 7, 9.8f,
+ new((float)x / AtlasWidth, (float)y / AtlasHeight),
+ new((x + 5f) / AtlasWidth, (y + 7f) / AtlasHeight), color);
+ }
+ }
+
+ MeshDraw FindDraw(uint start, uint count) => destination.Draws.FirstOrDefault(d =>
+ d.FirstIndex == start && d.IndexCount == count && d.TextureId == textureId && d.ScreenSpace)
+ ?? throw new ArgumentException("Destination omits debug overlay draws", nameof(destination));
+
+ void Quad(int start, float x, float y, float width, float height, Vector2 minUv, Vector2 maxUv, Vector3 color)
+ {
+ destination.Vertices[start] = new(Position(x, y), minUv, color);
+ destination.Vertices[start + 1] = new(Position(x + width, y), new(maxUv.X, minUv.Y), color);
+ destination.Vertices[start + 2] = new(Position(x + width, y + height), maxUv, color);
+ destination.Vertices[start + 3] = new(Position(x, y + height), new(minUv.X, maxUv.Y), color);
+ }
+ }
+
+ private static Vector3 Position(float x, float y) => new(2 * x / 640 - 1, 2 * y / 480 - 1, 0);
+
+ private static PngImage CreateFont()
+ {
+ // Seven rows of five bits per glyph. This intentionally simple developer
+ // font is generated from code, not a claim about the original font layout.
+ var glyphs = new Dictionary
+ {
+ ['A']="0E11111F111111", ['B']="1E11111E11111E", ['C']="0F10101010100F",
+ ['D']="1E11111111111E", ['E']="1F10101E10101F", ['F']="1F10101E101010",
+ ['G']="0F10101711110F", ['H']="1111111F111111", ['I']="1F04040404041F",
+ ['J']="0101010111110E", ['K']="11121418141211", ['L']="1010101010101F",
+ ['M']="111B1515111111", ['N']="11191513111111", ['O']="0E11111111110E",
+ ['P']="1E11111E101010", ['Q']="0E11111115120D", ['R']="1E11111E141211",
+ ['S']="0F10100E01011E", ['T']="1F040404040404", ['U']="1111111111110E",
+ ['V']="11111111110A04", ['W']="11111115151B11", ['X']="11110A040A1111",
+ ['Y']="11110A04040404", ['Z']="1F01020408101F",
+ ['0']="0E11131519110E", ['1']="040C040404040E", ['2']="0E11010204081F",
+ ['3']="1E01010E01011E", ['4']="02060A121F0202", ['5']="1F10101E01011E",
+ ['6']="0E10101E11110E", ['7']="1F010204080808", ['8']="0E11110E11110E",
+ ['9']="0E11110F01010E", [' ']="00000000000000", ['.']="00000000000C0C",
+ [',']="00000000000C08", [':']="000C0C000C0C00", [';']="000C0C000C0C08",
+ ['-']="0000001F000000", ['_']="0000000000001F", ['+']="0004041F040400",
+ ['=']="00001F001F0000", ['/']="01010204081010", ['\\']="10100804020101",
+ ['(']="02040808080402", [')']="08040202020408", ['[']="0E08080808080E",
+ [']']="0E02020202020E", ['<']="01020408040201", ['>']="10080402040810",
+ ['!']="04040404040004", ['?']="0E110102040004", ['#']="0A0A1F0A1F0A0A",
+ ['%']="19190204081313", ['*']="00150E1F0E1500", ['|']="04040404040404",
+ ['\'']="04040800000000", ['"']="0A0A1400000000", ['@']="0E11171517100E",
+ ['$']="040F140E051E04", ['&']="0C12140C15120D", ['^']="040A1100000000",
+ ['~']="00000D12000000", ['{']="02040408040402", ['}']="08040402040408",
+ ['`']="08040200000000"
+ };
+ var pixels = new byte[AtlasWidth * AtlasHeight * 4];
+ for (var i = 0; i < pixels.Length; i += 4) pixels[i] = pixels[i + 1] = pixels[i + 2] = 255;
+ for (var character = ' '; character <= '~'; character++)
+ {
+ var rows = Convert.FromHexString(glyphs.GetValueOrDefault(char.ToUpperInvariant(character), glyphs['?']));
+ var cell = character - ' ';
+ for (var y = 0; y < 7; y++)
+ for (var x = 0; x < 5; x++)
+ if ((rows[y] & (1 << (4 - x))) != 0)
+ pixels[((cell / 16 * 8 + y) * AtlasWidth + cell % 16 * 8 + 1 + x) * 4 + 3] = 255;
+ }
+ pixels[(AtlasWidth * AtlasHeight - 1) * 4 + 3] = 255;
+ return new(AtlasWidth, AtlasHeight, pixels);
+ }
+}
diff --git a/src/GamePort/Audio/SceneAudio.cs b/src/GamePort/Audio/SceneAudio.cs
index 3603211..5f20535 100644
--- a/src/GamePort/Audio/SceneAudio.cs
+++ b/src/GamePort/Audio/SceneAudio.cs
@@ -10,6 +10,7 @@ public sealed class SceneAudio : IDisposable
private (string Database, int Id)? selectedMusic;
private readonly List effects = [];
private readonly Dictionary loops = new(StringComparer.OrdinalIgnoreCase);
+ public bool Paused { get; private set; }
public int EffectCount => effects.Count;
public int LoopCount => loops.Count;
public int QueuedEffectBytes => effects.Sum(effect => effect.QueuedBytes) + loops.Values.Sum(effect => effect.QueuedBytes);
@@ -26,13 +27,13 @@ public sealed class SceneAudio : IDisposable
{
StopMusic();
if (selectedMusic is { } selection && resources.Wave(selection.Database, selection.Id) is { } wave)
- music = new(wave.Path, true);
+ music = new(wave.Path, true, Paused);
}
public void Speech(string database, int id)
{
StopSpeech();
var wave = resources.Wave(database, id) ?? throw new FileNotFoundException($"Missing prepared speech: {database}:{id}");
- speech = new(wave.Path);
+ speech = new(wave.Path, paused: Paused);
}
public void StopSpeech() { speech?.Dispose(); speech = null; }
// Default current bank set by Jimmy PostLoad423642..656; positional attenuation
@@ -41,11 +42,11 @@ public sealed class SceneAudio : IDisposable
{
var wave = resources.Wave("SoundEffects.omt", id)
?? throw new FileNotFoundException($"Missing original default sound effect {id}");
- if (loopOwner == null) effects.Add(new(wave.Path));
+ if (loopOwner == null) effects.Add(new(wave.Path, paused: Paused));
else
{
StopLoop(loopOwner);
- loops.Add(loopOwner, new(wave.Path, true));
+ loops.Add(loopOwner, new(wave.Path, true, Paused));
}
}
public void StopLoop(string owner)
@@ -60,10 +61,19 @@ public sealed class SceneAudio : IDisposable
}
public void Pump()
{
+ if (Paused) return;
music?.Pump(); speech?.Pump();
foreach (var effect in loops.Values) effect.Pump();
for (var i = effects.Count - 1; i >= 0; i--)
if (effects[i].QueuedBytes == 0) { effects[i].Dispose(); effects.RemoveAt(i); }
}
+ /// Modern debug pause; new streams also inherit this state.
+ public void SetPaused(bool paused)
+ {
+ music?.SetPaused(paused); speech?.SetPaused(paused);
+ foreach (var effect in effects) effect.SetPaused(paused);
+ foreach (var effect in loops.Values) effect.SetPaused(paused);
+ Paused = paused;
+ }
public void Dispose() { StopEffects(); StopSpeech(); StopMusic(); }
}
diff --git a/src/GamePort/Audio/SdlAudio.cs b/src/GamePort/Audio/SdlAudio.cs
index f6e2e77..2190296 100644
--- a/src/GamePort/Audio/SdlAudio.cs
+++ b/src/GamePort/Audio/SdlAudio.cs
@@ -9,6 +9,8 @@ public sealed class SdlAudio : IDisposable
private nint data;
private int length;
private readonly bool loop;
+ private bool audioInitialized;
+ public bool Paused { get; private set; }
public int QueuedBytes
{
get
@@ -17,10 +19,11 @@ public sealed class SdlAudio : IDisposable
return bytes >= 0 ? bytes : throw new InvalidOperationException(Sdl.Error);
}
}
- public SdlAudio(string path,bool loop=false)
+ public SdlAudio(string path,bool loop=false,bool paused=false)
{
this.loop=loop;
if(!Sdl.SDL_InitSubSystem(Sdl.InitAudio))throw new InvalidOperationException(Sdl.Error);
+ audioInitialized = true;
try
{
if(!Sdl.SDL_LoadWAV(Path.GetFullPath(path),out var spec,out data,out var size))throw new InvalidOperationException(Sdl.Error);
@@ -28,17 +31,28 @@ public sealed class SdlAudio : IDisposable
stream=Sdl.SDL_OpenAudioDeviceStream(uint.MaxValue,ref spec,0,0);
if(stream==0)throw new InvalidOperationException(Sdl.Error);
Queue();
- if(!Sdl.SDL_ResumeAudioStreamDevice(stream))throw new InvalidOperationException(Sdl.Error);
+ // SDL_OpenAudioDeviceStream starts paused. Keep it paused from its
+ // first sample when created while a debug menu has stopped playback.
+ Paused = true;
+ SetPaused(paused);
Console.WriteLine($"SDL3 WAV stream: {spec.Frequency} Hz, {spec.Channels} channel(s), {length} source bytes.");
}
catch{Dispose();throw;}
}
+ public void SetPaused(bool paused)
+ {
+ ObjectDisposedException.ThrowIf(stream == 0, this);
+ if (Paused == paused) return;
+ var changed = paused ? Sdl.SDL_PauseAudioStreamDevice(stream) : Sdl.SDL_ResumeAudioStreamDevice(stream);
+ if (!changed) throw new InvalidOperationException(Sdl.Error);
+ Paused = paused;
+ }
private void Queue(){if(!Sdl.SDL_PutAudioStreamData(stream,data,length))throw new InvalidOperationException(Sdl.Error);}
- public void Pump(){if(loop && QueuedBytes 3600 || storyTime > 0 && !headless)
throw new ArgumentException("Story time must be0..3600 seconds in headless mode.");
- var frames = int.Parse(Option(args, "--frames") ?? (walkSmoke ? "240" : jetpackSmoke ? "300" : objectiveWindowSmoke ? "180" : carlSmoke ? "60" : headless ? "1" : "0"));
+ var frames = int.Parse(Option(args, "--frames") ?? (walkSmoke ? "240" : jetpackSmoke ? "300" : objectiveWindowSmoke ? "180" : carlSmoke ? "60" : debugSmoke ? "16" : headless ? "1" : "0"));
+ if (debugSmoke && (headless || frames < 16 || director == null || level?.Code != "LV1B" || loadedSave != null || debugMenu.Open))
+ throw new ArgumentException("Debug SDL smoke requires fresh windowed LV1B, closed debug menu and at least16 frames");
if (objectiveWindowSmoke && (headless || frames < 180)) throw new ArgumentException("Objective window smoke needs180 window frames");
if ((carlSmoke || objectiveSmoke) && (level?.Code != "LV1B" || loadedSave != null || objectiveSmoke && !headless && !objectiveWindowSmoke))
throw new ArgumentException("Lab conversation/objective smoke requires fresh LV1B (objective check is headless)");
@@ -378,8 +391,9 @@ internal static class Program
{
using var renderer = new VulkanRenderer(mesh, texture, 960, 720, window, !args.Contains("--no-validation"));
using var audio = Option(args, "--audio") is { } audioFile
- ? new SdlAudio(audioFile, args.Contains("--loop-audio")) : null;
+ ? new SdlAudio(audioFile, args.Contains("--loop-audio"), debugMenu.Open) : null;
using var sceneAudio = resources != null && !headless && !args.Contains("--mute") ? new SceneAudio(resources) : null;
+ sceneAudio?.SetPaused(debugMenu.Open);
double initialPoseTime = 0;
if (director != null)
{
@@ -410,7 +424,7 @@ internal static class Program
Console.WriteLine($"Practice RETURN: exact saved root={restored}, root={simulation.ActorRoot}, STRT yaw={simulation.Yaw}, intro suppressed={!director.Playing}, companion restored={companionRestored}.");
if (!restored) throw new InvalidOperationException("RETURN did not restore the live departure root without replaying STRT actions");
}
- if (args.Contains("--skip-intro") || jetpackSmoke) { sceneAudio?.StopSpeech(); director.Skip(); }
+ if (args.Contains("--skip-intro") || jetpackSmoke || debugSmoke) { sceneAudio?.StopSpeech(); director.Skip(); }
if (practiceReturnSmoke && level.Code == "VR04")
{
director.Skip();
@@ -456,7 +470,7 @@ internal static class Program
if (!practice.Active) throw new InvalidOperationException("Original lab pickup did not open practice modal");
if (args.Contains("--smoke-practice-transition") || practiceReturnSmoke) practice.Key(28, Vector2.Zero);
}
- for (var tick = 0; tick < (int)Math.Round(storyTime * 60) && !practice.Active; tick++)
+ for (var tick = 0; tick < (int)Math.Round(storyTime * 60) && !practice.Active && !debugMenu.Open; tick++)
{
foreach (var patrol in patrols.Values) patrol.Step(FixedStepClock.Step);
mechanisms!.Step(FixedStepClock.Step);
@@ -469,6 +483,7 @@ internal static class Program
}
}
var keys = new HashSet();
+ var debugCapturedKeys = new HashSet();
var running = true;
var fullscreen = false;
var sawKey = false;
@@ -494,6 +509,65 @@ internal static class Program
double last = clock.Elapsed.TotalSeconds;
float angle = 0.6f, elevation = 0.32f;
var count = 0;
+ var debugPauseObserved = false;
+ var debugActionsObserved = false;
+ var debugEscapeObserved = false;
+ var debugResumeObserved = false;
+ var debugPausedRoot = simulation?.ActorRoot ?? Vector3.Zero;
+ var debugPausedSteps = simulation?.Steps ?? 0;
+ void ResetScene()
+ {
+ if (simulation == null) { debugMenu.Message = "RESET REQUIRES PLAY MODE"; return; }
+ if (practice.Active) practice.Key(17, Vector2.Zero);
+ simulation.Reset(); poseTime = 0; sceneAudio?.StopSpeech(); director?.Begin(originalStart!);
+ interactions?.Reset(); mechanisms?.Reset();
+ director?.SyncActor(level!.Player!.Tag!, simulation.ActorRoot, new Vector3(0, simulation.Yaw, 0));
+ }
+ void ToggleCamera()
+ {
+ if (originalStart == null) { debugMenu.Message = "CAMERA REQUIRES A SCENE START"; return; }
+ if (simulation == null) { originalCamera = !originalCamera; return; }
+ inspecting = !inspecting;
+ originalCamera = false; target = simulation.ActorRoot; radius = 600;
+ if (window != 0 && !Sdl.SDL_SetWindowTitle(window, inspecting ? animations!.WindowTitle : WalkTitle))
+ throw new InvalidOperationException(Sdl.Error);
+ }
+ void DebugInputBoundary()
+ {
+ debugCapturedKeys.UnionWith(keys);
+ keys.Clear(); mouseJump = false; stepClock.Reset(); last = clock.Elapsed.TotalSeconds;
+ audio?.SetPaused(debugMenu.Open); sceneAudio?.SetPaused(debugMenu.Open);
+ }
+ void DebugCommand(DebugAction action)
+ {
+ switch (action)
+ {
+ case DebugAction.Resume: debugMenu.Close(); break;
+ case DebugAction.Camera: ToggleCamera(); debugMenu.Close(); break;
+ case DebugAction.SkipCutscene:
+ if (director is { Controlled: false }) { sceneAudio?.StopSpeech(); director.Skip(); debugMenu.Message = "CUTSCENE SKIPPED"; }
+ else debugMenu.Message = "NO ACTIVE CUTSCENE";
+ break;
+ case DebugAction.RefillEnergy when simulation != null:
+ simulation.Energy = 100; interactions?.UpdateEnergy(100); debugMenu.Message = "ENERGY REFILLED"; break;
+ case DebugAction.GiveJetpack when interactions != null:
+ interactions.Inventory.SetState(0, 3, 1); interactions.Inventory.SelectGadget(3);
+ debugMenu.Message = "JET PACK GIVEN AND SELECTED"; break;
+ case DebugAction.ApplySceneTask when storyTasks != null:
+ storyTasks.SetExisting("SCENE", debugMenu.SceneTask); debugMenu.Message = $"SCENE TASK SET TO {debugMenu.SceneTask}"; break;
+ case DebugAction.LoadScene when simulation != null && interactions != null && debugMenu.Scene is { } selected:
+ var prepared = Path.GetFullPath(Path.Combine(Path.GetDirectoryName(scene!)!, ".."));
+ var selectedWorld = Mesh.LoadSceneJson(AssetPath.Resolve(prepared,
+ Path.GetFileNameWithoutExtension(selected.LevelFile) + "/scene.json"));
+ var selectedStart = GamLevel.Load(AssetPath.Resolve(root, "gam/" + selected.LevelFile)).FindStart(debugMenu.Start)!;
+ if (new SceneCollision(selectedWorld).GroundHeight(selectedStart.Position, 2500) == null)
+ { debugMenu.Message = "SELECTED START HAS NO SUPPORTED FLOOR"; break; }
+ RequestTransition(new(selected.LevelFile, debugMenu.Start!, 0, -1)); debugMenu.Close(); break;
+ case DebugAction.Reset: ResetScene(); debugMenu.Close(); break;
+ case DebugAction.None: break;
+ default: debugMenu.Message = "ACTION REQUIRES PLAY MODE"; break;
+ }
+ }
Vector2 Pointer()
{
Sdl.SDL_GetMouseState(out var x, out var y);
@@ -524,9 +598,27 @@ internal static class Program
if (e.Type is Sdl.Quit or 0x210) running = false;
if (e.Type is Sdl.WindowResized or Sdl.WindowPixelSizeChanged) renderer.Resize();
if (e.Type is Sdl.WindowFocusLost or Sdl.WindowMinimized)
- { keys.Clear(); mouseJump = false; active = false; stepClock.Reset(); }
+ { keys.Clear(); debugCapturedKeys.Clear(); mouseJump = false; active = false; stepClock.Reset(); }
if (e.Type is Sdl.WindowFocusGained or Sdl.WindowRestored)
{ active = true; stepClock.Reset(); last = clock.Elapsed.TotalSeconds; }
+ if (e.Type == Sdl.KeyUp && debugCapturedKeys.Remove(e.Scancode)) continue;
+ if (e.Type == Sdl.KeyDown && !debugMenu.Open && debugCapturedKeys.Contains(e.Scancode)) continue;
+ if (e.Type == Sdl.KeyDown && e.Scancode == DebugMenu.ToggleKey)
+ {
+ debugCapturedKeys.Add(e.Scancode);
+ if (e.Repeat == 0) { debugMenu.Toggle(storyTasks?.Get("SCENE") ?? 0); DebugInputBoundary(); }
+ continue;
+ }
+ if (debugMenu.Open)
+ {
+ if (e.Type == Sdl.KeyDown)
+ {
+ debugCapturedKeys.Add(e.Scancode);
+ DebugCommand(debugMenu.Key(e.Scancode, e.Repeat != 0));
+ if (!debugMenu.Open) DebugInputBoundary();
+ }
+ continue;
+ }
if (practice.Active && e.Type == Sdl.MouseButtonDown)
{ if (e.MouseButton == 1) practice.Click(Pointer()); keys.Clear(); mouseJump = false; stepClock.Reset(); continue; }
if (practice.Active && e.Type == Sdl.KeyDown)
@@ -558,22 +650,11 @@ internal static class Program
}
if (e.Scancode == 6 && e.Repeat == 0 && originalStart != null)
{
- if (simulation != null)
- {
- inspecting = !inspecting;
- keys.Clear(); mouseJump = false; stepClock.Reset();
- originalCamera = false;
- target = simulation.ActorRoot;
- radius = 600;
- if (!Sdl.SDL_SetWindowTitle(window, inspecting ? animations!.WindowTitle : WalkTitle)) throw new InvalidOperationException(Sdl.Error);
- }
- else originalCamera = !originalCamera;
+ ToggleCamera(); keys.Clear(); mouseJump = false; stepClock.Reset();
}
if (!inspecting && e.Scancode == 21 && e.Repeat == 0)
{
- simulation!.Reset(); poseTime = 0; sceneAudio?.StopSpeech(); director?.Begin(originalStart!);
- interactions?.Reset(); mechanisms?.Reset();
- director?.SyncActor(level!.Player!.Tag!, simulation.ActorRoot, new Vector3(0, simulation.Yaw, 0));
+ ResetScene();
}
if (e.Scancode == 68 && e.Repeat == 0)
{
@@ -587,9 +668,10 @@ internal static class Program
var elapsed = now - last;
var dt = (float)Math.Min(elapsed, 0.1);
last = now;
- if (simulation != null && !inspecting && !practice.Active && (active || headless || walkSmoke || jetpackSmoke || objectiveWindowSmoke))
+ if (debugMenu.Open) animationStarted += elapsed;
+ if (simulation != null && !debugMenu.Open && !inspecting && !practice.Active && (active || headless || walkSmoke || jetpackSmoke || objectiveWindowSmoke || debugSmoke))
{
- var steps = headless || walkSmoke || jetpackSmoke || practiceWindowSmoke || carlSmoke || objectiveWindowSmoke ? 1 : stepClock.Advance(elapsed);
+ var steps = headless || walkSmoke || jetpackSmoke || practiceWindowSmoke || carlSmoke || objectiveWindowSmoke || debugSmoke ? 1 : stepClock.Advance(elapsed);
for (var step = 0; step < steps; step++)
{
var input = carlSmoke ? new PlayerInput(true, false, true, false, true)
@@ -629,7 +711,7 @@ internal static class Program
}
characterModel = simulation.Model;
}
- if (inspecting)
+ if (inspecting && !debugMenu.Open)
{
if (keys.Contains(80) || keys.Contains(4)) angle -= dt;
if (keys.Contains(79) || keys.Contains(7)) angle += dt;
@@ -659,11 +741,17 @@ internal static class Program
staticVisuals?.Update(mesh);
jetpackVisuals?.Update(mesh, simulation!);
spriteVisuals?.FaceCamera(renderEye, renderTarget, mesh);
- objectivePanel?.Key(keys.Contains(18) && !inspecting && !practice.Active
+ objectivePanel?.Key(keys.Contains(18) && !debugMenu.Open && !inspecting && !practice.Active
&& director is { Controlled: true, InventoryEnabled: true });
objectivePanel?.Step(0, director?.ControlledTag != null, practice.Active);
hud?.Update(mesh, interactions!.CurrentObjective, level!.Code == "LV1B" && objectivePanel!.PadVisible,
practice.Active, objectivePanel!.YOffset, objectivePanel.ContentVisible);
+ var debugView = debugMenu.View(new(level?.Code ?? "PREVIEW", originalStart?.Tag ?? "NONE",
+ simulation?.ActorRoot ?? Vector3.Zero, simulation?.Yaw ?? 0, simulation?.Speed ?? 0,
+ simulation?.Grounded ?? false, simulation?.Energy ?? 0, interactions?.Score ?? 0,
+ storyTasks?.Get("SCENE") ?? 0, director?.CurrentTag ?? "NONE", director?.Controlled ?? false,
+ director?.Issues.Count ?? 0, SceneProjection.FarPlane(level?.Code), inspecting));
+ debugOverlay.Update(mesh, debugView.Lines, debugView.SelectedLine);
var projection = originalCamera || simulation != null && !inspecting
? SceneProjection.CreateGameplay(level?.Code, (float)renderer.Width / renderer.Height)
: Matrix4x4.CreatePerspectiveFieldOfView(MathF.PI / 3, (float)renderer.Width / renderer.Height, Math.Max(radius / 10000, 0.01f), radius * 20);
@@ -673,12 +761,60 @@ internal static class Program
animations.Current.Sample(simulation != null && !inspecting ? poseTime
: fixedTime ?? (headless ? count / 60.0 : now - animationStarted),
mesh.Vertices.AsSpan(characterOffset, animations.Current.Base.Vertices.Length), characterModel);
- renderer.UpdateVertices(mesh.Vertices);
}
+ renderer.UpdateVertices(mesh.Vertices);
renderer.Render(view * projection);
count++;
audio?.Pump();
sceneAudio?.Pump();
+ if (debugSmoke)
+ {
+ void Push(uint key, bool down = true, bool repeat = false)
+ {
+ var e = new Sdl.Event { Type = down ? Sdl.KeyDown : Sdl.KeyUp, Scancode = key,
+ Down = down ? (byte)1 : (byte)0, Repeat = repeat ? (byte)1 : (byte)0 };
+ if (!Sdl.SDL_PushEvent(ref e)) throw new InvalidOperationException(Sdl.Error);
+ }
+ void Tap(uint key) { Push(key); Push(key, false); }
+ if (count == 1)
+ {
+ debugPausedRoot = simulation!.ActorRoot; debugPausedSteps = simulation.Steps;
+ director!.Trigger("neutron1a"); // Exercise opening the menu during an actual source MCA.
+ Push(82); Tap(DebugMenu.ToggleKey);
+ if (!Sdl.SDL_SetWindowSize(window, 800, 600)) throw new InvalidOperationException(Sdl.Error);
+ }
+ if (count == 3)
+ {
+ debugPauseObserved = debugMenu.Open && simulation!.ActorRoot == debugPausedRoot
+ && simulation.Steps == debugPausedSteps && sceneAudio?.Paused != false && director!.Playing;
+ Tap(81); Tap(81); Tap(40); // Skip cutscene.
+ Tap(81); Tap(40); // Refill.
+ Tap(81); Tap(40); // Jet pack.
+ Tap(81); Tap(75); Tap(40); // SCENE30 ->40 via staged PageUp then apply.
+ }
+ if (count == 5)
+ {
+ debugActionsObserved = debugMenu.Open && director!.Controlled && !director.Playing
+ && simulation!.Energy == 100 && interactions!.Inventory.State(0, 3) == 1
+ && storyTasks!.Get("SCENE") == 40 && simulation.ActorRoot == debugPausedRoot
+ && simulation.Steps == debugPausedSteps;
+ if (Option(args, "--screenshot") is { } debugScreenshot)
+ renderer.SavePpm(Path.ChangeExtension(debugScreenshot, ".open.ppm"));
+ }
+ if (count == 7) { Push(41); Push(41, repeat: true); Push(82, repeat: true); }
+ if (count == 8)
+ {
+ debugEscapeObserved = running && !debugMenu.Open && sceneAudio?.Paused != true
+ && MathF.Abs(simulation!.ActorRoot.X - debugPausedRoot.X) < .001f
+ && MathF.Abs(simulation.ActorRoot.Z - debugPausedRoot.Z) < .001f;
+ Push(41, false); Push(82, false); Push(82); // Release captured input, then a fresh movement press.
+ }
+ if (count == 12)
+ {
+ debugResumeObserved = simulation!.Steps > debugPausedSteps && simulation.Travel > 1;
+ Push(82, false);
+ }
+ }
if (objectiveWindowSmoke)
{
if (count == 1) objectiveWasHidden = !objectivePanel!.PadVisible;
@@ -712,7 +848,7 @@ internal static class Program
if (!Sdl.SDL_PushEvent(ref cycle)) throw new InvalidOperationException(Sdl.Error);
}
}
- if ((smoke || walkSmoke || jetpackSmoke || practiceWindowSmoke || objectiveWindowSmoke) && renderer.Width == 800 && renderer.Height == 600) didResize = true;
+ if ((smoke || walkSmoke || jetpackSmoke || practiceWindowSmoke || objectiveWindowSmoke || debugSmoke) && renderer.Width == 800 && renderer.Height == 600) didResize = true;
if (frames > 0 && count >= frames) break;
if (transitionRequest != null) break;
}
@@ -727,6 +863,11 @@ internal static class Program
if (Math.Abs(pixels[i] - 31) + Math.Abs(pixels[i + 1] - 51) + Math.Abs(pixels[i + 2] - 76) > 6) changed++;
Console.WriteLine($"Rendered {count} frame(s), {changed} non-background pixels, {renderer.ValidationErrors} Vulkan validation error(s).");
if (simulation != null) Console.WriteLine(simulation.Report);
+ if (debugSmoke)
+ {
+ Console.WriteLine($"Debug SDL check: paused={debugPauseObserved}, actions={debugActionsObserved}, Escape/input capture={debugEscapeObserved}, resumed={debugResumeObserved}, resize800x600={didResize}.");
+ if (!debugPauseObserved || !debugActionsObserved || !debugEscapeObserved || !debugResumeObserved || !didResize) return 2;
+ }
if (carlSmoke)
{
var locked = director is { Controlled: false, Playing: true, CurrentTag: "neutron1a" } && simulation!.Steps == 0;
@@ -778,7 +919,8 @@ internal static class Program
var nextArgs = new List();
for (var i = 0; i < args.Length; i++)
{
- if (args[i] is "--smoke-transition" or "--smoke-lab-route" or "--smoke-practice-prompt" or "--smoke-practice-transition") continue;
+ if (args[i] is "--smoke-transition" or "--smoke-lab-route" or "--smoke-practice-prompt" or "--smoke-practice-transition"
+ or "--debug-menu" or "--smoke-debug-menu") continue;
if (args[i] is "--scene" or "--level" or "--start" or "--load-save" or "--story-time") { i++; continue; }
nextArgs.Add(args[i]);
}
@@ -818,7 +960,7 @@ internal static class Program
}
}
- private const string WalkTitle = "Jimmy Neutron — lab checkpoint | Arrows move | Shift / Insert / right mouse jump | R reset | C inspect";
+ private const string WalkTitle = "Jimmy Neutron — lab checkpoint | Arrows move | Shift / Insert / right mouse jump | F1 debug | R reset | C inspect";
private static int VerifyAssets(string root)
{
diff --git a/tests/GamePort.AudioPauseTests/GamePort.AudioPauseTests.csproj b/tests/GamePort.AudioPauseTests/GamePort.AudioPauseTests.csproj
new file mode 100644
index 0000000..d30681f
--- /dev/null
+++ b/tests/GamePort.AudioPauseTests/GamePort.AudioPauseTests.csproj
@@ -0,0 +1,15 @@
+
+
+ Exenet10.0
+ enableenable
+ truefalse
+
+
+
+
+
+
+
+
+
+
diff --git a/tests/GamePort.AudioPauseTests/Program.cs b/tests/GamePort.AudioPauseTests/Program.cs
new file mode 100644
index 0000000..b5032fc
--- /dev/null
+++ b/tests/GamePort.AudioPauseTests/Program.cs
@@ -0,0 +1,96 @@
+using System.Text;
+using System.Text.Json;
+using GamePort.Assets;
+using GamePort.Audio;
+
+// Actual SDL dummy-device behavior. Generated four-second WAVs keep this test
+// independent of original resources and long enough to observe consumption.
+var directory = Path.GetFullPath("artifacts/audio-pause");
+Directory.CreateDirectory(directory);
+var wave = Path.Combine(directory, "silence.wav");
+const int frequency = 11025, sourceBytes = frequency * 4 * 2;
+using (var file = File.Create(wave))
+using (var writer = new BinaryWriter(file))
+{
+ writer.Write(Encoding.ASCII.GetBytes("RIFF")); writer.Write(36 + sourceBytes);
+ writer.Write(Encoding.ASCII.GetBytes("WAVEfmt ")); writer.Write(16);
+ writer.Write((short)1); writer.Write((short)1); writer.Write(frequency);
+ writer.Write(frequency * 2); writer.Write((short)2); writer.Write((short)16);
+ writer.Write(Encoding.ASCII.GetBytes("data")); writer.Write(sourceBytes);
+ writer.Write(new byte[sourceBytes]);
+}
+
+using (var stream = new SdlAudio(wave, loop: true, paused: true))
+{
+ Require(stream.Paused && stream.QueuedBytes == sourceBytes, "New paused stream must retain its complete first WAV");
+ var first = stream.QueuedBytes;
+ Thread.Sleep(200); stream.Pump();
+ Require(stream.QueuedBytes == first, "Paused loop must neither consume nor refill");
+ stream.SetPaused(false); stream.SetPaused(false);
+ Require(!stream.Paused, "Resume state");
+ Thread.Sleep(200);
+ Require(stream.QueuedBytes < first, "Resumed SDL device must consume queued audio");
+ stream.SetPaused(true); stream.SetPaused(true);
+ var stopped = stream.QueuedBytes;
+ Thread.Sleep(200); stream.Pump();
+ Require(stream.Paused && stream.QueuedBytes == stopped, "Existing stream pause must stop consumption and loop refills");
+ stream.SetPaused(false);
+ Thread.Sleep(200);
+ Require(stream.QueuedBytes < stopped, "Second resume must consume again");
+}
+Console.WriteLine("PASS actual SDL stream starts paused, pause/resume is idempotent and loop pumping freezes");
+
+var manifest = Path.Combine(directory, "resources.json");
+File.WriteAllText(manifest, JsonSerializer.Serialize(new { resources = new[]
+{
+ Resource("music.omt", 0), Resource("voice.omt", 1),
+ Resource("SoundEffects.omt", 58), Resource("SoundEffects.omt", 59)
+}}));
+using (var scene = new SceneAudio(new PreparedEntityResources(manifest)))
+{
+ scene.SetPaused(true);
+ scene.Music("music.omt", 0); scene.Speech("voice.omt", 1);
+ scene.Effect(58); scene.Effect(59, "door");
+ Require(scene.EffectCount == 1 && scene.LoopCount == 1, "One-shot and loop fixture");
+ var first = Queued(scene);
+ Require(scene.Paused && first == (sourceBytes, sourceBytes, sourceBytes * 2),
+ "Every stream created under paused mixer must start with all source data queued");
+ Thread.Sleep(200); scene.Pump();
+ Require(Queued(scene) == first, "Paused music/speech/effects must retain their queues");
+ scene.SetPaused(false); scene.SetPaused(false);
+ Thread.Sleep(200);
+ var consumed = Queued(scene);
+ Require(consumed.Music < first.Music && consumed.Speech < first.Speech && consumed.Effects < first.Effects,
+ "Every mixer stream category must resume consumption");
+ scene.SetPaused(true); scene.SetPaused(true);
+ var stopped = Queued(scene);
+ Thread.Sleep(200); scene.Pump();
+ Require(Queued(scene) == stopped, "Pausing active mixer must freeze music, speech, one-shots and loops");
+ scene.RestartMusic(); scene.Speech("voice.omt", 1); scene.Effect(59, "door");
+ var replaced = Queued(scene);
+ Thread.Sleep(200); scene.Pump();
+ Require(Queued(scene) == replaced, "Replacement streams inherit paused state");
+ scene.SetPaused(false);
+ Thread.Sleep(200);
+ var restarted = Queued(scene);
+ Require(restarted.Music < replaced.Music && restarted.Speech < replaced.Speech && restarted.Effects < replaced.Effects,
+ "Replaced streams must resume with the existing one-shot");
+}
+Console.WriteLine("PASS mixer pauses all stream categories and preserves pause across replacement streams");
+
+var disposed = new SdlAudio(wave, paused: true);
+disposed.Dispose(); disposed.Dispose();
+try { disposed.SetPaused(false); throw new InvalidOperationException("Expected disposed-state rejection"); }
+catch (ObjectDisposedException) { }
+Console.WriteLine("PASS repeated disposal balances SDL audio initialization and rejects further pause changes");
+
+static object Resource(string database, int id) => new
+{
+ database, id, type = "Wave", path = "silence.wav", audio = new { seconds = 4 }
+};
+static (int Music, int Speech, int Effects) Queued(SceneAudio scene) =>
+ (scene.QueuedMusicBytes, scene.QueuedSpeechBytes, scene.QueuedEffectBytes);
+static void Require(bool condition, string message)
+{
+ if (!condition) throw new InvalidOperationException(message);
+}
diff --git a/tests/GamePort.DebugMenuTests/GamePort.DebugMenuTests.csproj b/tests/GamePort.DebugMenuTests/GamePort.DebugMenuTests.csproj
new file mode 100644
index 0000000..dd0c787
--- /dev/null
+++ b/tests/GamePort.DebugMenuTests/GamePort.DebugMenuTests.csproj
@@ -0,0 +1,8 @@
+
+ Exenet10.0enableenablefalse
+
+
+
+
+
+
diff --git a/tests/GamePort.DebugMenuTests/Program.cs b/tests/GamePort.DebugMenuTests/Program.cs
new file mode 100644
index 0000000..90ee701
--- /dev/null
+++ b/tests/GamePort.DebugMenuTests/Program.cs
@@ -0,0 +1,48 @@
+using System.Numerics;
+using GamePort.Application;
+
+var menu = new DebugMenu([new("level1b.gam", "LV1B", ["STARTEXP", "riverlab"]),
+ new("VR04.gam", "VR04", ["PHONEBOOTH"])], "LEVEL1B.GAM", "startexp");
+Require(!menu.Open && menu.Key(40) == DebugAction.None, "Closed menu cannot issue commands");
+menu.Toggle(30);
+Require(menu.Open && menu.SceneTask == 30 && menu.Start == "STARTEXP", "F1 opens current context");
+menu.Key(82);
+Require(menu.Selected == 9 && menu.Key(40) == DebugAction.Reset, "Navigation wraps to reset");
+menu.Key(81);
+Require(menu.Selected == 0 && menu.Key(40, true) == DebugAction.None && menu.Key(40) == DebugAction.Resume,
+ "Enter repeats cannot repeat commands");
+for (var i = 0; i < 5; i++) menu.Key(81);
+menu.Key(79); menu.Key(75);
+Require(menu.SceneTask == 41 && menu.Key(40) == DebugAction.ApplySceneTask, "SCENE edit is staged until apply");
+menu.Key(78); menu.Key(80);
+Require(menu.SceneTask == 30, "SCENE coarse/fine editing is reversible");
+for (var i = 0; i < 110; i++) menu.Key(78);
+Require(menu.SceneTask == 0, "SCENE lower bound");
+for (var i = 0; i < 110; i++) menu.Key(75);
+Require(menu.SceneTask == 999, "SCENE upper bound");
+menu.Key(81); menu.Key(79);
+Require(menu.Scene?.Code == "VR04" && menu.Start == "PHONEBOOTH", "Scene selection updates starts");
+menu.Key(80); menu.Key(81); menu.Key(79);
+Require(menu.Scene?.Code == "LV1B" && menu.Start == "riverlab", "Original named starts can be selected");
+menu.Key(81);
+Require(menu.Key(40) == DebugAction.LoadScene, "Load action is explicit");
+var view = menu.View(new("LV1B", "STARTEXP", new(1, 2, 3), 155, 0, true, 20, 50, 30, "NONE", true, 0, 10000, false));
+Require(view.Lines.Length <= 32 && view.SelectedLine == 17 && view.Lines.Any(s => s.Contains("riverlab")), "Bounded menu view highlights its action");
+menu.Key(41);
+Require(!menu.Open && menu.View(new("", "", Vector3.Zero, 0, 0, false, 0, 0, 0, "", false, 0, 0, false)).Lines.Length == 0,
+ "Escape closes and hides the menu");
+menu.Toggle(65);
+Require(menu.SceneTask == 65, "Reopening refreshes live task state");
+Console.WriteLine("PASS debug navigation, input repeat, staged tasks, scene/start selection and view");
+
+var original = Path.GetFullPath(args.Length == 1 ? args[0] : "../Original");
+var catalog = DebugMenu.AvailableScenes(original, Path.GetFullPath("artifacts/extracted"));
+Require(catalog.Length == 33 && catalog.All(s => s.Starts.Length > 0), "Only33 supplied scenes with prepared geometry are offered");
+Require(catalog.All(s => s.Code is not ("LV3B" or "LV3E")), "Absent geometry is not substituted into the menu");
+Require(catalog.Single(s => s.Code == "LV1B").Starts.Contains("riverlab"), "Actual underground STRT is available");
+Console.WriteLine("PASS original33-scene debug catalog and source startpoint coverage");
+
+static void Require(bool condition, string message)
+{
+ if (!condition) throw new InvalidOperationException(message);
+}
diff --git a/tests/GamePort.DebugOverlayTests/GamePort.DebugOverlayTests.csproj b/tests/GamePort.DebugOverlayTests/GamePort.DebugOverlayTests.csproj
new file mode 100644
index 0000000..513f179
--- /dev/null
+++ b/tests/GamePort.DebugOverlayTests/GamePort.DebugOverlayTests.csproj
@@ -0,0 +1,9 @@
+
+ Exenet10.0enableenablefalse
+
+
+
+
+
+
+
diff --git a/tests/GamePort.DebugOverlayTests/Program.cs b/tests/GamePort.DebugOverlayTests/Program.cs
new file mode 100644
index 0000000..d3ff180
--- /dev/null
+++ b/tests/GamePort.DebugOverlayTests/Program.cs
@@ -0,0 +1,34 @@
+using System.Numerics;
+using GamePort.Assets;
+using GamePort.Application;
+
+var source = new Mesh([new(new(10, 20, 30), Vector2.Zero, Vector3.One)], [0, 0, 0])
+ { Textures = new() { [int.MinValue] = PngImage.White } };
+var overlay = new DebugMenuOverlay(source);
+Check(overlay.Mesh.Vertices.Length == 1 + (2 + 32 * 76) * 4, "Fixed bounded vertex capacity");
+Check(overlay.Mesh.Draws.Length == 35 && !overlay.Mesh.Draws[0].ScreenSpace, "Implicit source draw preserved");
+Check(overlay.Mesh.Textures.Count == 2 && overlay.Mesh.Textures[int.MinValue + 1].Width == 128,
+ "Atlas has its own noncolliding texture identity");
+Check(overlay.Mesh.Textures[int.MinValue + 1].Rgba.Count(b => b == 0) > 1000, "Font atlas contains alpha-tested spacing");
+var final = overlay.Mesh with { Vertices = overlay.Mesh.Vertices.ToArray(), Draws = overlay.Mesh.Draws.Select(d => d with {}).ToArray() };
+overlay.Update(final, ["Debug menu", "X: -123.5 / Y: 40.0", "Resume"], 2);
+Check(final.Vertices[0].Position == source.Vertices[0].Position, "World vertex preserved");
+Check(final.Draws.Skip(1).Count(d => d.Visible) == 5, "Background, selected row and three text draws shown");
+Check(final.Vertices[1].Position != Vector3.Zero && overlay.Mesh.Vertices[1].Position == Vector3.Zero,
+ "Update targets final copied buffer");
+Check(final.Vertices.All(v => float.IsFinite(v.Position.X + v.Position.Y + v.Uv.X + v.Uv.Y)), "All overlay coordinates finite");
+overlay.Update(final, [new string('X', 100)], -1);
+Check(final.Draws.Skip(1).Count(d => d.Visible) == 2, "Long labels clip to bounded text range");
+overlay.Update(final, []);
+Check(final.Draws.Skip(1).All(d => !d.Visible) && final.Draws[0].Visible, "Closing hides overlay without hiding world");
+Reject(() => overlay.Update(source, ["Debug"]));
+Reject(() => overlay.Update(final, Enumerable.Repeat("X", 33).ToArray()));
+Reject(() => overlay.Update(final, ["Debug"], 1));
+Console.WriteLine("PASS fixed debug overlay capacity, texture identity, final-buffer composition, visibility and bounds");
+
+static void Check(bool condition, string message) { if (!condition) throw new InvalidOperationException(message); }
+static void Reject(Action action)
+{
+ try { action(); } catch (ArgumentException) { return; }
+ throw new InvalidOperationException("Expected bounded overlay rejection");
+}