IndicatorService

AUTO-GENERATED FILE – DO NOT EDIT MANUALLY

IndicatorService - Service component for managing rule-check indicators within IndicatorManager.

Source File: addons/grid_building/placement/manager/components/indicator_service.gd

Extends: GBInjectable

Signals

  • Signal: indicators_changed(_indicators: Array[RuleCheckIndicator])

    Emitted when the active RuleCheckIndicators change. Usually in response to a placement or move action that needs rule evaluation for TileCheckRules. Also emitted during reset operations when indicators are cleared.

Private Properties

  • Property: _indicators: Array[RuleCheckIndicator] = [] (private)
  • Property: _collision_mapper : [CollisionMapper](./collision-mapper/) (private)
  • Property: _testing_indicator: [RuleCheckIndicator](./rule-check-indicator/) (private)
  • Property: _indicator_template: PackedScene (private)
  • Property: _targeting_state: [GridTargetingState](./grid-targeting-state/) (private)
  • Property: _logger : [GBLogger](./gb-logger/) (private)
  • Property: _indicator_contact_positions: Array = [] (private)
  • Property: _indicators_parent : Node (private)
  • Property: _starting_rotation : float (private)
  • Property: _starting_scale : Vector2 (private)

Public Methods

create_with_injection

1
2
3
4

create_with_injection(
    container: GBCompositionContainer,
    parent: Node
) -> IndicatorService

Flags: static

Creates an IndicatorService with dependency injection from container. Container serves as single source of truth for all dependencies. This method handles the complete setup including dependency resolution, validation, and logging of any issues found during initialization.

Parameters: container: GBCompositionContainer - The dependency container providing all required services parent: Node2D - The parent node for indicators (required - cannot be resolved from container)

Returns: IndicatorService - Fully configured indicator service with validated dependencies

Note: Callers should check get_runtime_issues() after creation to handle any validation warnings.

resolve_gb_dependencies

1

resolve_gb_dependencies(container: GBCompositionContainer) -> bool

Resolves dependencies from the composition container. This method is called during initialization and can be called again if the container becomes available later. Primarily used to inject dependencies into the collision mapper.

Parameters:

container: GBCompositionContainer - The dependency container to resolve dependencies from Returns: bool - True if dependencies were successfully resolved, false otherwise

force_update

1

force_update() -> void

Forces all managed indicators to update their shapecast collision detection. This is useful when the scene state has changed and indicators need to recalculate their collision status without regenerating the indicators themselves. Only processes indicators that are still valid instances.

get_runtime_issues

1

get_runtime_issues() -> Array[String]

Validates that all required dependencies and state are properly set. Performs comprehensive validation of the indicator service’s internal state including parent node validity, template availability, targeting state readiness, logger availability, and collision mapper dependency issues.

Returns: Array[String] - List of validation issues (empty if all dependencies are valid)

Note: This method is non-mutating and safe to call frequently for diagnostic purposes.

reset

1

reset(parent_node: Node = null) -> void

Performs comprehensive cleanup of all managed indicators and test setups. This enhanced reset function provides critical cleanup logging and orphaned indicator detection to prevent test pollution and ensure proper teardown.

Cleanup sequence:

  1. Frees all managed indicators with proper validation
  2. Clears collision mapper test setups
  3. Cleans up testing indicator with extra validation
  4. Detects and removes orphaned testing indicators from the scene tree
  5. Emits indicators_changed signal to notify listeners

Parameters: parent_node: Node - Optional parent node to check for orphaned indicators

Note: This method includes critical logging for debugging cleanup issues and double-validation to ensure indicators array is properly cleared.

is_service_ready

1

is_service_ready() -> bool

Checks if the service is in a ready state for indicator operations. Returns true when all critical dependencies are available.

get_indicators

1

get_indicators() -> Array[RuleCheckIndicator]

Returns a duplicate of the current indicators array for safe external use. This method provides read-only access to the managed indicators without allowing external modification of the internal indicators array.

Returns: Array[RuleCheckIndicator] - Duplicate of current indicators (safe for external iteration)

get_diagnostic_info

1

get_diagnostic_info() -> Dictionary

Returns diagnostic information about the current state of the indicator service. This method provides comprehensive diagnostic data useful for debugging indicator cleanup issues, test pollution, and understanding the current state of the service.

The returned dictionary includes:

  • indicators_count: Number of currently managed indicators
  • has_testing_indicator: Whether a testing indicator exists
  • testing_indicator_valid: Whether the testing indicator is a valid instance
  • collision_mapper_setups_count: Number of collision mapper test setups
  • orphaned_indicators: Array of orphaned indicators found (currently unused)

Returns: Dictionary - Diagnostic information about the indicator service’s current state

Note: This method is non-mutating and safe to call for debugging purposes.

get_collision_mapper

1

get_collision_mapper() -> CollisionMapper

Gets the collision mapper instance. [returns] The collision mapper instance.

set_indicators

1

set_indicators(value: Array[RuleCheckIndicator]) -> void

setup_indicators

1
2
3
4

setup_indicators(
    p_test_object: Node2D,
    p_tile_check_rules: Array[TileCheckRule]
) -> IndicatorSetupReport

Creates and positions rule check indicators for validation. This is the main method for setting up indicators based on a test object and tile check rules. The method performs comprehensive validation, collision mapping, and indicator generation with detailed error reporting and diagnostic metadata.

Process overview:

  1. Validates environment and inputs through guard checks
  2. Normalizes positioning for stable geometry calculations
  3. Gathers collision shapes from the test object
  4. Sets up collision mapper with test configurations
  5. Maps collision positions to applicable rules
  6. Generates indicators using the factory pattern
  7. Builds and returns comprehensive setup report

Parameters: p_test_object: Node2D - The object being tested for placement p_tile_check_rules: Array[TileCheckRule] - Rules to create indicators for parent_node: Node - Parent node to attach indicators to

Returns: IndicatorSetupReport - Contains created indicators plus diagnostic metadata

Note: This method includes extensive logging and error handling to support debugging and testing scenarios. It will return error reports instead of throwing exceptions.

calculate_indicator_count

1
2
3
4

calculate_indicator_count(
    p_test_object: Node2D,
    p_tile_check_rules: Array[TileCheckRule]
) -> int

Calculates the number of indicators that would be created for a test object without actually creating them. This performs the same collision analysis as setup_indicators but stops before indicator creation. p_test_object The object to test for placement. p_tile_check_rules The tile check rules to apply. [returns] The number of indicators that would be created, or -1 if calculation fails.

build_collision_test_setups

1
2
3
4

build_collision_test_setups(
    owner_shapes: Dictionary,
    tile_size: Vector2i
) -> Dictionary

Builds per-owner collision test setups for CollisionMapper using utility function. Creates appropriate test setup configurations for different collision owner types. This is a convenience wrapper around IndicatorSetupUtils.build_collision_test_setups().

Parameters: owner_shapes: Dictionary[Node2D, Array] - Mapping of collision owners to their shapes tile_size: Vector2i - Size of tiles for positioning calculations

Returns: Dictionary - Test setups keyed by collision owner

build_collision_test_setups_with_targeting_state

1

build_collision_test_setups_with_targeting_state(owner_shapes: Dictionary) -> Dictionary

Builds collision test setups using targeting state for more accurate configuration. This variant uses the service’s GridTargetingState for consistent tile size handling. This is a convenience wrapper around IndicatorSetupUtils.build_collision_test_setups_with_factory().

Parameters: owner_shapes: Dictionary[Node2D, Array] - Mapping of collision owners to their shapes

Returns: Dictionary - Test setups keyed by collision owner

gather_collision_shapes

1

gather_collision_shapes(test_object: Node2D) -> Dictionary

Gathers collision shapes from a test object. This is a convenience wrapper around IndicatorSetupUtils.gather_collision_shapes().

Parameters: test_object: Node2D - Object to gather collision shapes from

Returns: Dictionary[Node2D, Array] - Mapping of collision owners to their shapes

validate_indicator_positions

1
2
3
4

validate_indicator_positions(
    indicators: Array[RuleCheckIndicator],
    expected_positions: Array[Vector2i]
) -> IndicatorSetupUtils.PositionValidationResult

Validates indicator positions against expected positions. This is a convenience wrapper around IndicatorSetupUtils.validate_indicator_positions().

Parameters: indicators: Array[RuleCheckIndicator] - Indicators to validate expected_positions: Array[Vector2i] - Expected tile positions

Returns: IndicatorSetupUtils.PositionValidationResult - Validation result with details

validate_setup_preconditions

1
2
3
4

validate_setup_preconditions(
    test_object: Node2D,
    tile_check_rules: Array[TileCheckRule]
) -> Array[String]

Validates setup preconditions for indicator creation. This is a convenience wrapper around IndicatorSetupUtils.validate_setup_preconditions().

Parameters: test_object: Node2D - Object being tested for placement tile_check_rules: Array[TileCheckRule] - Rules to validate

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

get_or_create_testing_indicator

1

get_or_create_testing_indicator(parent_node: Node) -> RuleCheckIndicator

Gets or creates a testing indicator using the utility function. Uses lazy initialization to create the testing indicator only when needed. This is a convenience wrapper around IndicatorSetupUtils.create_testing_indicator().

Parameters: parent_node - The parent node for the testing indicator

Returns: RuleCheckIndicator - The testing indicator instance, or null if creation fails

get_colliding_indicators

1

get_colliding_indicators() -> Array[RuleCheckIndicator]

Returns array of indicators that are currently colliding with other objects. Filters all managed indicators to find only those with active collision states. This is useful for determining which placement positions are blocked or invalid.

Returns: Array[RuleCheckIndicator] - Array of indicators currently in collision state

Note: Only includes indicators that are valid instances and have active collisions.

get_colliding_nodes

1

get_colliding_nodes() -> Array[Node2D]

Returns array of Node2D objects that are colliding with any indicators. Collects all unique collision objects from all colliding indicators. This provides a convenient way to identify which scene objects are blocking placement.

Returns: Array - Array of unique Node2D objects colliding with any managed indicators

Note: Automatically deduplicates colliding nodes to avoid duplicates in the result.

add_indicators

1

add_indicators(new_indicators: Array[RuleCheckIndicator]) -> void

Adds new indicators to the managed collection. Appends the provided indicators to the internal indicators array and emits the indicators_changed signal to notify listeners of the change.

Parameters: new_indicators: Array[RuleCheckIndicator] - New indicators to add to the collection

Note: Safely handles null or empty arrays by returning early without modification.

free_indicators

1

free_indicators(to_free: Array[RuleCheckIndicator]) -> void

Frees and removes indicators from memory and scene tree. Enhanced cleanup method that properly handles indicator lifecycle management with validation and comprehensive cleanup logging.

Parameters: to_free: Array[RuleCheckIndicator] - Indicators to free and remove

Note: Creates a copy of the array before clearing to avoid modification during iteration. Includes validation and error logging for debugging cleanup issues.

clear_indicators

1

clear_indicators() -> void

Private Methods

_init

1
2
3
4
5
6

_init(
    p_indicators_parent : Node,
    p_targeting_state: GridTargetingState,
    p_indicator_template : PackedScene,
    p_logger : GBLogger
) -> void

Flags: private

_find_all_indicators

1
2
3
4

_find_all_indicators(
    node: Node,
    result: Array
) -> void

Flags: private

Helper method to recursively find all RuleCheckIndicator nodes in the scene tree. Used internally for diagnostic purposes to locate indicator instances.

Parameters: node: Node - Root node to start the recursive search from result: Array - Array to append found indicators to (modified in-place)

_get_corner_suffix

1

_get_corner_suffix(tile_pos: Vector2i) -> String

Flags: private

Helper function to determine if a tile position is at a corner and return appropriate suffix. Analyzes the current indicator positions to determine bounds and identifies corner positions.

Parameters: tile_pos: Vector2i - The tile position to check for corner status

Returns: String - Corner abbreviation (TL, TR, BL, BR) or empty string if not a corner

_log_summary

1

_log_summary(p_report : IndicatorSetupReport)

Flags: private

_get_indicator_tile_pos

1

_get_indicator_tile_pos(indicator: RuleCheckIndicator)

Flags: private

Helper: compute tile position for an indicator using targeting state

_reconcile_indicators

1
2
3

_reconcile_indicators(
    new_indicators: Array[RuleCheckIndicator]
) -> Array[RuleCheckIndicator]

Flags: private

Reconcile newly created indicators with existing managed indicators. Strategy:

  • Build a map of existing indicators keyed by tile position
  • For each new indicator, compute its tile position; if an existing indicator exists at that position, reuse it: clear its rules and add the rules from the new indicator, update its global_position and visuals, then free the newly created duplicate.
  • Any existing indicators not matched are freed.
  • Returns the final array of indicators managed by the service.