GBGridRotationUtils

Summary

Grid-aware object rotation utilities for 2D grid-based games.

Provides clean, typed helper functions for rotating objects on a grid with proper alignment to grid tiles, particularly for isometric and square tile layouts. Supports configurable rotation increments (90°, 45°, 30°, 60°, or any custom angle).

Key features: - Configurable rotation increments (4-direction, 8-direction, or any custom angle) - Cardinal direction rotation (backward compatible, convenience API) - Isometric-aware rotation handling with complex transform support - Snap-to-grid positioning after rotation - Integration with existing GridPositioner2D and GBPositioning2DUtils - Static methods for easy testing and reuse

Usage Examples: - 4-direction (RTS-style): rotate_node_clockwise(node, map, 90.0) - 8-direction (isometric with diagonals): rotate_node_clockwise(node, map, 45.0) - 6-direction (hex-style): rotate_node_clockwise(node, map, 60.0) - 12-direction: rotate_node_clockwise(node, map, 30.0)

Designed to work seamlessly with the existing Grid Building plugin architecture while providing specialized rotation functionality for grid-based gameplay.

Enums

enum CardinalDirection

Cardinal directions for grid-based rotation (backward compatibility) Use these with cardinal_*() methods for 4-direction rotation systems

NORTH = 0 — 0 degrees / up
EAST = 1 — 90 degrees / right
SOUTH = 2 — 180 degrees / down
WEST = 3 — 270 degrees / left

Methods

static func degrees_to_cardinal( degrees: float ) -> CardinalDirection: Convert rotation degrees to cardinal direction degrees: Rotation in degrees (will be normalized to 0-360 range) Returns: CardinalDirection enum value
static func cardinal_to_degrees( direction: CardinalDirection ) -> float: Convert cardinal direction to rotation degrees direction: CardinalDirection enum value Returns: Rotation in degrees (0, 90, 180, or 270)
static func rotate_clockwise( current: CardinalDirection ) -> CardinalDirection: Get the next cardinal direction (clockwise rotation) current: Current CardinalDirection Returns: Next CardinalDirection clockwise
static func rotate_counter_clockwise( current: CardinalDirection ) -> CardinalDirection: Get the previous cardinal direction (counter-clockwise rotation) current: Current CardinalDirection Returns: Previous CardinalDirection counter-clockwise
static func rotate_node_clockwise( node: Node2D, map: TileMapLayer, increment_degrees: float, snap_to_grid: bool ) -> float: Rotate a Node2D clockwise by a specified increment while maintaining grid alignment node: Node2D to rotate (must be on a grid tile) map: TileMapLayer providing grid alignment increment_degrees: Rotation increment in degrees (default 90.0 for 4-direction) - Use 90.0 for 4-direction (RTS-style) - Use 45.0 for 8-direction (isometric with diagonals) - Use 60.0 for 6-direction (hex-style) - Use 30.0 for 12-direction - Or any custom angle snap_to_grid: Whether to snap position to grid after rotation (default true) Returns: New rotation angle in degrees (0-360 range)
static func rotate_node_counter_clockwise( node: Node2D, map: TileMapLayer, increment_degrees: float, snap_to_grid: bool ) -> float: Rotate a Node2D counter-clockwise by a specified increment while maintaining grid alignment node: Node2D to rotate (must be on a grid tile) map: TileMapLayer providing grid alignment increment_degrees: Rotation increment in degrees (default 90.0 for 4-direction) - Use 90.0 for 4-direction (RTS-style) - Use 45.0 for 8-direction (isometric with diagonals) - Use 60.0 for 6-direction (hex-style) - Use 30.0 for 12-direction - Or any custom angle snap_to_grid: Whether to snap position to grid after rotation (default true) Returns: New rotation angle in degrees (0-360 range) Rotate a Node2D counter-clockwise by a specified increment while maintaining grid alignment node: Node2D to rotate (must be on a grid tile) map: TileMapLayer providing grid alignment increment_degrees: Rotation increment in degrees (default 90.0 for 4-direction) - Use 90.0 for 4-direction (RTS-style) - Use 45.0 for 8-direction (isometric with diagonals) - Use 60.0 for 6-direction (hex-style) - Use 30.0 for 12-direction - Or any custom angle snap_to_grid: Whether to snap position to grid after rotation (default true) Returns: New rotation angle in degrees (0-360 range)
static func set_node_direction( node: Node2D, direction: CardinalDirection, map: TileMapLayer, snap_to_grid: bool ) -> void: Set a Node2D to a specific cardinal direction with grid alignment node: Node2D to rotate direction: Target CardinalDirection map: TileMapLayer providing grid alignment snap_to_grid: Whether to snap position to grid after rotation (default true)
static func get_direction_tile_delta( direction: CardinalDirection ) -> Vector2i: Get a tile delta vector for movement in a cardinal direction direction: CardinalDirection to move in Returns: Vector2i tile delta for the direction
static func get_opposite_direction( direction: CardinalDirection ) -> CardinalDirection: Get the opposite cardinal direction direction: Input CardinalDirection Returns: Opposite CardinalDirection (180 degrees)
static func is_horizontal( direction: CardinalDirection ) -> bool: Check if a direction is horizontal (East or West) direction: CardinalDirection to check Returns: True if direction is East or West
static func is_vertical( direction: CardinalDirection ) -> bool: Check if a direction is vertical (North or South) direction: CardinalDirection to check Returns: True if direction is North or South
static func direction_to_string( direction: CardinalDirection ) -> String: Convert cardinal direction to a human-readable string direction: CardinalDirection to convert Returns: String representation (“North”, “East”, “South”, “West”)
static func _snap_node_to_grid( node: Node2D, map: TileMapLayer ) -> void: Snap a node to the nearest grid tile center using existing positioning utilities node: Node2D to snap to grid map: TileMapLayer providing grid alignment
static func _normalize_degrees( degrees: float ) -> float: Normalize degrees to 0-360 range degrees: Angle in degrees (can be negative or > 360) Returns: Normalized angle in 0-360 range
static func _set_node_global_rotation( node: Node2D, target_global_rotation: float ) -> void: Helper function to set a node’s rotation to achieve a target global rotation node: Node2D to rotate target_global_rotation: Desired global rotation in radians

Source

addons/grid_building/utils/gb_grid_rotation_utils.gd

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