Skip to content
Grid Building Docs

GBGeometryMath

Summary

Section titled “Summary”

Geometry & collision math utilities for the grid building addon.

Provides compact, well-documented helper functions used across the addon for tile/polygon overlap and collision tasks. Main responsibilities include: - Computing polygon vs polygon intersection areas (uses Godot Geometry2D). - Producing tile polygons for square and isometric tiles and testing polygon overlaps against tiles (area-based and optimized native collision checks). - Converting various Shape2D types to polygon approximations for geometry processing (Rectangle, Circle, Capsule, ConvexPolygon, fallback to rect). - Utility helpers: axis-aligned rectangle detection and polygon bounding rect.

:::note[Note] TILE SHAPE ENFORCEMENT: All functions use TileSet.TileShape enum values.

Use: TileSet.TILE_SHAPE_SQUARE, TileSet.TILE_SHAPE_ISOMETRIC, TileSet.TILE_SHAPE_HALF_OFFSET_SQUARE

Do NOT use: integers (0, 1, 2) or strings (“square”, “isometric”, etc.) :::

Methods

Section titled “Methods”
static func polygon_intersection_area( poly_a: PackedVector2Array, poly_b: PackedVector2Array ) -> float

Returns the intersection area between two polygons using Godot’s Geometry2D.

poly_a: PackedVector2Array - First polygon.

poly_b: PackedVector2Array - Second polygon.

Returns: float - Area of intersection (0.0 if no overlap).

static func get_tile_polygon( tile_top_left_pos: Vector2, tile_size: Vector2, tile_shape: TileSet.TileShape ) -> PackedVector2Array

Returns the corners of a tile as a polygon for collision or geometry checks.

tile_top_left_pos: Vector2 - Top-left position of the tile in world space.

tile_size: Vector2 - Size of the tile (width, height).

tile_shape: TileSet.TileShape - Tile shape from TileSet (SQUARE, ISOMETRIC, HALF_OFFSET_SQUARE).

Returns: PackedVector2Array - Polygon corners in counterclockwise order.

static func intersection_area_with_tile( polygon: PackedVector2Array, tile_top_left_pos: Vector2, tile_size: Vector2, tile_shape: TileSet.TileShape ) -> float

Returns the intersection area between a polygon and a tile polygon.

polygon: PackedVector2Array - The polygon to check.

tile_top_left_pos: Vector2 - Top-left position of the tile in world space (not center).

tile_size: Vector2 - Size of the tile (width, height).

tile_shape: TileSet.TileShape - Tile shape from TileSet (SQUARE, ISOMETRIC, etc.).

Returns: float - Area of intersection (0.0 if no overlap).

static func does_polygon_overlap_tile( polygon: PackedVector2Array, tile_top_left_pos: Vector2, tile_size: Vector2, tile_shape: TileSet.TileShape, epsilon: float ) -> bool

Returns true if the intersection area between a polygon and a tile polygon exceeds epsilon.

polygon: PackedVector2Array - The polygon to check.

tile_top_left_pos: Vector2 - Top-left position of the tile in world space (not center).

tile_size: Vector2 - Size of the tile (width, height).

tile_shape: TileSet.TileShape - Tile shape from TileSet (SQUARE, ISOMETRIC, etc.).

epsilon: float - Minimum intersection area to count as covered.

Returns: bool - True if intersection area > epsilon.

static func does_shape_overlap_tile_optimized( shape: Shape2D, shape_transform: Transform2D, tile_top_left_pos: Vector2, tile_size: Vector2, tile_shape: TileSet.TileShape, epsilon: float ) -> bool

Optimized collision detection using native Godot collision as primary method.

shape: Shape2D - The collision shape to test.

shape_transform: Transform2D - Transform of the shape.

tile_top_left_pos: Vector2 - Top-left position of the tile in world space (not center).

tile_size: Vector2 - Size of the tile.

tile_shape: TileSet.TileShape - Tile shape from TileSet (SQUARE, ISOMETRIC, HALF_OFFSET_SQUARE).

epsilon: float - Minimum overlap area (only used for polygon fallback).

Returns: bool - True if shape overlaps the tile.

static func does_polygon_overlap_tile_optimized( polygon: PackedVector2Array, tile_top_left_pos: Vector2, tile_size: Vector2, tile_shape: TileSet.TileShape, epsilon: float ) -> bool

Optimized polygon overlap detection - uses native collision when possible.

polygon: PackedVector2Array - The polygon points to test.

tile_top_left_pos: Vector2 - Top-left position of the tile in world space (not center).

tile_size: Vector2 - Size of the tile.

tile_shape: TileSet.TileShape - Tile shape from TileSet (SQUARE, ISOMETRIC, HALF_OFFSET_SQUARE).

epsilon: float - Minimum intersection area threshold.

Returns: bool - True if polygon overlaps the tile significantly.

static func _is_axis_aligned_rectangle( polygon: PackedVector2Array ) -> bool

Returns true if the polygon is an axis-aligned rectangle (all edges horizontal or vertical).

polygon: PackedVector2Array - Polygon to check.

Returns: bool - True if axis-aligned rectangle.

static func get_polygon_bounds( polygon: PackedVector2Array ) -> Rect2

Returns the bounding rectangle of a polygon.

polygon: PackedVector2Array - The polygon points.

Returns: Rect2 - Bounding rectangle of the polygon.

static func convert_shape_to_polygon( shape: Shape2D, transform: Transform2D ) -> PackedVector2Array

Converts a Shape2D to a polygon for consistent processing.

shape: Shape2D - The shape to convert.

transform: Transform2D - Transform to apply to the shape.

Returns: PackedVector2Array - Polygon representation of the shape.

static func intersection_polygon_area( points: PackedVector2Array ) -> float

Calculates the area of a polygon defined by a PackedVector2Array. Used to determine the area of intersection between two polygons (e.g., tile and collision shape). Returns 0.0 if the input does not form a valid polygon (fewer than 3 points). This is used in overlap checks to ensure that only true area overlaps (not just edge or point contacts) are counted.

static func is_exact_polygon_match( poly_a: PackedVector2Array, poly_b: PackedVector2Array ) -> bool

Checks if two polygons are exactly the same (vertex by vertex)

static func exact_polygon_area( poly: PackedVector2Array ) -> float

Returns area for exact polygon match

Source

Section titled “Source”

addons/grid_building/utils/gb_geometry_math.gd

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