diff --git a/README.md b/README.md
index d3e3a7a..da939bc 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,8 @@ control returns, including after skipping.
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
+reset. Page Up/Down changes the staged SCENE value by 10.
+The Force Control toggle keeps Jimmy controllable during scripted control locks. See
[debug menu controls](docs/debug-menu.md).
The original lab pickup is internally tagged `shrinkray`; the original objective
diff --git a/docs/architecture.md b/docs/architecture.md
index 3da15c1..64cec4d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,3 +156,9 @@ 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.
+
+SceneDirector keeps authored controlledTag separate from DebugForceControl.
+Effective control/tag queries expose Jimmy while forced; source shot assignments
+still update the authored tag. DEFAULT uses authored ownership for its music
+handoff. Disabling force reveals current script state; Begin clears the override.
+The debug flag is never serialized into original saves.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index d77c78f..51ddfae 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -24,6 +24,7 @@ separate evidence categories. **The game is not fully reconstructed/playable yet
| 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 |
+| F1 Force Control | Menu/director/interaction checks + native Linux SDL pass |Persistent override through source shots; disable/reset restores normal ownership; actual movement with neutron1a active, zero Vulkan errors; music handoff regression passes |
| 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 |
diff --git a/docs/debug-menu.md b/docs/debug-menu.md
index ac2713a..43d25c8 100644
--- a/docs/debug-menu.md
+++ b/docs/debug-menu.md
@@ -21,6 +21,13 @@ the existing task system and its callbacks. Inventory/energy/task actions affect
current runtime state and its normal checkpoint snapshots; they do not write files
by themselves. Debug tools do not imply reconstructed progression or full gameplay.
+Force Control toggles a persistent debug override. Set it to TRUE and close the
+menu to let Jimmy move even while a cutscene or scripted control lock is active.
+Subsequent camera shots cannot clear the override. The cutscene, camera and audio
+continue normally; Skip Current Cutscene remains available separately. Toggling
+back to FALSE exposes the current scripted ownership. Reset or loading another
+scene clears the override; it is not written into original TSK saves.
+
The level picker offers only supplied GAMs with prepared geometry, a player and
original STRT records. It currently offers33 scenes; Level3B/E are absent because
their registered geometry is unavailable. No substitute geometry is supplied.
@@ -51,6 +58,9 @@ uses actual SDL dummy-device queues to verify freeze/resume for all stream types
`--debug-menu` opens the menu immediately, including headless captures.
`--smoke-debug-menu` runs a16-frame window test: open during a source MCA, pause,
skip/refill/grant/apply task, close with held/repeated input, resume and resize.
+It also enables Force Control through the menu and verifies actual movement while
+Carl's MCA is still playing. Director checks cover disabling the override, shot
+changes, scene reset and the normal completion music handoff.
Native Linux GTX1070 window test passes with zero Vulkan validation errors:
artifacts/debug-window.log. GPU screenshots debug-menu.png and debug-window.open.ppm
diff --git a/docs/decisions.md b/docs/decisions.md
index 6e6f416..c63b213 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -84,3 +84,6 @@
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.
+ Force Control is a persistent debug override over authored ownership, with
+ FALSE restoring the current scripted state. Reset/new scene clears it, and
+ source music handoff continues to use authored ownership.
diff --git a/docs/progress.md b/docs/progress.md
index e5186a2..cce0b9d 100644
--- a/docs/progress.md
+++ b/docs/progress.md
@@ -6,6 +6,17 @@ jet pack tutorial flow. This is not a verified faithful complete scene or releas
## User-requested F1 debug menu
+Follow-up: Force Control is now a persistent TRUE/FALSE menu toggle. It overrides
+effective ownership while preserving authored control state; switching it off
+restores that state. Reset/new scene clears it. Cutscene execution continues and
+DEFAULT music restoration uses authored ownership, avoiding a debug-induced silent
+return. Menu/director/interaction checks pass; the extended16-frame Linux SDL
+test records actual forced movement during active neutron1a,14.00 total travel,
+all menu checks true and zero Vulkan validation errors
+(artifacts/force-control-window.log).539 original hashes remain unchanged.
+Both executables are republished for this follow-up; no Windows runtime
+check is claimed. The full-suite evidence below is from the preceding menu build.
+
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
diff --git a/docs/tasks.md b/docs/tasks.md
index efd67e5..3d77b21 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -31,6 +31,8 @@ compile, runtime and original-fidelity verification are separate.
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.
+- [x] Force Control TRUE/FALSE override in F1; persists through scripted shots,
+ restores authored ownership when disabled, clears on reset/new scene.
## Immediate continuation
diff --git a/scripts/package.sh b/scripts/package.sh
index fa729f6..47611b2 100755
--- a/scripts/package.sh
+++ b/scripts/package.sh
@@ -48,7 +48,7 @@ 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.
+energy/jetpack/task changes, level/start selection, reset and Force Control toggle.
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/src/GamePort/Application/DebugMenu.cs b/src/GamePort/Application/DebugMenu.cs
index 18912d5..d36dc40 100644
--- a/src/GamePort/Application/DebugMenu.cs
+++ b/src/GamePort/Application/DebugMenu.cs
@@ -5,17 +5,17 @@ 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 enum DebugAction { None, Resume, Camera, SkipCutscene, RefillEnergy, GiveJetpack, ApplySceneTask, LoadScene, Reset, ForceControl }
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);
+ int Issues, float FarPlane, bool Inspecting, bool ForcedControl = false);
/// 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 const int ItemCount = 11;
public bool Open { get; private set; }
public int Selected { get; private set; }
public int SceneTask { get; private set; }
@@ -65,6 +65,7 @@ public sealed class DebugMenu
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,
+ 10 => DebugAction.ForceControl,
_ => DebugAction.None
};
return DebugAction.None;
@@ -95,6 +96,7 @@ public sealed class DebugMenu
$"START: {Start ?? "UNAVAILABLE"}",
"LOAD SELECTED LEVEL / START",
"RESET CURRENT START",
+ $"FORCE CONTROL: {status.ForcedControl} (ENTER TOGGLE)",
"",
"UP/DOWN SELECT LEFT/RIGHT CHANGE ENTER APPLY",
"SCENE TASK: PAGE UP/DOWN CHANGES BY 10",
diff --git a/src/GamePort/Game/SceneDirector.cs b/src/GamePort/Game/SceneDirector.cs
index afad8a5..26759c5 100644
--- a/src/GamePort/Game/SceneDirector.cs
+++ b/src/GamePort/Game/SceneDirector.cs
@@ -70,8 +70,15 @@ public sealed class SceneDirector
public List Actors { get; } = [];
public IReadOnlyList Issues => issues;
+ private string? controlledTag;
+ /// Modern debug override; leaves authored control/camera transitions intact.
+ public bool DebugForceControl { get; set; }
public bool Controlled => Equal(ControlledTag, level.Player?.Tag);
- public string? ControlledTag { get; private set; }
+ public string? ControlledTag
+ {
+ get => DebugForceControl ? level.Player?.Tag : controlledTag;
+ private set => controlledTag = value;
+ }
public bool InventoryEnabled { get; private set; } = true;
public bool Blocked { get; private set; }
public bool Playing => shot is not null;
@@ -116,6 +123,7 @@ public sealed class SceneDirector
public void Begin(GamEntity start, bool activateStartTrigger = true)
{
if (start.Kind != "STRT") throw new ArgumentException("Expected original STRT entity", nameof(start));
+ DebugForceControl = false;
shot = null; pending.Clear(); activations.Clear();
Blocked = skipping = false; blockedNext = blockedCaller = null;
CameraEye = CameraTarget = null;
@@ -492,7 +500,9 @@ public sealed class SceneDirector
private void RestoreControl()
{
- var wasControlled = Controlled;
+ // Authored music handoff must use authored ownership even if debug input
+ // is forced during the cutscene. The override does not grant source control.
+ var wasControlled = Equal(controlledTag, level.Player?.Tag);
shot = null;
ControlledTag = level.Player?.Tag;
InventoryEnabled = true;
diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs
index 258ac69..f92db39 100644
--- a/src/GamePort/Program.cs
+++ b/src/GamePort/Program.cs
@@ -513,6 +513,8 @@ internal static class Program
var debugActionsObserved = false;
var debugEscapeObserved = false;
var debugResumeObserved = false;
+ var debugForceObserved = false;
+ float debugForceTravel = 0;
var debugPausedRoot = simulation?.ActorRoot ?? Vector3.Zero;
var debugPausedSteps = simulation?.Steps ?? 0;
void ResetScene()
@@ -545,7 +547,8 @@ internal static class Program
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"; }
+ if (director is { Playing: true } or { Blocked: true } or { Controlled: false })
+ { sceneAudio?.StopSpeech(); director.Skip(); debugMenu.Message = "CUTSCENE SKIPPED"; }
else debugMenu.Message = "NO ACTIVE CUTSCENE";
break;
case DebugAction.RefillEnergy when simulation != null:
@@ -564,6 +567,9 @@ internal static class Program
{ 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.ForceControl when director != null:
+ director.DebugForceControl = !director.DebugForceControl;
+ debugMenu.Message = $"FORCE CONTROL {director.DebugForceControl}; CLOSE MENU TO RESUME"; break;
case DebugAction.None: break;
default: debugMenu.Message = "ACTION REQUIRES PLAY MODE"; break;
}
@@ -750,7 +756,7 @@ internal static class Program
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));
+ director?.Issues.Count ?? 0, SceneProjection.FarPlane(level?.Code), inspecting, director?.DebugForceControl ?? false));
debugOverlay.Update(mesh, debugView.Lines, debugView.SelectedLine);
var projection = originalCamera || simulation != null && !inspecting
? SceneProjection.CreateGameplay(level?.Code, (float)renderer.Width / renderer.Height)
@@ -813,7 +819,15 @@ internal static class Program
{
debugResumeObserved = simulation!.Steps > debugPausedSteps && simulation.Travel > 1;
Push(82, false);
+ director!.Trigger("neutron1a");
+ Tap(DebugMenu.ToggleKey);
+ for (var row = 5; row < 10; row++) Tap(81);
+ Tap(40); // Enable force control while the new MCA remains active.
}
+ if (count == 13) { debugForceTravel = simulation!.Travel; Tap(41); Push(82); }
+ if (count == 16)
+ debugForceObserved = director is { DebugForceControl: true, Controlled: true, Playing: true }
+ && simulation!.Travel > debugForceTravel + .1f;
}
if (objectiveWindowSmoke)
{
@@ -865,8 +879,8 @@ internal static class Program
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;
+ Console.WriteLine($"Debug SDL check: paused={debugPauseObserved}, actions={debugActionsObserved}, Escape/input capture={debugEscapeObserved}, resumed={debugResumeObserved}, forced movement during MCA={debugForceObserved}, resize800x600={didResize}.");
+ if (!debugPauseObserved || !debugActionsObserved || !debugEscapeObserved || !debugResumeObserved || !debugForceObserved || !didResize) return 2;
}
if (carlSmoke)
{
diff --git a/tests/GamePort.DebugMenuTests/Program.cs b/tests/GamePort.DebugMenuTests/Program.cs
index 90ee701..de782d8 100644
--- a/tests/GamePort.DebugMenuTests/Program.cs
+++ b/tests/GamePort.DebugMenuTests/Program.cs
@@ -7,8 +7,11 @@ Require(!menu.Open && menu.Key(40) == DebugAction.None, "Closed menu cannot issu
menu.Toggle(30);
Require(menu.Open && menu.SceneTask == 30 && menu.Start == "STARTEXP", "F1 opens current context");
menu.Key(82);
+Require(menu.Selected == 10 && menu.Key(40) == DebugAction.ForceControl && menu.Key(40, true) == DebugAction.None,
+ "Force-control row emits one command per Enter press");
+menu.Key(82);
Require(menu.Selected == 9 && menu.Key(40) == DebugAction.Reset, "Navigation wraps to reset");
-menu.Key(81);
+menu.Key(81); 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);
diff --git a/tests/GamePort.DirectorTests/Program.cs b/tests/GamePort.DirectorTests/Program.cs
index b28f1b0..b2baf04 100644
--- a/tests/GamePort.DirectorTests/Program.cs
+++ b/tests/GamePort.DirectorTests/Program.cs
@@ -42,6 +42,27 @@ Check(skipMusicPlaying,"Skipping must restore selected gameplay music");
Check(skip.FindActor("C3DGODDARD")!.Position==endGoddard,"Skip must preserve AI/toggle actions");
Console.WriteLine("PASS original intro skip preserves action sequence");
+var forced = new SceneDirector(level, new TaskStates(save.Tasks), (_, _) => .1);
+var forcedRestarts = 0;
+forced.MusicRestarted += () => forcedRestarts++;
+forced.Begin(level.FindStart()!);
+var forcedTag = forced.CurrentTag;
+forced.DebugForceControl = true;
+Check(forced.Controlled && forced.ControlledTag == level.Player!.Tag && forced.Playing && forced.CurrentTag == forcedTag,
+ "Debug force grants Jimmy input without skipping the source camera chain");
+forced.Step(.15f);
+Check(forced.Controlled && forced.Playing, "Forced control survives subsequent authored camera control assignments");
+forced.DebugForceControl = false;
+Check(!forced.Controlled && forced.ControlledTag == null && forced.Playing,
+ "Disabling force exposes current authored control state");
+forced.DebugForceControl = true;
+for (var i = 0; i < 300 && forced.Playing; i++) forced.Step(.1f);
+Check(forced.Controlled && !forced.Playing && forcedRestarts == 1,
+ "Force does not suppress normal cutscene completion music restart");
+forced.Begin(level.FindStart()!);
+Check(!forced.DebugForceControl && !forced.Controlled, "Scene reset clears the debug override");
+Console.WriteLine("PASS debug forced control persistence, source state restoration, music handoff and reset");
+
var returnDirector = new SceneDirector(level, new TaskStates(save.Tasks), (_, _) => 10);
var returnCues = 0;
returnDirector.Speech += (_, _) => returnCues++;