Grid Placement separates runtime logic from scene/game context.
You usually interact with three layers:
GridPlacementHost— routes the active interaction.PlacementSession— owns per-player/controller state and configuration references.- Context/provider adapters — connect the current level/player/game facts to placement validation/services.
Default path
Use the shipped template/injector wiring unless your game has a reason to build the runtime in code. The template path exists so a normal project does not need to instantiate and wire every service manually.
Manual composition
For a code-built scene:
host.configure(session)For independent controllers:
host.register_session(controller_root, session, device_id)The host composes the service group from the active session/configuration. Consumers should call the supported host/service surfaces rather than finding private service nodes by scene path.
Context injection
Use contexts/providers for facts that come from the current game scene, for example:
- target
TileMapLayer/GridMapsurface; - placed-object parent;
- placement owner/controller;
- game-owned reserved/occupied zones;
- inventory/cost/world-state facts used by custom rules.
Do not copy those facts into long-lived plugin globals when their lifetime belongs to a level/session/game system.
Shared world authority
Services may expose dimension-specific projections, but committed placement identity/occupancy must remain coordinated through the shared placement world.
This is especially important for:
- GRID vs SMOOTH conflicts;
- EDGE/FACE/socket occupancy;
- multiple sessions;
- save/restore.
Do not construct an independent occupancy registry and treat it as a second commit authority.
When to inject a custom service/provider
Add custom composition only when the project needs a real policy/integration seam. Examples:
- a game-owned world-facts provider;
- custom placement validation rule;
- inventory/refund bridge;
- custom input/controller/session setup.
Avoid replacing plugin services just to change naming or add logging.