Introduction
When you are creating a project using Unreal Engine's (UE) procedural content generation (PCG) features, you have access to debugging features and workflows. This page provides an overview of those tools, to help you improve your work.
General Tools
This section describes tools useful for improving your PCG projects.
Screen Overlay
The screen overlay provides a high-level overview of what the system is doing. You can use this to validate at a glance that runtime generation is active.
To enable the feature, use the following cvar: pcg.RuntimeGeneration.EnableDebugOverlay 1
The data values shown are unfiltered, to give you clean data for each frame.
Considering most projects run at 30 FPS or higher, we recommend capturing a video to study transient behaviors, so you can use the scroll and pause features to review the data for any given frame during the generation process.
UE displays the following data fields after you enable this feature.
| Overlay Data Field | Description |
|---|---|
Tick time | Shows game thread time spent inside the runtime generation system during the current frame. |
Generate Calls | Shows how often
|
Cleanup Calls | Shows how often
|
Num Generating Components | Shows how many PCG components / cells were generating this frame. |
PA Pool | Shows the generated results placed on partition actors (PAs) in the level. These are pooled to reduce runtime cost. When the current pool is exhausted, it is doubled in size, an expensive operation you should avoid triggering during gameplay. You can set the initial pool size using the cvar
|
VT Preloads | Shows how many times
You can enable or disable VT preloading using the cvar
You can visualize VT preloading using the cvar
|
The screen overlay functions in Editor and Development builds, not Test or Shipping builds.
Draw Generated Cells
The draw generated cells feature shows a visualization of the runtime generation state.
To enable the feature, use the following cvar: pcg.GraphExecution.DebugDrawGeneratedCells 1
UE shows the following visuals when you enable this feature:
Red wireframe sphere: These are drawn for each generation source, at the smallest generation radius. The fine detail (as in the above screenshot) generates when grid cells are overlapped by the red sphere. In the editor, a label displays near the center of the generation source.
Yellow triple-wireframe boxes: These are drawn around any cell that is currently generating. In the editor, a label displays near the center of the generation cell with the grid size and cell coordinates, which can aid in further inspection and debugging in the graph editor.
If either the Generate Landscape Textures node or the Generate Grass Maps node is in use, a single wireframe box is drawn in cells waiting for grass map textures to stream in.
A red sphere is drawn for each generation radius for each grid that has runtime components. Pressing F8 to eject from your character while in PIE and moving to view the wireframe spheres from a different perspective gives better understanding of the procedural generation behavior.
This visualization serves several tasks and workflows. It helps you to:
Understand how the system is behaving at a glance.
Diagnose visual pop issues (for correlating visible pops with generating cells).
Fine-tune the runtime processing budget pcg.FrameTime (or pcg.EditorFrameTime outside of PIE). To do so, observe whether the generation is happening promptly when the generation radius sphere starts overlapping the cell.
If cells generate immediately on overlap, the system is keeping up with the workload.
If cells are still generating well within the generation radius, there is a danger of visual pops.
A visual pop is a sudden, unintended change in what the player sees—such as a jump, flicker, or snapping transition—that breaks the visual continuity of the scene.
This feature functions in Editor and Development builds. By default it does not function for Test and Shipping builds, but you can enable it by setting UE_ENABLE_DEBUG_DRAWING to true in the respective config files.
Other Console Commands and Variables
| Console Command / Variable | Description |
|---|---|
| Cleans up all current grid cells. The system then regenerates them in following ticks. Useful for checking whether an issue is transient (that is, refreshing fixes it) or persistent.Command, emit when needed. |
| Controls runtime generation ticking. The current generated state of cells is frozen when disabled. To remove all runtime-generated data, set it to disabled then emit
|
| Controls whether the PCG graph cache is enabled, which caches output data from CPU nodes to avoid later re-executing on the same data. Applies to game worlds. Disabled by default. |
| Controls whether the PCG graph cache is enabled, which caches output data from CPU nodes to avoid later re-executing on the same data. Applies to editor worlds. Enabled by default. |
| Controls how much memory the PCG graph cache is allowed to use in game worlds. When memory usage exceeds this value, old entries are dropped from the cache. Requires an integer value. |
| Controls how much memory the PCG graph cache is allowed to use in editor worlds. When memory usage exceeds this value, old entries are dropped from the cache. Requires an integer value. |
| Randomly initializes buffer memory before execution in GPU graphs. This helps test if all data is properly written, and helps reproduce undefined behavior bugs which can be hard to isolate, especially when uninitialized data is often 0 by chance. Disabled by default. |
| Controls whether runtime generation actors are visible in the Outliner. Enabled by default. |
| Delays runtime generation for the number of ticks you specify. The PCG system waits this duration until beginning to generate, which is useful to provide buffer time for Virtual Textures to populate. Requires an integer value, the default is 0. |
| Enable to use Virtual Textures to obtain landscape height data. This is primarily useful in GPU graphs. Enabled by default. |
Debugging
This section describes features specifically for debugging your CPU and GPU when working with PCG.
CPU Debugging
Every node has a Break In Debugger setting which, when enabled, triggers breakpoints in CPU debuggers when the node enters any execute phase.
Requirements:
You must attach a debugger.
You must select the component or grid cell of interest in the Debug Object Tree. The breakpoint is only active for the currently inspected object.
If the node result is already cached, the node might not execute unless the cache is flushed (for example, by ctrl-clicking the Force Regen button in the graph editor toolbar).
GPU Debugging
Nodes set to execute on GPU expose additional debug settings, as shown in the image below.
| GPU Debug Setting | Description |
|---|---|
Dumped Cooked HLSL | Enable to show the cooked HLSL source before it is passed to Compute Framework to assemble the final kernel. Useful for kernel development. |
Dump Data Descriptions | Enable to dump the description of data flowing through GPU nodes, which PCG uses to determine buffer sizes and thread counts. |
Print Shader Debug Values | Enable to allocate an array of floats initialized with a default value of 0, and expose an API for overwriting these values from the HLSL. After the array values are updated from the GPU kernel, they are printed to the log. See
|
Trigger Render Capture | Enable to trigger a render capture when this node executes while a debug object is selected in the graph editor. Editor-only. Render captures must be enabled (for example,
|
The pcg.GPU.FuzzMemory cvar described above under Other Console Commands and Variables is useful for debugging. GPU memory allocated each frame can result in values of 0, or similar random contents every frame, which can obscure bugs when either data is not written or uninitialized data is read. Enabling this option can make such bugs obvious and significantly improve reproducibility.
Profiling
This section describes tools for profiling your CPU and GPU activity.
CPU Profiling
The Profiling pane in the PCG Graph Editor window gives a detailed breakdown of CPU time spent in each node. This does not yet cover GPU execution.
For more detailed profiling, Unreal Insights is the standard tool. A range of PCG functions are instrumented with profile scopes (including UPCGSubystem::Tick which is typically the root for much of the work, and which you can plot as a starting point when opening a trace).
GPU Profiling
PCG kernels execute in ComputeFrame_ExecuteBatches. On some platforms and build configs, each kernel has a scope which gives the kernel name.
For more detailed profiling, select a GPU profiling tool for your platform. Repeatable profiling can be tricky as PCG work produces bursts of activity when generating cells, but does not do predictable work every frame. To help with repeatable profiling, there is a Profile Kernel Index setting on GPU-enabled nodes.
This index perpetually dispatches a kernel executed by this node every frame, which provides a way to capture a GPU trace using a GPU profiling tool to analyze performance. Some nodes emit multiple kernels from CreateKernels(), this setting is an index for this array. Set it to -1 to disable profiling.
Any grid cells will progress up to this kernel and then repeatedly execute each frame, and this can result in a lot of dispatches which might skew performance. You can set pcg.RuntimeGeneration.NumGeneratingComponents to limit how many cells can execute simultaneously.
To enable this functionality, enable PCG_GPU_KERNEL_PROFILING in PCG.Build.cs.
