One correlated placement attempt: what the player's input aimed at, what the preview showed, and what the dispatch actually committed or removed. The plugin already records each of those in its own surface — the positioner keeps the live pick, the session keeps the preview, the lifecycle result carries the outcome. What was missing is the join: a failure block could only show the pick, and a successful run showed the outcome with no memory of the input that produced it. This class builds that one bounded record from those surfaces, keyed by the attempt id the host mints. Read it through GridPlacementHost.get_last_attempt_trace() or, on a failure, as the origin block of PlacementFailureEvidence. It never casts a second ray, dispatches anything or invents a value: a field the live surfaces do not carry is left out, and PlacementFailureEvidence names it missing.
Source: addons/grid_placement/telemetry/placement_attempt_trace.gd
Syntax
class PlacementAttemptTrace extends RefCountedMembers
| Name | Kind | Summary |
|---|---|---|
MAX_CANDIDATES | Field | Candidate rows kept per attempt. Enough to show near/far ordering, bounded so a crowded level cannot turn one click into a payload. |
TOLERANCE_NOTE | Field | What the numbers mean, not just that they exist: preview and commit are the same seat, so their projected images must coincide. The original pointer and the committed cell center are NOT the same point — a cell snap moves the piece off the exact cursor, by up to half a cell. |
PARITY_TOLERANCE_PX | Field | Distance that counts as "the same pixel" in the preview->commit comparison. |
REGISTRY_SIZE_KEY | Field | Internal keys consumed by complete() and erased before the record is read: the registry size before the action, and the camera that aimed it. |
CAMERA_KEY | Field | |
origin_before | Method | |
origin | Property | |
targeting | Property | |
target | Property | |
viewport | Property | |
positioner_3d | Property | |
is_3d | Property | |
complete | Method | |
trace | Property | |
lifecycle | Property | |
camera | Property | |
before | Property | |
after | Property | |
instance_id | Property | |
transform | Property | |
pick | Property | |
hit | Property | |
ray_origin | Property | |
ray_dir | Property | |
candidates | Property | |
rows | Property | |
grid | Property | |
seat | Property | |
map | Property | |
acquired | Property | |
hovered | Property | |
record | Property | |
registry_2d | Property | |
record_2d | Property | |
origin | Property | |
preview | Property | |
delta | Property | |
camera | Property | |
preview_px | Property | |
commit_px | Property | |
parity_px | Property | |
preview_2d | Property | |
origin_2d | Property | |
delta_2d | Property | |
viewport_2d | Property |
Tutorials built on Grid Placement
- Godot multiplayer grid placement: one host, four sessions
- Godot 2D grid building system: paint, place, save
- Godot 3D grid building system: the runtime loop
- Godot 4 grid-building plugins: build mode vs editor tools
- 3D room placement in Godot: build rooms and stack storeys
- 3D grid placement in Godot 4: full setup tutorial
- Snap to a TileMap in Godot: 2D grid placement
- How to make a farming system in Godot
- How to snap objects to a 3D grid in Godot