IndicatorService
Summary
Section titled “Summary”IndicatorService - Service component for managing rule-check indicators within IndicatorManager.
This class is a service component that IndicatorManager uses to handle the creation, placement, and lifecycle management of RuleCheckIndicator instances. It encapsulates the complex logic for indicator setup, collision mapping, and diagnostic reporting while providing a clean interface for IndicatorManager to delegate indicator-related operations.
Architecture Role IndicatorService acts as a specialized component within the IndicatorManager architecture: - IndicatorManager: Main coordinator that owns and orchestrates indicator operations - IndicatorService: Service component that handles the detailed implementation - IndicatorFactory: Pure logic class for indicator creation and validation
Section titled “Architecture Role IndicatorService acts as a specialized component within the IndicatorManager architecture: - IndicatorManager: Main coordinator that owns and orchestrates indicator operations - IndicatorService: Service component that handles the detailed implementation - IndicatorFactory: Pure logic class for indicator creation and validation”Key Responsibilities - Execute indicator setup workflows with collision mapping and validation - Manage indicator lifecycle including creation, positioning, and cleanup - Provide diagnostic capabilities and comprehensive error reporting - Handle collision detection integration with CollisionMapper - Generate detailed setup reports for testing and debugging
Section titled “Key Responsibilities - Execute indicator setup workflows with collision mapping and validation - Manage indicator lifecycle including creation, positioning, and cleanup - Provide diagnostic capabilities and comprehensive error reporting - Handle collision detection integration with CollisionMapper - Generate detailed setup reports for testing and debugging”Usage Pattern
Section titled “Usage Pattern”var service = IndicatorService.create_with_injection(container, parent_node)var report = service.setup_indicators(test_object, rules, parent_node)var indicators = service.get_indicators()service.reset()For detailed usage guide and examples, see: docs_website/docs/systems/indicator_manager_guide.md
Responsibilities: - Execute indicator setup workflows with collision mapping and validation - Manage indicator lifecycle including creation, positioning, and cleanup - Provide diagnostic capabilities and comprehensive error reporting - Handle collision detection integration with CollisionMapper - Generate detailed setup reports for testing and debugging - Maintain indicator state and provide access to managed indicators - Support comprehensive reset functionality with orphaned indicator detection
Key Features: - Comprehensive reset() function with critical cleanup logging and orphaned indicator detection - Guarded indicator setup with detailed error reporting and diagnostic metadata - Collision mapper integration with test setup management and validation - Grid alignment utilities for stable geometry calculations - Diagnostic information reporting for debugging indicator state and issues - Dependency injection support with comprehensive validation - Signal emission for indicator state changes to support reactive programming
Signals
Section titled “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.
Methods
Section titled “Methods”func _init( p_indicators_parent: Node, p_targeting_state: GridTargetingState, p_indicator_template: PackedScene, p_logger: GBLogger ) -> voidstatic func create_with_injection( container: GBCompositionContainer, parent: Node ) -> IndicatorServiceCreates 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 servicesparent: Node2D - The parent node for indicators (required - cannot be resolved from container)Returns: IndicatorService - Fully configured indicator service with validated dependencies
:::note[Note] Callers should check get_runtime_issues() after creation to handle any validation warnings. :::
func resolve_gb_dependencies( container: GBCompositionContainer ) -> boolResolves 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 otherwisefunc force_update( ) -> voidForces 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.
func 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[Note] This method is non-mutating and safe to call frequently for diagnostic purposes. :::
func reset( parent_node: Node ) -> voidPerforms 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[Note] This method includes critical logging for debugging cleanup issues and double-validation to ensure indicators array is properly cleared. :::
func 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)
func get_diagnostic_info( ) -> DictionaryReturns 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[Note] This method is non-mutating and safe to call for debugging purposes. :::
func get_collision_mapper( ) -> CollisionMapperGets the collision mapper instance. [returns] The collision mapper instance.
func _find_all_indicators( node: Node, result: Array ) -> voidHelper 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 fromresult: Array - Array to append found indicators to (modified in-place)func set_indicators( value: Array[RuleCheckIndicator] ) -> voidfunc setup_indicators( p_test_object: Node2D, p_tile_check_rules: Array[TileCheckRule] ) -> IndicatorSetupReportCreates 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 placementp_tile_check_rules:Array[TileCheckRule]- Rules to create indicators forparent_node:Node- Parent node to attach indicators toReturns: IndicatorSetupReport - Contains created indicators plus diagnostic metadata
:::note[Note] This method includes extensive logging and error handling to support debugging and testing scenarios. It will return error reports instead of throwing exceptions. :::
func calculate_indicator_count( p_test_object: Node2D, p_tile_check_rules: Array[TileCheckRule] ) -> intCalculates 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.func build_collision_test_setups( owner_shapes: Dictionary, tile_size: Vector2i ) -> DictionaryBuilds 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 shapestile_size: Vector2i - Size of tiles for positioning calculationsReturns: Dictionary - Test setups keyed by collision owner
func build_collision_test_setups_with_targeting_state( owner_shapes: Dictionary ) -> DictionaryBuilds 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 shapesReturns: Dictionary - Test setups keyed by collision owner
func gather_collision_shapes( test_object: Node2D ) -> DictionaryGathers 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 fromReturns: Dictionary[Node2D, Array] - Mapping of collision owners to their shapes
func validate_indicator_positions( indicators: Array[RuleCheckIndicator], expected_positions: Array[Vector2i] ) -> IndicatorSetupUtils.PositionValidationResultValidates indicator positions against expected positions. This is a convenience wrapper around IndicatorSetupUtils.validate_indicator_positions().
Parameters:
indicators: Array[RuleCheckIndicator] - Indicators to validateexpected_positions: Array[Vector2i] - Expected tile positionsReturns: IndicatorSetupUtils.PositionValidationResult - Validation result with details
func 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 placementtile_check_rules: Array[TileCheckRule] - Rules to validateReturns: Array[String] - List of validation issues (empty if all valid)
func get_or_create_testing_indicator( parent_node: Node ) -> RuleCheckIndicatorGets 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
func 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[Note] Only includes indicators that are valid instances and have active collisions. :::
func 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[Note] Automatically deduplicates colliding nodes to avoid duplicates in the result. :::
func add_indicators( new_indicators: Array[RuleCheckIndicator] ) -> voidAdds 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[Note] Safely handles null or empty arrays by returning early without modification. :::
func free_indicators( to_free: Array[RuleCheckIndicator] ) -> voidFrees 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[Note] Creates a copy of the array before clearing to avoid modification during iteration. Includes validation and error logging for debugging cleanup issues. :::
func clear_indicators( ) -> voidfunc _get_corner_suffix( tile_pos: Vector2i ) -> StringHelper 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 statusReturns: String - Corner abbreviation (TL, TR, BL, BR) or empty string if not a corner
func _log_summary( p_report: IndicatorSetupReport )func _get_indicator_tile_pos( indicator: RuleCheckIndicator )Helper: compute tile position for an indicator using targeting state
func _reconcile_indicators( new_indicators: Array[RuleCheckIndicator] ) -> Array[RuleCheckIndicator]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.
Source
Section titled “Source”addons/grid_building/placement/manager/components/indicator_service.gd
This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.