GridPositioner2D

Unit test helper: verify tile...

sort Weight: 10

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

Version: v5.0.0

STABLE

Inherits: Node2D
Source: grid_positioner_2d.gd
Parsing: AST-based for maximum accuracy with symbol typing

Constants

LOG_PREFIX

Enums are defined in logic/utils

Type: String

Value: "[GridPositioner2D]"

Variables

_debug_settings:

_logger:

Explicitly injected dependencies (no service locator usage inside this class)

_actions:

_targeting_state: GridTargetingState

The state of the building/targeting system holding a reference to this positioner.

Type: GridTargetingState

_targeting_settings: GridTargetingSettings

Type: GridTargetingSettings

_mode_state: ModeState

Start invisible until proper dependencies are injected

Type: ModeState

_last_mouse_world:

Cache last known mouse world position from events/projection for safe per-frame follow

_has_mouse_world:

input_processing_enabled:

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

_enabled_internal:

Internal storage for assignments performed directly on the property

_last_mouse_input_status

Last evaluation of mouse input gate and projection snapshot for diagnostics

_last_gate_allowed:

Track last mouse gate state to throttle logs

_last_manual_recenter_mode:

Track last manual recenter mode (for diagnostics/tests)

_last_visibility_event_reason:

Capture the most recent visibility toggle reason to enhance diagnostics when turned off

Methods

_init

Signature: _init() -> void

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

Returns: void

_ready

Signature: _ready() -> void

Returns: void

_physics_process

Signature: _physics_process(delta: float) -> void

Returns: void

Parameters:

  • delta: float

_process

Signature: _process(delta: float) -> void

Diagnostics when enabled (guarded by debug mode)

Returns: void

Parameters:

  • delta: float

set_input_processing_enabled

Signature: set_input_processing_enabled(p_enabled: bool) -> void

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

Returns: void

Parameters:

  • p_enabled: bool

is_input_processing_enabled

Signature: is_input_processing_enabled() -> bool

Returns: bool

is_input_ready

Signature: is_input_ready() -> bool

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

Returns: bool

are_dependencies_ready

Signature: are_dependencies_ready() -> bool

Use this to guard input methods that need to log or access settings

Returns: bool

resolve_gb_dependencies

Signature: resolve_gb_dependencies(p_config : GBCompositionContainer: Variant) -> void

Internally delegates to set_dependencies() for actual wiring.

Returns: void

Parameters:

  • p_config : GBCompositionContainer: Variant

_input

Signature: _input(event : InputEvent: Variant) -> void

INPUT: All mouse movement is handled here in response to events; not in physics.

Returns: void

Parameters:

  • event : InputEvent: Variant

_handle_mouse_motion_event

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

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

Returns: void

Parameters:

  • motion: InputEventMouseMotion
  • current_mode: GBEnums.Mode: Variant

_convert_screen_to_world

Signature: _convert_screen_to_world(screen_pos: Vector2) -> Vector2

Delegates to GBPositioning2DUtils for DRY compliance and maintainability

Returns: Vector2

Parameters:

  • screen_pos: Vector2

_move_to_cached_mouse_world

Signature: _move_to_cached_mouse_world() -> Vector2i

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

Returns: Vector2i

_cache_current_world_position

Signature: _cache_current_world_position() -> void

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

Returns: void

_get_active_viewport

Signature: _get_active_viewport() -> Viewport

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

Returns: Viewport

_get_active_camera

Signature: _get_active_camera(p_vp: Viewport) -> Camera2D

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

Returns: Camera2D

Parameters:

  • p_vp: Viewport

_is_disabled_in_off_mode

Signature: _is_disabled_in_off_mode() -> bool

Returns true if positioner should be blocked from input/positioning in OFF mode

Returns: bool

_is_mouse_cursor_on_screen

Signature: _is_mouse_cursor_on_screen() -> bool

Returns true if mouse cursor is within the visible viewport area

Returns: bool

_is_mouse_follow_allowed

Signature: _is_mouse_follow_allowed() -> bool

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

Returns: bool

_mouse_input_gate

Signature: _mouse_input_gate() -> bool

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

Returns: bool

_apply_mouse_world

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

Centralizes caching + movement application and diagnostics

Returns: void

Parameters:

  • world: Vector2
  • method: int
  • screen: Vector2

_log_mouse_motion

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

Helper: structured mouse motion log

Returns: void

Parameters:

  • p_method: int
  • p_screen: Vector2
  • p_world: Vector2

_log_mouse_gate

Signature: _log_mouse_gate(p_allowed: bool) -> void

Helper: structured mouse gate log

Returns: void

Parameters:

  • p_allowed: bool

_apply_recenter_on_enable

Signature: _apply_recenter_on_enable() -> void

Respects the active when off setting - no positioning changes when disabled in OFF mode

Returns: void

_apply_positioning_and_visibility_sequence

Signature: _apply_positioning_and_visibility_sequence() -> void

This ensures Camera2D is available for positioning and visibility is updated based on final position

Returns: void

_recenter_decision_to_string

Signature: _recenter_decision_to_string(p_decision: int) -> String

Then apply visibility based on current state (respect hide_on_handled)

Returns: String

Parameters:

  • p_decision: int

_handle_mouse_movement

Signature: _handle_mouse_movement(mouse_global_override: Variant = null) -> void

compatibility with tests (SceneRunner) and hidden cursor scenarios.

Returns: void

Parameters:

  • mouse_global_override: Variant (optional, default: null)

_move_positioner_by_tile

Signature: _move_positioner_by_tile(p_tile_delta: Vector2i) -> void

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

Returns: void

Parameters:

  • p_tile_delta: Vector2i

move_to_viewport_center_tile

Signature: move_to_viewport_center_tile() -> Vector2i

Returns the tile coordinate where the positioner was positioned, or Vector2i.ZERO if failed.

Returns: Vector2i

move_to_cursor_center_tile

Signature: move_to_cursor_center_tile() -> Vector2i

Returns the tile coordinate where the positioner was positioned.

Returns: Vector2i

_apply_recenter

Signature: _apply_recenter() -> void

Apply manual recenter logic based on settings.

Returns: void

get_last_manual_recenter_mode

Signature: get_last_manual_recenter_mode() -> int

Retrieve the last manual recenter mode applied.

Returns: int

_exit_tree

Signature: _exit_tree() -> void

Returns: void

remove_self_as_positioner

Signature: remove_self_as_positioner() -> void

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

Returns: void

update_visibility

Signature: update_visibility() -> void

be visible or invisible. Only called when hide_on_handled is true

Returns: void

should_be_visible

Signature: should_be_visible() -> bool

Mouse handled gating remains event-driven and is not applied here.

Returns: bool

set_dependencies

Signature: set_dependencies(p_states : GBStates: Variant, p_config : GBConfig: Variant, p_logger: GBLogger = null, p_actions: GBActions = null, enable_input: bool = true) -> void

[param enable_input] When true, enable input processing immediately (default true)

Returns: void

Parameters:

  • p_states : GBStates: Variant
  • p_config : GBConfig: Variant
  • p_logger: GBLogger (optional, default: null)
  • p_actions: GBActions (optional, default: null)
  • enable_input: bool (optional, default: true)

get_runtime_issues

Signature: get_runtime_issues() -> Array

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

Returns: Array

validate_dependencies

Signature: validate_dependencies() -> bool

Call after all dependencies are expected to be resolved.

Returns: bool

_on_mode_changed

Signature: _on_mode_changed(p_mode : GBEnums.Mode: Variant) -> void

Returns: void

Parameters:

  • p_mode : GBEnums.Mode: Variant

_should_be_visible_for_mode

Signature: _should_be_visible_for_mode(p_mode: GBEnums.Mode: Variant) -> bool

Helper to compute visibility given an explicit mode value

Returns: bool

Parameters:

  • p_mode: GBEnums.Mode: Variant

get_visual_node

Signature: get_visual_node() -> Node

Visual helpers are provided by GBSearchUtils universally

Returns: Node

is_visual_visible

Signature: is_visual_visible() -> bool

Returns: bool

_set_visible_state

Signature: _set_visible_state(p_visible: bool) -> void

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

Returns: void

Parameters:

  • p_visible: bool

log_current_visual_state

Signature: log_current_visual_state() -> void

Helper: explicit render state log for manual triggering if needed

Returns: void

_schedule_end_of_frame_state_log

Signature: _schedule_end_of_frame_state_log() -> void

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

Returns: void

_log_end_of_frame_state_async

Signature: _log_end_of_frame_state_async() -> void

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

Returns: void

_log_screen_and_mouse_state

Signature: _log_screen_and_mouse_state() -> void

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

Returns: void

_visibility_context

Signature: _visibility_context(visual: CanvasItem) -> String

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

Returns: String

Parameters:

  • visual: CanvasItem

is_positioner_active

Signature: is_positioner_active() -> bool

Whether the positioner is active and should update each frame

Returns: bool

should_hide_under_handled_ui

Signature: should_hide_under_handled_ui() -> bool

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

Returns: bool

are_dependencies_resolved

Signature: are_dependencies_resolved() -> bool

Check if all critical dependencies have been resolved

Returns: bool

to_diagnostic_string

Signature: to_diagnostic_string() -> String

Safe to call even before dependency injection - provides fallback values

Returns: String

_set_visibility_reason

Signature: _set_visibility_reason(p_reason: String) -> void

Defensive: provide diagnostic info even if dependencies aren’t fully resolved

Returns: void

Parameters:

  • p_reason: String

_visibility_decision_trace

Signature: _visibility_decision_trace() -> String

Returns: String

_get_debug_log_mode

Signature: _get_debug_log_mode() -> GBDebugSettings

Pass a Dictionary snapshot (public API) to the logic helper to satisfy its typed signature

Returns: GBDebugSettings

_is_logging_mode

Signature: _is_logging_mode(p_mode: GBDebugSettings.GridPositionerLogMode: Variant) -> bool

Returns: bool

Parameters:

  • p_mode: GBDebugSettings.GridPositionerLogMode: Variant

_is_visibility_logging_enabled

Signature: _is_visibility_logging_enabled() -> bool

Returns: bool

_is_mouse_input_logging_enabled

Signature: _is_mouse_input_logging_enabled() -> bool

Returns: bool

_is_positioning_logging_enabled

Signature: _is_positioning_logging_enabled() -> bool

Returns: bool

_is_state_flow_logging_enabled

Signature: _is_state_flow_logging_enabled() -> bool

Returns: bool

_log_debug

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

Returns: void

Parameters:

  • p_mode: GBDebugSettings.GridPositionerLogMode: Variant
  • p_message: String
  • p_throttled: bool (optional, default: true)

_log_visibility

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

Returns: void

Parameters:

  • p_message: String
  • p_throttled: bool (optional, default: true)

_log_mouse

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

Returns: void

Parameters:

  • p_message: String
  • p_throttled: bool (optional, default: true)

_log_positioning

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

Returns: void

Parameters:

  • p_message: String
  • p_throttled: bool (optional, default: true)

_log_state_flow

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

Returns: void

Parameters:

  • p_message: String
  • p_throttled: bool (optional, default: true)

_test_convert_screen_to_world

Signature: _test_convert_screen_to_world(screen_pos: Vector2) -> Vector2

Returns the converted world position for testing purposes

Returns: Vector2

Parameters:

  • screen_pos: Vector2

_test_get_tile_center_from_screen

Signature: _test_get_tile_center_from_screen(screen_pos: Vector2) -> Dictionary

Returns the tile coordinate and world position for testing

Returns: Dictionary

Parameters:

  • screen_pos: Vector2

_apply_visibility_result

Signature: _apply_visibility_result(p_result: MouseEventVisibilityResult) -> void

Calculate tile center position using TileMapLayer methods

Returns: void

Parameters:

  • p_result: MouseEventVisibilityResult