GBPositioning2DUtils

AUTO-GENERATED FILE – DO NOT EDIT MANUALLY

GBPositioning2DUtils Static utility functions for 2D grid-based positioning and tile movement operations.

Source File: addons/grid_building/utils/gb_positioning_2d_utils.gd

Extends: RefCounted

Public Methods

get_tile_from_global_position

1
2
3
4

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

Flags: static

Convert a global position to tile coordinates on the given map. Essential function for 2D grid-based games to map world positions to tile indices. global_position The world position to convert (e.g., mouse position, node position). map The TileMapLayer providing map<->local coordinate conversions. [return] The tile coordinate as Vector2i (e.g., Vector2i(5, 3) for tile at column 5, row 3).

move_to_tile_center

1
2
3
4
5

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

Flags: static

Move the given node to a specific tile position on the map (centered). Positions the node at the exact center of the specified tile for precise 2D alignment. node The Node2D to position (e.g., player character, cursor, building preview). tile The target tile coordinate (e.g., Vector2i(3, 7) for column 3, row 7). map The TileMapLayer providing coordinate conversions and tile size information. [return] The Vector2i tile coordinate that the node was moved to (should match input tile).

move_to_closest_valid_tile_center

1
2
3
4
5
6
7

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

Flags: static

Move the node to the closest valid tile, respecting settings and map bounds. If limit_to_adjacent is true, uses GridTargetingSystem to constrain movement. node The Node2D to move. target_tile The desired tile coordinate. source A source node used by GridTargetingSystem for adjacency queries. map The map node providing map<->local conversions. settings Targeting settings influencing adjacency/limits. [return] The Vector2i tile coordinate that the node was moved to.

is_region_valid

1

is_region_valid(region: Rect2i) -> bool

Flags: static

Check if a region is valid for snapping operations. region The region to validate. [return] True if the region is valid (non-empty with positive size).

snap_tile_to_region

1
2
3
4

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

Flags: static

Snap a tile coordinate into the provided region bounds. tile The tile coordinate to snap. region The region bounds to snap within. [return] The snapped tile coordinate, or original tile if region is invalid.

get_tile_from_node_position

1
2
3
4

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

Flags: static

Convert a node’s global position to its tile coordinate. node The Node2D whose position to convert. map The map providing coordinate conversions. [return] The tile coordinate as Vector2i, or Vector2i.ZERO if inputs are invalid.

move_node_by_tiles

1
2
3
4
5

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

Flags: static

Move the node by an absolute tile delta. node The node to move. p_tile_delta Tile delta as Vector2i (e.g., (1,0) right, (0,1) down, (1,1) down-right). target_map The map used for tile <-> local conversions. [return] The Vector2i tile coordinate that the node was moved to.

convert_screen_to_world_position

1
2
3
4

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

Flags: static

Recenter a node to the viewport/camera center snapped to the map grid. node The node to reposition. map The tile map providing conversions. viewport The viewport providing screen center coordinates. [return] The Vector2i tile coordinate that the node was moved to. Convert screen coordinates to world coordinates using Camera2D. ⭐ CORE COORDINATE CONVERSION FUNCTION - REQUIRES CAMERA2D ⭐

This is the essential coordinate conversion functionality that powers the entire Grid Building system. [color=yellow]This function EXPLICITLY REQUIRES Camera2D for pixel-perfect accuracy![/color]

Camera2D Requirements: • Camera2D must be present in viewport (viewport.get_camera_2d()) • Camera2D must be enabled (camera.enabled = true) • Camera2D should be current (camera.make_current())

Why Camera2D is Essential: • [color=lime]Zoom Support[/color] - Handles 0.5x, 1x, 2x, 4x zoom levels accurately • [color=lime]Camera Panning[/color] - Accounts for camera position and movement • [color=lime]Sub-pixel Precision[/color] - Grid building requires exact tile centers • [color=lime]Viewport Scaling[/color] - Works with different screen resolutions • [color=lime]Canvas Transforms[/color] - Uses proper Godot coordinate pipeline

Alternative Methods Are Insufficient: Canvas transform alone cannot provide the accuracy needed for pixel-perfect grid placement. Only Camera2D + canvas transform combination delivers the precision required.

screen_pos Screen position to convert (e.g., from InputEventMouseMotion.position) viewport Viewport containing the Camera2D node [return] World position corresponding to screen position, or Vector2.ZERO if Camera2D missing

viewport_center_to_world_position

1

viewport_center_to_world_position(viewport: Viewport) -> Vector2

Flags: static

Convert viewport center coordinates to world position using camera transforms. ⭐ REQUIRES CAMERA2D - Essential for viewport center calculations

This function calculates the world position at the center of the viewport, accounting for camera position, zoom, and viewport scaling. Critical for centering operations.

Camera2D Dependency: Uses convert_screen_to_world_position internally, which requires Camera2D for accurate coordinate conversion.

viewport The viewport containing the Camera2D node [return] The world position at the center of the viewport ⚠️ Warning: Returns Vector2.ZERO if Camera2D is missing from viewport

move_node_to_tile_at_viewport_center

1
2
3
4
5

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

Flags: static

Move a node to the viewport center, snapped to the grid. ⭐ REQUIRES CAMERA2D - Essential for viewport-based positioning

This function positions a node at the exact center of the viewport, snapped to the nearest tile on the grid. Perfect for centering cursors, UI elements, or objects at the camera’s focus point in 2D games with pixel-perfect accuracy.

Camera2D Requirement: Uses viewport center coordinate conversion, which requires Camera2D for accurate screen-to-world transformation. Without Camera2D, positioning will be inaccurate and may not account for zoom/pan operations.

Common Use Cases: • Centering grid cursor when camera moves • Positioning UI indicators at screen center • Snapping objects to viewport focus point • Recentering after zoom/pan operations

node The Node2D to reposition (e.g., grid cursor, selection indicator) map The TileMapLayer providing coordinate conversions and grid alignment viewport The viewport containing the Camera2D node [return] The Vector2i tile coordinate where the node was positioned ⚠️ Warning: Positioning may be inaccurate if Camera2D is missing

direction_to_tile_delta

1
2
3
4

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

Flags: static

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. direction The input direction from joystick, keyboard, or mouse (any Vector2). 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. Example: Vector2(0.8, -0.2) becomes Vector2i(1, 0) for rightward movement.

Private Methods

_limit_using_astar

1
2
3
4
5
6
7
8

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

Flags: static, private

_limit_via_step

1
2
3
4
5
6
7
8

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

Flags: static, private

_step_toward

1
2
3
4
5

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

Flags: static, private