Save and Load

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.

SceneEntryInstance

Committed objects use SceneEntryInstance for stable placement identity and base serialization data.

SceneEntryInstance.save() writes these plugin-owned keys:

Save key	Purpose
instance_name	Restored node name.
transform	Serialized placement transform.
scene_entry	ScenePlacementEntry reference/load data.
placement_instance_id	Stable placement identity.

If restore needs mount/socket and shared occupancy data, your save integration must also include mount and placement_world; SceneEntryInstance.save() does not write those records. Game-owned data can stay alongside these keys in the same dictionary.

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.

Keep one canonical copy per fact. Your game owns entities and its save schema; Grid Placement records placement bookkeeping. SceneEntryInstance.saved_game_data carries other dictionary fields through a plugin save/load round trip. snapshot_lifecycle() and restore_lifecycle() preserve lifecycle IDs and allocator state; they do not save objects or occupancy.

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:

1. Clear the existing committed placement world.
2. Load the saved placement records.
3. Restore placed scenes and stable IDs.
4. Rebuild GRID, SMOOTH, mount, and socket occupancy together.
5. Validate the restored placement world.
6. 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 SceneEntryInstance 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.

The 3D restore coordinator applies the GridMap cell data supplied by your save layer. Pass p_full_grid_snapshot = true when the data should replace the whole map. The 3D demo saves every used cell with its item and orientation, then clears the map before applying them so cells removed since the save do not remain. 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.

Related guides

• Placement Workflow
• 3D Object Placement
• Smooth Placement
• Session Ownership
• Migration Guide