Grid Placement provides stable placement IDs, placement records, and restore helpers. Your game still owns the complete save file, profile or cloud format, versioning, and game-specific data.
What must be preserved
For placed scene objects, preserve enough information to rebuild:
- stable
placement_instance_id; - originating
ScenePlacementEntry; - transform;
- GRID or SMOOTH occupancy data;
- CELL/EDGE/FACE/CORNER/TOP mount data or SMOOTH socket data when applicable;
- any game-owned data your game needs.
Do not save placement previews or temporary manipulation copies as committed objects.
PlaceableInstance
Committed objects use PlaceableInstance for stable placement identity and base serialization data.
Typical plugin-owned fields include:
| Field | Purpose |
|---|---|
instance_name |
Restored node name. |
transform |
Serialized placement transform. |
placeable |
ScenePlacementEntry reference/load data. |
placement_instance_id |
Stable 6.0 placement identity. |
Game-owned data can be stored alongside these fields in your save wrapper.
Save game-owned state separately
Game-specific fields can stay under the game's own identity rather than moving into Grid Placement.
Examples of game-owned state:
- health or durability;
- inventory contents;
- faction or owner ID;
- construction progress;
- quest or progression state.
Store that data under your game identity and/or placement_instance_id, then reconnect it after placement restore.
One canonical copy per fact. Plugin placement records and the game save are separate scopes: the game owns authoritative entities and their save schema, while the plugin placement record carries placement bookkeeping. PlaceableInstance.saved_game_data passes game-owned save fields through plugin round trips, and snapshot_lifecycle()/restore_lifecycle() cover plugin identity only.
Restore coordinated placement state
GRID, SMOOTH, CELL/EDGE/FACE/CORNER/TOP mounts, sockets, and shared occupancy are related projections of the same committed placement world and must be restored together.
Use PlacementWorldRestoreCoordinator2D or PlacementWorldRestoreCoordinator3D instead of rebuilding one occupancy registry on its own.
A reliable restore sequence is:
- Clear the existing committed placement world.
- Load the saved placement records.
- Restore placed scenes and stable IDs.
- Rebuild GRID, SMOOTH, mount, and socket occupancy together.
- Validate the restored placement world.
- Continue placing, moving, or removing objects.
3D mounts and sockets
3D save data must preserve the mount or socket relationship, not only the final transform.
A wall, window, corner, roof, or socket-mounted object can look correct after loading while its logical mount key is missing. The next placement could then incorrectly reuse the same EDGE, FACE, CORNER, TOP, or socket occupancy.
Restore both the visible transform and the occupancy/provider relationship.
2D terrain persistence
2D terrain cells are not PlaceableInstance scene objects. Persist TileMapLayer terrain/cell data through the terrain persistence path or your game save system.
Keep the same TileSet and terrain definitions available when loading saved terrain indices.
3D GridMap painted cells persist through the coordinated 3D restore path (full-grid snapshot); the TileMapLayer terrain persistence below is the 2D equivalent. See 3D Terrain Painting.
Continue-after-restore check
Objects reappearing on screen is not enough to prove save/load correctness.
After restore, test at least:
- place a new valid object;
- reject an overlap or duplicate mount;
- move and cancel a restored object;
- remove and re-place an object, then confirm the old occupancy was released;
- for 3D, verify the GRID, SMOOTH, mount, and socket paths your project actually uses.
5.x save migration
The supported converter input is 5.0.9.
5.x placement data does not contain every 6.0 identity or occupancy field. During 5.x → 6.0 migration, the restore path may need to generate or rebuild missing 6.0 placement identity and occupancy data.
Do not expect an unchanged 5.x save schema to contain native 6.0 mount or SMOOTH occupancy data.
See Migrate a 5.x Project to 6.0.
Common failures
| Symptom | Likely cause |
|---|---|
| Object appears twice | Restore and scene bootstrap both committed it, or stable identity was ignored. |
| Visual object restored but target mount is reusable | EDGE/FACE/CORNER/TOP/socket occupancy was not restored. |
| SMOOTH overlaps after load | World occupancy was rebuilt independently or incompletely. |
| New placements all reject after load | Stale occupancy was not cleared before restore. |
| Terrain looks wrong | Different/missing TileSet or terrain indices. |
| Game-specific object state disappeared | It was never stored by the game save layer. |