Skip to content
Grid Building Docs

CollisionGeometryUtils

Summary

Section titled “Summary”

Pure, stateless helpers used by the placement/collision mapping pipeline. These functions are extracted from the runtime mapper to allow focused unit tests and reuse from multiple contexts without side-effects.

Default Overlap Thresholds

  • Edge epsilon: 0.01 (1% tolerance for edge detection) - Minimum area fraction: 0.05 (5% of tile area required for overlap) - Very small polygons (< 5% of tile area) are filtered out to avoid spurious detections - For 16×16 tiles, minimum overlap area is 12.8 square units - For 32×32 tiles, minimum overlap area is 51.2 square units

Testing Notes

  • Micro polygons smaller than 5% threshold return zero tiles (by design) - Use larger polygons (≥25% tile area) for reliable collision detection in tests - Production mapper may use different thresholds for specific shape types

Documentation style: Comments use BBCode to render nicely in the Godot editor’s help panel.

Cross‑references - Center‑based tile semantics: Indicator and mapper math assume tile centers; e.g., 16×16 → center offset (+8,+8). - Iteration range epsilon: compute_tile_iteration_range applies symmetric epsilons to min/max to avoid fencepost tiles when world bounds align exactly to tile borders (bottom‑inclusive, top‑exclusive in practice).

Methods

Section titled “Methods”
static func build_shape_transform( col_obj: Node2D, shape_owner: Node2D ) -> Transform2D

Dependency: Calculator providing pure geometry operations such as polygontile overlap.

Builds a world transform for a specific collision shape_owner attached to a col_obj (the owning Node2D).

Order of operations

  1. Apply the object’s rotation and scale. 2) Apply the shape owner’s local rotation and scale. 3) Apply the shape owner’s local offset (position) in the object’s rotated/scaled space.

Returns identity when inputs are invalid.

Parameters

  • col_obj: Node2D — The collision object (owner of the shape). - shape_owner: Node2D — The node that carries the local transform for the shape.

Returns

  • Transform2D — World transform for the individual shape owner.

Notes

  • Keeps parity with legacy mapper logic; use when composing per-shape transforms. - Does not consider a TileMap’s transform; see the center_tile_for_* helpers for world↔local conversions against TileMap layers.
static func to_world_polygon( polygon_node: CollisionPolygon2D ) -> PackedVector2Array

Converts a CollisionPolygon2D to world-space points.

Applies the node’s global transform to each local polygon vertex. Returns an empty array when polygon_node is null.

Parameters

  • polygon_node: CollisionPolygon2D

Returns

  • PackedVector2Array — World-space vertices.
static func compute_tile_iteration_range( bounds: Rect2, map: TileMapLayer ) -> Dictionary

Converts world-space bounds to a tile iteration range.

Mirrors mapper iteration by computing the inclusive start tile and an exclusive end tile using the TileMap layer’s transform. A small epsilon is subtracted from the max corner to avoid fencepost inclusion of a tile when the bounds sit exactly on a tile border.

Parameters

  • bounds: Rect2 — World-space AABB to iterate over. - map: TileMapLayer — Target TileMap layer.

Returns

  • Dictionary — { "start" : Vector2i, "end_exclusive" : Vector2i }
static func center_tile_for_polygon_positioner( map: TileMapLayer, positioner: Node2D ) -> Vector2i

Computes the center tile for a polygon positioner node on a given TileMap layer. Uses map.to_local() followed by local_to_map() to respect map transforms. Returns Vector2i.ZERO if inputs are invalid.

Parameters

  • map: TileMapLayer - positioner: Node2D

Returns

  • Vector2i — Tile coordinates of the center.
static func center_tile_for_shape_object( map: TileMapLayer, col_obj: Node2D ) -> Vector2i

Computes the center tile for a collision shape-carrying object on a TileMap layer. Uses map.to_local() followed by local_to_map() to respect map transforms. Returns Vector2i.ZERO if inputs are invalid.

Parameters

  • map: TileMapLayer - col_obj: Node2D

Returns

  • Vector2i — Tile coordinates of the center.
static func compute_polygon_tile_offsets( world_points: PackedVector2Array, tile_size: Vector2, center_tile: Vector2i, tile_shape: TileSet.TileShape, tile_map_layer: TileMapLayer ) -> Array[Vector2i]

Computes tile offsets covered by a world-space polygon relative to a center_tile.

This delegates to CollisionGeometryCalculator.calculate_tile_overlap() with conservative defaults suitable for unit tests.

Thresholds

  • Edge epsilon: 0.01 (1% of tile size) - Min area fraction: 0.05 (5% of tile area)

Parameters

  • world_points: PackedVector2Array — Polygon in world space. - tile_size: Vector2 — Size of a tile in world units. - center_tile: Vector2i — Origin tile for computing offsets. - tile_type: TileSet.TileShape = TileSet.TILE_SHAPE_SQUARE — Tile shape type.

Returns

  • Array[Vector2i] — Offsets from center_tile for all overlapped tiles.

Notes

  • The production mapper may use different thresholds per shape type; these test defaults are intentionally conservative and stable.
static func is_polygon_convex( points: PackedVector2Array ) -> bool

Checks strict convexity of a polygon (winding-agnostic).

Uses cross product sign consistency and ignores collinear or duplicate edges. Triangles are considered convex.

Parameters

  • points: PackedVector2Array

Returns

  • bool — true if the polygon is strictly convex; otherwise false.

Source

Section titled “Source”

addons/grid_building/utils/collision_geometry_utils.gd

This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.