Grid Placement

IndicatorService

AUTO-GENERATED FILE — DO NOT EDIT MANUALLY

Source: placement/manager/components/indicator_service.gd

Version: 5.0

class_name: IndicatorService extends: GBInjectable

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

  • indicators_changed
    • 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.

Exports

(none)

Methods

  • _init()
  • resolve_gb_dependencies()
    • 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: [br] [code]container[/code]: [i]GBCompositionContainer[/i] - The dependency container to resolve dependencies from [b]Returns[/b]: [i]bool[/i] - True if dependencies were successfully resolved, false otherwise

  • force_update()
    • 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()
    • 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: [i]Array[String][/i] - 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()
    • 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: [code]parent_node[/code]: [i]Node[/i] - 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()
    • 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: [i]Array[RuleCheckIndicator][/i] - Duplicate of current indicators (safe for external iteration)

  • get_diagnostic_info()
    • 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:

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

Returns: [i]Dictionary[/i] - 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()
    • Gets the collision mapper instance. [returns] The collision mapper instance.
  • _find_all_indicators()
    • Helper method to recursively find all RuleCheckIndicator nodes in the scene tree. Used internally for diagnostic purposes to locate indicator instances.

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

  • set_indicators()
  • setup_indicators()
    • 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: [code]p_test_object[/code]: [code]Node2D[/code] - The object being tested for placement [code]p_tile_check_rules[/code]: [code]Array[TileCheckRule][/code] - Rules to create indicators for [code]parent_node[/code]: [code]Node[/code] - Parent node to attach indicators to

Returns: [i]IndicatorSetupReport[/i] - 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()
    • 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. [param p_test_object] The object to test for placement. [param 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()
    • 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: [code]owner_shapes[/code]: [i]Dictionary[Node2D, Array][/i] - Mapping of collision owners to their shapes [code]tile_size[/code]: [i]Vector2i[/i] - Size of tiles for positioning calculations

Returns: [i]Dictionary[/i] - Test setups keyed by collision owner

  • build_collision_test_setups_with_targeting_state()
    • 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: [code]owner_shapes[/code]: [i]Dictionary[Node2D, Array][/i] - Mapping of collision owners to their shapes

Returns: [i]Dictionary[/i] - Test setups keyed by collision owner

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

Parameters: [code]test_object[/code]: [i]Node2D[/i] - Object to gather collision shapes from

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

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

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

Returns: [i]IndicatorSetupUtils.PositionValidationResult[/i] - Validation result with details

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

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

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

  • get_or_create_testing_indicator()
    • 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: [i]parent_node[/i] - The parent node for the testing indicator

Returns: [i]RuleCheckIndicator[/i] - The testing indicator instance, or null if creation fails

  • get_colliding_indicators()
    • 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: [i]Array[RuleCheckIndicator][/i] - Array of indicators currently in collision state

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

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

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

  • add_indicators()
    • 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: [code]new_indicators[/code]: [i]Array[RuleCheckIndicator][/i] - New indicators to add to the collection

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

  • free_indicators()
    • 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: [code]to_free[/code]: [i]Array[RuleCheckIndicator][/i] - 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()
  • _get_corner_suffix()
    • 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: [code]tile_pos[/code]: [i]Vector2i[/i] - The tile position to check for corner status

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

  • _log_summary()
  • _get_indicator_tile_pos()
    • Helper: compute tile position for an indicator using targeting state
  • _reconcile_indicators()
    • 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.