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 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
Do not move game-specific fields into Grid Placement only because the object is placeable.
Examples your game should own:
- 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.
Restore coordinated placement state
GRID, SMOOTH, CELL/EDGE/FACE/CORNER mounts, sockets, and shared occupancy 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, fence, or corner can look correct after loading while its logical mount key is missing. The next placement could then incorrectly reuse the same EDGE, FACE, CORNER, or socket.
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 terrain editing is not supported in Grid Placement 6.0, so this section applies to 2D TileMapLayer terrain.
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 legacy migration source 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/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. |