Validation: Configuration

Historical 5.x guide. This page describes a legacy API and is not current integration guidance. For new projects, start with Getting Started.

This page outlines validation utilities for configuration validation at initialization — checking that settings, resources, and dependencies are properly configured when the scene loads.

This guide = Validation of configuration at startup (via GBInjectorSystem or manual setup). Placement Rules = Runtime validation when placing objects (e.g., checking grid bounds).

Configuration Validation with PlacementValidator

In 5.0.8: PlacementValidator handles validation. It uses placement rules to validate potential placements at runtime.

Core Validation Classes

1. PlacementValidator: The main class that orchestrates validation. It takes a list of rules and evaluates them against the current placement context.
2. ValidationResults: A data container that captures the outcome of validation. It holds is_successful, issues (errors), and warnings.

How It Works

1. Setup: Create a PlacementValidator with your configured rules.
2. Validation: Call validate_placement(context) to check a potential placement.
3. Results: Get a ValidationResults object with success status and any issues.

ValidationResults

Property	Type	Description
is_successful	bool	True if no blocking issues were found.
issues	Array[String]	List of critical errors that prevent operation.
warnings	Array[String]	List of non-critical observations.

Usage Example

# Example: Using PlacementValidator
var validator= PlacementValidator.new(rules, logger)
var context= PlacementRuleContext.new()
context.target_cell= Vector2i(5,3)
context.grid_size= Vector2i(10,10)

var results= validator.validate_placement(context)
if not results.is_successful:
    for issuein results.issues:
        print("Validation failed: ", issue)

Add to entity (Component-based)

my_entity.add_child(rule_comp)

By standardizing on `PlacementRule`, the system can transparently inspect, validate, and execute rules without needing to know the specific logic of every single rule type.

## Tips

- Keep configuration validation fast; it runs during entity creation or system startup.
- Differentiate between **Invalid Configuration** (developer error, e.g., missing resource) and **Invalid Placement** (player error, e.g., placing inside a wall).
- Use `ValidationResults` to combine results from multiple rules into a single report.

## Related Guides

* [Placement Rules](/docs/grid-placement/v5-0/guides/placement-rules/)
* [Placement Workflow](/docs/grid-placement/v5-0/guides/placement-workflow/)

## Validated By

The validation architecture is verified by the following test suites, which ensure that validation result containers and rule components behave correctly under various configurations.

* **Configuration Validation**: **res://addons/grid_placement/test/utilities/gb_configuration_validator_test.gd** — Verifies that the injector correctly triggers validation after wiring.
* **Result Management**: **res://addons/grid_placement/test/rules/validation/valid_placement_tile_rule_test.gd** — Tests tile rule validation and placement correctness.
* **System Integration**: **res://addons/grid_placement/test/rules/validation/rule_system_integration_tests.gd** — Validates the full sequence of validation logic within the placement systems.

## Further Tips