Placement Rules

This page documents the placement rule classes and validation system in Grid Building v5.0.0.

Core Concepts

Placement Rules System

The placement rules system provides extensible validation logic for determining where objects can be placed. This is a core entry point for customizing building behavior.

🎯 Key Entry Points

Base Classes (extend these):

• PlacementRule - Base class for all validation
• TileCheckRule - Spatial/per-tile validation

Common Rule Classes (use these):

• CollisionsCheckRule - Physics collision validation
• WithinTilemapBoundsRule - Tilemap boundary validation
• ValidPlacementTileRule - Custom tile validation

1. setup(params: RuleValidationParameters) -> Array[String] — validate context & capture references.
2. validate_placement() -> RuleResult — compute pass/fail (and message).
3. apply() -> bool (optional) — run only after all rules pass (e.g. spend inventory materials).
4. tear_down() — cleanup when preview target changes or build mode exits.

Each RuleResult couples: the rule instance, is_successful: bool, and a human‑readable message.

Rules that operate on per‑tile indicators usually extend TileCheckRule, which adds:

• indicators : Array[RuleCheckIndicator] (shape casts / tile probes)
• visual_priority & fail_visual_settings for indicator coloring precedence.

RuleFilters.only_tile_check(rules) helps extract all TileCheckRule instances from a mixed array.

Major Enhancements in v5.0.0

🏗️ Architectural Improvements

• Enhanced RuleResult Structure: More detailed validation reporting with better error messages
• Improved Diagnostics: Better logging and debugging support for rule execution
• Performance Optimizations: Reduced allocations and faster validation cycles {/* Supports 4.5 as well. Minimum 4.4+. */}

🔧 Validation Enhancements

• Detailed Error Messages: All rules now provide more specific failure reasons
• Better Rule Execution Tracing: Enhanced debugging capabilities for rule validation
• Improved Visual Priority: More sophisticated indicator coloring precedence
• Enhanced Collision Detection: Better physics collision handling and reporting

📊 Migration from v4.3.1

• Automatic Compatibility: Legacy rule implementations continue to work
• Enhanced Error Reporting: Gradual migration path to detailed error messages {/* Removed internal testing class reference */}

Shipped Rule Classes

Only classes present in the repository are listed. No speculative or future rule names are included.

Validation Flow (Simplified)

1
2
3
4
5
6
7
8
9

1. Indicators prepared & attached (via Indicator / Placement setup).
2. For each rule in configured order:
  rule.setup(params)  (once per preview change)
  result := rule.validate_placement()
  aggregate failure state & collect messages
3. If all results successful:
  for each rule: rule.apply() (side‑effects like spending materials)
4. On preview change / exit:
  rule.tear_down()

There is no global fatal short‑circuit flag built into the base class; each pipeline step decides whether to continue based on aggregated success.

Key Behaviors by Rule

CollisionsCheckRule

• Toggles behavior with pass_on_collision (expect overlap vs expect empty space).
• Temporarily overrides each indicator’s collision_mask then restores it.
• Adds preview bodies as exceptions so a building never collides with itself.
• Reports counts (passed / failed / collision occurrences) at verbose log level.

WithinTilemapBoundsRule

• Converts each indicator global position to tile coordinates on the target TileMapLayer.
• Success requires a valid tile (tile data present) for every indicator.
• Gracefully handles null / freed indicators with warnings (cleaned elsewhere).

ValidPlacementTileRule

• Performs a tile validity test (consult file for exact assertion logic).
• Supplies messages for success/failure similar to the bounds rule.

SpendMaterialsRule (Inventory Addon)

• Searches for an ItemContainer on the placer (or its children) that can hold all required item types.
• validate_placement() builds a missing item list; failure message enumerates deficits.
• apply() removes counted items (ensuring atomic resource deduction post‑success).

SpendMaterialsRuleGeneric

• Underlying generic implementation invoked by specialized spend rules; provides shared messages / logic.

Implementing a Custom Rule

1. Extend PlacementRule or TileCheckRule.
2. Export any configuration properties (messages, thresholds, masks).
3. In setup(params) call super.setup(params) first; return collected issue strings.
4. In validate_placement() guard with if not guard_ready(): for robustness.
5. Return a RuleResult (never null). Keep messages concise & player‑oriented.
6. If you need side‑effects only on successful placement, override apply().
7. Add the rule resource to your placement rule list (project settings, config resource, or placeable‑specific rule array).

Indicator Visual Priority

When multiple TileCheckRule instances fail for the same tile, indicator appearance is selected by the failing rule with the highest visual_priority that provides fail_visual_settings. This centralizes which failure reason drives tile coloring.

Logging & Diagnostics

Rules use the shared logger from RuleValidationParameters:

• Warnings for null / invalid indicators (should be rare; indicates cleanup race).
• Verbose summaries including pass/fail counts (CollisionsCheckRule, WithinTilemapBoundsRule).

Use these logs to confirm rule ordering and detect misconfigured masks or missing containers.

Inventory Integration (SpendMaterialsRule)

To enable resource spending:

1. Add the GridPlacementInventory addon (addons/grid_building_inventory/), which provides the demo inventory plugin for GridPlacement.
2. Create a SpendMaterialsRule resource and set materials_to_spend (array of BaseItemStack).
3. Ensure the placer (typically the player / controller node) or a child has an ItemContainer that does_it_allow() every item type required.
4. Add the rule to the active rule set. On successful placement, items are automatically deducted in apply().

Cross References

• Collision Mapping: Collision detection and mapping system
• Indicator Setup Report: Indicator configuration diagnostics
• Isometric Implementation: Implementing Grid Building in isometric games (shapes, rotation, collision)
• Building System Process: Complete building system workflow
• Dependency Injection: Dependency injection patterns

Support / Purchase Hub: Linktree – All Grid Builder Links