Grid Placement provides placement identity/state and restore helpers. Your game still owns the complete save file, profile/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/SMOOTH coordinate/occupancy evidence;
- EDGE/FACE/socket mount evidence when applicable;
- game-owned custom data that your game needs.
Do not save preview ghosts 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
Do not move game-domain fields into Grid Placement just because the object is placeable.
Examples your game should own:
- health/durability;
- inventory contents;
- faction/owner id;
- construction progress;
- quest/progression state.
Store them keyed by your game identity and/or placement_instance_id, then reconnect them after placement restore.
Restore as one placement world
GRID, SMOOTH, CELL/EDGE/FACE mounts, sockets, and shared occupancy are related projections of the same committed placement world.
Restore them through the supported PlacementWorldRestoreCoordinator2D / PlacementWorldRestoreCoordinator3D path rather than rebuilding one occupancy registry independently.
A healthy restore sequence is:
- clear the existing committed placement world;
- load authoritative saved placement records;
- instance/restore placed scenes and stable IDs;
- rebuild GRID/SMOOTH/mount/socket occupancy consistently;
- validate the restored world;
- continue placing/moving/removing without duplicate occupancy.
3D mounts and sockets
3D save data must preserve the mount/socket relationship, not only the final transform.
Why: a wall/window/fence can look correct after loading while the logical EDGE/FACE/socket key is missing. The next placement could then incorrectly reuse the same mount.
Restore must reproduce both the visible transform and the occupancy/provider relationship.
2D terrain persistence
2D terrain cells are not PlaceableInstance scene objects. Persist the TileMapLayer terrain/cell data through the terrain persistence path or your game save system.
Keep the same TileSet/terrain definitions available when loading saved terrain indices.
3D terrain editing is not part of Grid Placement 6.0, so this terrain-persistence section applies to 2D TileMapLayer terrain.
Continue-after-restore check
Do not consider save/load proven because objects reappear visually.
After restore, test at least:
- place a new valid object;
- reject an overlap/duplicate mount;
- move/cancel a restored object;
- remove/re-place and confirm occupancy frees correctly;
- for 3D, verify GRID + SMOOTH + EDGE/FACE/socket state if your project uses them.
5.x save migration
The supported legacy migration source is 5.0.9.
5.x placement data does not contain every 6.0 identity/occupancy field. The 5.x→6.0 project migration and restore path may generate/rebuild the missing 6.0 identity as part of conversion. Do not expect an untouched 5.x save schema to provide native 6.0 mount/SMOOTH evidence.
See Migrate a 5.x Project to 6.0.
Common failures
| Symptom | Likely cause |
|---|---|
| Object appears twice | Restore/scene bootstrap both committed it, or stable identity was ignored. |
| Visual object restored but target mount is reusable | EDGE/FACE/socket occupancy relationship was not restored. |
| SMOOTH overlaps after load | World occupancy was rebuilt independently/incompletely. |
| New placements all reject after load | Stale occupancy was not cleared/reconciled 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. |