Entry Points & Data Flow (5.1)

Why entry points matter

5.1 is stable when you integrate through a small number of entry points and treat everything else as internal.

This reduces:

breakage when internals refactor
test brittleness
“mystery wiring” during debugging

Canonical mental model (the runtime chain)

The recommended debugging / architecture chain is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Godot nodes
  ↓
Input routing + adapters
  ↓
Workflow orchestrators
  ↓
Services
  ↓
State
  ↓
Outputs/effects (applied by Godot)

For the deeper explanation, see:

/v5-1/guides/runtime-chain/

Entry points (what your game should call)

1) Composition container / registry (dependency access)

Your scene should resolve dependencies from a single “composition” surface.

What you use it for:

get services (placement, targeting, mode)
get workflow orchestrators (or factories that create them)

What you should not do:

store random global singletons elsewhere
reach directly into unrelated internal folders

2) Input routing (`GPInputService`)

Input should be routed through the input service (instead of random nodes each interpreting events).

High-level flow:

1
2
3
4
5
6
7
Godot InputEvent
  ↓
GPInputService
  ↓
Input adapters
  ↓
Workflow orchestrators

3) Workflow orchestrators (decisions)

Orchestrators own workflow decisions and return outputs.

They should be the only place that decides things like:

“do we confirm placement now?”
“should drag-build commit?”
“what effects should be emitted?”

4) Effects application (`GPEffectApplier`)

Outputs/effects should be interpreted by the effect applier, which emits typed signals.

Rule of thumb:

orchestrators decide
effect applier applies
scene nodes render

Authoritative components (who is the source of truth)

Concern	Source of truth	Notes
Current targeting result	`TargetingService2D`	Emits EventData payloads; snapshots are for diagnostics/tests
Placement validity	placement workflow/services	Don’t implement placement rules in UI nodes
Mode (build/manipulate/none)	mode service	Mode should gate input adapters
Scene mutation (spawn preview, show indicators)	`GPEffectApplier` + listeners	Keep scene mutation centralized

“What not to do” (common architecture drift)

Don’t put placement/manipulation rules in scene nodes.
Don’t have multiple systems interpret input independently.
Don’t reach into state objects directly from Godot nodes.
Don’t make “snapshots” the authoritative representation (snapshots are read-only projections).