Chaos Visual Debugger User Guide

The Chaos Visual Debugger (CVD) is a runtime system and editor tool that allows you to record the state of a Chaos Physics Simulation for later playback and inspection.

CVD supports recording data from Rigid Solvers and RBAN solvers. It can record either directly to a file, or it can attach to a live debugging session.

For known issues and upcoming features, see Known Issues and What's Next. The known issues list will be updated as any new issue is discovered, with information about any possible fix or workaround.

What is new in UE 5.5?

To use Chaos Visual Debugger with Unreal Engine 5.4, see Chaos Visual Debugger - User Guide for UE 5.4. 

New features

• Scene Query Browser: See all scene queries made in any given frame, and search by properties like tag name or type, in a new dedicated window.

• Recorded Log Browser: CVD shows a recorded output log, similar to Unreal Insights. When you scrub to any frame in CVD, the correct log line is selected and visualized. Also, when you select any log line, the corresponding frame is visualized.

• Network Tick Sync mode: In Play In Editor (PIE) Sessions, CVD was already able to record server and client data, but they were synchronized using timestamps. In Unreal Engine 5.5, there is a new "Network Tick" sync mode that calculates and applies the required offsets to show the visualization as the expected state, taking into account client-side prediction. In this mode, any divergence you see between server and client is a network de-sync.

• Collision Geometry Inspector: A new details panel that allows you to see recorded data per collision geometry (not just from a whole particle or rigid body). This feature processes all the chaos data and decodes it back to settings used in the Unreal Editor. For example, you can set whether to show if a shape is query only, or query and physics. 

• Recent Files: The last 5 files opened in CVD are remembered and can be assessed using the File menu.

• Acceleration Structures: CVD records and visualizes the acceleration structure used by the scene query system.

• Character Ground Constraints: We added support to record & visualize character ground constraint data. This is the constraint type used by the Physics Based Character Movement system.

• Generic Debug Draw: Record simple shapes (Sphere, Boxes, Lines) using Macros in C++ or dedicated BP nodes in Blueprints, that then will be visualized with the rest of the simulation in CVD.

Improvements

• Performance: On-the-fly geometry generation was improved by removing work, and moving more of the remaining work into worked threads. We will continue improving this area in future releases.

• Show Menu: In Unreal Engine 5.5, the Show menu is a proper Unreal Engine tool menu, with added save support. Now all available visualization flags are organized in submenus and sections. Also, when you change a flag, the new setting is auto-saved (you can revert to default if needed).

• Particle Colorization scheme: In Unreal Engine 5.4, CVD used the color scheme used by Chaos Debug Draw. That color set is good for wire-frame representations, but it is not ideal for solid representation. Unreal Engine 5.5 now uses a different color scheme, which can also be changed.

• Scene queries: The Scene Query Inspector decodes the collision query response flags to show the collision channel response matrix.

Open Chaos Visual Debugger

To open the Chaos Visual Debugger, click Tools > Debug > Chaos Visual Debugger.

Recording Data with Chaos Visual Debugger

Chaos Visual Debugger is able to record the state of all particles (Velocities, Accelerations, Mass Properties, Object states), Collision Constraints (Contacts pairs with their state), Scene Queries (Line Traces, Overlaps, Sweeps), and Joint Constraints (State and Joint Settings).

At a solver level, CVD records each solver sub-step performed. At a sub-step level, CVD records a snapshot of each particle's state at different stages of the evolution. This means you can inspect, for example, the state of a particle before and after the Integrate stage within a single sub-step.

As recording different snapshots within a single solver step is not free (in terms of performance and CVD file sizes), you can configure what stages are recording via the Data Channels option.

UI Overview

Chaos Visual Debugger uses a very similar layout to the Level Editor. There is a Viewport for visualizing recorded data, and a simplified version of the Scene Outliner.

The main way to interact with CVD is using Solver Tracks, which allows you to playback each recorded solver individually. The Details panel shows the state of any selected particle. This section will also hold multiple tabs called "Data Inspectors", which show details for selected Scene Queries, Collision Constraints, or Joint Constraints.

Record a Playback Session

Depending what you want to record (a Play In Editor session, a local cooked client, or server build), you have different ways to start a recording. They range from console commands to UI buttons where you can get up and running in just a few clicks.

Select The Data Channels to Record

Chaos Visual Debugger records a considerable amount of data from several systems including Scene Queries, Collision data, and Joint Constraints data. The more complex a scene is, the larger the CVD file (and performance impact) will be.

To address that, you can decide to opt out of recording certain data by setting the data channels you want to record (the channels can be changed before or after a recording has started). You can select data channels using UI controls, a console command, or a command line argument.

Select Data Channels Using the UI

This option is available only when the recording is controlled by CVD's user interface. That means it is available only for Play in Editor sessions.

To enable or disable a data channel, follow these steps:

1. In the Chaos Visual Debugger toolbar, click Data Channels.

2. Select the data channels you want to record.

Select Data Channels Using A Console Command

To change the data channels selection in recording environments that are not controlled by the Chaos Visual Debugger UI (for example, if the recording is on a server or client build), you can use the following console command.

p.Chaos.VD.SetCVDDataChannelEnabled [newstate] [channelname]

You can also enable or disable the multiple channels by providing them as a comma-separated list. The following example enables the Post-Integrate and Scene Queries channels.

p.Chaos.VD.SetCVDDataChannelEnabled true SceneQueries,PostIntegrate

Select Data Channels Using A Command Line Argument

You can start a game client or server with a predefined set of data channels by adding the following command line argument.

-CVDDataChannelsOverride=[ChannelName1,ChannelName2,...]

The following example would enable the Post-Integrate and Scene Queries channels.

-CVDDataChannelsOverride=SceneQueries,PostIntegrate

Record a Play In Editor Session

In Play In Editor (PIE) sessions, you can start a recording using a console command or using the Chaos Visual Debugger UI.

You can either start a recording directly to file or start a live debugging.

Record to File

To record to file, follow these steps:

1. Click Record to File. The recording session will be saved to the Profiling folder.

2. Reproduce the issue you are having.

3. Click Stop when you are done recording.

4. Click Yes if you want to load the recorded file now.

Record Live Session

If you start PIE with the CVD editor open, the Record Live Session button becomes available. If you click the button, CVD will automatically start a recording session, and attach to it. Once attached, it will play the visualization of the recorded data.

Record a Game Client or Server

Currently the only way to start a recording on a game client or server is executing a console command or using command line arguments. 

Record Using A Console Command

You can start a recording by executing the following console command.

p.Chaos.StartVDRecording

To stop the recording, use the following console command.

p.Chaos.StopVDRecording

This creates a CVD file in the default profiling folder (Saved\Profiling) that you can then load into the tool when desired.

Record Using A Command Line Argument

You can start a CVD recording from a game client, server, or the editor as soon CVD is initialized by adding the following command line argument:

-StartCVDRecording

If you also want to record to a remote CVD instance (or Live Debugging, you can specify the host address with the following argument. This is optional, by default the recording will be made to file in the Game's or Server's profiling folder.

-CVDHostAddress="[IP of the workstation running CVD]"

Load An Existing Recording into Chaos Visual Debugger

To load a recorded session, follow these steps:

1. In the Chaos Visual Debugger toolbar, click the Open File button.

2. In the CVD Recording Source Selector window, in the dropdown menu, select the location of the recording file.

   

   • Last Opened Folder: The last folder you opened in Unreal Engine.

   • Profiling Folder: The default profiling folder (Saved\Profiling). By default, all recordings done using the console command go here.

   • Trace Store Folder: CVD uses Traces to transport data, so all recordings are essentially .utrace files. By default, all recordings done for remote or live debugging go here.

3. Click Open.

Most CVD files load instantly, but if you are loading a large recording from a complex scene with several data channels enabled, you will see a progress bar.

The progress bar is there for the initial blocking operation, which is to spawn all the actors for the first frame of the recording. Then, all the meshes required to represent each particle's geometry data need to be generated from scratch. The last part of the process is async, so you might see a notification progress bar on the bottom-right corner while that is being done, and geometry will start appearing in the viewport. You should be able to use the tool while the file is loaded.

Load a Simple File

Load a Complex File

Remote or Live Debugging

You can start a recording in CVD using console commands (or command line arguments) where instead of recording to file, you can provide an IP.

That IP needs to correspond to a Trace server. You can use localhost for live debugging sessions running in the same machine as CVD, but it is possible to connect to a session running in another machine within the same network.

The first thing you need to do is to start recording using the following console command.

 p.Chaos.StartVDRecording Server

This will start recording data to the local trace store.

If you are on a remote machine, you can add the IP of the workstation where the CVD Editor will be running.

p.Chaos.StartVDRecording Server YOURWORKSTATIONIP

If the recording started successfully, in a game client you should see a debug message in the Viewport that says "Chaos Visual Debugger recording in progress...". On a server, currently the only way to know that a recording started successfully is by checking the logs.

After the recording starts, go to CVD and click the Connect To Session button. This will bring up a window where you can select the session you just started and connect to it. Once you're connected, you can start debugging.

Connect to a Complex Project like City Sample

In the following video you can see how you can start and connect to a live debugging session in a complex project like City Sample. Keep in mind that the game client and CVD will be competing for GPU resources, so if the playback in CVD is struggling you can try to limit the framerate or reduce the graphics quality. For this video, the FPS was capped at 30fps. We will continue improving in this area in future releases. Recording directly to file does not have this limitation.

Connect to a Live Session in a Play In Editor Session

In the following video you can see how you can start and connect to a live debugging session using in one click.

Viewport Controls

CVD uses a modified version of the normal Level Editor Viewport toolbar. 

Transform Toolbar

CVD uses the same transform toolbar as the Level Editor. This includes the camera speed control and the snapping settings. The only difference is that transformation controls are disabled for everything, except for non-CVD actors (such as light actors) to allow you to control the lighting used in CVD.

View Mode Button

This button lets you change the view mode between the following options: Perspective, Top, Bottom, Left, Right, Front, and Back.

Lighting Mode Button

You can use this button to switch between Lit, Unlit, Lit Wireframe, and Wireframe view modes. Unlit mode is best used with the visualization flag that enables the visualization triangle lines.

Show Menu

The Show menu is the place where all the visualization flags and options are contained. Any change to a flag or option in this menu automatically gets saved and persists between sessions, but it can be reverted back to the defaults if needed.

Show Debug Text

All visualizable data controlled by the flags in the Show menu is accompanied with debug text that includes details about the data. For example, if you have enabled particle data visualization and the velocity flag, the debug text will include the values of the velocity vector and the units. 

This option is most useful when the visualization is limited to specific options of a single particle. If you enable Show Debug Text when most of the visualization flags are enabled for all particles, all the debug text will overlap and be difficult to read.

Debug draw text can be enabled per visualization category. For example, you can choose to enable debug draw text just for Scene Queries data and not for Particle Data.

Data Visualization Flags

The Show menu is divided in several sections, one per recorded data type.

In each section there is a series of sub-menus, each named [Data Type] Data Visualization flags. These flags control which recorded data is "debug drawn" in the viewport. 

Each data visualization flag sub-menu has an Enable Draw flag, which enables visualization for a specific category. If there is a type of data you expected to see but can't find it, make sure the Enable Draw flag is enabled for that category.

For performance reasons, there is a limit on the number of debug draw lines allowed at any moment. If you reach the limit, a message is shown in the viewport. You can increase the limit using the variable p.Chaos.VD.Tool.MaxDebugDrawLinesPerFrame, but it is not recommended. 

In Unreal Engine 5.5, the following sections are available:

• Collision Data Visualization

• Scene Queries Visualization

• Particle Data Visualization

• Joints Constraints Data Visualization

• Character Ground Constraints Data Visualization

• Acceleration Structures Data Visualization

• Generic Debug Draw Data Visualization

Particle Data Visualization Flags

When you click any of the available flags, the data corresponding to these flags will be "debug drawn" if available and if the Enable Draw flag is enabled.

By default, only the data for the selected particle will be drawn, but you can uncheck the flag Draw Data Only for Selected Particle. Once that is done, debug draw will be done for all particles visible in the scene.

If you click on any of the Debug Draw sections under Particle Data Visualization Settings, the corresponding particle will be selected so it can be further inspected.

Collision Data Visualization Flags

These flags allow you to enable debug draw of any available collision data. The visualizations use the same color scheme as the runtime debug draw that's available in Chaos.

Once any collision data flag is enabled, a new section will appear that allows you to control how the data should be drawn. You can draw it in world space or in the foreground, and you can control the scale of certain elements.

Scene Queries Visualization Flags

CVD records most scene queries performed during a session. You can use these flags to enable or disable visualization of the recording queries by type (Line Trace, Sweep, Overlap) or to just visualize a selected query, which is useful as several queries can be visualized within a small space.

As queries are new each frame, CVD treats them as new pieces of data, so each shape drawn for a specific recorded query will be assigned a random color.

To learn how to find a specific query, see Scene Query Browser.

Visualization Details Per Scene Query Type

Particle Colorization

This section allows you to change the colorization mode for particles in the viewport. By default, particles are colorized based on their state. You can choose between debug drawing particles by particle state or by geometry shape type.

Geometry Visualization Flags

These flags control which type of geometry should be visualized. For example, most particles have the complex and simple version of the geometry, although only one is used for collision detection. The flags also indicate whether to visualize query-only geometry.

Joint Constraints Visualization Flags

These flags control which data points related to Joint Constraints are visualized.

Currently, joint constraint data is recorded every frame as an individual piece of data, so keeping a selection between frames is not possible. That will be addressed in the next release when we add a way to keep a stable ID for each joint constraint.

Visualized joints can be clicked for further inspection, which will focus or open the Joint Constraint Data Inspector.

Joint constraint data recording is disabled by default. To record and visualize joint data, you need to enable the Joint Constraints data channel (see Select the Data Channels to Record).

Character Ground Constraints Visualization Flags

CVD can record the constraint state of the new constraint type used by the Physics Base Character Movement System.

Character Ground Constraints data recording is disabled by default. To record and visualize joint data, you need to enable the Character Ground Constraints data channel (see Select the Data Channels to Record).  

Acceleration Structures Visualization Flags

As part of the scene query support category, optionally, CVD is able to record and visualize the acceleration structure used by the scene query system as an AABB Tree.

This is useful for cases where you were expecting to hit an object in your scene query, but didn't, and after inspecting the query in CVD you see the object was not evaluated at all.

The AABB Tree visualization allows you to see the composition of the tree, and the bounds of each object as they were registered in the tree. This lets you determine if the bounds are in the tree or if they are correct.

Acceleration Structures data recording is disabled by default. To record and visualize joint data you need to enable the Acceleration Structures data channel (see Select the Data Channels to Record).    

Generic Debug Draw Visualization Flags

In Unreal Engine 5.5, you can use a series of Macros and Blueprint nodes to record debug draw shapes directly into CVD recordings.

In C++, you can use the following macros.

CVD_TRACE_DEBUG_DRAW_BOX 
 
CVD_TRACE_DEBUG_DRAW_LINE 
 
CVD_TRACE_DEBUG_DRAW_VECTOR 
 
CVD_TRACE_DEBUG_DRAW_SPHERE

Each macro has its own set of parameters depending on the shape you need to draw, but every macro has the following optional parameters:

• Tag Name: An FName that will be shown if debug Draw Text is enabled.

• Owner: Any object this debug draw shape will be related to. This is used internally to know if a shape is recorded from a server solver or a client solver.

In Blueprint, you can use the function nodes shown in the following screenshot.

The following video shows CVD visualizing debug draw shapes recorded from blueprint using the graph in the screenshot above (a `Sphere` in Begin Play, A `Box` during tick, and a `Line` on End Play).

Viewport Hamburger Menu

Playback Frame Rate Control

CVD records the frame time of each game frame or solver frame. Therefore when you are playing back a recording, by default CVD is attempting to match the recorded frame times.

If you desire to do so, you can override the recorded frame rate to a fixed one by enabling Override Recorded Framerate.

Viewport Tracking

In CVD, you can select an object in the scene and make it to be followed by the camera automatically.

Select an object in the viewport or the scene outliner and use the F8 key to toggle tracking. Alternatively, you can enable Follow Selected Object in the viewport's hamburger menu.

The following video shows the auto-track feature being activated in a live recording of Lyra, using the F8 key after selecting the shape in CVD.

Data Inspectors

In addition to the Details panel (currently used in CVD to show the recorded Particle Data or any selected particle), CVD has dedicated data inspectors for some data categories.

Collision Data Inspector

The Collision Data Inspector in CVD shows you the data for a selected contact or a selected particle. When a particle is selected, you can access a dropdown where you can see all the Mid-phase pairs the particle is part of, which you can select for further inspection. When a mid-phase pair is selected, you can see the Constraint Data.

When a contact is selected, you can see all the contact's data, plus the constraint data to which the contact belongs.

The inspector also allows you to select the involved particles in the pair in the viewport.

As the Collision Data Inspector is independent of the normal details panel, you can inspect each particle data without losing the collision data being inspected.

Scene Queries

Scene Query Browser

If you need to inspect any scene query in particular, you can use the Scene Query Browser.

The Scene Query Browser shows you all the scene queries made in the current visualized frame, inside a Scene Outliner kind of window.

You can search queries by the Trace tag, Trace Owner tag, or type. Here, you also have access to the Scene Queries Visualization flags (the same ones available in the Show menu). If a query is hidden, it will be noted in the UI.

You can teleport to the location of any given query by double clicking them in the Scene Query Browser.

Lastly, instead of visualizing all the recorded queries for the current frame at once, you can switch to the Recorded Order mode. This mode will only visualize one query at the time, and give you a playback control to jump back and forth between the recorded queries. This is useful if in any given frame, you have several scene queries happen in the same or very similar location (the scene queries of the character movement component are an example of this). 

Scene Query Inspector

Scene queries can be inspected in a similar way to how collision data can be inspected. You can click any visualized query (or hit) and CVD will load all the relevant data on the scene query inspector. This inspector will show recorded data of the current selected scene query Visit and data of the query itself. 

A recorded visit, for example a scene query against the world, contains data captured in a specific step of the AABB Tree traversal where a valid Shape is visited. A visit may or might not contain any hit data. The scene query inspector has a stepping timeline control that allows you to step through back and forth each SQ visit as it was recorded. When you change between steps, the viewport visualization will be updated to only draw the query up to the selected step.

Some queries can perform sub-traces (something done when a cluster union is hit and if the sub-trace flag is enabled). CVD detects if a query has performed a subquery (or if the selected query itself is a subquery) and based on that, there will be a button to go to the parent query or the subquery data if available.

The Scene Query Inspector includes the properties and controls shown in the following screenshots.

Joint Constraint Data Inspector

Visualized Joints can be clicked in the viewport to be fully inspected. Doing so will focus the joint constraints data inspector (or open it if it is closed).

Here you can inspect the state of the joint and the joint settings at the current visualized frame.

Details Panel

The CVD Details panel is a slightly-modified version of the Actor Details panel. It uses the same components.

Multi-selection is not currently supported in CVD, so the details panel only shows the data for the currently selected object.

When a particle is selected, at the bottom of the panel there is a floating button that will take you to the Collision Inspector Panel. The panel is populated with the collision data of the particle being inspected. If the particle is not part of any generated collision contact in the current visualized frame, the button will be disabled.

Not all particle types have the same type of data available. CVD hides data that is not supported for a specific particle type. 

For example, you can see the difference in the view for a dynamic and static particle below.

Collision Geometry Inspector

When you select an object in the CVD viewport, you are selecting the particle (or rigid body as a whole), and the data that is visualized in the Details panel is the particle (or body) state. But there are situations where you want to see properties of the collision geometry. For example, you want to see if it was configured to be Query Only, Query, and Physics, or what collision profile was applied to it.

Hold the Left Shift key while you click on any object in the viewport to select only the particle's collision geometry, instead of the whole particle.

When an individual collision geometry (Implicit Object) is selected, the detail panel will show the following information:

• Shape Type

• Collision Enabled setting (such as Query Only, or Query and Physics)

• Collision Channel

• Collision Channel response matrix (based on the collision profile used)

• Additional filter data flags

The following video shows the new panel. Close to the end, it shows how the panel data auto-updates to show how the collision channel of an object was changed at runtime.

Recorded Log Browser

Similar to Unreal Insights, CVD records the log stream of your game. You can visualize this data by focusing on the Recorded Log Browser tab (you can also un-dock it if needed).

During playback or scrubbing, CVD will automatically highlight all the log lines that were recorded for the frame you are visualizing.

You can also double-click on any log line, and CVD will jump to and visualize the corresponding frame for that log line, as shown in the following video.

Scene Outliner

The Scene Outliner in CVD is based on the Level Editor scene outliner, but with fewer options exposed (as they are not needed).

As each recording can contain multiple solvers at the same time (for example, all RBAN solvers and the Rigid Solver, or the Client and Server Rigid solver when recording in PIE), each solver's particles are put under a folder with the name and ID of the solver they belong. Each particle is labeled with its Debug Name recorded on the Chaos side.

Playback Controls

Game Frames Timeline

The Game Frames Timeline represents each recorded game thread frame. These are not specifically tied to a solver frame number. This is especially true with async physics enabled, where one Game Thread frame is not the same as one Solver Frame.

When a Game Thread frame is played, CVDs will search for the closest Solver frame available for the Game Thread frame timestamp and play it back. Therefore, playing back a recording using the game frame timeline will play all recorded solvers in sync automatically.

You can play a recording, go back and forth frame by frame, and scrub the timeline.

Solver Timeline

For each available solver on any given game frame, a new timeline control is created that lets you see which solver frame number was recorded for that game frame, and lets you play back data for only a specific solver.

In addition to the Play, Stop, Step Forward, and Step Back controls, each Solver Timeline has an additional sub-timeline that allows you to step through the different stages of the simulation within that solver frame, if available.

The following solver stages are available for recording.

Solver Stages Usage Example

In the following video, you can see how to use the solver stages timeline to inspect how a Linear impulse was applied. The linear impulse was consumed during the Integrate stage, so just a visualization of the end of the solver frame would not have shown the linear impulse values the particle received, just the resulting velocity change.

Track Sync Modes

Unreal Engine 5.5 includes a new sync mode tailored for networking debugging. In 5.4, CVD was already capable of recording a PIE session with a server and client instance, but the visualization was shown as it happened, using timestamps to sync the visualization between the server and client instance (which in a client side prediction model, it will show the server visualization slightly behind).

Now, you can choose to sync the tracks based on the recorded network tick. This mode uses new data we are recording on games that use our networked physics system. When this mode is enabled, the visualization represents each solver track as they would be if the client side prediction logic worked correctly. Therefore, any divergence seen in this mode indicates a client/server de-sync.

In the following video, you can see how in the default sync mode (Recorded Timestamp), the server visualization is lagging behind. As mentioned earlier, this is expected because in client-side prediction, the client is executing the inputs in real-time "predicting" what the server will do when it eventually gets the inputs.

When we switch to the Network Tick sync mode, you can see how Server and Client visualization matches, as expected.  In addition, there is a section where server and client start to diverge, which results in a Rewind & Resim scenario as a net correction is issued.

CVD shows that a solver is re-simulation using a blue ReSim badge.

ReSimulation Badge

For recording sessions where the Chaos network prediction system and re-simulation is active, CVD is able to identify if a current visualized frame is part of a re-simulation done during the network desync correction process. When a solver timeline is playing any of these types of frames, the blue ReSim badge will be shown in the timeline.

Visibility Control

You can click on the eye button to hide or show all the particles and debug draw data of the solver that the timeline represents. 

Known Issues

As mentioned at the beginning of this guide, CVD is being released as Beta and as such there are a few known issues and limitations which we will be working on addressing for the next release.

• Landscape Collision representation might be shown incorrectly if between frames the collision is unloaded and then loaded in rapid succession (usually while scrubbing a recording and going through the event): This will be fixed in the next hotfix build available for Unreal Engine 5.5.

  Workaround: One you get into that state, the only workaround is to Reload the CVD file (it can be done using the recent files menu in a few clicks)  

What's Next

There are several features planned for upcoming versions, including the following:

• Custom Data Filters (Scripting system): CVD records a vast amount of data, but currently CVD's UI is a limiting factor. We are working on a system that allows you to create custom queries to highlight or only show recorded data that matches your query.

• Support for more types of constraints: Currently CVD does not support Suspension Constraints

• Re-Simulation & Re-Query:  This feature will allow you to re-run the simulation (or Scene Query) from any given frame inside CVD. This will allow you to test a data change or code change without leaving CVD, resulting in faster iteration times.

• CVD Extension: An API you can use to create your own plugins or modules, in which you can define your own types for serialization and your own visualization code. This will allow you to record and visualize custom data into CVD from non-engine systems (like simulation code implemented in the Game module or plugins).