To help you identify unusual physics behavior, Chaos Visual Debugger (CVD) provides debug draw tools to visualize aspects of your application that are not normally visible during runtime.
You can control which debug draw tools are visualized in the viewport by toggling data flags. Data flags are organized into the following categories:
Certain flags, such as Center of Mass, can have a performance impact on CVD. If the debug draw limit is reached, a warning appears in the viewport reading:
Max Debug Draw lines limit reached! Try selecting fewer debug draw categories or focus the camera in a narrower area.
Collision Data
Visualized collision data can help you identify areas where collisions are behaving unexpectedly. For example, when two objects intersect one another, instead of colliding as expected.
To enable collision data, follow these steps:
In the Viewport Toolbar, click Show > Collision Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Collision Data Visualization Settings to customize how the data is drawn in the viewport.
The visualization settings include the following options:
Show Debug Text: Toggles viewport debug text (if any) on and off.
Depth Priority: Draws data in worldspace or in the foreground (always on top of any other scene components).
Options for Scale and Radius: Control the size of debug draw elements, making them easier to see in the viewport.
Most data flags include visualization settings that contain similar toggleable features.
Scene Queries
Visualized scene queries (line traces, sweeps, and overlaps) can help you debug cases where you performed a query during runtime but the query didn't find an expected object.
To enable scene query data, follow these steps:
In the Viewport Toolbar, click Show > Scene Query Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Scene Query Visualization Settings to customize how the data is drawn in the viewport.
Particle Data
Visualized particle data can help you identify irregular particle behavior, such as a particle moving faster than expected after applying a force.
To enable particle data, follow these steps:
In the Viewport Toolbar, click Show > Particle Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Particle Data Visualization Settings to customize how the data is drawn in the viewport.
CVD only records and visualizes physics thread particle data, not game thread particle data. Game thread particle data is not visualized.
Geometry
Most particles have both simple and complex collision geometry, but only one is used for collision detection.
Options for toggling between simple and complex geometry, and other geometry visualization flags, are located in the Viewport Toolbar under Show > Geometry Flags menu.
Query Only geometry is visualized with translucent material. You can click through translucent materials by pressing T (or click Allow Translucent Selection in the Hamburger Menu) to enable or disable translucent selects.
Particle Colorization
To increase draw visibility, you can choose to colorize particles using the following modes:
None: Draws particles in default gray.
State: Colorizes based on a physics body’s state in a simulation (dynamic, sleeping, kinematic, or static).
Shape Type: Colorizes based on collision geometry type (simple shapes, convex, heightfield, or trimesh).
Client Server: Colorizes based on client or server-spawned particles.
State and Default Gray
To change the mode and customize the colors, follow these steps:
In the Viewport Toolbar, click Show > Particle Colorization.
In the Colors Mode dropdown, click the Particle Color Mode dropdown, and select the mode to use.
Click the Colors by [mode] dropdown menu to customize colors. Then, click a color tile to open a contextual color picker.
The table below describes the contextual color picker user interface (UI).
| Number | Description |
|---|---|
1 | Color wheel (or color spectrum if toggled). |
2 | Displays current and previously selected colors. |
3 | Toggles sRGB preview. |
4 | Toggles between the color wheel and color spectrum. |
5 | Toggles visibility of Color Schemes. |
6 | Eyedropper tool. |
7 | RBG/HSV sliders. |
8 | Alpha slider. |
9 | Displays the current color’s hex code. |
10 | Color Schemes: Functions similarly to swatches in Adobe Photoshop and other design programs. |
Joint Constraints
Visualized joint constraints can help you debug unwanted ragdoll behavior, such as twisting joints. CVD records joint constraint data as an individual piece of data for every frame. Due to this, maintaining a selection across gameplay frames is not currently possible.
To enable joint constraint data, follow these steps:
In the Viewport Toolbar, click Show > Joint Constraint Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Joint Constraint Visualization Settings to customize how the data is drawn in the viewport.
CVD doesn’t record joint constraints by default. To enable it, click the Data Channel dropdown menu in the main toolbar, and check JointConstraints.
Character Ground Constraints
CVD can record the state of character ground constraints used by Unreal Engine’s Character Movement System, called Mover 2.0. Using this flag, you can identify and debug unusual behavior such as characters floating above or clipping through a ground plane.
To enable character ground constraint data, follow these steps:
In the Viewport Toolbar, click Show > Character Ground Constraints Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Character Ground Constraints Visualization Settings, to customize how the data is drawn in the viewport.
CVD doesn’t record character ground constraints by default. To enable it, click the Data Channel dropdown menu in the main toolbar, and check Character Ground Constraints.
Generic Debug Draw Data
The following C++ macros and Blueprint nodes record debug draw shapes directly in CVD. Debug draw shapes can offer context when debugging physics calculations.
For example, if you use two points in space to calculate a force applied to a physics body, CVD only shows the body before and after the force is applied. If something looks off, you can use generic debug draw macros (or Blueprint nodes) to visualize the two points, and the force, frame-by-frame. This workflow can provide context on how the force was calculated and help you to correct it.
C++ Macros
Depending on the shape you need to draw, each macro has its own set of parameters — except for the following optional parameters, which each macro uses:
| Macro | Parameter | Description |
|---|---|---|
TraceDebugDrawBox | InBox | The shape you want to record. |
All macros | Tag | The FName that is used as a tag for filtering, search, and debug draw as a text tag in CVD’s viewport. |
All macros | Color | The color to apply to this shape when it’s debug drawn in CVD. |
All macros | SolverID | The ID of the solver this shape should be associated with. If no ID is provided, this shape is added as part of the current game from data bucket. |
TraceDebugDrawLine, TraceDebugDrawVector | InStartLocation | The start point of the line. |
TraceDebugDrawLine | InEndLocation | The end point of the line. |
TraceDebugDrawVector | InVector | The vector you want to record. |
TraceDebugDrawSphere | Center | The origin point of the sphere. |
TraceDebugDrawSphere | Radius | The radius of the sphere. |
All macros | Owner | Any UObject this debug draw shape is related to. This is used internally to know if a shape is recorded from a server solver or a client solver. |
Blueprint Nodes
The following generic debug draw macros can also be implemented as function nodes in a Blueprint’s Event Graph:
CVD Record Debug Draw Sphere
CVD Record Debug Draw Box
CVD Record Debug Draw Line
For more information about each node, see the Chaos Visual Debugger section of Unreal Engine Blueprint API Reference.
Enable Generic Debug Draw Data
To enable generic debug draw data, follow these steps:
In the Viewport Toolbar, click Show > Generic Debug Draw Data Flags > Enable Draw. This option opens a list of data flags.
Choose from the list of data flags to toggle on or off.
Click Generic Debug Draw Data Visualization Settings to customize how the data is drawn in the viewport.
Acceleration Structures
CVD can record and visualize acceleration structures used by the scene query system, which is currently an AABB (Axis-Aligned Bounding Box) Tree. An AABB Tree is a bounding volume hierarchy you can use to determine potential overlaps between objects.
In CVD, you can use AABB Tree visualization to see the composition of the tree and the bounds of each object as they were added to the tree.
This visualization is useful when an object that a scene query should have hit wasn’t hit, or wasn’t even evaluated by the physics engine. You can use AABB Tree visualization in CVD to inspect the bounds of the object and determine whether the error was caused by, for example, the bounds failing to encompass the object visually or incorrect bounds within the tree.
To customize which acceleration structure data flags are drawn, follow these steps:
In the Viewport, click Show > Acceleration Structure Data Flags, and select your desired data flags.
Click Acceleration Structure Visualization Settings to customize how the data is drawn in the viewport.
CVD doesn’t record acceleration structures by default. To enable it, click the Data Channel dropdown menu in the Main Toolbar, and check Acceleration Structures Data.
Common Show Flags
The Common Show Flags menu contains flags derived from the engine itself that can assist with visibility in CVD.
To customize which flags are enabled, in the Viewport Toolbar, click the Show > Common Show Flags.
Next Up
Data Inspectors
Understand data inspectors in Chaos Visual Debugger.
Capturing Data with Chaos Visual Debugger
Capture and play back recordings with Chaos Visual Debugger.