PlacementReport

Full 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:
  - indicators_report: Results from RuleCheckIndicator2D validation
  - placer: The PlacementOwner entity initiating the placement
  - preview_instance: The Node2D being tested for placement validity
  
  Usage Example: [codeblock] # Create a placement report after attempting to build var report = PlacementReport.new(placer, preview, indicators_report, PlacementEnums.Action.PLACE) # 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) [/codeblock]
  
  Key Properties:
  - placer: The PlacementOwner entity responsible for initiating placement
  - preview_instance: The Node2D object being placed/tested
  - indicators_report: Validation results from IndicatorSetupReport
  - action_type: Type of placement action (PlacementEnums.Action)
  - issues: Array of error messages and validation failures
  - 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.
  
  

Source: addons/grid_placement/placement/manager/placement_report.gd

Syntax

class PlacementReport

Members

Name	Kind	Summary
lifecycle_result	Property	Canonical lifecycle result for this compatibility view. Legacy fields remain intact; new consumers should read this value for identities, typed outcome, reason, and opaque correlation context.
placer	Property	PlacementOwner 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	Property	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	Property	The root of the placed object (if any). This should be set after successful placement
indicators_report	Property	The report from RuleCheckIndicator2D generation for the preview object. Contains detailed information about collision detection, rule validation, and indicator setup.
action_type	Property	The type of action that was attempted for this placement. Indicates whether this was a PLACE, MOVE, or other type of placement operation.
issues	Property	Issues encountered during the placement attempt. Each entry pairs an internal service tag (for logs/telemetry) with a player-facing message (for the UI). See PlacementIssue. Use add_issue_tagged() for gameplay issues so the service name never leaks to players; use add_issue() for internal config errors that never reach the UI.
notes	Property	Additional notes collected at setup time (aggregated from indicator reports and validator). Contains diagnostic information and metadata about the placement process.
validation_results	Property	Validation results from rule evaluation, when available. Preserved so the action log can display detailed rule-level failure reasons (e.g. "Colliding on 3 tile(s)").
surface_of	Property	Surface metadata: mesh-library item name of the surface the placed object rests on (e.g. &"Ground", &"Block"). Default &"" means "unpopulated": a fresh report, or a placement that failed before commit. Populated on a successful 3D commit by the 3D service commit path.
snapped_y	Property	Surface metadata: global Y of the resting surface the object was snapped onto. Default @GDScript.NAN means "unpopulated"; consumers should branch on is_nan(snapped_y) rather than a magic elevation.
snapped_cell	Property	Surface metadata: the grid cell the object was committed to. Default Vector3i.ZERO when unpopulated.
add_issue	Method
add_issue_tagged	Method
add_note	Method
get_owner_root	Method
is_successful	Method
set_lifecycle_result	Method
get_lifecycle_result	Method
get_issues	Method
from_failed_validation	Method