GridPositioner2D

AUTO-GENERATED FILE – DO NOT EDIT MANUALLY

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

Source File: addons/grid_building/systems/grid_targeting/grid_positioner/grid_positioner_2d.gd

Extends: Node2D

Properties

  • Property: input_processing_enabled: bool = false - Public flag & API for enabling/disabling input processing (used by tests)

Private Properties

  • Property: _debug_settings: [GBDebugSettings](./gb-debug-settings/) = null (private)
  • Property: _logger: [GBLogger](./gb-logger/) = null (private)
  • Property: _actions: [GBActions](./gb-actions/) = null (private)
  • Property: _targeting_state : [GridTargetingState](./grid-targeting-state/) : (private) - The state of the building/targeting system holding a reference to this positioner.
  • Property: _targeting_settings : [GridTargetingSettings](./grid-targeting-settings/) (private)
  • Property: _mode_state : [ModeState](./mode-state/) : (private)
  • Property: _last_mouse_world: Vector2 = Vector2.ZERO (private)
  • Property: _has_mouse_world: bool = false (private)
  • Property: _enabled_internal: bool = false (private)
  • Property: _last_mouse_input_status := GBMouseInputStatus.new() (private)
  • Property: _last_gate_allowed: bool = false (private)
  • Property: _last_manual_recenter_mode: int = GBEnums.CenteringMode.CENTER_ON_SCREEN (private)
  • Property: _last_visibility_event_reason: String = "" (private)

Constants

  • Constant: LOG_PREFIX : String = "[GridPositioner2D]"

Public Methods

set_input_processing_enabled

1

set_input_processing_enabled(p_enabled: bool) -> void

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

is_input_processing_enabled

1

is_input_processing_enabled() -> bool

is_input_ready

1

is_input_ready() -> bool

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

are_dependencies_ready

1

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

resolve_gb_dependencies

1

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.

move_to_viewport_center_tile

1

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.

move_to_cursor_center_tile

1

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.

get_last_manual_recenter_mode

1

get_last_manual_recenter_mode() -> int

Retrieve the last manual recenter mode applied.

remove_self_as_positioner

1

remove_self_as_positioner()

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

update_visibility

1

update_visibility() -> void

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

should_be_visible

1

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.

set_dependencies

1
2
3
4
5
6
7

set_dependencies(
    p_states : GBStates,
    p_config : GBConfig,
    p_logger: GBLogger = null,
    p_actions: GBActions = null,
    enable_input: bool = true
) -> 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)

get_runtime_issues

1

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)

validate_dependencies

1

validate_dependencies() -> bool

Runtime validation logs all issues that should be resolved at runtime

Call after all dependencies are expected to be resolved.

get_visual_node

1

get_visual_node() -> Node

Visual helpers are provided by GBSearchUtils universally

is_visual_visible

1

is_visual_visible() -> bool

log_current_visual_state

1

log_current_visual_state()

Helper: explicit render state log for manual triggering if needed

is_positioner_active

1

is_positioner_active() -> bool

(Stack summary moved to GBDiagnostics.format_stack_summary) Whether the positioner is active and should update each frame

should_hide_under_handled_ui

1

should_hide_under_handled_ui() -> bool

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

are_dependencies_resolved

1

are_dependencies_resolved() -> bool

Check if all critical dependencies have been resolved

to_diagnostic_string

1

to_diagnostic_string() -> String

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

Private Methods

_init

1

_init() -> void

Flags: private

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

_ready

1

_ready() -> void

Flags: private

_physics_process

1

_physics_process(delta: float) -> void

Flags: private

_process

1

_process(delta: float) -> void

Flags: private

_input

1

_input(event : InputEvent)

Flags: private

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.

_handle_mouse_motion_event

1
2
3
4

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

Flags: private

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

_convert_screen_to_world

1

_convert_screen_to_world(screen_pos: Vector2) -> Vector2

Flags: private

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

_move_to_cached_mouse_world

1

_move_to_cached_mouse_world() -> Vector2i

Flags: private

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.

_cache_current_world_position

1

_cache_current_world_position() -> void

Flags: private

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

_get_active_viewport

1

_get_active_viewport() -> Viewport

Flags: private

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

_get_active_camera

1

_get_active_camera(p_vp: Viewport) -> Camera2D

Flags: private

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

_is_disabled_in_off_mode

1

_is_disabled_in_off_mode() -> bool

Flags: private

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

_is_mouse_cursor_on_screen

1

_is_mouse_cursor_on_screen() -> bool

Flags: private

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

_is_mouse_follow_allowed

1

_is_mouse_follow_allowed() -> bool

Flags: private

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

_mouse_input_gate

1

_mouse_input_gate() -> bool

Flags: private

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

_apply_mouse_world

1
2
3
4
5

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

Flags: private

Centralizes caching + movement application and diagnostics

_log_mouse_motion

1
2
3
4
5

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

Flags: private

Helper: structured mouse motion log

_log_mouse_gate

1

_log_mouse_gate(p_allowed: bool) -> void

Flags: private

Helper: structured mouse gate log

_apply_recenter_on_enable

1

_apply_recenter_on_enable() -> void

Flags: private

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

_apply_positioning_and_visibility_sequence

1

_apply_positioning_and_visibility_sequence() -> void

Flags: private

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

_recenter_decision_to_string

1

_recenter_decision_to_string(p_decision: int) -> String

Flags: private

_handle_mouse_movement

1

_handle_mouse_movement(mouse_global_override: Variant = null) -> void

Flags: private

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.

_move_positioner_by_tile

1

_move_positioner_by_tile(p_tile_delta: Vector2i) -> void

Flags: private

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)

_apply_recenter

1

_apply_recenter() -> void

Flags: private

Apply manual recenter logic based on settings.

_exit_tree

1

_exit_tree() -> void

Flags: private

_on_mode_changed

1

_on_mode_changed(p_mode : GBEnums.Mode)

Flags: private

_should_be_visible_for_mode

1

_should_be_visible_for_mode(p_mode: GBEnums.Mode) -> bool

Flags: private

Helper to compute visibility given an explicit mode value

_set_visible_state

1

_set_visible_state(p_visible: bool) -> void

Flags: private

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

_schedule_end_of_frame_state_log

1

_schedule_end_of_frame_state_log() -> void

Flags: private

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

_log_end_of_frame_state_async

1

_log_end_of_frame_state_async() -> void

Flags: private

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

_log_screen_and_mouse_state

1

_log_screen_and_mouse_state()

Flags: private

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

_visibility_context

1

_visibility_context(visual: CanvasItem) -> String

Flags: private

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

_set_visibility_reason

1

_set_visibility_reason(p_reason: String) -> void

Flags: private

_visibility_decision_trace

1

_visibility_decision_trace() -> String

Flags: private

_get_debug_log_mode

1

_get_debug_log_mode() -> GBDebugSettings.GridPositionerLogMode

Flags: private

_is_logging_mode

1

_is_logging_mode(p_mode: GBDebugSettings.GridPositionerLogMode) -> bool

Flags: private

_is_visibility_logging_enabled

1

_is_visibility_logging_enabled() -> bool

Flags: private

_is_mouse_input_logging_enabled

1

_is_mouse_input_logging_enabled() -> bool

Flags: private

_is_positioning_logging_enabled

1

_is_positioning_logging_enabled() -> bool

Flags: private

_is_state_flow_logging_enabled

1

_is_state_flow_logging_enabled() -> bool

Flags: private

_log_debug

1
2
3
4
5

_log_debug(
    p_mode: GBDebugSettings.GridPositionerLogMode,
    p_message: String,
    p_throttled: bool = true
) -> void

Flags: private

_log_visibility

1
2
3
4

_log_visibility(
    p_message: String,
    p_throttled: bool = true
) -> void

Flags: private

_log_mouse

1
2
3
4

_log_mouse(
    p_message: String,
    p_throttled: bool = true
) -> void

Flags: private

_log_positioning

1
2
3
4

_log_positioning(
    p_message: String,
    p_throttled: bool = true
) -> void

Flags: private

_log_state_flow

1
2
3
4

_log_state_flow(
    p_message: String,
    p_throttled: bool = true
) -> void

Flags: private

_test_convert_screen_to_world

1

_test_convert_screen_to_world(screen_pos: Vector2) -> Vector2

Flags: private

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

_test_get_tile_center_from_screen

1

_test_get_tile_center_from_screen(screen_pos: Vector2) -> Dictionary

Flags: private

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

_apply_visibility_result

1

_apply_visibility_result(p_result: MouseEventVisibilityResult) -> void

Flags: private