Particle trace report

From PopcornFX
Jump to navigation Jump to search

The PopcornFX editor has a few tools to help debug particle systems.
One of these tools is the trace report. It allows you, at any time, to inspect the properties of individual particles, using mouse-picking or rectangular selection in the realtime viewport. It can be a powerful help when used in conjunction with the particle history, allowing you to trace and inspect previous frames, in case you spotted a glitch and want to make out the cause.

(you can also see the trace report video tutorial)


To use the tool, you just need to pause the effect (Hit F2 in the viewport), and left-click on the particle you wish to inspect, in the realtime viewport. The values of all its fields will appear in the "TraceReport" panel, located on the middle bottom panel of the default layout, under the second tab of the attributes panel:


The trace report panel provides various tools and buttons:


1: Focus selected particle Only works in PAUSED mode. Will to zoom in the cam and center it on the currently selected particle. You can then orbit the particle using the Alt+Right mouse button in the viewport.
2: Break on problematic particles Pauses simulation and selects all particles considered problematic (fields containing infinities or NaN values)
3: Search for problematic particles When clicked, will break on problematic particles, but only this frame.
4: Developer display mode Displays the floating-point values in scientific notation, and the integer values in hexadecimal notation.
5: Jump to next selected particle When more than one particle is selected, cycles through the selection by jumping to the next particle in the list
6: Currently selected particle Selected particle number, out of the total number of selected particles
7: Total number of selected particles Number of particles in the whole list of selected particles
8: Current layer Name of the layer containing the particle being currently selected
9: Current page number ID of the current page in the current layer storage
10: Total page count Total number of selected pages in the current layer storage
11: Current particle number ID of the current particle in the current page
12: Total particle count Total number of selected particles in the current page
13: Field list : type Type of the particle field (this matches the "Fields" node of the layer in the treeview)
14: Field list : Name Name of the particle field (this matches the "Fields" node of the layer in the treeview)
15: Field list : Value Value of the particle field for this frame. You cannot currently edit these values directly, It might be implemented in a future release of the editor.
16: Enable history / time-machine When activated, the editor will record all properties of all particles every frame
17: History frame slider Allows you to scrub through past frames to inspect potential glitches
18: Current history frame ID Index of the past frame you're currently inspecting
19: Total number of history frames Size of the frame cache used by the editor. Tells how many frames you can go back in time for.


The picked particle will have red outlines rendered (matching its billboard's triangles). However, unless the particle system is very sparse, there most likely won't be a single particle picked. All particles hit by the picking ray will be highlighted with light white outlines.

You can cycle through all traced particles by repeatingly left-clicking on the same spot. If you move the mouse between two clicks, a whole new trace will be cast, and cycling will start over.


The ray used for picking is also rendered as a bright red line, due to projection on the screen plane, it appears as a single red pixel, but you can visualize it better by moving the camera around:


You can also use a rectangular selection by left-clicking and dragging the mouse in the viewport for a more precise picking. The rectangular selection will only consider the particle centers.


Trace filtering

Picking is affected by layer visibility. This can be useful if you wish to isolate a specific layer out of a big mess.

In the example below (the Blast.pkfx, coming in the default FX sample package), we trace the 11 different layers (8 main layers + 3 sub-layers that are trail spawners in the 'Debris_Smoking' layer).

The result is pretty horrifying, and it can be tedious to isolate a specific particle. Here, you can see the ray picked 64 particles:


If we hide the layers we're not interested in, we can pick only the smoke trails layer, and the result is much easier to work with. Only 9 particles were picked: