Draft — Unreleased:This page is in active development. APIs, class names, and behavior may change before the release is finalized. Use it as a preview of what's coming — not as a stable integration target.
Comprehensive report for placement operation results and validation feedback. The [b]PlacementReport[/b] 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. [br][br][b]Core Purpose:[/b][br] This class aggregates data from multiple sources to provide a unified view of:[br]
- The entity performing the placement action[br]
- The object being placed or manipulated[br]
- Validation results from rule checking systems[br]
- Any issues or problems encountered during the process[br]
- Diagnostic notes for debugging and monitoring[br][br] [b]Primary Use Cases:[/b][br] - [b]Success Validation:[/b] Determine if a placement operation completed successfully[br] - [b]Error Reporting:[/b] Collect and present validation failures to users[br] - [b]Debugging Support:[/b] Provide detailed diagnostic information for developers[br] - [b]Audit Logging:[/b] Maintain records of all placement attempts and outcomes[br] - [b]System Integration:[/b] Pass placement results between different system components[br][br] [b]Architecture Integration:[/b][br] The report works closely with:[br] - [member indicators_report]: Results from RuleCheckIndicator2D validation[br] - [member placer]: The PlacementOwner entity initiating the placement[br] - [member preview_instance]: The Node2D being tested for placement validity[br][br] [b]Usage Example:[/b] [codeblock] # Create a placement report after attempting to build var report = PlacementReport.new(placer, preview, indicators_report, PlacementEnums.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) [/codeblock][br][br] [b]Key Properties:[/b][br] - [member placer]: The PlacementOwner entity responsible for initiating placement[br] - [member preview_instance]: The Node2D object being placed/tested[br] - [member indicators_report]: Validation results from IndicatorSetupReport[br] - [member action_type]: Type of placement action (PlacementEnums.Action)[br] - [member issues]: Array of error messages and validation failures[br] - [member notes]: Additional diagnostic information and metadata[br][br] [b]Thread Safety:[/b] This class is not thread-safe. All operations should be[br] performed on the main thread to ensure proper integration with Godot's scene system.[br][br] [b]Performance Notes:[/b] Reports are lightweight objects designed for frequent[br] creation during placement operations. Memory usage scales with the number of[br] issues and notes collected.[br][br]
Source: addons/grid_placement/placement/manager/placement_report.gd
Syntax
class PlacementReportMembers
| Name | Kind | Summary |
|---|---|---|
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 BUILD, MOVE, or other type of placement operation. |
issues | Property | General setup issues encountered during the placement attempt. Contains error messages and validation failures that prevented successful placement. |
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. [code]&"Ground"[/code], [code]&"Block"[/code]). Default [code]&""[/code] means "unpopulated": a fresh report, or a placement that failed before commit. Populated on a successful 3D commit by [method ObjectPlacementService3D.populate_surface_metadata]. |
snapped_y | Property | Surface metadata: global Y of the resting surface the object was snapped onto. Default [constant @GDScript.NAN] means "unpopulated"; consumers should branch on [code]is_nan(snapped_y)[/code] rather than a magic elevation. |
snapped_cell | Property | Surface metadata: the grid cell the object was committed to. Default [constant Vector3i.ZERO] when unpopulated. |
add_issue | Method | |
add_note | Method | |
get_owner_root | Method | |
to_verbose_string | Method | |
parts | Property | |
is_successful | Method | |
get_issues | Method | |
all_issues | Property | |
from_failed_validation | Method | |
report | Property | |
keys | Property | |
first_key | Property | |
msgs | Property |
Source
addons/grid_placement/placement/manager/placement_report.gd
Plugin docs root:gdscript/plugins/grid_placement_dev/docs