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 converter input remains Grid Placement 5.0.9. Later 5.x maintenance patches do not change that converter contract unless the migration tooling explicitly says otherwise.
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— canonical shared runtime coordinator.PlacementSession— per-player/per-controller placement interaction state.PlacementLevelContext— active level surface/object-parent context.PlacementOwner— interaction owner.
PlacementInjectorSystem remains only as a compatibility path for converted/editor-composed scenes that still depend on injection. It is not the recommended destination architecture for a newly authored or actively modernized 6.0 scene.
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 | Converter/6.0 result |
|---|---|
Placeable |
ScenePlacementEntry |
GBCompositionContainer |
PlacementSession |
GBInjectorSystem |
May map to PlacementInjectorSystem to preserve legacy scene wiring; converge maintained scenes on GridPlacementHost. |
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.
A converter mapping is not necessarily the preferred architecture for new code. Compatibility rewrites exist so old projects can migrate safely without requiring every scene to be redesigned in the same step.
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
TileMapLayerobject placement.TileMapLayerterrain painting.- Terrain brushes:
SINGLE,LINE,RECTANGLE_FILL,RECTANGLE_OUTLINE,FLOOD_FILL. - Optional object
LINEplacement by profile/category.
3D
GridMapGRID and SMOOTH object placement.- CELL, EDGE, FACE, CORNER, and TOP structure workflows, plus optional SMOOTH sockets.
- Multi-cell footprints, manipulation, persistence, and configurable slope/support.
Not migrated as a 6.0 feature: 3D GridMap terrain editing/painting.
TOP is the 6.0.1 GRID roof/gable/ridge mount. Do not recreate old 5.x assumptions about roof presentation as a custom snap-family convention; follow the current 3D Object Placement contract.
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 rebuild together.
After migration, verify the actual workflows your project uses:
- Place.
- Save.
- Clear or reload.
- Restore.
- Continue placing or 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 2D Object Scene Setup.
Do not assume a 2D sprite-swap option changes 3D GRID mount or yaw rules.
Removed concepts
| Removed/legacy surface | 6.0 direction |
|---|---|
PlacementSystem runtime dispatch |
GridPlacementHost + PlacementSession |
PlacementContainer compatibility adapters |
PlacementSession directly |
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 or replace known legacy runtime system subtrees;
- write backup/report metadata;
- reject ambiguous mappings for manual review.
After Apply, run Dry Run again and inspect any remaining findings before deleting your migration branch or backups.