Architecture Overview

You do not need this page for first setup. Use it when deciding who owns state or policy.

Vocabulary: entry, entry, manipulation

Three words cover three different things. Mixing them up is a common source of confusion:

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.
Entry	The catalog thing: what the selection UI lists and what gets instanced into the world. A noun for the object, not the resource.	ui/scene_entry/ scenes, SceneEntryInstance on committed objects, placement/entries/ catalog folders.
Manipulation	Post-commit operations on placed instances: move, rotate, flip, demolish.	ManipulationService2D, manipulate/demolish tools.

The 5.x resource class literally named Entry no longer exists; it was renamed to ScenePlacementEntry (see the migration reference). Generic "entry" usage elsewhere — UI names, folder names, "supported entries" — 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.
Placement mechanics (plugin) vs game simulation (consumer)	Plugin sessions/services vs your game	Plugin: placement-session state, candidate transforms, placement validity. Game: gameplay entities and consequences.

The key ownership rules

Grid Placement is authoritative for placement mechanics, not for the consuming game's simulation. It decides placement-session state, candidate transforms and placement validity. The consuming game remains authoritative for gameplay entities and consequences such as resources, construction, ownership, persistence and destruction.

1. Sessions own interaction state. Two players should not share one session unless they intentionally share selection/targeting/action state.
2. The host routes; it does not become a second copy of placement state.
3. Committed occupancy/identity is shared world authority. GRID, SMOOTH, mounts, and restore must not become independent competing truths.
4. The game owns game meaning. Feed facts into validation and consume placement results instead of moving faction/economy/construction systems into the addon.

Presentation is a separate layer

The addon's visual feedback is layered so a game can ship it without the placement mechanics:

• Authority layer: session, host, candidate transform and validity, commit, world records, manipulation, and lifecycle results.
• Presentation layer: contact ring, validity indicator, presentation profile, and visual settings. It copies verdicts and transforms; it never computes them.

An integration that decides placement itself — for example, a game whose own native simulation owns placement — can stage a copy with no authority code present. See Presentation-Only Consumption.

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.

Related guides

• Session Ownership
• Composition & Injection
• Placement World Facts Provider
• Placement Workflow
• Multiplayer & Split-Screen