GridMathUtils

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: shared/math/grid_math_utils.gd

Version: 6.0

class_name: GridMathUtils extends: RefCounted

Signals

(none)

Exports

(none)

Methods

• distance(pos1: Vector2i, pos2: Vector2i) -> float
• manhattan_distance(pos1: Vector2i, pos2: Vector2i) -> int
• is_adjacent(pos1: Vector2i, pos2: Vector2i) -> bool
  • Determines if two grid positions are orthogonally adjacent (cardinal directions only).

  • Preconditions:

  • • Both pos1 and pos2 must be valid Vector2i instances

  • Postconditions:

  • • Returns true if positions are exactly 1 unit apart in x or y, but not both
  • • Returns false if positions are the same, diagonal, or more than 1 unit apart

  • Invariants:

  • • is_adjacent(pos1, pos2) == is_adjacent(pos2, pos1)
  • • is_adjacent(pos, pos) == false
  • • If is_adjacent(pos1, pos2) then manhattan_distance(pos1, pos2) == 1

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• is_diagonal(pos1: Vector2i, pos2: Vector2i) -> bool
  • Determines if two grid positions are diagonally adjacent.

  • Preconditions:

  • • Both pos1 and pos2 must be valid Vector2i instances

  • Postconditions:

  • • Returns true if positions are exactly 1 unit apart in both x and y
  • • Returns false if positions are the same, orthogonal, or more than 1 unit apart

  • Invariants:

  • • is_diagonal(pos1, pos2) == is_diagonal(pos2, pos1)
  • • is_diagonal(pos, pos) == false
  • • If is_diagonal(pos1, pos2) then manhattan_distance(pos1, pos2) == 2

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• get_neighbors(pos: Vector2i, include_diagonal: bool = true) -> Array
  • Returns all valid neighboring positions for a given grid position.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • include_diagonal must be a boolean

  • Postconditions:

  • • If include_diagonal is true: returns exactly 8 positions (4 orthogonal + 4 diagonal)
  • • If include_diagonal is false: returns exactly 4 positions (orthogonal only)
  • • All returned positions are exactly 1 unit from the input position
  • • No duplicate positions are returned
  • • The input position is never included in the result

  • Invariants:

  • • Result array size is either 4 or 8
  • • All returned positions are adjacent to the input position
  • • Order of returned positions is deterministic (clockwise starting from right)

  • Performance:

  • • O(1) time complexity (fixed number of operations)
  • • O(1) space complexity (fixed array size)
• get_orthogonal_neighbors(pos: Vector2i) -> Array
  • Returns only orthogonal (cardinal direction) neighbors for a given grid position.

  • Preconditions:

  • • pos must be a valid Vector2i instance

  • Postconditions:

  • • Returns exactly 4 positions (up, down, left, right)
  • • All returned positions are exactly 1 unit from the input position
  • • No diagonal positions are included

  • Invariants:

  • • Result array size is always 4
  • • Equivalent to get_neighbors(pos, false)

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• grid_to_world(grid_pos: Vector2i, cell_size: Vector2i = Vector2i(32, 32)
  • Converts grid coordinates to world coordinates.

  • Preconditions:

  • • grid_pos must be a valid Vector2i instance
  • • cell_size must have positive x and y values

  • Postconditions:

  • • Returns world position corresponding to the top-left corner of the grid cell
  • • World position is calculated as grid_pos * cell_size
  • • Returned Vector2 has floating-point precision

  • Invariants:

  • • grid_to_world(Vector2i.ZERO, cell_size) == Vector2.ZERO
  • • grid_to_world(pos, Vector2i(1, 1)) == Vector2(pos)
  • • world_to_grid(grid_to_world(pos, size), size) == pos

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• world_to_grid(world_pos: Vector2, cell_size: Vector2i = Vector2i(32, 32)
  • Converts world coordinates to grid coordinates.

  • Preconditions:

  • • world_pos must be a valid Vector2 instance
  • • cell_size must have positive x and y values

  • Postconditions:

  • • Returns grid position containing the world position
  • • Uses integer division (floor division) for coordinate conversion
  • • Returned Vector2i represents the grid cell containing the world position

  • Invariants:

  • • world_to_grid(Vector2.ZERO, cell_size) == Vector2i.ZERO
  • • world_to_grid(pos, Vector2i(1, 1)) == Vector2i(pos)
  • • grid_to_world(world_to_grid(pos, size), size) <= pos (component-wise)

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• get_positions_in_distance(center: Vector2i, distance: int) -> Array
  • Use optimized diamond pattern generation instead of brute-force square iteration
• get_positions_in_area_physics(center: Vector2i, distance: int, cell_size: Vector2i = Vector2i(32, 32)
• _get_physics_space_state -> PhysicsDirectSpaceState2D
  • Helper to get physics space state for spatial queries
• is_within_bounds(pos: Vector2i, bounds: Vector2i) -> bool
  • Checks if a grid position is within rectangular bounds.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • bounds must have non-negative x and y values

  • Postconditions:

  • • Returns true if 0 <= pos.x < bounds.x and 0 <= pos.y < bounds.y
  • • Uses inclusive lower bound and exclusive upper bound semantics
  • • Bounds represent a rectangle from (0,0) to (bounds.x, bounds.y)

  • Invariants:

  • • is_within_bounds(Vector2i.ZERO, bounds) is true if bounds has positive components
  • • is_within_bounds(bounds - Vector2i(1,1), bounds) is always true
  • • is_within_bounds(bounds, bounds) is always false

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• clamp_to_bounds(pos: Vector2i, bounds: Vector2i) -> Vector2i
  • Clamps a grid position to be within rectangular bounds.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • bounds must have positive x and y values

  • Postconditions:

  • • Returns a position guaranteed to be within bounds
  • • If input position is within bounds, returns it unchanged
  • • Uses inclusive lower bound and exclusive upper bound semantics
  • • Result satisfies: 0 <= result.x < bounds.x and 0 <= result.y < bounds.y

  • Invariants:

  • • is_within_bounds(clamp_to_bounds(pos, bounds), bounds) is always true
  • • If is_within_bounds(pos, bounds) then clamp_to_bounds(pos, bounds) == pos

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• add_offset(pos: Vector2i, offset: Vector2i) -> Vector2i
  • Adds an offset to a grid position.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • offset must be a valid Vector2i instance

  • Postconditions:

  • • Returns the vector sum of pos and offset
  • • Operation is component-wise addition
  • • Result may be outside any grid bounds

  • Invariants:

  • • add_offset(pos, Vector2i.ZERO) == pos
  • • add_offset(pos, offset) - offset == pos
  • • add_offset(pos1, offset) + add_offset(pos2, offset) == add_offset(pos1 + pos2, offset)

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• clamp_to_bounds_rect(pos: Vector2i, bounds: Rect2i) -> Vector2i
  • Clamps a grid position to be within a rectangular bounds region.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • bounds must have positive width and height

  • Postconditions:

  • • Returns a position guaranteed to be within the bounds rectangle
  • • Uses bounds.position as inclusive lower bound
  • • Uses bounds.position + bounds.size as exclusive upper bound
  • • Result satisfies: bounds.position.x <= result.x < bounds.position.x + bounds.size.x

  • Invariants:

  • • is_within_bounds_rect(clamp_to_bounds_rect(pos, bounds), bounds) is always true
  • • If is_within_bounds_rect(pos, bounds) then clamp_to_bounds_rect(pos, bounds) == pos

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• wrap_to_grid(pos: Vector2i, grid_size: Vector2i) -> Vector2i
  • Wraps a grid position to fit within grid dimensions using modular arithmetic.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • grid_size must have positive x and y values

  • Postconditions:

  • • Returns a position within grid bounds: 0 <= result.x < grid_size.x
  • • Uses wraparound semantics (toroidal topology)
  • • Preserves relative positioning modulo grid dimensions

  • Invariants:

  • • is_within_bounds(wrap_to_grid(pos, grid_size), grid_size) is always true
  • • wrap_to_grid(pos + grid_size, grid_size) == wrap_to_grid(pos, grid_size)
  • • wrap_to_grid(Vector2i.ZERO, grid_size) == Vector2i.ZERO

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• grid_to_world_centered(grid_pos: Vector2i, cell_size: Vector2 = Vector2(16, 16)
  • Converts grid coordinates to world coordinates centered on the cell.

  • Preconditions:

  • • grid_pos must be a valid Vector2i instance
  • • cell_size must have positive x and y values

  • Postconditions:

  • • Returns world position at the center of the grid cell
  • • Center is calculated as (grid_pos * cell_size) + (cell_size / 2)
  • • Returned Vector2 has floating-point precision

  • Invariants:

  • • grid_to_world_centered(Vector2i.ZERO, cell_size) == cell_size / 2
  • • grid_to_world_centered(pos, cell_size) - grid_to_world(pos, cell_size) == cell_size / 2
  • • Result is always offset by half cell size from top-left corner

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• world_to_grid_centered(world_pos: Vector2, cell_size: Vector2 = Vector2(16, 16)
  • Converts world coordinates to grid coordinates using cell center alignment.

  • Preconditions:

  • • world_pos must be a valid Vector2 instance
  • • cell_size must have positive x and y values

  • Postconditions:

  • • Returns grid position whose center contains the world position
  • • Uses cell center as reference point for grid alignment
  • • Returned grid cell’s center is closest to the input world position

  • Invariants:

  • • world_to_grid_centered(cell_size / 2, cell_size) == Vector2i.ZERO
  • • grid_to_world_centered(world_to_grid_centered(pos, size), size) is closest to pos
  • • More accurate than world_to_grid for center-based positioning

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• positions_equal(pos1: Vector2i, pos2: Vector2i) -> bool
  • Checks if two grid positions are equal.

  • Preconditions:

  • • Both pos1 and pos2 must be valid Vector2i instances

  • Postconditions:

  • • Returns true if positions have identical x and y coordinates
  • • Uses exact equality comparison

  • Invariants:

  • • positions_equal(pos1, pos2) == positions_equal(pos2, pos1)
  • • positions_equal(pos, pos) == true
  • • positions_equal(pos1, pos2) implies pos1.x == pos2.x and pos1.y == pos2.y

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• position_hash(pos: Vector2i, layer: int = 0) -> int
  • Generates a hash value for a grid position with optional layer.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • layer must be an integer (can be negative)

  • Postconditions:

  • • Returns an integer hash value suitable for hash tables
  • • Hash function distributes values evenly across integer space
  • • Incorporates position coordinates and layer information

  • Invariants:

  • • position_hash(pos, layer) == position_hash(pos, layer) (deterministic)
  • • position_hash(pos1, layer) != position_hash(pos2, layer) for most pos1 != pos2
  • • Different layers produce different hashes for the same position

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity

  • Notes:

  • • Uses prime number multiplication (31) for better hash distribution
  • • Hash collisions are possible but unlikely for typical grid sizes
• is_position_valid_for_grid(pos: Vector2i, grid_id: String) -> bool
  • Validates if a position is suitable for grid placement.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • grid_id must be a string (can be empty)

  • Postconditions:

  • • Returns true if position has non-negative coordinates and grid_id is not empty
  • • Validates basic position constraints for grid systems
  • • Does not check against specific grid boundaries

  • Invariants:

  • • is_position_valid_for_grid(Vector2i.ZERO, “test”) == true
  • • is_position_valid_for_grid(Vector2i(-1, 0), “test”) == false
  • • is_position_valid_for_grid(pos, “”) == false

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity
• get_occupied_cells(pos: Vector2i) -> Array
  • Returns the cells occupied by a position (single-cell assumption).

  • Preconditions:

  • • pos must be a valid Vector2i instance

  • Postconditions:

  • • Returns array containing exactly one position: the input position
  • • Represents single-cell occupation pattern
  • • Useful for multi-cell extension interfaces

  • Invariants:

  • • get_occupied_cells(pos).size() == 1
  • • get_occupied_cells(pos)[0] == pos
  • • Always returns a new array (no shared references)

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity

  • Notes:

  • • Designed for extension to multi-cell objects
  • • Provides consistent interface for occupation queries
• position_to_string(pos: Vector2i, layer: int = 0) -> String
  • Creates a string representation of a grid position with layer.

  • Preconditions:

  • • pos must be a valid Vector2i instance
  • • layer must be an integer

  • Postconditions:

  • • Returns formatted string: “GridPosition(x, y, layer: L)”
  • • String is suitable for debugging and logging
  • • Format is consistent and parseable

  • Invariants:

  • • position_to_string(pos, layer) contains pos.x and pos.y values
  • • position_to_string(pos, layer) contains layer value
  • • Format is consistent across calls

  • Performance:

  • • O(1) time complexity
  • • O(1) space complexity

  • Notes:

  • • Useful for debugging and serialization debugging
  • • Format may change in future versions