v6.0 Migration Guide

Grid Placement 6.0 is a major upgrade for existing Grid Building / Grid Placement 5.x users. This guide focuses on practical project migration: what changed, what to rename, and which setup path to use going forward.

Audience: existing 5.x users upgrading a game project.
Scope: GDScript plugin line. The beginner-facing 6.0 path is 2D TileMapLayer placement.

1. Product and Addon Naming

The product name is now Grid Placement.

The old Grid Building name described one common use case: placing buildings. The new name describes the broader plugin surface: placing terrain, scene objects, decorations, fences, roads, walls, interactables, and other grid-authored content.

Compatibility aliases may remain where provided, but new docs and examples use the Grid Placement naming family.

2. Recommended Setup Path

For new 6.0 wiring, use GridPlacementHost as the main runtime node and PlacementSession as the per-player/per-controller state root.

Recommended runtime shape:

GridPlacementHost
PlacementSession resource
GridPositioner2D for human targeting
PlacementLevelContext for target_map + objects_parent
PlacementOwner on the actor/player that performs placement

PlacementInjectorSystem is still useful for editor-composed template scenes, but the docs should treat GridPlacementHost + PlacementSession as the primary mental model.

3. System Template Migration

In 5.x, copied system-template scenes often wired several sibling nodes such as building, targeting, and manipulation systems.

In 6.0, prefer one host plus session/state resources. This reduces scene-tree wiring and makes split-screen or AI-driven controllers easier to model as additional sessions.

When upgrading:

1. Replace old copied system-template scenes with the 6.0 templates when possible.
2. Move runtime configuration into GridPlacementBundle, GridPlacementSettings, PlacementSession, PlacementLevelContext, and PlacementOwner.
3. Use GridPositioner2D for human placer targeting.
4. Keep old scene copies only as temporary migration references.

4. PlacementProfile Replaces Category-Only Tags

PlacementProfile is the canonical 6.0 category/settings resource.

Use a profile when several placeables should share behavior:

• buildings: normal grid placement, collision checks, cost rules
• decorations/doodads: optional grid-snap disable or lighter overlap behavior
• repeated props: opt-in object LINE placement
• terrain-adjacent content: category defaults that keep object placement separate from terrain painting

Decorations are not a separate placement mode. Decoration-like objects are grouped by profile and inherit category behavior.

5. Terrain vs Scene Objects

Use terrain tiles for content that visually connects to neighbors and benefits from tile/terrain workflows:

• fences
• walls
• roads
• hedges
• floors
• connected ground areas

Use scene objects when each placed thing needs per-instance identity:

• buildings
• crates
• lamps
• NPCs
• interactable props
• anything that needs scripts, health, selection, movement, or object-level demolish

Terrain uses terrain validation, paint gates, and terrain hooks. Scene objects use the object placement rules pipeline.

6. Brush Workflows

6.0 includes terrain brush workflows for:

• SINGLE
• LINE
• RECTANGLE_FILL
• RECTANGLE_OUTLINE
• FLOOD_FILL

Object LINE placement is opt-in through profile/category support. Do not assume every scene object can be line-placed.

Hexagonal tilemaps are an advanced path. Verify your exact hex tilemap, input, preview, and brush behavior before publishing support claims in your own game or store copy.

7. Placement Event Hooks

Important hooks include:

• pre_instance_added — object scene has been instantiated but is not yet in the tree.
• pre_terrain_paint — terrain paint is planned and can still be vetoed.
• post_terrain_paint — terrain paint landed successfully.
• pre_terrain_demolish — terrain demolish can still be vetoed.
• post_terrain_demolish / post_terrain_removed — terrain removal has completed.

Use these for game-level integration such as stamping runtime data, spawning overlays, blocking terrain placement during combat, or connecting custom economy/interaction logic.

8. Demolish Refund Migration

6.0 object refunds are centered on RefundService, RefundCalculator, BuildCost, and Refunder.

Use object refunds for demolishable scene objects with Manipulatable. Do not assume terrain tiles use the same object refund path; terrain cells are not Manipulatable scene objects.

See Refund on Demolish for the current object refund contract.

9. Naming Migration

New user-facing APIs should use the Placement* and GridPlacement* naming family.

Common examples:

Do not invent renamed methods from this table. Check the API/source for the exact method you need before migrating call sites.

10. Upgrade Checklist

Before upgrading a real project:

• Back up or branch your 5.x project.
• Replace copied templates with 6.0 templates where possible.
• Move setup toward GridPlacementHost + PlacementSession.
• Use GridPositioner2D for human targeting.
• Convert category/tag authoring to PlacementProfile.
• Decide which content is terrain and which content is a scene object.
• Wire terrain gameplay restrictions through terrain hooks such as pre_terrain_paint.
• Use RefundService for object refunds.
• Verify hex or other advanced grid claims in your own project before publishing them.

Related Guides

• Getting Started
• Choosing Terrain vs Objects
• Placement Workflow
• Refund on Demolish
• Naming Convention