Geometry Collection Debug Draw

Describes how to use Geometry Collection Debug Draw and expose Chaos Rigid Body properties.

Windows
MacOS
Linux

The Chaos Destruction tools must be enabled and compiled using a 4.23 Source build. Chaos currently will not work with the pre-compiled builds off the Epic Launcher.

While working with Geometry Collections, it may be useful to see information for a particular Geometry Collection (or set of Geometry Collections). The Geometry Collection Debug Draw Actor provides a way to toggle the display of information such as the hierarchy, clustering, information about rigid bodies, and more either through the properties in the Details panel or through console commands.

Debug From the Editor

Once you have Geometry Collections in your Level that you want to debug, during a Play in Editor session, use the World Outliner and find and select the GeometryCollectionDebugDrawActor.

DebugDrawActor_Outliner.png

This will show the Debug Draw properties panel that controls the different types of visualization modes available for the Geometry Collections inside the current Level.

Show Rigid Body Ids

A good place to start debugging is to visualize the Rigid Body Ids. In the Actor's Debug Draw category and Rigid Body sub-category, enable the Show Rigid Body Id checkbox.

DebugDrawActor_RigidBodyIDs.png

The Selected Rigid Body property enables you to view all Rigid Bodies (-1) or enter in the Id for the Rigid Body you want to visualize.

DebugDrawActor_SelectedBody.png

In the image above, we enter 95 into the Id field, this enables us to visualize only the pillar on the left and not both objects in our scene.

Enabling visualization of all Geometry Collections in a scene can be useful for small test scenarios, but can seriously affect the frame rate for large Levels.

In addition to entering the Id into the Selected Rigid Body field, you can use the eyedropper to select something from your scene.

DebugDrawActor_EyeDropper.png

You can also get more information by visualizing the inactive children of a clustered Geometry Collection by enabling the Debug Draw Clustering option.

DebugDrawActor_DrawClustering.png

Under the Selected Rigid Body option, you can move between child/parents as well as cycle between the different clusters.

In the video above, we enable Debug Draw Hierarchy and Show Faces which enables us to view the faces of each cluster as we cycle through.

Visualization Options

You can choose whether to visualize the whole collection with the Debug Draw Whole Collection property. This will display the debug information for all Rigid Bodies belonging to the same Geometry Collection as the selected Rigid Body Id.

Enabling the while Geometry Collection can make it more challenging to visualize things and can adversely affect the frame rate depending on the size of the collection.

You can also visualize your geometry information in a top-down manner (by default, graphic representation of the Geometry Collection is from the bottom of the hierarchy). If the focus is to explore the top nodes' geometries, then the Debug Draw Hierarchy option will enable the ability to visualize the parents first. This option can also be combined with the Debug Draw Clustering option to show both the parent and children.

DebugDrawActor_TopDownGeo.png

The Debug Draw Hierarchy option only affects visualization of the Geometry Collection Component properties, because the Rigid Body information is already presented from the parent.

Hiding Geometry

By default, the geometry associated with the selected Rigid Body Id only gets hidden when the Collision Volumes are displayed, but there are a few other options available under the Hide Geometry property.

Option

Description

Hide None

Do not hide any geometry.

Hide Collision

Hide the geometry associated with Rigid Bodies that are selected for collision volume visualization (default option).

Hide Selected

Hide the geometry associated with the selected Rigid Bodies.

Hide Whole Collection

Hide the entire Geometry Collection associated with the selected Rigid Bodies.

Hide All

Hide all Geometry Collections.

When -1 is used as the selected Rigid Body Id, then the last four options are equivalent (all Geometry Collections will be hidden).

Toggle Properties to Visualize

You can toggle the desired properties you want to visualize in the Details panel (or through the console). Combining multiple properties together will produce different results, for example below we enable Show Rigid Body Collision along with the Show Rigid Body Id and Hide Geometry with the Hide Selected option.

DebugDrawActor_MultipleOptions.png

When displaying Level Set type collision volumes, only one volume can be displayed at a time, even if the Debug Draw Whole Collection option is enabled.

There are several different categories which are grouped into multiple categories: Rigid Body, Rigid Clustering, and Geometry Collection Component. These categories apply either to the selected Rigid Body or to the entire Geometry Collection containing the selected Rigid Body.

GeometryCollectionDebugDraw_Properties.png

Most properties are self-explanatory, for example, Show Vertices toggles the display of the Rigid Bodies vertices on or off or Show Bounding Box toggles the display of the Rigid Bodies Bounding Box on or off. There are some exceptions which are cited below.

  • Show Rigid Body Velocity - this displays both Linear (arrow's length) and Angular velocities (circle's radius). GeometryCollectionDebugDraw_Velocity.png

  • Show Rigid Body Force - displays both Force (arrow) and Torque (circle).

  • Show Rigid Body Infos - displays the complete on-screen textual debug information for the selected Rigid Body. DebugDrawActor_ShowInfo.png

  • Show Connectivity Edges - shows each logical connection to the sibling Rigid Body while they are still clustered. DebugDrawActor_ClusterConnectivity.png

    Requires the Debug Draw Clustering option, since it's visualizing the child nodes' information.

  • Show Single Face and Single Face Index - display a selected face to help debug geometries.

    This visualization is available only once a specific Geometry Collection is selected (Selected Rigid Body must not be -1).

Visualization Settings

You can toggle the debug visualization settings under the Settings category.

GeometryCollectionDebugDraw_Settings.png

Customizations, such as changing the drawing color or the transform scale properties, can be made here. This can help with cases where the color background makes it harder to see the visualization. Most of these properties are self-explanatory and affect the drawing of the basic debug draw elements. Also enable Use Active Visualization to allow the visualization to change with each cluster level of the Geometry Collection, debug lines and text will get darker, while transform axis will get smaller as the clustering level increases.

DebugDrawActor_ActiveVisualization.png

Debug From the Console

All Geometry Collection Debug Draw Actor properties can also be directly changed from the console by following these steps.

List the Debug Draw Commands

The Geometry Collection Debug Draw commands are all under the p.gc prefix:

GeometryCollectionDebugDraw_ConsoleCommandList.png

Each command's description can be accessed by adding and interrogation mark ? at the end of the command:

GeometryCollectionDebugDraw_ConsoleCommandInfo.png

Since each command matches the Debug Draw actor's properties, also refer to the Debug From the Editor section for additional description on the properties' effect.

To Display the Rigid Body Ids

Use the command:

p.gc.ShowRigidBodyIds 1

To select the Rigid Body to Debug Draw

Use the command:

p.gc.SelectedRigidBodyId X

In the command above, replace X with the Id of the Rigid Body you want to visualize information for.

Enable/Disable Visualization of the Whole Collection.

Use the command:

p.gc.DebugDrawWholeCollection 1

This will display the debug information for all Rigid Bodies belonging to the same Geometry Collection as the selected Rigid Body Id.

Hiding Geometry

By default, the geometry associated with the selected Rigid Body Id only gets hidden when the Collision Volumes are displayed, use this command to select another option:

p.gc.HideGeometry [0|1|2|3|4|]
0 Hide None, do not hide any geometry.
1 Hide with Collision, hide the geometry associated with rigid bodies that are selected for collision volume visualization (the default).
2 Hide Selected, hide the geometry associated with the selected rigid bodies.
3 Hide Whole Collection, hide the entire geometry collection associated with the selected rigid bodies.
4 Hide All, hide all geometry collections.

When -1 is used as the selected Rigid Body Id, then the last four options are equivalent (all Geometry Collections will be hidden).

Enable/Disable/Query the Debug Draw properties

The following commands are also avaliable through the console:

Command

Description

p.gc.DebugDrawHierarchy [0|1|]

Show debug visualization from the top of the hierarchy instead of the leaf nodes, starting at the selected rigid body id (or root if none is selected). Default = 0.

p.gc.DebugDrawClustering [0|1|]

Show debug visualization for the clustered children for the currently selected rigid body id. Default = 0.

p.gc.ShowRigidBodyCollision [0|1|]

Show the selected's rigid body's collision volume. Default = 1.

p.gc.CollisionAtOrigin [0|1|]

Show any collision volume at the origin, in local space. Default = 0.

p.gc.ShowRigidBodyTransform [0|1|]

Show the selected's rigid body's transform. Default = 1.

p.gc.ShowRigidBodyVelocity [0|1|]

Show the selected's rigid body's linear and angular velocities. Default = 0.

p.gc.ShowRigidBodyForce [0|1|]

Show the selected's rigid body's applied force and torque. Default = 0.

p.gc.ShowRigidBodyInfo [0|1|]

Show the selected's rigid body's information. Default = 0.

p.gc.ShowConnectivityEdges [0|1|]

Show the selected's rigid body's clustering connectivity edges. Default = 0.

p.gc.ShowTransformIndex [0|1|]

Show the geometry collection's transform index matching the selected rigid body. Default = 0.

p.gc.ShowLevel [0|1|]

Show the geometry collection's hierachical level matching the selected rigid body. Default = 0.

p.gc.ShowTransform [0|1|]

Show the geometry collection's transform matching the selected rigid body. Default = 0.

p.gc.ShowBoundingBox [0|1|]

Show the geometry collection's bounding box matching the selected rigid body. Default = 0.

p.gc.ShowFace [0|1|]

Show the geometry collection's faces matching the selected rigid body. Default = 0.

p.gc.ShowFaceIndex [0|1|]

Show the geometry collection's face indices matching the selected rigid body. Default = 0.

p.gc.ShowFaceNormal [0|1|]

Show the geometry collection's face normals matching the selected rigid body. Default = 0.

p.gc.ShowVertex [0|1|]

Show the geometry collection's vertices matching the selected rigid body. Default = 0.

p.gc.ShowVertexIndex [0|1|]

Show the geometry collection's vertex index matching the selected rigid body. Default = 0.

p.gc.ShowVertexNormal [0|1|]

Show the geometry collection's vertex normals matching the selected rigid body. Default = 0.

Rigid Body Collision

The following commands are available for showing Rigid Body Collisions:

To enable:

p.gc.ShowRigidBodyCollision 1

To disable:

p.gc.ShowRigidBodyCollision 0

To query:

p.gc.ShowRigidBodyCollision

Changing the Visualization Settings

The following commands are also available to help you customize the way the debug information are drawn:

Command

Description

p.gc.PointThickness [float|]

Point thickness. Default = 6.

p.gc.LineThickness [float|]

Line thickness. Default = 1.

p.gc.TextShadow [0|1|]

Text shadow under indices for better readability. Default = 1.

p.gc.TextScale [float|]

Text scale. Default = 1.

p.gc.NormalScale [float|]

Normal size. Default = 10.

p.gc.TransformScale [float|]

Transform size. Default = 20.

p.gc.ArrowScale [float|]

Arrow size for normals. Default = 2.5.

Effects of Post Processing

If you notice artifacts on the debug draw lines it is likely that post-processing is affecting the way the Debug Draw lines are rendered.

Switching Post-Processing Off for Lines

Using a console command, it is possible to switch off post-processing:

ShowFlag.PostProcessing 0

Before, with post-processing on:

GeometryCollectionDebugDraw_PostprocessingOn.png

After, with post-processing off:

GeometryCollectionDebugDraw_PostprocessingOff.png

Switching post-processing off will prevent the LevelSet collision volumes from rendering (see next section below).

Switching Post-Processing on for LevelSet Renders

Before using the Debug Draw to visualize LevelSet, you must ensure that the post-processing is on as otherwise the Ray March material will not get rendered.

ShowFlag.PostProcessing 2

Before, with post-processing off, the LevelSet isn't rendered:

GeometryCollectionDebugDraw_LevelSetPostprocessingOff.png

After, with post-processing on, the LevelSet is drawn as expected:

GeometryCollectionDebugDraw_LevelSetPostprocessingOn.png

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback