v6.0 Migration Guide

Grid Placement 6.0 is a runtime/API rewrite. Do not replace the addon in a production 5.x project and hope the old scene wiring continues to work.

The supported migration source is the final legacy 5.0.9 project format.

Before you start

Commit or back up the 5.x project.
Make sure the project opens cleanly on 5.0.9 before conversion.
Work on a migration branch/copy, not your only project files.

Use the editor converter

With the 6.0 addon available:

Run Project → Tools → Grid Placement → Migrate 5.x Project (Dry Run)….
Read every finding. The dry run does not modify the project.
Resolve anything the converter cannot map safely.
Run Migrate 5.x Project (Apply)….
Run the dry run again. It should report zero remaining convertible findings.
Open the converted scenes/resources and run the project under 6.0.

The converter creates backups/a migration report for the files it changes. It fails closed on ambiguous transformations instead of guessing.

Main architecture change

The 6.0 runtime model is:

GridPlacementHost
  └─ registered PlacementSession(s)
       ├─ selection / coordinate mode
       ├─ targeting state
       ├─ rules/settings
       └─ per-controller interaction state

PlacementLevelContext connects the active level surface/object parent, and PlacementOwner identifies the player/controller performing the interaction.

New integrations should use this model instead of rebuilding the old multi-system-node runtime.

Product-scope changes to understand

2D

6.0 supports TileMapLayer scene-object placement and terrain painting. Terrain brushes are SINGLE, LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, and FLOOD_FILL. Object LINE placement is opt-in by profile/category.

3D

6.0 supports GridMap object placement in GRID and SMOOTH modes, including supported CELL/EDGE/FACE/socket workflows, manipulation, persistence, and configurable slope/support rules.

6.0 does not provide 3D GridMap terrain editing/painting.

Profiles replace loose category-only authoring

PlacementProfile is the reusable placeable category/tool/rule configuration surface. Use it when multiple entries should share behavior such as:

supported placement tools;
common validation/rules;
building vs decoration behavior;
object LINE capability.

A ScenePlacementEntry still describes the individual placeable scene.

Keep terrain and scene objects separate

Use 2D terrain painting for TileMapLayer terrain cells that should participate in Godot terrain/tile workflows.

Use scene objects when each placement needs its own node identity, script, health/state, manipulation, mount data, save record, or object-level demolition.

In 3D, use object placement; do not migrate 2D terrain-painting assumptions into GridMap terrain editing.

Reconnect game-owned systems

After conversion, verify integrations that belong to your game rather than the plugin:

inventory/economy and costs;
construction/progression/ownership;
custom placement rules/world facts;
save-domain data beyond placement records;
custom UI/input;
multiplayer/session ownership.

Keep game-domain authority outside Grid Placement. Consume placement results rather than duplicating plugin occupancy/validation.

Migration verification checklist

Dry run reports no unresolved convertible references.
Converted scenes/resources import without errors.
One 2D or 3D object can preview, validate, and commit.
Manipulation/removal works for supported placeables.
Save → restore → continue works for the workflows your game uses.
Custom rules/inventory/game-owned hooks still receive the expected placement outcomes.
If using 3D, GRID/SMOOTH/mount/slope behavior matches the 6.0 guides rather than 5.x assumptions.
No project code depends on legacy 5.x docs as the current API reference.

Need the rename details?

Use Migration Reference for removed concepts, common serialized renames, and compatibility notes.