Search public documentation:
UE3 Home > PhysX? > PhysX Destructible Reference
Document Summary: Description of the PhysXDestructible class. Document Changelog: Created by Bryan Galdrikian.
- PhysX Destructible Reference
- When to use a PhysXDestructible instead of a FracturedStaticMesh
- Guidelines for creating a suitable FracturedStaticMesh
- How to Create a PhysXDestructible
- Known Issues
The PhysXDestructible is a feature built on top of UE3's FracturedStaticMesh (FSM). As a starting point, it will be assumed that the reader is familiar with the FSM. See the Fracture Tool page to familiarize yourself with that feature.
The FracturedStaticMeshActor is an efficient way to generate small levels of destruction within a UE3 level. However, if you wish to scale up the amount destruction, the FracturedStaticMeshActor will soon reach some limitations. For one thing, every piece (or conglomorate) that gets ejected is represented by an AActor. If hundreds of pieces are ejected, the AActor overhead can be quite large. The PhysXDestructibleActor is designed to operate within the regime of hundreds, or even thousands, of rigid body pieces. It handles this in two ways. First, it represents its pieces as bones in SkeletalMeshes. This greatly reduces the AActor overhead. Secondly, it fractures hierarchically. So large pieces that are unfractured remain represented as one rigid body, and one SkeletalMesh bone. In addition, PhysXDestructibles have some extra features that enhance the effect of destruction. You may assign a "crumble particle system," which is intended to be a PhysXParticleSystem (see PhysXParticleSystemReference). This will represent the finest level of fracturing. That is, when the smallest pieces are destroyed, their volume will be replaced by a set of PhysX fluid particles. If you use a mesh data type, this can give a convincing crumbling effect. You may also assign a crumble sound, as well as a more traditional particle effect (for smoke or dust, e.g.). PhysXDestructibleActors can be static or dynamic. If they are static, there are two ways to assign some parts of the Actor to be "support." When a contiguous path (via chunk pieces) is lost between a chunk and a support chunk, then the chunk will come loose. This feature is available through the FracturedStaticMeshActor, but the PhysXDestructibleActor has an additional feature that allows them to create a support structure between touching actors. That is, islands of touching PhysXDestructibleActors will form one support structure. You may use this, for example, to create a tall column out of several PhysXDestructibleActors. If you shoot through the middle of the column, the actors on top will automatically come loose. Finally, the PhysXDestructibleActor supports impact damage. By supplying an impact-to-damage scale, fracturing will occur when the PhysXDestructibleActor is hit (or hits) hard enough. Note: Impact damage currently contains a bug which prevents it from working in all cases. This will be addressed as soon as possible. By starting out life as a FracturedStaticMesh (in its unbroken state), a PhysXDestructible gets the benefit of more efficient static rendering until it is broken.
Summary: choose a small number of pieces (roughly 5 to 20) to fragment your static mesh with the FractureTool. In more detail... the FractureTool can fracture a StaticMesh into a moderately large number of pieces. Currently the tool allows up to 150 pieces. However, we recommend keeping this count small (perhaps a dozen, maybe even fewer for a small object). The reason is that each fragment of the FracturedStaticMesh will become one AActor. After that, however, no more AActors are created. Each of these AActors (PhysXDestructibleParts) is represented by one or more SkeletalMeshes. It is possible to "fragment" your StaticMesh into one piece! If you do this, the FracturedStaticMesh, and will be replaced entirely by SkeletalMesh(es) when any damage is taken. But the idea behind starting with the FracturedStaticMesh is to keep as much of the undamaged mesh static for as long as possible, to take advantage of the more efficient rendering that offers. So, we do not recommend fragmenting into too small a number of pieces (like 1). Note: Currently this optimization is not in place. As soon as a PhysXDestructible is fractured, all fragments become separate SkeletalMeshes. We plan to implement the static optimization soon. But we recommend you follow the above guidelines, and a later code drop implementing this optimization should give your levels better fracturing performance.
bAccumulateDamage - when checked, damage applied to chunks will accumulate. When the damage exceeds a damage threshold, the chunk will break free. When unchecked, damage is not accumulated, and a single application of damage must exceed the threshold in order to break the chunk free.
DamageCap - applied damage will be limited to this amount. If set to 0 (default) there is no limit to the applied damage.
DamageToRadius - this translates damage to a distance within the destructible. If the damage type applies 'bFullDamage' then all chunks within this radius will have this amount applied. Otherwise, damage falls off linearly from the full damage (at the damage origin) to 0 (at the damage radius). Some notes about damage:
- After a chunk takes damage, the DamageThreshold is subtracted from the damage and the remainder is applied to all of the chunk's "children" in the fracture hierarchy. At each level of the hierarchy, DamageThreshold is the amount needed to break a chunk loose. When linear falloff is used in the damage type, the effect is that the mesh breaks into finer pieces near the damage origin, and tends to break into large pieces farther away.
- The actual translation from damage to radius goes as follows: damage is divided by DamageThreshold, then the result is multiplied by DamageToRadius, and finally multiplied by the size of the object (the mean width of the object's bounding box). This scales both damage and size, so that both DamageThreshold and mesh scale may be varied, but the damage propagation remains unchanged.
ForceToDamage - Impact force is translated into damage by this factor. In order for this to work, bNotifyRigidBodyCollision must be checked in the Actor's CollisionComponent.
CrumbleParticleSystem - This is intended to be a particle system containing PhysX emitters. (See PhysXParticleSystemReference.) You may use a PhysX Mesh Emitter to emulate crumbling. When a chunk at the lowest (smallest) level of the hierachy takes DamageThreshold in damage, it is destroyed. If you have selected a CrumbleParticleSystem then the volume of that chunk will be replaced by a group of mesh "fluid" particles. These can collide with geometry and emulate many small bodies.
CrumbleParticleSize - When using a CrumbleParticleSystem (see above), the chunk destroyed is filled with particles spaced at this distance.
FractureSound - A SoundCue that may be played when a chunk is broken free (or crumbles).
DepthParameters - This is an array of parameter sets, one set for each level of the chunk hierarchy. This array cannot be resized; it is set in size by the number of levels in the chunk hierarchy. Set  gives parameters for the PhysXDestructibleActor. Set  gives parameters for the top-level chunks (each single chunk representing a FracturedStaticMesh fragment). If you used one level of slicing, there will be a set , which applies to the next-finer level of chunks. If you used two levels of slicing, there will be a set , etc. At each level, the paramaters are:
- bTakeImpactDamage - if ForceToDamage > 0, impact force will apply damage at this level.
- bPlaySoundEffect - if FractureSound is set, then it will be played when chunks at this level break free (or crumble).
- bPlayParticleEffect - chunks broken at this level will play the FragmentDestroyEffect set in the FracturedStaticMesh. (This is set in the FSM in the StaticMesh editor, see the Fracture Tool page.)
- bDoNotTimeOut - if set, chunks at this level will remain indefinitely, as long as the config. variable MaxDynamicChunkCount is not exceeded (see LOD Scaling, below). If this is not set, then after the time given by the config. variable DebrisLifetime (again, see LOD Scaling), this chunk will be destroyed.
DebrisLifetime - This sets how long "debris" chunks are kept around. In this case "debris" simply means the bDoNotTimeOut field (see Destructible Parameters, above) is not checked. If a chunk is removed due to the max. chunk count limit being exceeded, or the timeout is exceeded, then it will crumble completely using the CrumbleParticleSystem. If no CrumbleParticleSystem is set, the chunk will simply disappear.
- The DestructibleParameters are copied from the PhysXDestructible, and may be modified for this actor instance.
- You may make the PhysXDestructibleActor dynamic by changin its Physics to PHYS_RigidBody.
- If the PhysXDestructibleActor is not dynamic, then it may be part of a support island. This will be described in detail in the Support section below. Here we will describe the four support fields:
- SupportDepth - support calculations are done at this depth in the hierarchy. Depth = 0 (default) means that support calculations are done at the FracturedStaticMesh fragment depth, i.e. the largest pieces.
- PerFrameProcessBudget - how many iterations (steps through the support graph) will be allowed to perform support calculations, per frame. This is usually not an issue, unless a support island is very large. If the process budget is exceeded, unprocessed chunks will break loose automatically.
- bSupportChunksInSupportFragment - if this is checked, then a chunk at SupportDepth is considered a "support chunk" only if it a child of a FracturedStaticMesh support chunk. (Set in the FractureTool.)
- bSupportChunksTouchWorld - if this is checked, then a chunk at SupportDepth is considered a "support chunk" only if it touches world geometry.
- Impact damage does not always work. This is either due to an integration bug or a bug in the PhysX SDK.
- The FracturedStaticMesh is remvoved upon first damage, and replaced by SkeletalMeshes. A more efficient approach is planned where the framgents will be made invisible and replaced by SkeletalMeshes only as needed, thereby keeping as much represented by a static mesh as possible.
- If a mesh is sliced down too finely, some strange errors can occur that cause small shards to appear "floating" in mid-air.
- Changes to FracturedStaticMeshes and PhysXDestructibles are not propagated to the PhysXDestructibleActor instances in the level.
- Destructible1.wmv: Destructible1.wmv