Grid Placement

GridPositioner2D

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: systems/grid_targeting/grid_positioner/grid_positioner_2d.gd

Version: 5.0

class_name: GridPositioner2D extends: Node2D

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.

Signals

(none)

Exports

(none)

Methods

  • _init()
    • Fail fast design. Defaults should be explicitly set by scenes or tests.
  • _ready()
  • _physics_process()
  • _process()
  • set_input_processing_enabled()
    • Public API used by tests to enable input handling on this node.
  • is_input_processing_enabled()
  • is_input_ready()
    • Public helper: returns true when dependencies are injected and a target map is assigned
  • are_dependencies_ready()
    • 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()
    • 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.
  • _input()
    • 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()
    • Extracted helper: handle an InputEventMouseMotion event (snapped move + visibility)
  • _convert_screen_to_world()
    • Single source of truth: centralized screen-to-world coordinate conversion Delegates to GBPositioning2DUtils for DRY compliance and maintainability
  • _move_to_cached_mouse_world()
    • Move the positioner back to its cached mouse world location when available.
  • _cache_current_world_position()
    • Cache the current global position as the latest mouse world reference.
  • _get_active_viewport()
    • Helper: retrieve active Viewport for the current target map (may be null)
  • _get_active_camera()
    • Helper: retrieve active Camera2D from a viewport (may be null)
  • _is_disabled_in_off_mode()
    • 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()
    • Helper: check if mouse cursor is within viewport bounds Returns true if mouse cursor is within the visible viewport area
  • _is_mouse_follow_allowed()
    • Helper: decide whether mouse-follow behavior should run this frame
  • _mouse_input_gate()
    • Returns a gate result for handling mouse input with an explicit reason when blocked
  • _apply_mouse_world()
    • Centralizes caching + movement application and diagnostics
  • _log_mouse_motion()
    • Helper: structured mouse motion log
  • _log_mouse_gate()
    • Helper: structured mouse gate log
  • _apply_recenter_on_enable()
    • 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()
    • 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()
  • _handle_mouse_movement()
    • 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()
    • Moves the positioner by a specified number of tiles in a given direction.[br][br] [code]p_direction[/code]: [i]Vector2[/i] - Direction vector (e.g., Vector2(1,0) for right, Vector2(0,1) for down)
  • move_to_viewport_center_tile()
    • 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()
    • 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.
  • _apply_recenter()
    • Apply manual recenter logic based on settings.
  • get_last_manual_recenter_mode()
    • Retrieve the last manual recenter mode applied.
  • _exit_tree()
  • remove_self_as_positioner()
    • Removes this object from being set to the _targeting_state.positioner property
  • update_visibility()
    • 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()
    • Returns whether the positioner should be visible given current mode/settings. Mouse handled gating remains event-driven and is not applied here.
  • set_dependencies()
    • 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. [param p_states] GBStates providing .targeting and .mode [param p_config] GBConfig for settings (expects settings.targeting) [param p_logger] Optional GBLogger for diagnostics [param p_actions] Optional GBActions for keyboard bindings [param enable_input] When true, enable input processing immediately (default true)
  • get_runtime_issues()
    • Checks if the properties of the GridPositioner2D are set properly during gameplay. Returns validation issues if dependencies are missing, empty array if valid.[br][br] [code]return[/code]: [i]Array[String][/i] - List of validation issues (empty if valid)
  • validate_dependencies()
    • Runtime validation logs all issues that should be resolved at runtime [br] Call after all dependencies are expected to be resolved.
  • _on_mode_changed()
  • _should_be_visible_for_mode()
    • Helper to compute visibility given an explicit mode value
  • get_visual_node()
    • Visual helpers are provided by GBSearchUtils universally
  • is_visual_visible()
  • _set_visible_state()
    • Helper to keep this node and its visual in sync for visibility
  • log_current_visual_state()
    • Helper: explicit render state log for manual triggering if needed
  • _schedule_end_of_frame_state_log()
    • Schedule end-of-frame state logging (deferred to next frame to catch final state)
  • _log_end_of_frame_state_async()
    • Async log of end-of-frame state (called deferred)
  • _log_screen_and_mouse_state()
    • Diagnostic: log screen/camera bounds, positioner screen relation, mouse world, and tile info
  • _visibility_context()
    • Build a visibility context string: first hidden ancestor, alpha, z-index, and position
  • is_positioner_active()
    • Whether the positioner is active and should update each frame
  • should_hide_under_handled_ui()
    • Whether the positioner should hide when the mouse events are handled by UI
  • are_dependencies_resolved()
    • Check if all critical dependencies have been resolved
  • to_diagnostic_string()
    • Diagnostics: concise state summary for tests and debug logging Safe to call even before dependency injection - provides fallback values
  • _set_visibility_reason()
  • _visibility_decision_trace()
  • _get_debug_log_mode()
  • _is_logging_mode()
  • _is_visibility_logging_enabled()
  • _is_mouse_input_logging_enabled()
  • _is_positioning_logging_enabled()
  • _is_state_flow_logging_enabled()
  • _log_debug()
  • _log_visibility()
  • _log_mouse()
  • _log_positioning()
  • _log_state_flow()
  • _test_convert_screen_to_world()
    • Unit test helper: verify screen-to-world coordinate conversion Returns the converted world position for testing purposes
  • _test_get_tile_center_from_screen()
    • Unit test helper: verify tile center calculation Returns the tile coordinate and world position for testing
  • _apply_visibility_result()