IndicatorService

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

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

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

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

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( ) -> 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( ) -> 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( parent_node: Node ) -> 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.

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( ) -> 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( ) -> CollisionMapper

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

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

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.

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( ) -> 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[Node2D] - Array of unique Node2D objects colliding with any managed indicators

Note

Automatically deduplicates colliding nodes to avoid duplicates in the result.

get_or_create_testing_indicator( parent_node: Node ) -> RuleCheckIndicator

Returns the shared testing indicator, creating it if it doesn’t exist. The testing indicator is used for collision setup and validation before creating real indicators. This method implements lazy initialization and is safe to call multiple times. The testing indicator is configured to suppress rule-ready logs and is named “_TestingIndicator” for easy identification.

Parameters: parent_node: Node - Parent node to attach the testing indicator to

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

Note

Validates dependencies before creation and returns null with error logging if validation fails.

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( 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.

Source

addons/grid_building/placement/manager/components/indicator_service.gd

---

This page was auto-generated from GDScript source. Edit the source file to improve documentation.

Generated on 2025-09-07