Unreal Engine 5 Documentation has been moved to the Epic Developer Community

The Chaos Destruction system is a collection of tools within Unreal Engine 4 (UE4) that can be used to achieve cinematic-quality levels of destruction in real time. In addition to great-looking visuals, the system is optimized for performance, and grants artists and designers more control over content creation. The system relies on Geometry Collections (to define items to be destroyed), Fracturing (to define how Geometry Collections are destroyed), and Clustering (to define the varying levels in which to break apart Geometry Collections). There are additional tools that can be used to control how your Geometry Collections are destroyed including the Connection Graph (how the fractured pieces of a Geometry Collection are connected to one another), and Fields (a method in which to directly interact with and control fractured pieces).

Setting up Chaos Destruction

If you are using Unreal Engine version 4.23, 4.24, 4.25, or 4.26 standard, follow the steps below to download the Unreal Engine Source code, build the Engine, and enable the required Chaos Destruction plugins.

1. Download the Unreal Engine Source Code from GitHub .

   We recommend downloading as a .ZIP file as there may be issues with missing plugins when cloning the repo using GitHub Desktop.

2. Extract the .ZIP files to your desired location.

3. Inside the Engine/Source folder, open the UE4Editor.Target.cs file in Visual Studio, Notepad ++ , or a similar text editor.

4. Add the following to the UE4Editor.Target.cs file and save:

   BuildEnvironment = TargetBuildEnvironment.Unique;
   bCompileChaos = true;
   bUseChaos = true;

   Your UE4Editor.Target.cs file should look like the following:

   public class UE4EditorTarget : TargetRules
   {
       public UE4EditorTarget( TargetInfo Target ) : base(Target)
       {
           Type = TargetType.Editor;
           BuildEnvironment = TargetBuildEnvironment.Unique;
           bBuildAllModules = true;
           ExtraModuleNames.Add("UE4Game");
   
           bCompileChaos = true;
           //Note that the following line is not needed for 4.23 or previous versions.
           bUseChaos = true;
   
       }
   }

5. In the engine root folder, run the Setup batch file, then upon completion, run the GenerateProjectFiles batch file.

6. Load the project into Visual Studio by double-clicking the UE4.sln , then build the Engine from the Source code .

7. Create a new project and open it, then enable the following plugins from the Edit > Plugins menu:

   • Chaos Editor

   • Chaos Solver

   • Chaos Niagara

   • Planar Cut

   • Editable Mesh

   • Geometry

   • Geometry Cache

   • Field System

8. Restart the Editor.

Fracture Editor

To access the Chaos Destruction functions, open the Modes dropdown menu and select Fracture .

The Fracture Editor and Mode Toolbar will be displayed.

Using the Fracture Editor and Mode Toolbar, you can create Geometry Collections and control the fracturing and clustering of a Geometry Collection.

Geometry Collections

Destruction within the Chaos system starts with a new kind of asset called a Geometry Collection. These assets can be built from one or more Static Meshes, including those gathered together in Blueprints or even nested Blueprints. Once you have a Geometry Collection, you can break it apart using the Fracture Editor and define the settings that determine how it breaks apart. Before you start fracturing and breaking things apart with the Chaos tools, it's best to think about what it is you want to break apart, and how your Geometry Collections are constructed for the best results.

Construction Best Practices

When creating Geometry Collections, ideally your content will be set up in a modular way that is water-tight with no interpenetration. Doing so will enable you to have more flexibility and control when fracturing the Geometry Collection. One approach is to use Blueprint and several Static Mesh Components , as illustrated below.

In the video above, our Geometry Collection asset is comprised of a single Blueprint that contains all the meshes that make up a window section of a building. If you have worked with destruction systems before, the modularity and importance of water-tightness with no interpenetration may be familiar to you. If you are new to destruction systems, in essence, we cannot cheat the fracturing of this piece. Each piece needs to have mass, and know what to do when called upon to be fractured.

It is also recommended that when building modules, that your pivots obey Unreal's gridding system. Standardizing widths and heights with the grid in mind will make things easier as you continue to develop more complex content.

Another concept to consider is Material assignments. Even if your modules share the same textures, you should apply a unique Material ID per Material type. This allows, upon fracturing, a second Material ID to be generated, which you can then assign an appropriate internal Material. In the video below, we have a Geometry Collection comprised of two meshes that share the same textures but use two separate Material types. This allows both the Stonework and Concrete to use a unique Material for the internal faces; whereas, if one Material was used, you would have one Material ID to assign for the internal faces.

Once you have a module or collection of modules, it's time to start thinking about converting to a Geometry Collection. In the example below, the side of a building is comprised of five different modules each with multiple Material Instances applied. Converting to a Geometry Collection will consolidate any shared Materials into a single ID and lower draw calls.

Meshes can be converted into Geometry Collections in any combination. Small modules are more flexible in terms of placement, but risk high draw calls, visible seams, and repetition when duplicated across a structure. Larger, combined modules are less flexible, but can be fractured and clustered to hide seams. In the image below, the four pillars on the left are individual Geometry Collection assets, while the larger pillar on the right is a single Geometry Collection.

When fracturing each of the individual pieces, the risk of similar breaks and hard edges may occur. On the larger piece, the fracture is spread across the entire piece which may provide better results.

Creating a Geometry Collection

With a general understanding of the recommended approach to constructing your content, you can turn your content into a Geometry Collection by selecting the New button in the Fracture tab of the Mode Toolbar , illustrated below.

After entering a name and save location for your new Geometry Collection asset, the mesh will update in the viewport with a draw diagram that will display the fractures once you select a fracture type, so you have an idea of what it will look like.

Inside the Content Browser if you open your Geometry Collection asset, you can define any Material Elements (pictured as 1 below) or Collision Settings (pictured as 2 below).

In the image above under the Material section, we have the outer Material (element 0), the inner Material (element 1), and the debug draw Material (element 2) for which you can select a Material asset to apply.

The Collision Settings enable you to define the collision behavior for your Geometry Collection. There are several different options to choose from, each with their own advantages and disadvantages. The Collision Type is defined as either Particle-Implicit or Implicit-Implicit .

Next, you can choose the Implicit Type , which is how you want to initialize the collision structures. These come primarily in two forms, Analytic Collision Volumes or Level Set Volumes .

• Analytic Collision Volumes - These provide a simple representation of rigid bodies and consist of Boxes, Spheres, or Capsules. Boxes wrap the body in a similar way to a bounding box, whereas Spheres, and Capsules are positioned to fit within the rigid body. These provide faster computation, along with a low memory footprint but result in lower accuracy during the simulation. Another drawback to using Analytic Collisions is that the simulation may begin with bodies intersecting, and then you will see them pushing apart when the simulation starts. You can adjust the Collision Object Reduction Percentage property to improve this behavior. This may require some tuning to find your desired results.

• Level Set Volumes - These type of volumes sample a rigid body using a voxelized grid, and generate a signed distance field for the geometry. The resolution of the Level Set volume can be specified using the asset's Min or Max Level Set Resolution settings. While Level Set Volumes are highly accurate and are tuneable for performance, there is a higher memory footprint (the accuracy of volume scales cubically in memory).

Once you are satisfied with your Geometry Collection setup, you can begin fracturing and clustering the mesh using the Fracture Editor.

Fracturing and Clustering

There are several different types of fracture methods available. Combining the different techniques may lead to more interesting looking destruction. You will have to experiment with the different options and settings to achieve your desired results.

Fracturing

Once you have your Geometry Collection, you can choose the type of fracture to perform using the Mode Toolbar Fracture tab, and the settings used to perform the fracture using the Fracture Panel.

After selecting your type of fracture and settings, click the Fracture button to fracture the Geometry Collection.

Using the Explode tool on the Fracture tab of the Mode Toolbar, you can increase or decrease the exploded view percentage to see the bones.

You can also sub-fracture individual pieces as needed to create more interesting results.

In the example above, the pillar was fractured using a sparse Voronoi fracture with a min/max number of sites set to 8. The center pieces were then re-fractured into smaller pieces while keeping the top and bottom sections with the larger chunks.

You can view the varying levels of destruction inside Fracture Editor from the View section by clicking the Levels drop-down.

Clustering

The Clustering options within the Mode Toolbar Cluster tab provide a way for you to control the visual quality and performance of a fractured mesh.

Clicking the Auto Cluster option will automatically group together pieces of a fractured mesh (based on your settings) and assign them to a Fracture Level within the Geometry Collection.

In the example video below, we take two Static Meshes that have been converted to a Geometry Collection and step through each of the Levels. Initially, Level 0 represents the entity as a whole while Level 1 represents the two separate bones. When we fracture the Geometry Collection, each pillar has a separate set of pieces and a new Level 2 has been created which represents the pieces that are broken up from each pillar. We then flatten all the bones to Level 1 and select to Auto Cluster them, which updates bones in the Outliner . Level 1 (instead of the two separate pieces) now has a base fracture applied containing slightly larger chunks, while Level 2 has the smaller pieces.

Typically, when destroying things like buildings you will want a small number of clusters (or bigger pieces) on Level 1 and as the Level increases, the more breakage occurs (smaller pieces). For optimization, you might not want thousands of pieces on the initial break, but instead, have individual pieces break off as the building is coming down. Another option available for optimization is the ability to define the Max Cluster Level in which to fracture.

This option can be set on the Geometry Collection in your Level and enables you to define which Fracture Level you want to limit the breakage to. Once set, the Geometry Collection will not exceed the defined Level.

When clustering, it may be useful to see the number of pieces within each cluster. With a Geometry Collection asset selected, you can use the following console command to print statics to the log:

GeometryCollection.PrintDetailedStatistics

Inside the Output Log you will see information about the selected Geometry Collection asset.

To get a pared-back version, focusing on the number of Rigid Bodies contained in each Level of the Hierarchy, use the following command.

GeometryCollection.PrintDetailedStatisticsSummary

You can also define the Damage Threshold per Actor to determine how much strain is required for each successive Level to break. You can find this option under the Clustering section in the Details panel.

In the example above, the damage threshold required to break apart each Level is set up in a descending manner through each of the ascending Levels. This means that Level 4 will start to fracture first and as damage increases, the Levels before it starts to fracture as well. If you look at the image below, you can see that on Level 1 the pieces clustered together in larger chunks (toggle on/off with Shift + B ).

Below, you can see the actual simulation performed.

What is occurring here is that the large pieces fall away, while the thresholds control how easily collisions and forces will allow them to break down further. Typically as clusters fall down, the collisions will lower their velocities. This means that lower thresholds are needed to ensure that smaller pieces break down even more.

Cluster Group Index

Another tool you can use for controlling the clustering on a group of Geometry Collections is through the Cluster Group Index property on each individual Actor.

When assigning each Actor to the same Cluster Group, the clustered group of Actors behaves as Level 0. In the example below, different damage threshold settings are used to control the individual pillars during destruction.

Collision Particles Fraction

Inside the Geometry Collection asset, under the Chaos Physics section, you can increase the Collision Particles Fraction property to increase the number of particles on the triangulated surface that will be used for collisions.

This property is important, especially when sharing Cluster Group Index values, as low numbers will usually result in incorrect collision behaviors (rolling through the floor for example).

Fields

The Fields system within the Chaos Destruction tools is a way of directly affecting a physics simulation by occupying a region of space (with varying parameters) in order to produce different behaviors or breakage effects. Fields can be created inside the Content Browser , and are purely a container for data (they do not open up as an asset).

You can then create a Blueprint of the Field System Actor class that contains a Field System Component where you set the Field System to use.

It is inside the Field System Blueprint you can define the logic of your Field.

In Blueprint, you can use the Add Field Command or Apply Physics Field to specify the type of attributes affected by your field.

• Add Field Command is used during the Construction phase in Blueprints. It stacks up properties before the simulation starts. Initialization fields such as Anchors are a good example of this.

• Apply Physics Field is used to specify attributes during simulation. External Cluster Strain based explosions using forces and velocities are good examples of this.

A brief overview of each can be seen in the table below.

The following section outlines some of the more common Fields, however, you can mix and match different Fields; to achieve different results.

Anchor Fields

Anchor Fields can be used to lock portions of a Geometry Collection in place while the rest of the Geometry Collection breaks apart. Anchor Fields differ from most Field System nodes in that they must be established during the Construction phase since the connection graph must also be established prior to simulation. Therefore, their logic is defined within the Construction Script of a Field System Actor Blueprint and applied using an Add Field Command node ( Apply Physics Field will not work). Upon simulation, if Clustering is enabled, an anchored geometry collection will remain static until a Strain force is applied using a Strain Field .

Below is an example from the Chaos Destruction Demo project:

Cluster Strain Fields

A Cluster Strain Field can be used to cause sections of a Geometry Collection to decay and break away once values have been reached that exceed the Geometry Collections Damage Threshold . In the video below, an Anchor Field (yellow box) is used to lock a portion of the building in place while a Cluster Strain Field (pink sphere) is used to indicate the location in which to apply the strain. The result is an effect where part of the building breaks away while the rest remains intact, as seen in the sample below.

Force Fields

A Force Field applies the specified amount of force to rigid bodies within the given volume. In the video below, a combination of an Anchor Field (yellow box) and Force Field (blue sphere) cause the building to explode outward based on the force being applied. This particular example also has no falloff, meaning all active rigid bodies in the scene are affected each time the Blueprint is triggered.

Angular Torque

Like the previous Force Field example, this example uses Angular Torque along with a spherical falloff volume to limit the amount of force being applied. By applying a randomized vector to the angular torque, the building in this example explodes outward, which creates are more varied and interesting effect.

Noise and Culling Fields

Noise can be applied to any field by adding a NoiseField component and using the Set Noise Field function to determine the min and max range. Culling fields can be added in a similar way, by adding a Culling Field component and specifying the falloff in which to apply any culling. Culling fields restrain an operation to the given volume, and are a good way to maximize performance and prevent unwanted field leakage.

Sleep and Disable Fields

Both a Sleep Field and a Disable Field will put rigid bodies to rest when they enter the specified volume. Disable Fields differ from Sleep Fields in that disabled nodes can no longer be reactivated by collisions, making them very cheap during simulation. They can, however, be reactivated by other fields.

Below, on the left, a Sleep Field is used to put rigid bodies to rest (collisions wake the rigid bodies, so they continue to simulate). On the right, a Disable field is used to stop simulation entirely.

Internal Strain Fields

An Internal Cluster Strain provides a way for you to affect all rigid bodies values within the field, and can be used to achieve effects like a building collapsing apart over time. To achieve this, strain values are updated each tick where the previous values are subtracted from a noise field (with parameters for scaling). A Culling field is also used to contain the effects during simulation.

Geometry Collection Caching

For larger simulations, to improve performance, you may want to try changing from a runtime simulation to a cached simulation. Cached simulations are good for destruction that occurs in the background or does not involve player interaction. In future versions of Chaos, support for dynamically changing between simulation and cached simulation will become a more viable option. In order to play a cached simulation, you will first need to record it.

To record and play a cached simulation:

1. Select your fractured Geometry Collection, then in the Details panel, change the Cache Mode under Cache Parameters to Record .

   Additional parameters can be used to define the data to be recorded.

2. Simulate or Play in Editor so the Geometry Collection fractures.

   In the video above, as the simulation occurs, we take a little bit of a performance hit. Once we stop the session, the Target Cache is updated with the stored data (and an asset is also created and added to the Content Browser ).

3. Change your Geometry Collection to Kinematic , assign the Target Cache , set Cache Mode to Play , and then Play (or Simulate) in Editor .

   In the video above, we initially run a fully dynamic simulation (which has the performance hit). We then switch to Kinematic and Play our selected Target Cache . Since we are no longer performing the calculation at runtime and are playing back a cached animation, the performance improves and we no longer see the hitch when destroying the building.

In addition to setting a Geometry Collection to Play a cache, you can use Blueprint to change the Play Mode or Sequencer for added playback control.

Above, we add our Geometry Collection Actor to a Level Sequence, along with a Geometry Collection Component and Geometry Collection. Under Properties , you can assign the Geometry Collection Cache to play in the Sequence. Additionally, we set the When Finished state to Keep State so that after the cache is played and the building becomes destroyed, it stays in that state. With Sequencer, you can control playback speed and scrub forward and reverse through the cached animation.

Geometry Collection Debugging

You can visualize the information for Geometry Collection Actors using the Geometry Collection Debug Actor and toggling its associated properties.

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.

Chaos Solvers

By default, Chaos automatically generates a Chaos World Solver to handle Chaos related computation. To reduce the load, you can allocate Geometry Collections to a custom Chaos Solver that is placed in your Level. To create a Chaos Solver , click the Add New button in the Content Browser , then under Physics , select Chaos Solver .

You cannot open this asset directly. To access it's properties, drop it into the Level, and the properties will become accessible in the Details panel.

The Geometry Collections that you want to use this solver, can be assigned on each individual Actor under the Chaos Physics > Chaos Solver option.

Niagara Integration

Chaos solvers within the Chaos Destruction system can store a list of collision, breaking, and trailing events as the simulation runs. Inside the Niagara Effects system, those events are listened for through the Chaos Data Interface . A Niagara system that implements the Chaos Data Interface (by default) is active for all rigid bodies driven by the world Chaos Solver; however, you can point your Niagara system to your custom Chaos Solvers as well.

The following steps provide a general overview for implementing the Chaos Data Interface within a Niagara system for Collision, Breaking or Trail Events:

1. Create your desired Niagara Emitter .

2. Create a Niagara System and point it to your emitter.

3. Inside your Niagara System, add the Chaos Destruction Data parameter under System Exposed Parameters .

   The Data Source property enables you to define either Collision Data , Breaking Data , or Trail Data to track.

4. Under Particle Spawn , add the Apply Chaos Data module.

5. Drag the Niagara System into your Level, then on the System Actor, you can override the Data Source in the Details panel.

   You can create multiple versions of the Niagara System Actor, overriding the Data Source to Collision, Breaking and Trail data.

Below is an example of Collision, Breaking and Trailing Events.

Chaos and Gameplay

Geometry Collections can send collision and break events that can be used to trigger gameplay. For the Geometry Collection to send these events, the Notify Collisions (for collision events) or Notify Breaks (for break events) must be enabled on the Geometry Collection Actor. You can enable these options inside the Details panel for the selected Geometry Collection Actor under the General section.

With a reference to the Geometry Collection Actor (and Geometry Collection Component within), you can bind to the OnChaosBreakEvent which will fire when the Geometry Collection breaks.

The Chaos Break Event struct reports all relevant information about the breaks in the Geometry Collection such as the primitive component, location, velocity, angular velocity, and mass.

Like Break Events, you can bind to Collision Events using the OnChaosPhysicsCollision which will fire when the Geometry Collection collides with another object.

You can break apart the Collision Info struct to retrieve information about the collision such as the primitive component and other component involved in the collision, the location, normal, velocity values and mass.

Using a combination of Break and Collision Events, along with Fields, you can cause destruction through gameplay events such as firing a weapon. Using information from the Collision Event, you can spawn a Field at the impact location, causing a break as depicted in the video below.

Additional Chaos Training

In addition to the information cited on this page, you can view the Chaos Fundamentals Twitch Stream below covering several of these topics and more.