Skip to content
Forge

The Game Manager spine

Every Forge bundle ships with a GameManager that owns the systems for the project: AudioManager, EventBus, ProjectConfig, SaveSystem, StateMachine, InputManager, SettingsManager, CharacterController, ThemeManager. The GameManager is the spine. Your game code reaches in for whichever systems it needs and never has to wire startup order, dependency graphs, or singleton lookups by hand.

Each registered system has:

  • A canonical name like AudioManager or ProjectConfig.
  • A descriptor entry in .forge/gamemanager.toml recording its template version, source path, dependencies, and config.
  • A source file (usually under src/systems/<id>.ts) that the GameManager instantiates on boot.
  • An editor in the Inspector where you tune its config without writing code.

The whole point is that you can browse the spine, edit a system’s config, add or remove systems, and let Forge keep the wiring honest. You can also ignore the editors and hand-edit everything; the systems framework is opt-in for any individual change.

The Game Manager tab

Section titled “The Game Manager tab”

Open Inspector → Systems → Game Manager → Open to see the spine.

The tab lists every registered system in startup order. Each row shows the system’s name, the template version it was scaffolded from, the source file on disk, what it depends on, and a JSON preview of its config. Buttons let you re-order the startup sequence (drag-to-reorder), open the per-system editor, or remove the system entirely (which deletes its scaffold).

If you open a project that doesn’t have a descriptor yet, the empty state offers a single Create descriptor button. Forge writes the file, detects the project’s engine (web-phaser / web-threejs / web-vanilla / godot / unity / generic), and seeds an empty systems map.

The scaffold popover

Section titled “The scaffold popover”

The fastest way to add a new system to a project is the gear icon above the chat composer. It opens a popover listing the 9 single-system scaffolds:

  • Event Bus (pub/sub)
  • Project Config (designer-tunable constants)
  • UI / Theme Manager (palette and fonts)
  • Game State Machine (boot / menu / play / pause)
  • Save System (slots and autosave)
  • Audio Manager (bus tree, ducking, crossfade)
  • Input Manager (action map)
  • Settings Manager (audio / video / controls)
  • Character Controller (movement and polish constants)

Click one and Forge drops a prompt into the composer:

scaffold the audio manager into this project

You can refine that prompt before hitting send. The agent will use the forge.scaffold_system MCP tool, write the system source, register it in .forge/gamemanager.toml, and surface the diff for you to review in the usual proposal cards.

Full game-bundle scaffolds (the four bundles in Starter bundles) only appear in the new-project workflow. Once a project exists, individual systems are the right granularity to add. Bundles aren’t meant to merge into an existing project.

What a system file looks like

Section titled “What a system file looks like”

Each system source file is a single TypeScript class that the spine owns. The shape is consistent across bundles:

export class EventBus {
  private subscribers = new Map<string, Set<(payload: unknown) => void>>();


  on(event: string, handler: (payload: unknown) => void) { /* ... */ }
  emit(event: string, payload?: unknown) { /* ... */ }
  off(event: string, handler: (payload: unknown) => void) { /* ... */ }
}

The GameManager instantiates it once on boot, registers it under its canonical name, and exposes it to scenes via game.__forgeDeps.eventBus (for Phaser) or direct field access (for vanilla DOM bundles).

Why bother

Section titled “Why bother”

The spine pays off in three places:

  1. Consistency across bundles. A scene from the Platformer bundle can be dropped into the Top-down RPG bundle because both expect the same shape of dependencies.
  2. Editors instead of code edits for config. The AudioManager bus tree, the InputManager action map, the SettingsManager menu categories. All round-trip through the editors without you opening the source file.
  3. Agent scaffolds. When the agent adds a new system, the diff is small and the wiring is obvious. The agent doesn’t have to discover your conventions; it follows the spine.

Conflict detection

Section titled “Conflict detection”

When a system scaffolds, Forge records a sidecar at .forge/scaffolds/<id>.json listing every file the scaffold touched, the SHA of each, and a manifest of the lines it inserted. If you later hand-edit one of those files and the agent tries to re-scaffold or upgrade the system, Forge runs three checks:

  • Manifest tier: does the file still exist and match the recorded SHA?
  • Pre-diff tier: if the file changed, what does the patch look like? You see exactly what differs.
  • Post-diff tier: after the scaffold runs, did it touch lines you already touched? Merge conflicts surface as a card in the chat.

In practice you usually won’t see this. It only matters when the agent re-scaffolds an existing system. The point is that hand-edits are safe; the spine notices them and asks instead of overwriting.

Next

Section titled “Next”