Preview and Debug

The Procedural Placement Graph editor provides a suite of real-time tools for inspecting the output of any node during graph authoring — without requiring a full scene bake. This page covers all preview and diagnostic features.

---

Scene Preview

When the Graph Editor window is open, a PPG Preview overlay appears in the Scene View. The overlay is transient: it is only visible while a PPG Graph Editor window is the active editor.

The preview is rendered using Unity's GL batch API (Hidden/Internal-Colored) for high performance with large point counts. All point dots and orientation lines are batched into two draw calls (quads and lines) per Scene View repaint. The renderer:

• Frustum-culls points that are outside the camera frustum.
• Uses screen-space cell thinning to suppress overlapping dots at the current zoom level, keeping the view readable at any distance.
• Applies the source PPGComponent transform as the coordinate origin, so previewed points appear at the correct world position even when the component is moved.

Toggles

The overlay exposes three independent toggles. All three are available in both panel mode and toolbar mode.

Toggle	Default	What it shows
Dots	On	Filled quads at each point's world position, colored by the active Color Mode.
Orient	Off	A short line segment extending from each point along its local up axis, showing the orientation stored in the point transform. Useful for verifying slope-aligned placement.
Bounds	Off	A wireframe box around each point's boundsMin/boundsMax extents. Useful for debugging spatial node operations that depend on point bounds.

The same three toggles are mirrored in the Details Window header bar (see Details Window).

---

Color Modes

The Color Mode dropdown in the overlay controls how point dots are colored. It can also be changed from the Details Window header.

Density

Points are colored on a red-to-green gradient where red = 0 and green = 1, mapping the density field of each point. This is the default mode and is the most useful for verifying scatter density masks.

Legend: red swatch 0 — green swatch 1 — label (Density)

PointColor

Each dot is drawn using the point's own RGBA color field directly, with no remapping. Use this mode when upstream nodes write explicit colors (for example, a tint mask sampler).

Legend: Per-point RGBA color

Steepness

Points are colored on a blue-to-yellow gradient where blue = flat (0°) and yellow = steep (90°). Useful for verifying slope filter nodes.

Legend: blue swatch Flat — yellow swatch Steep

Index

Each point is assigned a color from a full HSV rainbow cycle based on its flat index in the output list. Useful for visualizing point ordering or tracing which input collection a point came from.

Legend: Rainbow by point index

CustomAttribute

Visualizes one named custom metadata attribute as a red-to-cyan gradient. When this mode is selected, two additional controls appear next to the dropdown:

• Attribute popup — lists all attribute names present in the current node output. If no attributes exist the label (no attributes) is shown.
• Auto toggle — when on (default), the gradient is auto-normalized to the actual min/max of the attribute values in the current result set. When off, the raw attribute values are clamped to 0–1. The current min/max is shown in the legend.

Legend: red swatch <min> — cyan swatch <max> — label (<attribute name>)

---

Auto Mode

The Auto toggle in the Graph Editor toolbar enables automatic re-execution whenever a meaningful graph change is detected.

What triggers Auto

Auto-preview fires on semantic changes only:

• An edge is created or removed (connection change).
• A node is added or removed.
• A node property value is changed in the inspector.

Node moves (dragging nodes around the canvas) do not trigger Auto. This prevents expensive re-execution during layout work.

Internally, PPGGraphView raises OnGraphSemanticChanged for these events. PPGGraphEditorWindow listens to this event and calls ScheduleAutoPreview(), which debounces execution by 200 ms using the UIElements scheduler. If another semantic change arrives within the window, the timer resets.

What Auto executes

When the debounce fires:

1. If a PPGComponent using the current graph is found in the scene, the full graph (including instancers) is executed via ExecuteFullGraph.
2. If no component is found, a preview-only execution runs (ExecutePreview), which skips instancer nodes.

Default setting

The initial state of the Auto toggle is controlled by the Auto Execute Default preference at Edit > Preferences > Procedural Placement Graph. It defaults to true.

---

Details Window

The Details Window is a standalone, dockable editor window that shows a sortable data table of all point output from the currently selected (or pinned) node.

Opening the window

• Menu: Window > Procedural Placement Graph > Details
• Toolbar button in the Graph Editor window

The window can be docked anywhere in the Unity layout like any other editor window.

Header bar

The header bar contains the same Dots / Orient / Bounds toggles and Color Mode dropdown as the Scene View overlay. Changes made in the Details Window are immediately reflected in the overlay, and vice versa — they share the same PPGPreviewState object.

When Color Mode is set to CustomAttribute, the attribute name dropdown and Auto toggle also appear in the header.

A small point count label on the left side of the header shows the total number of points currently displayed.

Tabs

The window has two tabs:

• Table — the sortable point data table (described below).
• Attributes — shows the graph-level custom attribute declarations defined on the PPGGraphAsset.

Point data table

The Table tab displays a sortable, resizable MultiColumnHeader TreeView. Up to 2000 rows are shown at once.

Clicking a row highlights the corresponding point in the Scene View with a large cone and label, driven by PPGPreviewState.HighlightedPointIndex. The highlighted row also appears selected in the table.

Columns can be sorted ascending or descending by clicking the column header.

Fixed columns (23 built-in)

#	Header	Content
0	#	Flat point index within the output
1–3	X Y Z	World position (F2)
4–6	Rot.X Rot.Y Rot.Z	Euler angles in degrees, extracted from the transform matrix (XYZ order, F1)
7–9	Sc.X Sc.Y Sc.Z	Non-uniform scale extracted from the transform matrix (F2)
10	Density	point.density field (F3)
11	Steepness	point.steepness field (F2)
12–15	R G B A	point.color RGBA channels (F2)
16	Seed	point.seed integer
17–19	Bmin.X Bmin.Y Bmin.Z	boundsMin (F2)
20–22	Bmax.X Bmax.Y Bmax.Z	boundsMax (F2)

Custom attribute columns

After the 23 fixed columns, one additional column is appended for each named custom metadata attribute present in the output. Column headers show the attribute name. Values are formatted according to their declared PPGAttributeType. Sorting custom attribute columns uses a numeric sort value extracted via PPGAttributeTypeTraits.GetSortValue.

---

Pin Preview

Normally the preview and Details Window follow the selected node — clicking a different node immediately switches the preview to that node's output. Pin Preview freezes the preview on one specific node while leaving you free to select and edit other nodes.

Pinning a node

• P key — with a node selected in the graph view, press P (no modifier keys) to toggle pin state.
• Right-click context menu — right-click any node and choose Pin Preview (or Unpin Preview if already pinned). The menu entry also shows the keyboard shortcut.

Only one node can be pinned at a time. Pinning a second node automatically unpins the first.

While pinned

• The Scene View preview and Details Window continue to show the pinned node's output regardless of which node you select or edit.
• The logic is implemented as PreviewNodeGuid = pinnedNodeGuid ?? selectedNodeGuid. While pinnedNodeGuid is set, selection changes do not call previewManager.SetSelectedNode.
• A lock icon badge (AssemblyLock) appears at the top-left corner of the pinned node in the graph canvas. The badge is a VisualElement added to the node view; if the built-in icon is unavailable it falls back to a blue rounded rectangle.

Unpinning

• Press P again while the pinned node is selected.
• Right-click and choose Unpin Preview.

Automatic unpin

The pinned node is cleared automatically in two situations:

• Graph switch — when a different PPGGraphAsset is loaded into the editor (pinnedNodeGuid is reset to null alongside the rest of per-graph state).
• Node deletion — when the pinned node is removed from the graph, pinnedNodeGuid is cleared and the pin badge is removed.

---

Output Pin Selector

Nodes that have more than one output port produce a PPGDataCollection that contains data tagged with the originating port label. The Output Pin Selector lets you filter both the Scene View preview and the Details Window table to a single output port.

The selector only appears when the current node's output contains data from two or more distinct ports. When visible it shows a popup dropdown with All as the first option followed by one entry per port name.

• All (default) — shows all output data combined.
• <port name> — restricts the preview and table to data from that port only.

Selecting a new node (or unpinning) resets the selector back to All.

---

Node Validation Badges

Each node view shows up to two overlaid badges that communicate static validation state and runtime execution results.

Error / Warning badge

A small colored circle appears at the top-right of the node title when PPGNodeValidator.Validate finds one or more issues. The badge color indicates the highest severity:

• Red — at least one Error-level issue.
• Yellow — one or more Warnings only (no errors).

Hover over the badge to read the tooltip, which lists all issues prefixed with [Error] or [Warn].

Validation runs automatically after every semantic change (OnGraphSemanticChanged). The following checks are performed:

Condition	Severity
Required input port is not connected	Warning
Prefab Instancer has no prefab assigned	Error
Set Variable node has an empty variable name	Error
Multiple Set Variable nodes share the same name	Warning
Set Variable / Get Variable pair declares mismatched types	Warning
Set Variable declared type does not match upstream data type	Warning
Get Variable has an empty variable name	Error
Get Variable references a name with no matching Set Variable	Warning
Get Binding has no binding slot selected	Warning
A custom attribute name referenced by the node does not appear in any upstream node's output	Warning

Custom attribute reference validation

Nodes that implement IPPGAttributeConsumer (for example, nodes that read a custom attribute by name to drive some behavior) are checked against the set of attribute names actually provided by upstream nodes. If a referenced name cannot be resolved, a Warning badge is shown with the message Custom attribute '<name>' not found in upstream nodes.

Point count badge

After execution, each node also shows a point count badge at the bottom-right:

• Green text when points are produced.
• Orange text when no points are output.
• Grey text for cached results.

The badge also shows the number of custom attributes (e.g. 42 pts · 3 attrs) and the last execution time in milliseconds. A cache-hit result appends (cached).