Use tile coordinates when your game needs grid-aligned facts such as pathfinding, occupancy, save metadata, or a link between a placed object and covered TileMapLayer cells.
This guide is 2D-only. 3D GridMap placement uses its own cell/mount records; do not reuse these Vector2i examples for 3D.
Current targeted cell
Convert the active 2D positioner's world position through the target TileMapLayer:
var targeting:GridTargetingState = container.get_states().targeting
var map:TileMapLayer = targeting.target_map
var positioner:Node2D = targeting.positioner
if map!= null and positioner!= null:
var cell:= PlacementPositioning2DUtils.get_tile_from_global_position(
positioner.global_position,
map
)Use this for cursor/UI feedback. It is not proof that placement succeeded.
Successful object placement
For committed placement, consume the placement result instead of guessing from the cursor position:
func _ready()-> void:
container.get_building_state().action_performed.connect(_on_action_performed)
func _on_action_performed(data:PlacementActionData)-> void:
if data== null or data.report== null or not data.report.is_successful():
return
var placed:Node = data.report.placed
var map:TileMapLayer = container.get_states().targeting.target_map
if placed== null or map== null:
return
var cell:= PlacementPositioning2DUtils.get_tile_from_global_position(
placed.global_position,
map
)In 6.0, success/failure and the placed node come from data.report. Do not depend on removed legacy PlacementActionData fields.
Terrain painting
Terrain paint callbacks already expose the target cell:
func _on_post_terrain_paint(data:TerrainPaintData)-> void:
print(data.target_cell)For LINE, rectangle, or FLOOD_FILL brushes, consume the brush/terrain result your workflow exposes. The cursor cell alone does not describe a multi-cell commit.
Terrain painting is a TileMapLayer feature in 6.0; this does not imply 3D GridMap terrain editing.
Multi-cell objects
If game logic needs every covered cell, derive the footprint from the same placement/rule geometry used by validation rather than from sprite bounds. Decorative pixels are not occupancy authority.
For example, rules that expose their checked tile positions can provide the exact cells they validated:
var cells:Array[Vector2i]= rule.get_tile_positions()Save/load ownership
Grid Placement persists its placement records. Extra game-domain metadata such as an anchor_tile, job id, faction id, or pathfinding reservation belongs in your game save unless a public plugin record already owns that fact.
Do not duplicate plugin occupancy as a second placement authority merely to remember a cell coordinate.