GBPositioning2DUtils

Convert an arbitrary direction vector...

sort Weight: 10

Convert an arbitrary direction vector into an 8-direction tile delta (-1/0/1 per axis). Perfect for 2D grid-based movement systems supporting 8-directional input (WASD + diagonals). Cardinal and diagonal directions are supported; tiny components are snapped to 0 by threshold. [param direction] The input direction from joystick, keyboard, or mouse (any Vector2). [param threshold] Components with absolute value below this are treated as 0 (default 0.33). [return] Vector2i with components in {-1, 0, 1} representing tile movement direction. [b]Example:[/b] Vector2(0.8, -0.2) becomes Vector2i(1, 0) for rightward movement.

Version: v5.0.0

STABLE

Inherits: RefCounted
Source: gb_positioning_2d_utils.gd
Parsing: AST-based for maximum accuracy with symbol typing

Methods

get_tile_from_global_position

Signature: static get_tile_from_global_position(global_position: Vector2, map: TileMapLayer) -> Vector2i

[return] The tile coordinate as Vector2i (e.g., Vector2i(5, 3) for tile at column 5, row 3).

Returns: Vector2i

Static: true

Parameters:

  • global_position: Vector2
  • map: TileMapLayer

move_to_tile_center

Signature: static move_to_tile_center(node: Node2D, tile: Vector2i, map: TileMapLayer) -> Vector2i

[return] The Vector2i tile coordinate that the node was moved to (should match input tile).

Returns: Vector2i

Static: true

Parameters:

  • node: Node2D
  • tile: Vector2i
  • map: TileMapLayer

move_to_closest_valid_tile_center

Signature: static move_to_closest_valid_tile_center(node: Node2D, target_tile: Vector2i, source: Node2D, map: TileMapLayer, settings: GridTargetingSettings) -> Vector2i

[return] The Vector2i tile coordinate that the node was moved to.

Returns: Vector2i

Static: true

Parameters:

  • node: Node2D
  • target_tile: Vector2i
  • source: Node2D
  • map: TileMapLayer
  • settings: GridTargetingSettings

limit_tile_to_max_distance

Signature: static limit_tile_to_max_distance(source: Node2D, target_tile: Vector2i, map: TileMapLayer, settings: GridTargetingSettings, region: Rect2i = Rect2i() -> void

[param astar_grid] Optional AStarGrid2D to honour path constraints; when null a heuristic fallback is used.

Returns: void

Static: true

Parameters:

  • source: Node2D
  • target_tile: Vector2i
  • map: TileMapLayer
  • settings: GridTargetingSettings
  • region: Rect2i (optional, default: Rect2i()

is_region_valid

Signature: static is_region_valid(region: Rect2i) -> bool

[return] True if the region is valid (non-empty with positive size).

Returns: bool

Static: true

Parameters:

  • region: Rect2i

snap_tile_to_region

Signature: static snap_tile_to_region(tile: Vector2i, region: Rect2i) -> Vector2i

[return] The snapped tile coordinate, or original tile if region is invalid.

Returns: Vector2i

Static: true

Parameters:

  • tile: Vector2i
  • region: Rect2i

get_tile_from_node_position

Signature: static get_tile_from_node_position(node: Node2D, map: TileMapLayer) -> Vector2i

[return] The tile coordinate as Vector2i, or Vector2i.ZERO if inputs are invalid.

Returns: Vector2i

Static: true

Parameters:

  • node: Node2D
  • map: TileMapLayer

_limit_using_astar

Signature: static _limit_using_astar(source: Node2D, target_tile: Vector2i, map: TileMapLayer, astar_grid: AStarGrid2D, max_steps: int, region: Rect2i) -> Variant

Returns: Variant

Static: true

Parameters:

  • source: Node2D
  • target_tile: Vector2i
  • map: TileMapLayer
  • astar_grid: AStarGrid2D
  • max_steps: int
  • region: Rect2i

_limit_via_step

Signature: static _limit_via_step(source: Node2D, target_tile: Vector2i, map: TileMapLayer, max_steps: int, diagonal_mode: int, region: Rect2i) -> Vector2i

Returns: Vector2i

Static: true

Parameters:

  • source: Node2D
  • target_tile: Vector2i
  • map: TileMapLayer
  • max_steps: int
  • diagonal_mode: int
  • region: Rect2i

_step_toward

Signature: static _step_toward(current: Vector2i, target: Vector2i, diagonal_mode: int) -> Vector2i

Returns: Vector2i

Static: true

Parameters:

  • current: Vector2i
  • target: Vector2i
  • diagonal_mode: int

move_node_by_tiles

Signature: static move_node_by_tiles(node: Node2D, p_tile_delta: Vector2i, target_map: TileMapLayer) -> Vector2i

[return] The Vector2i tile coordinate that the node was moved to.

Returns: Vector2i

Static: true

Parameters:

  • node: Node2D
  • p_tile_delta: Vector2i
  • target_map: TileMapLayer

convert_screen_to_world_position

Signature: static convert_screen_to_world_position(screen_pos: Vector2, viewport: Viewport) -> Vector2

[return] World position corresponding to screen position, or Vector2.ZERO if Camera2D missing

Returns: Vector2

Static: true

Parameters:

  • screen_pos: Vector2
  • viewport: Viewport

viewport_center_to_world_position

Signature: static viewport_center_to_world_position(viewport: Viewport) -> Vector2

⚠️ Warning: Returns Vector2.ZERO if Camera2D is missing from viewport

Returns: Vector2

Static: true

Parameters:

  • viewport: Viewport

move_node_to_tile_at_viewport_center

Signature: static move_node_to_tile_at_viewport_center(node: Node2D, map: TileMapLayer, viewport: Viewport) -> Vector2i

⚠️ Warning: Positioning may be inaccurate if Camera2D is missing

Returns: Vector2i

Static: true

Parameters:

  • node: Node2D
  • map: TileMapLayer
  • viewport: Viewport

direction_to_tile_delta

Signature: static direction_to_tile_delta(direction: Vector2, threshold: float = 0.33) -> Vector2i

Example: Vector2(0.8, -0.2) becomes Vector2i(1, 0) for rightward movement.

Returns: Vector2i

Static: true

Parameters:

  • direction: Vector2
  • threshold: float (optional, default: 0.33)