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 removed editor converter accepted Grid Placement 5.0.9 as its supported input. Later 5.x maintenance patches did not automatically expand that contract. The converter is available only in 6.2.1 and earlier; for 6.2.2, convert by hand.
When using the converter, run its dry-run/apply flow against a source-controlled project. Do not hand-edit hundreds of serialized paths before seeing what it 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.
GBInjectorSystem converts to GridPlacementHost. The converter drops the dangling session property. Assign the session to GridPlacementHost.session and enable auto_configure and the host starts itself; when a controller owns the session, wire the host from that controller with configure(), register_session(), bind_scene_consumers(), and watch_scene_consumers() instead.
PlacementSystem is not the supported 6.0 runtime dispatch path.
Common serialized mappings
The converter handles canonical mappings such as:
| 5.x concept | Converter/6.0 result |
|---|---|
Entry |
ScenePlacementEntry |
GBCompositionContainer |
PlacementSession |
GBInjectorSystem |
Re-scripts to GridPlacementHost; the session property is dropped and the controller must wire the host. |
tags |
profiles |
composition_container |
dropped on host nodes; assign the session to GridPlacementHost.session + auto_configure, or pass it to host.configure() from a controller |
| old building/targeting/manipulation system subtrees | host/session-owned runtime wiring |
The complete field/path map was retired with the converter in 6.2.2; the table above lists the canonical mappings. With 6.2.1 or earlier, let the converter apply deterministic rewrites and 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 entry.
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.
3D GridMap terrain painting was not part of the 6.0 migration. It is
available in current releases; see 3D Terrain Painting.
TOP is the 6.2.0 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, available through 6.2.1, 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.
Related guides
Using this in a game?
Grid Placement v6.3.0 — full source, playable demos, commercial license
The guide above is the same setup the shipped demos use. Try the build in your browser before you buy it.