You do not need this page for first setup. Use it when deciding who owns state or policy.
Vocabulary: entry, placeable, manipulation
Three words cover three different things. Mixing them up is the most common source of confusion in 6.0:
| Term | What it is | Example |
|---|---|---|
| Placement entry | The resource record describing what can be placed. PlacementEntry is the abstract base; ScenePlacementEntry describes a scene object, TilePlacementEntry describes a terrain. Never the thing itself. |
ScenePlacementEntry with packed_scene set. |
| Placeable | The catalog thing: what the selection UI lists and what gets instanced into the world. A noun for the object, not the resource. | ui/placeable/ scenes, PlaceableInstance on committed objects, placement/placeables/ catalog folders. |
| Manipulation | Post-commit operations on placed instances: move, rotate, flip, demolish. | ManipulationService2D, manipulate/demolish tools. |
The 5.x resource class literally named Placeable no longer exists; it was renamed to ScenePlacementEntry (see the migration reference). Generic "placeable" usage elsewhere — UI names, folder names, "supported placeables" — is intentional and stays.
Stable mental model
| Scope | Main surface | Owns |
|---|---|---|
| Shared configuration | GridPlacementBundle / settings/resources |
Reusable plugin configuration, actions, templates, rule/service configuration. |
| Player/controller | PlacementSession |
Mutable selection, targeting, coordinate mode, pending placement/manipulation state. |
| Runtime coordinator | GridPlacementHost |
Session registration, input/interaction routing, and service orchestration. |
| Shared placement world | Placement-world records/registries | Committed object identity, occupancy, mounts/sockets, restore authority. |
| Game domain | Your game | Inventory/economy, construction, ownership/factions, progression, game save schema, AI/pathfinding consequences. |
The key ownership rules
- Sessions own interaction state. Two players should not share one session unless they intentionally share selection/targeting/action state.
- The host routes; it does not become a second copy of placement state.
- Committed occupancy/identity is shared world authority. GRID, SMOOTH, mounts, and restore must not become independent competing truths.
- The game owns game meaning. Feed facts into validation and consume placement results instead of moving faction/economy/construction systems into the addon.
2D and 3D use the same ownership model
The dimensional details differ—TileMapLayer terrain/object paths vs GridMap GRID/SMOOTH/mounts—but the host/session/world ownership split stays the same.
This is intentional: adding a second player or a 3D coordinate mode should not require a second architecture.
When to create a game bridge
A simple game can connect directly to the public placement APIs. Add a typed game-side bridge/authority when your integration starts coordinating substantial game-owned policy such as costs, construction, ownership, or save-domain IDs.
Do not add a bridge merely to rename methods or wrap every plugin call.
See When to Write a Game Bridge.