v6.0 Migration Guide

Migration tool removed in 6.2.2: run the converter in 6.2.1 or earlier, or convert by hand. The editor steps below describe the older tool.

Migrate a 5.x Project to 6.0

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 converter input is Grid Placement 5.0.9. The 5.x maintenance line may receive later patches; that does not automatically expand the converter contract. If your project is on a later 5.x patch, keep a source-controlled copy and verify the converter's dry-run findings before applying changes.

Before you start

1. Commit or back up the 5.x project.
2. Make sure the project opens cleanly on the supported 5.0.9 converter input before conversion, or explicitly verify any later-maintenance differences in the dry run.
3. Work on a migration branch/copy, not your only project files.

Use the editor converter

With Grid Placement 6.2.1 or earlier:

1. Run Project → Tools → Grid Placement → Migrate 5.x Project (Dry Run)….
2. Read every finding. The dry run does not modify the project.
3. Resolve anything the converter cannot map safely.
4. Run Migrate 5.x Project (Apply)….
5. Run the dry run again. It should report zero remaining convertible findings.
6. 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.2.0 supports GridMap object placement in GRID and SMOOTH modes, including supported CELL/EDGE/FACE/CORNER/TOP/socket workflows, manipulation, persistence, and configurable slope/support rules.

3D GridMap terrain painting was not part of 6.0. It is available in current releases with game-authored rule evaluation; see 3D Terrain Painting.

Profiles replace loose category-only authoring

PlacementProfile is the reusable entry 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 entry 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 for discrete objects; GridMap paint brushes follow the same rule model as 2D terrain.

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 entries.
• 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 current 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.

Related guides

• Getting Started
• 2D Object Scene Setup
• Placement Workflow
• 3D Object Placement
• Save and Load
• Migration Reference