A PlacementSession represents one independent placement interaction—normally one player/controller.
What a session owns
Session-scoped state includes things that can differ between players at the same moment:
- selected placeable/terrain;
- GRID vs SMOOTH coordinate mode;
- current target/preview;
- pending brush/drag/manipulation state;
- controller/input context;
- per-session catalog/unlock filtering;
- session-specific settings/context references.
Two active players should use different sessions if those values must be independent.
What a session does not own
Committed world facts are shared by sessions operating in the same placement world:
- placed object identity;
- GRID occupancy;
- SMOOTH occupancy;
- CELL/EDGE/FACE/CORNER mount occupancy;
- SMOOTH socket occupancy;
- committed save/restore records.
This is why two sessions can have different previews but still reject attempts to occupy the same committed location or mount.
What the host owns
GridPlacementHost registers sessions and routes interaction to the active session/services. It should not become another mutable copy of selection/placement state.
For a single-player scene:
host.configure(session)For controller-specific sessions:
host.register_session(controller_root, session, device_id)Unregister the session when the controller/owner leaves.
Scene adapters
Positioners, targeting casts, previews, and UI live in the scene tree. Connect them to the correct session/context instead of relying on hard-coded node paths.
This matters most for split-screen, nested scenes, and reusable level/player scenes.
Game configuration vs session state
Shared resources such as placement settings/profiles/catalog definitions describe what the game supports. A session describes what one controller is doing now.
Do not duplicate shared catalog/settings resources per session unless a session truly needs a different configuration. For per-player progression, filter availability instead of rewriting the master catalog.
Save/load
A session's temporary preview or pending action is not normally part of the saved placement world. Persist committed placement records and game state, then recreate session interaction state when the player resumes.
See Save and Load.