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;
- EDGE/FACE/socket occupancy;
- authoritative save/restore records.
This is why two sessions can have different previews but still reject attempts to occupy the same committed location/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 rather than searching for private nodes through hard-coded 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 rather than rewriting the master catalog.
Save/load
A session's transient preview/pending action is not normally the authoritative saved placement world. Persist committed placement records/game state, then recreate interaction/session state as appropriate when the player resumes.
See Save and Load.