automation-mode

Automation Mode in FlatRedBall2

Automation mode lets an external process control a running game via NDJSON (newline-delimited JSON) over stdin/stdout — one command per line in, one response per line out. The primary use case is AI agents that need to observe and interact with the game the way Playwright interacts with a browser.

Debug builds only — gated on your own project's configuration. EnableAutomationMode() is a [Conditional("DEBUG")] call: the C# compiler strips the call site entirely when your project builds Release, regardless of how the FlatRedBall2 package itself was built. It's safe to leave the call in unconditionally. This is intentional — automation mode exposes internal state and allows arbitrary value forcing.

Setup

// Game.Initialize, after base.Initialize():
FlatRedBallService.Default.EnableAutomationMode();

The call itself does nothing unless --frb-auto is present in the command-line args. Ship the call unconditionally; the flag controls activation.

dotnet run -- --frb-auto

That's the entire required wiring. Entities and their public properties are auto-discovered — no per-property registration.

Hiding the window (Windows)

dotnet run -- --frb-auto --frb-auto-hide parks the game window off-screen at the back of the z-order and hands focus back to the window beneath it, so an agent-driven run does not cover the user's work. Pass it whenever you launch the game on a person's machine. The window still renders, so screenshots work, and without the flag the window shows as usual. Focus handback is best-effort (src/Automation/AutomationWindowParker.cs); the flag does nothing without --frb-auto and is ignored on other platforms.

Deterministic randomness

When automation activates, FlatRedBallService.Random is replaced with a deterministic GameRandom so recorded NDJSON sessions reproduce exactly. Pass an explicit seed to choose which run.

FlatRedBallService.Default.EnableAutomationMode(seed: 1234);