GBPositioning2DUtils

Summary

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

This class provides pure functions for common 2D game positioning tasks including: - Converting between world coordinates, viewport coordinates, and tile coordinates - Moving nodes to tile centers with proper alignment - Viewport-to-world coordinate transformations using Camera2D - Distance-limited movement with adjacency constraints - Direction vector normalization for tile-based movement

All functions are static and depend only on provided parameters, making them highly testable and reusable. Extracted from GridPositioner2D to reduce class coupling and improve maintainability.

⭐ CAMERA2D REQUIRED - Add a Camera2D node to your scene before using Grid Building operations. World coordinate calculations from mouse position depend on Camera2D for accurate positioning.

Requirements: Designed for 2D games using TileMapLayer and Camera2D nodes.

Methods

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

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. Returns: The tile coordinate as Vector2i (e.g., Vector2i(5, 3) for tile at column 5, row 3).

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

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. Returns: The Vector2i tile coordinate that the node was moved to (should match input tile).

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

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. Returns: The Vector2i tile coordinate that the node was moved to.

static func limit_tile_to_max_distance( source: Node2D, target_tile: Vector2i, map: TileMapLayer, settings: GridTargetingSettings, region: Rect2i )

Clamp a target tile so it does not exceed the configured max distance from the source node. source: The node whose tile position is used as the origin for distance checks. target_tile: Desired tile to move toward. map: Tile map providing conversions and used rect bounds. settings: Targeting settings driving adjacency/limit configuration. region: Optional precomputed map region to avoid repeated get_used_rect() calls. astar_grid: Optional AStarGrid2D to honour path constraints; when null a heuristic fallback is used.

static func is_region_valid( region: Rect2i ) -> bool

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

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

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

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

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

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

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

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

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

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. Returns: The Vector2i tile coordinate that the node was moved to.

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

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. Returns: 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. This function EXPLICITLY REQUIRES Camera2D for pixel-perfect accuracy!

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: • Zoom Support - Handles 0.5x, 1x, 2x, 4x zoom levels accurately • Camera Panning - Accounts for camera position and movement • Sub-pixel Precision - Grid building requires exact tile centers • Viewport Scaling - Works with different screen resolutions • Canvas Transforms - 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 Returns: World position corresponding to screen position, or Vector2.ZERO if Camera2D missing

static func viewport_center_to_world_position( viewport: Viewport ) -> Vector2

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 [method convert_screen_to_world_position] internally, which requires Camera2D for accurate coordinate conversion.

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

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

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 Returns: The Vector2i tile coordinate where the node was positioned ⚠️ Warning: Positioning may be inaccurate if Camera2D is missing

static func direction_to_tile_delta( direction: Vector2, threshold: float ) -> Vector2i

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). Returns: Vector2i with components in {-1, 0, 1} representing tile movement direction. Example: Vector2(0.8, -0.2) becomes Vector2i(1, 0) for rightward movement.

Source

addons/grid_building/utils/gb_positioning_2d_utils.gd

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