Migration Guide

Use Migrate a 5.x Project to 6.0 for the normal upgrade workflow. This page explains the major changes the converter/project migration must account for.

Migration source

The supported legacy conversion source is Grid Placement 5.0.9.

Run the editor dry-run/apply converter against a source-controlled project. Do not hand-edit hundreds of serialized paths before seeing what the converter can handle safely.

Runtime model

5.x used a set of placement/building system nodes as the primary runtime model. 6.0 uses:

GridPlacementHost — shared runtime coordinator.
PlacementSession — per-player/per-controller placement interaction state.
PlacementLevelContext — active level surface/object-parent context.
PlacementOwner — interaction owner.
PlacementInjectorSystem — optional editor-composed injection/template helper.

PlacementSystem is not the supported 6.0 runtime dispatch path.

Common serialized mappings

The converter handles the canonical mapping table; common examples include:

5.x concept	6.0 concept
`Placeable`	`ScenePlacementEntry`
`GBCompositionContainer`	`PlacementSession`
`GBInjectorSystem`	`PlacementInjectorSystem`
`tags`	`profiles`
`composition_container`	`session`
old building/targeting/manipulation system subtrees	host/session-owned runtime wiring

The complete field/path map lives in migration/mapping-5x-to-6x.md in the development repository. Let the converter apply deterministic rewrites; manually handle only findings it explicitly cannot resolve.

Placement profiles

PlacementProfile is the reusable 6.0 category/tool/rule configuration. A ScenePlacementEntry describes the individual placeable.

If 5.x code used loose tags to decide behavior, migrate that behavior into profiles/rules rather than recreating string checks throughout game code.

2D and 3D scope

2D

TileMapLayer object placement.
TileMapLayer terrain painting.
Terrain brushes: SINGLE, LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, FLOOD_FILL.
Optional object LINE placement by profile/category.

3D

GridMap GRID and SMOOTH object placement.
CELL, EDGE, FACE/socket structure workflows.
Multi-cell footprints, manipulation, persistence, and configurable slope/support.

Not migrated as a 6.0 feature: 3D GridMap terrain editing/painting.

Save/load

Do not treat placement persistence as independent copies of GRID, SMOOTH, and mount state. 6.0 coordinates restoration through the placement world so identity and occupancy projections rebuild consistently.

After migration, verify the actual workflows your project uses:

place;
save;
clear/reload;
restore;
continue placing/manipulating without duplicate occupancy.

See Save and Load.

Directional sprite workflows

ManipulatableSettings.disable_rotation_transform supports workflows where placement rotation changes logically but the visual art is swapped by the game instead of rotating the node transform.

Use this for authored cardinal sprites. Rotation input/state still advances; your consumer chooses the matching art frame. See Directional Sprite Rotation Demo.

Do not assume a 2D sprite-swap option changes 3D GRID mount/yaw rules.

Removed concepts

Removed/legacy surface	6.0 direction
`PlacementSystem` runtime dispatch	`GridPlacementHost` + `PlacementSession`
legacy `GridTargetingState.ready_changed` signal	Query/validate current targeting state through the 6.0 runtime surface

When a symbol is not in the 6.0 API, migrate to the documented replacement rather than recreating a compatibility wrapper in game code.

Converter output

The editor converter can:

rewrite canonical addon script/resource paths;
rename known serialized classes/fields;
migrate supported cost/rule resource structures;
remove/replace known legacy runtime system subtrees;
write backup/report metadata;
fail closed on ambiguous mappings.

After Apply, run Dry Run again and inspect any remaining findings before deleting your migration branch/backups.