Chris' Tutorials
Docs/Grid Placement

Grid Placement v6.0

Surface and Brush Reference

Review supported 6.0 placement surfaces, brush modes, and commit behavior.

StatusDraft
Versionv6.0
UpdatedDevelopment docs generated from GDScript source

This is unreleased documentation in active development. APIs, class names, and behavior may change before the final release.

Draft — Unreleased:This page is in active development. APIs, class names, and behavior may change before the release is finalized. Use it as a preview of what's coming — not as a stable integration target.

Use this page as the release-facing checklist for what Grid Placement 6.0.0 publicly supports and how the shipped demos exercise it.

Version note: Grid Placement 6.0.0's buyer-facing package is the 2D TileMapLayer path on Godot 4.5.0 through 4.7. The 3D placement surface exists for internal/next-release development and is not part of the public 6.0 support promise.

Shortest Successful Path

For a first integration, keep the path deliberately small:

  1. Install and enable addons/grid_placement.
  2. Run Project -> Tools -> Grid Placement / Setup Default Input Actions.
  3. Start from the shipped systems/template scenes instead of hand-building every node.
  4. Assign one PlacementLevelContext.target_map (TileMapLayer) and one PlacementLevelContext.objects_parent (Node2D).
  5. Add or select one ScenePlacementEntry object.
  6. Confirm one object placement.
  7. Add one terrain palette/entry only after object placement works.
  8. Confirm one terrain SINGLE paint.

Do not start with custom inventory, save/load, web export, split-screen, hex grids, or flood fill. Add those only after the basic object and terrain paths are green.

See Getting Started for the full setup walk-through.

Shipped 6.0 Demo Entry Points

The 6.0 package ships these public 2D demos:

Demo Surface What to try first
Top-down 2D placement Square/top-down TileMapLayer Select a scene object, place it, then select terrain and paint SINGLE.
Isometric 2D placement Isometric TileMapLayer Place a simple object and verify targeting/preview lines up with the isometric map.
Platformer 2D placement 2D platformer map Place the demo box/object and verify collision-based validation.
Hex 2D terrain demo Advanced TileMapLayer path Verify SINGLE, LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, and FLOOD_FILL behavior.

The 3D demo/config is internal-only for 6.0 release packaging. Do not present 3D placement as a supported public 6.0 surface unless the release package and release notes explicitly change that contract.

Supported vs Experimental Surfaces

Surface 6.0 public support Notes
Square/top-down 2D object placement Supported Recommended beginner path.
Square/top-down 2D terrain painting Supported SINGLE, LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, and FLOOD_FILL are the documented terrain brush modes.
Isometric 2D object placement Supported with project verification Verify tile transforms, collision layers, and visuals in your own map.
Isometric 2D terrain painting Supported through 2D TileMapLayer workflows Brush generation is in cell space; verify visuals/masks in your project.
Hex 2D terrain brushing Supported advanced 2D path Runtime proof covers the shipped hex tileset for SINGLE, LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, FLOOD_FILL, preview-no-mutation, commit, and cancel. Verify visuals/masks in your own project.
Web export Supported only after web-specific smoke proof Web resource loading is stricter than editor/desktop; see Web Export Guide and #310.
3D placement / GridMap terrain Internal/deferred for 6.0 public package 6.1 work may exist in branches/PRs, but 6.0 docs/store copy should not sell it as supported.

Brush Mode Matrix

Mode Terrain painting Object placement Commit semantics
SINGLE Supported Supported Hover/preview one cell; click/confirm commits one terrain cell or one object.
LINE Supported Opt-in by profile/category Press/hold at start cell, drag to end cell, release to validate/commit generated cells or object instances.
RECTANGLE_FILL Supported Not part of public object placement surface Press/hold at corner A, drag to corner B, release to validate/commit filled terrain cells.
RECTANGLE_OUTLINE Supported Not part of public object placement surface Press/hold at corner A, drag to corner B, release to validate/commit perimeter terrain cells.
FLOOD_FILL Supported terrain-region operation Not an object placement mode First click anchors/shows the pending region; second click commits; cancel clears the pending region without painting.

Important behavior:

  • Drag/rectangle/line preview must not mutate the real TileMapLayer before commit.
  • Flood-fill preview must not mutate the real TileMapLayer until the second confirm.
  • Object placement runs final validation at commit time. A preview that looked valid earlier can still fail if the world changes before confirm.
  • Object LINE placement is opt-in. Do not assume every placeable supports it.

Terrain Brush Cell Cap

PlacementSettings.max_terrain_brush_cells limits how many cells one terrain brush action may generate.

Setting Meaning
Default 4096 cells per terrain brush action.
Inspector clamp Values are clamped to [1, 16384].
Runtime hard ceiling 16384 cells, even if a resource is hand-edited or misconfigured.
Applies to LINE, RECTANGLE_FILL, RECTANGLE_OUTLINE, and FLOOD_FILL.
Why it exists Prevents accidental frame spikes or unbounded flood/drag work.

If a large drag/flood-fill paints fewer cells than expected, inspect this setting before debugging terrain rules.

Common Claim Boundaries

Use these phrases in docs/store copy:

  • Good: "Grid Placement 6.0 supports 2D object placement and 2D terrain painting on Godot TileMapLayer."
  • Good: "Hex terrain brushing is supported as an advanced 2D TileMapLayer path; verify visuals and masks in your project."
  • Good: "3D placement work is internal/deferred for the public 6.0 package."
  • Avoid: "All grid types are fully supported"; 6.0's public promise is 2D TileMapLayer, with hex terrain brushing as an advanced verified path.
  • Avoid: "3D/GridMap placement is included in 6.0" unless the release package explicitly changes.
  • Avoid: "Flood fill paints immediately on click"; it uses anchor/second-confirm semantics.

Related Open or Recently Closed Issues

  • #164 — package/export/docs reconciliation owns the final release package contract.
  • #282 — hex-grid multi-cell terrain brush verification (closed by the runtime proof for supported advanced hex terrain brushing).
  • #310 — WebGL/browser smoke workflow before web uploads.
  • #386 — terrain/object brush commit semantics audit (closed; this guide reflects those semantics).
  • #387 — terrain brush cell cap (closed; this guide documents the cap).

Related Guides

Source

docs/v6-0/guides/surface-and-brush-reference.md

Plugin docs root:gdscript/plugins/grid_placement_dev/docs