Validation: Configuration

Use this guide when the plugin is installed but you want to verify that the project, host, session, level, and rules are wired correctly.

Version note: This guide is for Grid Placement 6.0.0.

1. Project-Level Checks

After enabling the plugin:

1. Go to Project → Project Settings → Plugins and enable Grid Placement.
2. Run Project → Tools → Grid Placement / Setup Default Input Actions.
3. Check the Output panel for confirmation.
4. Restart or reload the project.
5. Open Project Settings → Input Map and confirm the placement actions exist.

If input does nothing, check this section before debugging placement code.

2. Host Runtime Checks

GridPlacementHost is the main runtime coordinator. After your level context and owner have entered the scene, check:

@onready var host: GridPlacementHost = $GridPlacementHost

func _ready() -> void:
    if not host.is_ready():
        push_warning("GridPlacementHost is not ready")

    for issue in host.get_runtime_issues():
        push_warning(issue)

host.get_runtime_issues() returns human-readable setup problems, such as missing session state, missing service group, or missing target map.

Common blocking issues:

• No PlacementSession configured or registered.
• PlacementLevelContext.target_map is not assigned.
• PlacementLevelContext.objects_parent is not assigned.
• PlacementOwner.owner_root is not assigned.
• GridPositioner2D did not register into the active targeting state.
• Required service settings are missing from the active bundle/settings.

3. Injector Validation

If you use PlacementInjectorSystem, remember that runtime validation is only meaningful after level/player nodes have been injected.

func _ready() -> void:
    await get_tree().process_frame
    injector.run_validation()

The injector does not invent missing nodes. It can wire existing nodes that implement resolve_placement_dependencies(...), but you still need to add and configure PlacementLevelContext, PlacementOwner, and any UI/preview nodes your scene uses.

4. Rule Validation Classes

Grid Placement has two different validation concerns:

Do not mix these up:

• Missing target_map is a configuration/readiness issue.
• Placing a building on a blocked tile is a placement-validity issue.

5. Placement Result Types

PlacementValidationResult

ValidationResults

PlacementReport

For user-facing placement attempts, the most useful type is usually PlacementReport from PlacementActionData.report.

func _on_action_performed(data: PlacementActionData) -> void:
    if data == null or data.report == null:
        return

    if not data.report.is_successful():
        for issue in data.report.get_issues():
            print(issue)

Tips

• Keep configuration validation fast; it may run during startup or scene setup.
• Differentiate between invalid configuration and invalid placement.
• Show PlacementReport.get_issues() in UI instead of re-implementing rule checks.
• Use PlacementValidationResult when you need cell-level granularity for multi-cell terrain or brush workflows.
• Save important runtime resources as external .tres files for web/export reliability. See Web Export Guide.

Related Guides

• Placement Rules
• Placement Workflow
• Troubleshooting
• Web Export Guide