Skip to content
Grid Building Docs

GridPositionerLogic

Summary

Section titled “Summary”

Static utility class for GridPositioner logic (visibility and decision helpers).

This class contains static functions for computing visibility decisions and diagnostic traces, making them easily unit testable without requiring a full GridPositioner2D instance.

All functions are pure and depend only on their input parameters.

Methods

Section titled “Methods”
static func proj_method_to_string( p_method: GBEnums.ProjectionMethod ) -> String
static func should_be_visible( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings, last_mouse_input_status: GBMouseInputStatus, has_mouse_world: bool ) -> bool

Computes whether the positioner should be visible based on mode and settings.

Visibility is determined by the following priority order: 1. Mode-based visibility: OFF mode respects remain_active_in_off_mode, INFO mode is always hidden 2. Recent allowed input: If mouse input was recently allowed, show positioner 3. Cached mouse world override: If mouse world position exists and mouse input enabled, show positioner (overrides hide_on_handled) 4. Hide on handled: If mouse input enabled + hide_on_handled=true + input blocked, hide positioner 5. Default: Show positioner for active modes (BUILD, MOVE, etc.)

Hide on handled behavior:

  • Only applies when targeting_settings.enable_mouse_input is true - When mouse input is disabled, hide_on_handled setting is ignored - Cached mouse world position takes precedence over hide_on_handled logic

mode: The current building mode (GBEnums.Mode) targeting_settings: The targeting settings object last_mouse_input_status: Dictionary with last mouse input gate status has_mouse_world: Whether cached mouse world position exists Returns: True if the positioner should be visible

static func should_be_visible_for_mode( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings ) -> bool

Computes visibility for a specific mode value. mode: The mode to check targeting_settings: The targeting settings Returns: True if visible in this mode

static func is_positioner_active( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings ) -> bool

Returns whether the positioner is considered active for the given mode/settings.

static func is_mouse_follow_allowed( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings, input_ready: bool ) -> bool

Mouse follow allowed gate

static func visibility_decision_trace( mode_state: ModeState, targeting_settings: GridTargetingSettings, last_mouse_input_status: GBMouseInputStatus, has_mouse_world: bool ) -> String

Builds a diagnostic trace string for visibility decisions. mode_state: The mode state object (can be null) targeting_settings: The targeting settings (can be null) last_mouse_input_status: Last mouse input status dict has_mouse_world: Whether cached mouse world exists Returns: Formatted trace string

static func visibility_on_mouse_event( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings, input_allowed: bool )

Event-driven visibility decision helper. Returns a MouseEventVisibilityResult with apply=true when the positioner visibility should be changed because of an InputEvent (mouse motion) and visible indicating the target visibility. Reason is a short string for diagnostics.

static func visibility_on_process_tick( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings, input_ready: bool, last_mouse_input_status: GBMouseInputStatus, has_mouse_world: bool ) -> MouseEventVisibilityResult

Per-tick visibility decision helper used by GridPositioner2D._process. It centralizes the behavior where, even when continuous follow without events is disabled, we keep the positioner visible if recent mouse input was allowed or a cached mouse world exists. Only applies when hide_on_handled is true.

static func visibility_reconcile( mode: GBEnums.Mode, targeting_settings: GridTargetingSettings, current_visible: bool, last_mouse_input_status: GBMouseInputStatus, has_mouse_world: bool ) -> MouseEventVisibilityResult

Per-tick reconciliation: if computed visibility differs from current, request an update. This ensures that when no event has fired yet (e.g., on scene load), the positioner is set to the expected visibility derived from mode/settings.

static func recenter_on_enable_decision( policy: int, has_cached_mouse_world: bool, mouse_input_enabled: bool, viewport_available: bool ) -> int

Decide how to recenter on enable based on policy and available context. Returns a RecenterDecision enum value indicating the preferred action. Policy mapping: - NONE -> NONE - LAST_SHOWN -> LAST_SHOWN if cached; else MOUSE_CURSOR if mouse enabled; else VIEW_CENTER - VIEW_CENTER -> VIEW_CENTER - MOUSE_CURSOR -> MOUSE_CURSOR if cached or (mouse enabled and viewport available); else VIEW_CENTER

static func get_tile_delta_from_key_event( event: InputEventKey, actions: GBActions ) -> Vector2i

Keyboard helper: compute tile delta from a key event and actions

static func get_rotation_direction_from_key_event( event: InputEventKey, actions: GBActions ) -> int

Keyboard helper: detect rotation input from a key event and actions event: The keyboard input event to check actions: GBActions containing rotation action mappings Returns: Rotation direction: 1 for clockwise, -1 for counter-clockwise, 0 for no rotation

Source

Section titled “Source”

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

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