Skip to content
Grid Building Docs

GridPositioner2D

Summary

Section titled “Summary”

Controls the on-grid cursor used by building/interaction systems.

Responsibilities: - Recenter according to GridTargetingSettings policy when input/mode is enabled - Follow mouse/keyboard input to update on-grid position - STRICTLY for tile center targeting - does NOT handle rotation or manipulation

Targeting separation: Target acquisition/collision detection is handled by dedicated components (e.g., TargetingShapeCast2D). GridPositioner2D no longer depends on or manages any shapecast component.

Manipulation separation: Object rotation, flipping, and manipulation are handled by ManipulationParent. GridPositioner2D focuses solely on positioning the targeting cursor at tile centers.

Dependency Injection: resolve_gb_dependencies(container) is the standard method called by GBInjectorSystem to inject dependencies. This is the primary integration pattern for runtime use. set_dependencies(...) is an internal helper for testing and advanced use cases.

Properties

Section titled “Properties”
input_processing_enabled: bool = false

Public flag & API for enabling/disabling input processing (used by tests)

Methods

Section titled “Methods”
func _init( ) -> void

Fail fast design. Defaults should be explicitly set by scenes or tests.

func _ready( ) -> void
func _physics_process( delta: float ) -> void
func _process( delta: float ) -> void
func set_input_processing_enabled( p_enabled: bool ) -> void

Public API used by tests to enable input handling on this node.

func is_input_processing_enabled( ) -> bool
func is_input_ready( ) -> bool

Public helper: returns true when dependencies are injected and a target map is assigned

func are_dependencies_ready( ) -> bool

Helper: returns true when all critical dependencies are injected (logger, settings, mode state) Use this to guard input methods that need to log or access settings

func resolve_gb_dependencies( p_config: GBCompositionContainer ) -> void

Standard dependency injection method called by GBInjectorSystem. This is the primary integration pattern - implement this method to participate in DI. Internally delegates to set_dependencies() for actual wiring.

func _input( event: InputEvent )

Forward to explicit dependency injection helper to avoid service locator usage.

Handles all input for the positioner including mouse movement, keyboard movement, and visibility INPUT: All mouse movement is handled here in response to events; not in physics.

func _handle_mouse_motion_event( motion: InputEventMouseMotion, current_mode: GBEnums.Mode ) -> void

Extracted helper: handle an InputEventMouseMotion event (snapped move + visibility)

func _convert_screen_to_world( screen_pos: Vector2 ) -> Vector2

Deprecated: Use GBPositioning2DUtils.get_tile_from_global_position() and move_to_tile_center() instead. This function has been removed to maintain DRY principles and single source of truth.

Single source of truth: centralized screen-to-world coordinate conversion Delegates to GBPositioning2DUtils for DRY compliance and maintainability

func _move_to_cached_mouse_world( ) -> Vector2i

Deprecated: Use GBPositioning2DUtils.get_tile_from_global_position() and move_to_tile_center() instead. This function has been removed to maintain DRY principles and single source of truth.

Move the positioner back to its cached mouse world location when available.

func _cache_current_world_position( ) -> void

Cache the current global position as the latest mouse world reference.

func _get_active_viewport( ) -> Viewport

Helper: retrieve active Viewport for the current target map (may be null)

func _get_active_camera( p_vp: Viewport ) -> Camera2D

Helper: retrieve active Camera2D from a viewport (may be null)

func _is_disabled_in_off_mode( ) -> bool

Helper: check if positioner should be disabled when in OFF mode Returns true if positioner should be blocked from input/positioning in OFF mode

func _is_mouse_cursor_on_screen( ) -> bool

Helper: check if mouse cursor is within viewport bounds Returns true if mouse cursor is within the visible viewport area

func _is_mouse_follow_allowed( ) -> bool

Helper: decide whether mouse-follow behavior should run this frame

func _mouse_input_gate( ) -> bool

Returns a gate result for handling mouse input with an explicit reason when blocked

func _apply_mouse_world( world: Vector2, method: int, screen: Vector2 ) -> void

Centralizes caching + movement application and diagnostics

func _log_mouse_motion( p_method: int, p_screen: Vector2, p_world: Vector2 ) -> void

Helper: structured mouse motion log

func _log_mouse_gate( p_allowed: bool ) -> void

Helper: structured mouse gate log

func _apply_recenter_on_enable( ) -> void

Recenter behavior when movement/input becomes enabled again User-specified logic: move to mouse cursor if mouse enabled and cursor on screen, otherwise move to center tile position Respects the active when off setting - no positioning changes when disabled in OFF mode

func _apply_positioning_and_visibility_sequence( ) -> void

Apply positioning and then visibility in proper sequence after dependency injection This ensures Camera2D is available for positioning and visibility is updated based on final position

func _recenter_decision_to_string( p_decision: int ) -> String
func _handle_mouse_movement( mouse_global_override: Variant ) -> void

Handle mouse movement to update positioner position. If a mouse_global_override is provided (e.g., from InputEventMouseMotion), it will be used instead of querying the viewport/cursor state. This enables compatibility with tests (SceneRunner) and hidden cursor scenarios.

func _move_positioner_by_tile( p_tile_delta: Vector2i ) -> void

Moves the positioner by a specified number of tiles in a given direction.

p_direction: Vector2 - Direction vector (e.g., Vector2(1,0) for right, Vector2(0,1) for down)

func move_to_viewport_center_tile( ) -> Vector2i

Move positioner to the center tile of the viewport/camera view. Returns the tile coordinate where the positioner was positioned, or Vector2i.ZERO if failed.

func move_to_cursor_center_tile( ) -> Vector2i

Move positioner to the center tile at the cursor location when available. Falls back to viewport mouse, then TileMap global, then view center. Returns the tile coordinate where the positioner was positioned.

func _apply_recenter( ) -> void

Apply manual recenter logic based on settings.

func get_last_manual_recenter_mode( ) -> int

Retrieve the last manual recenter mode applied.

func _exit_tree( ) -> void
func remove_self_as_positioner( )

Removes this object from being set to the _targeting_state.positioner property

func update_visibility( ) -> void

Remove self from being the state positioner

Uses whether the mouse movement was consumed by UI to determine if the positioner and child objects should be visible or invisible. Only called when hide_on_handled is true

func should_be_visible( ) -> bool

Returns whether the positioner should be visible given current mode/settings. Mouse handled gating remains event-driven and is not applied here.

func set_dependencies( p_states: GBStates, p_config: GBConfig, p_logger: GBLogger, p_actions: GBActions, enable_input: bool ) -> void

Internal dependency injection helper method. For runtime use, prefer implementing resolve_gb_dependencies() which is called by GBInjectorSystem. This method is primarily for testing and advanced use cases where you need explicit control. p_states: GBStates providing .targeting and .mode p_config: GBConfig for settings (expects settings.targeting) p_logger: Optional GBLogger for diagnostics p_actions: Optional GBActions for keyboard bindings enable_input: When true, enable input processing immediately (default true)

func get_runtime_issues( ) -> Array[String]

Checks if the properties of the GridPositioner2D are set properly during gameplay. Returns validation issues if dependencies are missing, empty array if valid.

return: Array[String] - List of validation issues (empty if valid)

func validate_dependencies( ) -> bool

Runtime validation logs all issues that should be resolved at runtime

Call after all dependencies are expected to be resolved.

func _on_mode_changed( p_mode: GBEnums.Mode )
func _should_be_visible_for_mode( p_mode: GBEnums.Mode ) -> bool

Helper to compute visibility given an explicit mode value

func get_visual_node( ) -> Node

Visual helpers are provided by GBSearchUtils universally

func is_visual_visible( ) -> bool
func _set_visible_state( p_visible: bool ) -> void

Helper to keep this node and its visual in sync for visibility

func log_current_visual_state( )

Helper: explicit render state log for manual triggering if needed

func _schedule_end_of_frame_state_log( ) -> void

Schedule end-of-frame state logging (deferred to next frame to catch final state)

func _log_end_of_frame_state_async( ) -> void

Async log of end-of-frame state (called deferred)

func _log_screen_and_mouse_state( )

Diagnostic: log screen/camera bounds, positioner screen relation, mouse world, and tile info

func _visibility_context( visual: CanvasItem ) -> String

Build a visibility context string: first hidden ancestor, alpha, z-index, and position

func is_positioner_active( ) -> bool

(Stack summary moved to GBDiagnostics.format_stack_summary)

Whether the positioner is active and should update each frame

func should_hide_under_handled_ui( ) -> bool

Whether the positioner should hide when the mouse events are handled by UI

func are_dependencies_resolved( ) -> bool

Check if all critical dependencies have been resolved

func to_diagnostic_string( ) -> String

Diagnostics: concise state summary for tests and debug logging Safe to call even before dependency injection - provides fallback values

func _set_visibility_reason( p_reason: String ) -> void
func _visibility_decision_trace( ) -> String
func _get_debug_log_mode( ) -> GBDebugSettings.GridPositionerLogMode
func _is_logging_mode( p_mode: GBDebugSettings.GridPositionerLogMode ) -> bool
func _is_visibility_logging_enabled( ) -> bool
func _is_mouse_input_logging_enabled( ) -> bool
func _is_positioning_logging_enabled( ) -> bool
func _is_state_flow_logging_enabled( ) -> bool
func _log_debug( p_mode: GBDebugSettings.GridPositionerLogMode, p_message: String, p_throttled: bool ) -> void
func _log_visibility( p_message: String, p_throttled: bool ) -> void
func _log_mouse( p_message: String, p_throttled: bool ) -> void
func _log_positioning( p_message: String, p_throttled: bool ) -> void
func _log_state_flow( p_message: String, p_throttled: bool ) -> void
func _test_convert_screen_to_world( screen_pos: Vector2 ) -> Vector2

Unit test helper: verify screen-to-world coordinate conversion Returns the converted world position for testing purposes

func _test_get_tile_center_from_screen( screen_pos: Vector2 ) -> Dictionary

Unit test helper: verify tile center calculation Returns the tile coordinate and world position for testing

func _apply_visibility_result( p_result: MouseEventVisibilityResult ) -> void

Source

Section titled “Source”

addons/grid_building/systems/grid_targeting/grid_positioner/grid_positioner_2d.gd

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