How to Move Multi-Tile Units on a Grid in Godot

The direct answer

To move a 2x2 or larger unit on a Godot grid, store one authoritative grid position: its anchor cell. Derive the occupied footprint and visual position from that anchor. Before changing it, check three separate things: the destination footprint fits, the transition doesn't touch blocked cells, and the cells required by your turn model aren't owned by another unit. Then commit the new anchor and animate toward the derived visual center.

The animation is never the source of truth.

This article uses the top-left occupied cell as the anchor, rectangular footprints measured with Vector2i, an orthogonal TileMapLayer, and one-cell steps. That matches the convention in the multi-size agent clearance guide and keeps every check in one coordinate system.

First choose the movement contract

“The unit is moving” means different things in different games. Pick the row that describes yours before deciding which cells must remain reserved.

Keep one authoritative grid position

The anchor is the unit's authoritative position, not its only state. A rotatable unit still has an orientation, and its footprint dimensions belong to its unit profile.

Use the top-left occupied cell as the anchor and derive every occupied cell from it. A 2x2 unit anchored at (6, 3) occupies (6, 3), (7, 3), (6, 4), and (7, 4). A 1x2 unit and a 2x1 unit use the same helper.

Use this convention everywhere: clearance, destination checks, reservations, rendering, save files, and replay commands. Mixing a top-left clearance map with center-anchored movement tests the wrong cells near every wall.

var anchor := Vector2i(6, 3)
var footprint_size := Vector2i(2, 2)

func footprint_cells(
    anchor: Vector2i,
    footprint_size: Vector2i
) -> Array[Vector2i]:
    var cells: Array[Vector2i] = []

    if footprint_size.x <= 0 or footprint_size.y <= 0:
        return cells

    for y in range(footprint_size.y):
        for x in range(footprint_size.x):
            cells.append(anchor + Vector2i(x, y))

    return cells

Fix the map_to_local() half-cell offset

TileMapLayer.map_to_local() returns the centered local position of one cell. That's exactly right for a 1x1 unit and wrong for the visual center of a 2x2 unit.

If the sprite is placed at map_to_local(anchor), a 2x2 body appears half a cell up and left of the four cells it occupies. For a 1x1 footprint the offset below is zero. For 2x2 it is half a cell in both directions; for 3x2 it is one full cell horizontally and half a cell vertically.

The returned position is local to the TileMapLayer. Use to_global() only if the moving node lives in global space. local_to_map() returns the cell containing a local position, so don't treat it as an exact floating-point inverse at cell boundaries.

The Godot docs also note that map_to_local() ignores TileData.texture_origin. Keep logical grid placement independent from tile art; apply a separate explicit visual_offset when the unit artwork needs one. For isometric or half-offset grids, define a layout-specific mapping instead of reusing this orthogonal formula unchanged. The broader coordinate setup lives in the TileMapLayer-to-navigation-grid guide.

func footprint_local_center(
    layer: TileMapLayer,
    anchor: Vector2i,
    footprint_size: Vector2i
) -> Vector2:
    var cell_size := Vector2(layer.tile_set.tile_size)
    var footprint_offset := (
        cell_size
        * Vector2(footprint_size - Vector2i.ONE)
        * 0.5
    )
    return layer.map_to_local(anchor) + footprint_offset

Check destination fit, transition geometry, and ownership separately

A legal endpoint doesn't automatically make a legal move. Before committing one step, run three distinct checks:

Fit is a property of a footprint at an anchor, not of an individual cell — transition cells get bounds and traversability checks instead.

1. Destination fit: can the complete footprint occupy the new anchor? Use a square clearance check or validate every destination cell. For W x H rectangles or circular bodies, use the shape-aware clearance predicate. If several square sizes share one search grid, the Annotated A* implementation shows where that predicate enters the frontier.
2. Transition geometry: are all conservatively touched cells inside the board and traversable?
3. Ownership: are the destination or time-indexed cells available under the movement contract chosen above?

Cardinal steps touch the endpoint union

For a one-cell cardinal move, an axis-aligned rectangular body touches the union of its old and new footprints. A 2x2 unit stepping right touches a 3x2 block: six cells.

The delta guard matters. Without it, a helper named “swept cells” can quietly accept jumps or diagonals while returning only endpoint cells.

The downloadable footprint_movement.gd implements these same guarded rules in one helper and is exercised by the headless verifier.

func cardinal_touched_cells(
    from_anchor: Vector2i,
    to_anchor: Vector2i,
    footprint_size: Vector2i
) -> Array[Vector2i]:
    var delta := to_anchor - from_anchor
    if abs(delta.x) + abs(delta.y) != 1:
        return []

    var seen: Dictionary = {}
    for cell in footprint_cells(from_anchor, footprint_size):
        seen[cell] = true
    for cell in footprint_cells(to_anchor, footprint_size):
        seen[cell] = true

    var cells: Array[Vector2i] = []
    for cell: Vector2i in seen:
        cells.append(cell)

    cells.sort_custom(func(a: Vector2i, b: Vector2i) -> bool:
        if a.y != b.y:
            return a.y < b.y
        return a.x < b.x
    )
    return cells

Diagonal steps need a conservative touched-cell set

Consider a 2x2 unit moving from anchor (0, 0) to (1, 1). The endpoint footprints don't contain (2, 0) or (0, 2), but the sliding body intersects both cells during the move.

At grid-cell resolution, a conservative touched set for this one-cell diagonal translation is the bounding rectangle of the two footprints: a 3x3 block with nine cells. This is intentionally conservative; the exact continuous swept polygon isn't itself a rectangle.

If partially touched cells count as blocked, the 3x3 set is a simple deterministic contract. If the body moves continuously and should pass according to collision geometry rather than cell rules, use a Godot physics shape cast. Cardinal-only movement is also valid when it's a deliberate design constraint rather than a hidden workaround.

func diagonal_touched_cells(
    from_anchor: Vector2i,
    to_anchor: Vector2i,
    footprint_size: Vector2i
) -> Array[Vector2i]:
    var delta := to_anchor - from_anchor
    if abs(delta.x) != 1 or abs(delta.y) != 1:
        return []

    var top_left := Vector2i(
        min(from_anchor.x, to_anchor.x),
        min(from_anchor.y, to_anchor.y)
    )
    var end := Vector2i(
        max(from_anchor.x, to_anchor.x) + footprint_size.x,
        max(from_anchor.y, to_anchor.y) + footprint_size.y
    )

    var cells: Array[Vector2i] = []
    for y in range(top_left.y, end.y):
        for x in range(top_left.x, end.x):
            cells.append(Vector2i(x, y))
    return cells

Ownership depends on when other moves resolve

For sequential tactical movement, commit the new anchor and destination footprint atomically, then animate the sprite. No other unit resolves a move during that animation, so the renderer doesn't redefine logical ownership frame by frame.

The reservation-table article ships a separate verified Godot project for that contract: destination claims, conflict ownership, undo, release, and 2x2 footprint reservations.

For queued or simultaneous movement, destination ownership isn't enough. Two units can swap positions, cross the same edge, or occupy the same swept region at different moments. Resolve requests in a deterministic batch and add a time dimension to reservations. Holding the endpoint union until an animation callback fires can be a conservative policy, but it isn't a universal substitute for space-time conflict resolution.

For real-time movement, reservations solve planning conflicts; they don't prove physical clearance along the animated trajectory. Use a shape sweep for that.

Rotation needs a declared pivot

A rectangular footprint changes dimensions when it turns. If the pivot is the top-left anchor, a 1x2 unit becomes 2x1 while keeping the same anchor. Validate the rotated footprint exactly as you would a move: bounds, traversability, clearance, and ownership.

That convention shifts the visual center. On 80x56 cells, the verified 1x2 to 2x1 example moves the center by (40, -28) pixels while the anchor stays fixed. That's the consequence of rotating around the top-left corner.

If the unit must rotate around its visual center, compute a new anchor as part of the rotation command. Some even/odd footprint combinations place that center between cells, so define the pivot and rounding rule before writing the move. Never rotate the sprite first and discover afterward that the new footprint is inside a wall.

func rotated_size_clockwise(size: Vector2i) -> Vector2i:
    return Vector2i(size.y, size.x)

func rotate_around_top_left(
    anchor: Vector2i,
    footprint_size: Vector2i
) -> Dictionary:
    return {
        "anchor": anchor,
        "footprint_size": rotated_size_clockwise(footprint_size),
        "pivot": "top_left",
    }

What the verified Godot 4.7 proof covers

The source project contains the full helper, a runnable before/after scene, and a headless verifier. Its machine-readable receipt records 11 named checks on Godot 4.7 stable.

The checks cover 1x1, 2x2, 1x2 and 2x1 footprints, non-square tile dimensions, six-cell cardinal coverage, nine-cell conservative diagonal coverage, invalid moves, bounds, the top-left rotation contract, and runnable-scene smoke.

Measurement-gap: this article makes no performance or throughput claim, so it doesn't publish a benchmark or Dataset. Its evidence is the named correctness suite and reproducible source project. The receipt also states what the project doesn't prove: simultaneous reservation policy and exact continuous physics sweeps.

Common mistakes

Centering the sprite on map_to_local(anchor). That's the center of one cell, not an even-sized footprint.

Keeping both a sprite position and an anchor authoritative. They disagree after an interrupted tween, load, or replay. Store the anchor and derive the visual position.

Using size: int before adding rectangular rotation. A square-only model can't represent 1x2 becoming 2x1.

Checking only the destination. A diagonal body can touch cells outside both endpoint footprints.

Calling every touched cell a clearance check. Clearance answers whether a footprint fits at an anchor; transition cells need bounds and traversability checks.

Holding old cells until animation finishes without defining the turn model. That can be unnecessarily restrictive for sequential turns and still insufficient for simultaneous edge or time conflicts.

Rotating without naming the pivot. Keeping the same anchor means top-left pivot, not center pivot.

Applying orthogonal tile-size arithmetic to isometric grids. Define a layout-specific mapping instead.