Architecture Overview (5.1)
Boundary (what belongs where)
GridPlacement 5.1 is easiest to understand as two layers.
- Godot layer (engine glue)
- Nodes, scenes, visuals, input events, and signals.
- Backend logic (workflow/services/state)
- Decision logic, validation, state transitions, and event payloads.
Even in 5.1 (GDScript), the intent is to keep most “rules” inside backend logic and keep nodes thin.
The 5.1 building blocks
Composition container / registry
In 5.1, a composition container is the practical “composition root” where your scene resolves the runtime’s backend dependencies.
- It is the place you go to obtain authoritative services (mode, placement, targeting, etc.).
- It should be treated as the stable integration seam for gameplay scenes.
Workflows and orchestrators
Workflows/orchestrators are the “application layer” responsible for:
- tracking workflow state (e.g., “currently previewing”)
- deciding what to do when input events arrive
- emitting outputs/effects instead of mutating scenes directly
Services
Services are where most authoritative operations live (queries + commands), typically backed by state objects.
Examples (conceptual):
- placement service
- targeting service
- indicator/preview calculation service
State
State is data that represents the current runtime situation (grid occupancy, selection/targeting, mode, etc.).
Rule of thumb:
- Prefer state to remain private to services.
- Expose read-only projections/snapshots for diagnostics/tests when needed.
Effects (output model)
A core 5.1 stability pattern is:
- orchestrators return or emit
GBOrchestratorOutput - effects are interpreted by
GPEffectApplier - scene nodes listen to signals and update visuals
This keeps the “what should happen” decision logic testable and keeps “how we mutate the scene” in one place.
What “stable API” means in 5.1
For a project consuming 5.1, the stable surface should be:
- a small set of public nodes / container accessors
- a small set of public signals for outputs
Avoid coupling your game code to:
- internal helper scripts
- deep folder internals
- direct state mutation
How 5.1 maps forward to 6.0 (high level)
The 6.0 C# architecture makes the boundaries explicit (ports/adapters, service registry, explicit lifetimes).
For 5.1 consumers, the practical guidance is:
- keep your gameplay code calling entry points
- keep backend logic behind workflow/service seams
See: