Skip to content
Grid Building Docs

PlacementReport

Summary

Section titled “Summary”

Comprehensive report for placement operation results and validation feedback.

The PlacementReport class serves as a detailed snapshot of any placement attempt within the Grid Building system. It encapsulates all relevant information about build, move, or placement operations, providing a complete audit trail for debugging, logging, and user feedback.

Core Purpose:

This class aggregates data from multiple sources to provide a unified view of:

  • The entity performing the placement action

  • The object being placed or manipulated

  • Validation results from rule checking systems

  • Any issues or problems encountered during the process

  • Diagnostic notes for debugging and monitoring

Primary Use Cases:

  • Success Validation: Determine if a placement operation completed successfully

  • Error Reporting: Collect and present validation failures to users

  • Debugging Support: Provide detailed diagnostic information for developers

  • Audit Logging: Maintain records of all placement attempts and outcomes

  • System Integration: Pass placement results between different system components

Architecture Integration:

The report works closely with:

  • [member indicators_report]: Results from RuleCheckIndicator validation

  • [member placer]: The GBOwner entity initiating the placement

  • [member preview_instance]: The Node2D being tested for placement validity

Usage Example:

# Create a placement report after attempting to build
var report = PlacementReport.new(placer, preview, indicators_report, GBEnums.Action.BUILD)


# Check if placement was successful
if report.is_successful():
    print("Placement completed successfully!")
    # Log successful placement for analytics
    log_placement_success(report)
else:
    print("Placement failed: ", report.get_issues())
    # Handle placement failure - show user feedback
    show_placement_errors(report)

Key Properties:

  • [member placer]: The GBOwner entity responsible for initiating placement

  • [member preview_instance]: The Node2D object being placed/tested

  • [member indicators_report]: Validation results from IndicatorSetupReport

  • [member action_type]: Type of placement action (GBEnums.Action)

  • [member issues]: Array of error messages and validation failures

  • [member notes]: Additional diagnostic information and metadata

Thread Safety: This class is not thread-safe. All operations should be

performed on the main thread to ensure proper integration with Godot’s scene system.

Performance Notes: Reports are lightweight objects designed for frequent

creation during placement operations. Memory usage scales with the number of

issues and notes collected.

Properties

Section titled “Properties”
placer: GBOwner

GBOwner for the root entity responsible for placing the preview_instance into the game world. This represents the player, AI, or other entity that initiated the placement action.

preview_instance: Node

The preview instance for the object being manipulated (built, placed, etc.). This is the Node2D that represents the object being tested for placement validity.

placed: Node

The root of the placed object (if any). This should be set after successful placement

indicators_report: IndicatorSetupReport

The report from RuleCheckIndicator generation for the preview object. Contains detailed information about collision detection, rule validation, and indicator setup.

action_type: GBEnums.Action

The type of action that was attempted for this placement. Indicates whether this was a BUILD, MOVE, or other type of placement operation.

issues: Array[String] = []

General setup issues encountered during the placement attempt. Contains error messages and validation failures that prevented successful placement.

notes: Array[String] = []

Additional notes collected at setup time (aggregated from indicator reports and validator). Contains diagnostic information and metadata about the placement process.

Methods

Section titled “Methods”
func _init( p_placer: GBOwner, p_preview_instance: Node, p_indicators_report: IndicatorSetupReport, p_action: GBEnums.Action ) -> void

Creates a new PlacementReport with the specified parameters.

p_placer: The GBOwner entity responsible for the placement action

p_preview_instance: The Node2D being tested for placement

p_indicators_report: The IndicatorSetupReport containing validation results

p_action: The type of placement action being performed

func add_issue( p_issue: String ) -> void

Adds an issue to the report’s issues list.

Issues represent problems or validation failures that occurred during placement.

p_issue: The issue message to add to the report

func add_note( p_note: String ) -> void

Adds a diagnostic note to the report’s notes list.

Notes contain additional information about the placement process that may be useful for debugging or logging, but don’t represent errors.

p_note: The diagnostic note to add to the report

func get_owner_root( ) -> Node

Returns the root node of the entity responsible for placement.

This is a convenience method that accesses the owner_root property of the placer.

Returns: The root Node of the GBOwner entity, or null if no placer is set

func to_verbose_string( ) -> String

Converts the report to a detailed multi-line string representation.

Generates a comprehensive string containing all report information including success status, action type, preview details, indicator report summary, issues, and notes. Useful for debugging and logging.

Returns: A formatted string representation of the entire report

func is_successful( ) -> bool

Determines if the placement attempt was successful.

A placement is considered successful if there are no issues in either the main report or the indicators report.

Returns: true if placement was successful, false otherwise

func get_issues( ) -> Array[String]

Returns all issues from both the main report and indicators report.

Combines issues from the report’s own issues array with any issues found in the indicators report, providing a complete list of all problems encountered during the placement attempt.

Returns: An array containing all issues from the report and indicators

static func from_failed_validation( validator_issues: Dictionary, owner: GBOwner, target: Node, action: GBEnums.Action ) -> PlacementReport

Factory: build a PlacementReport from validation issue dictionary Builds a PlacementReport using the owning GBOwner (not the owner_root Node)

Source

Section titled “Source”

addons/grid_building/placement/manager/placement_report.gd

This API reference is automatically generated from the plugin source code. For implementation examples and usage guides, see the guides section.