From BlenderWiki

Jump to: navigation, search

Extension of Explode Modifier by Voronoi Cell Mode

Draft of Documentation for New Fracture Modifier Implementation

New Fracture Modifier Proposal

New Fracture Modifier Design Overview


The Voronoi Explode Modifier Extension is a C alternative to the existing voronoi fracturing code, which existed before in two flavors as Cell Fracture add-on and the Blender Destructability Editor add-on, both written in Python. The latter of the two used the voro++ library already, in a version compiled by Cython to be accessible from Python. The modifier's benefits are the increased fracture speed, its non-destructive operation on an existing mesh and the possibility to animate the resulting voronoi cells with the underlying particle system. Instead of moving single faces with the particles whole voronoi cells aka independent parts of the mesh are moved. To operate on arbitrary meshes, another boolean intersection step with the original mesh is necessary, because the underlying voro++ library cannot handle arbitrary domains. Instead, the object's bounding box will be used as voronoi domain, and cells are generated within it. Each shard needs to be intersected with the actual mesh so that the cells form the original mesh again, piece by piece. The cell fracture add-on operates in a similar way, using boolean operations as well.


The modifier uses the small open source voro++ library, available here and licensed under a BSD compatible license. Actually version 0.4.5 is up-to-date and used by the modifier.


  1. Add a particle System to the object to be fractured
  2. Add a Explode Modifier to the object, after the particle system modifier
  3. Choose Voronoi Cells at Mode
  4. For particle animation: Check Use Animation", optionally choose a cluster size and a cluster percentage
  5. For rigidbody physics: Add a Rigidbody Modifier below the Explode Modifier and make the object an active rigidbody. The Rigidbody Modifier can work without the Explode Modifier too, if you don't need the voronoi shards. For example you can add a Rigidbody Modifier right below an Array Modifier to make each mesh island a rigid body.
Note: there are calculation limitations for higher shard numbers in the library, if particles are very close to each other in case of missing cells, use 
"Volume" particle emission mode and "Random" distribution.

Usage Video (old):

Usage Video (updated):

Overview Screenshot

Explode modifier.png Rigidbody modifier.png

Options for Voronoi Explode Modifier:

Point Sources

You can choose multiple options of the following list:

  • Own Particles: Use the particle system on this object above the explode modifier as pointcloud.
  • Own Vertices: Use the own vertices of the object as pointcloud.
  • Extra Particles: Use the particle systems of all objects in the Extra Group as pointcloud.
  • Extra Vertices: Use the vertices of all objects in the Extra Group as pointcloud.
  • Grease Pencil: Use the greasepencil drawing of this object as pointcloud.

Extra Group

The group the extra objects must belong to.

Particle Mask

Use any combination between unborn, alive and dead particles as fracture pointcloud. Applies to own and extra particles as well, at the same time.


Apply some random distortion to the pointcloud.


Use only the given percentage of the pointcloud as actual point source.

Use Boolean Intersection

To boolean intersect with original geometry, necessary for arbitrary shapes, inner material setting and uv texture support, enable "Use Boolean Intersection"

Note: you need to fix non-manifolds in the mesh by hand before using "Boolean Intersection", otherwise the result may look unexpected. 

Inner Material

If the inner faces should get another material, you can choose an inner material. The material does not need to be necessarily on the object, it will be copied there if you choose it from the material list.

Use Clipping(WIP)

An alternative fracture algorithm, which should target non-manifold objects as well. The geometry is intersected with the voronoi cells. It still is very slow and needs a relative fine subdivided geometry to work in a satisfying way. Wont work with an unsubdivided default cube for example, but it gets better with more subdivisions, although holes in the geometry may arise.

Use Animation(Own Particles)

Let the shards move with the particles, if an own particle system is defined and no rigidbody modifier has been added.

Cluster Size

If you want to follow each cell its particle, choose a cluster size of 1. The object will dissolve according to particle movement. To have bigger clusters of cells, increase cluster size. Cluster size will be taken into account in Rigidbody Modifier as well, when constraints are used. The constraint threshold between members of the same cluster will be set to a different (e.g. higher) value than the constraint between members of different clusters. This inner cluster threshold is adjustable in Rigidbody Modifier, experimental section.

Cluster Percentage

Percentage of shards which will belong to a cluster at all, the rest forms single cells only.

Shard Objects

To get separate shard objects from explode modifier only, simply apply the modifier and separate the mesh by loose parts. In conjunction with the Rigidbody Modifier there is an option to convert modifier rigidbodies and constraints to regular rigidbodies and constraints, thus retaining the fracture and having similar simulation behavior. That way a fracture can be reused in blender versions without rigidbody modifier support.

Auto Refresh

Enable live preview of fracture, useful for instant feedback how the fracture will look. Best used in wireframe mode or with "Wire" rendering enabled. Disable this for faster particle animation performance and when you want to use the rigidbody modifier as well. The latter point is mandatory.


Update the fracture cache after making changes. This works for some settings automatically, e.g. particle count and point source, for others you need to push this button after making a change.

Note: This is required after most changes and after each reload of the file, this applies to undo as well !

Options for Rigidbody Modifier:

Refresh All Data

Update the rigidbody modifier cache. This is necessary if you made some changes to the modifier or did refresh the explode modifier above the rigidbody modifier (if used). This way the entire meshislands and rigidbodies will be rebuilt.

Note: This is required after most changes and after each reload of the file, this applies to undo as well !

Refresh Constraints Only

A faster way to invalidate the cache and update just the constraints and compounds. Rigidbodies will be retained this way.

Use Constraints

Creates inner constraints between all adjacent mesh shards.

Contact Distance Target

Determines where the given distance in blender units applies to: Vertices or centroids. Cells+centroids is an alternative approach to distribute the constraints among a cell grid more evenly across the object. This is also necessary for the compound option.

Contact Distance

Searching distance around vertices or centroids to find other rigidbodies nearby to connect with a constraints. The higher this distance is, the more potential constraints will be built. Can be reduced in conjunction with Cells+Centroids since rigidbodies will be searched from within a regular cell grid over the objects bounding box.

Cell Size

Size of each cell of the grid in blender units. The objects bounding box will be divided into a cell grid of the given size and constraints will be searched from cell centroids instead of object centroids. This allows a more regular distribution of constraints, and can reach more parts with a lower search radius as well. Otherwise the search radius must be higher to connect the desired parts, which can lead to potentially more unwanted constraints.

Use Compounds(WIP)

Glues all rigidbodies from within a cell together to a compound rigidbody. Useful in conjunction with constraints, to drastically reduce the constraint count by just establishing constraints between compounds. Will be destroyed entirely when all constraints are broken. Notice: needs a constraint refresh when the object is moved, because internally it stores the fracture frame, to make it work with baking. This might differ if the object is moved farther away from the ground for example and leads to incorrect results. Benefit of compounds is an increased simulation speed, but drawbacks are incorrect movements of compound while it is being destroyed.

Constraint Breaking Settings

Here you can adjust the breaking threshold, above which a constraint is broken. This is highly dependent of the object mass. The higher the mass is, the earlier the constraints with the same threshold will break. The rigidbody mass is calculated from the object mass and the volume fraction of the rigidbody in relation to the total volume of the object. Furthermore you can set a breaking angle, distance or percentage. If the angle or distance between two constrained objects are exceeded, the constraint breaks. And if the percentage of broken constraints of an object is exceeded, the rest will break too immediately. 0 means deactivated.

Convert to Objects

Automates the modifier application and object seperation as well as the constraint conversion. You get an equivalent fracture representation consisting of regular rigidbodies and regular constraints, if constraints were enabled before.

Experimental Rigidbody Modifier Features - (WIP) Options may still crash

Use Both Directions

Check to establish constraints in both directions between each pair of constrained rigidbodies. Makes the object more stable.

Disable Self Collision

Collision between constrained objects are disabled by default. Enabling this checkbox disables the collisions.

Constraint limit, between MeshIslands

Maximum number of constraints each meshisland can have. 0 means unlimited. If only the most necessary constraints are created, simulation speed will increase.

Constraint Group(WIP)

Creates additional outer constraints between this objects shards and shards of the objects in the given group. Each other object must have a rigidbody Modifier as well. The "master" object will be the object where the "slave" objects (belonging to the constraint group) will be attached to. The master must NOT belong to the constraint group itself, it only points to the constraint group via the group selector field.

Group Contanct Distance, Fixed Only(WIP)

A similar distance setting as Contact Distance, but used between shards of different objects. Applies to fixed constraints only, because for other constraint types the closest shards of both objects will be searched and constrained together.

Inner Constraint Type

The constraint type of the shards within the same objects. Default is "Fixed", which means the objects are stuck together. All other types allow certain movement between the shards. Refer to the Blender Viewport Rigidbody Documentation for details to each constraint type.

Outer Constraint Type

The according constraint type for shards within different objects. Default is "Fixed" as well, and options are the same as with Inner Constraint Type.

Outer Constraint Location

  • Master: the constraint is located at the master object e.g. useful when attaching the object firmly to a passive ground slave object.
  • Slave: the constraint is located at the slave object, e.g. useful when hanging a fractured object at a passive pivot slave with point constraint.
  • Center: the constraint is located exactly between both objects, the default for inner and outer constraints.

Use Proportional Limit

Smaller shards get a lower constraint limit in relation to the set constraint limit, which defines the maximum (means the biggest shards get higher limits). This way smaller shards should break off more easily.

Use Proportional Distance

Smaller shards get a lower constraint search distance, so they dont get so many potential connections to other shards. This way smaller shards should break off more easily too.

Outer Breaking Threshold

The forces affecting the constrained shards must be higher than this value to make the according inner constraint break and shards drop off. Similar to the regular breaking threshold, but used between shards of different objects.

Use Mass Dependent Thresholds

This lowers the thresholds of smaller objects according to their smaller volume and mass, so they can break off more easily at impact.

Use Distance Dependent Thresholds

This raises the thresholds of smaller objects according to their possibly lower contact distance, so objects farther apart can break off more easily at impact.

Solver Iterations Override

Use the given iteration count for all constraints between shards of this object. Set to 0 to use the Rigidbody World Solver Iteration count.

Use Proportional Solver Iterations

Set the solver iterations proportional to the participating shards "constraint mass", that simply is the added mass of both shards. The higher the mass fraction of that constraint is in relation to the total object mass, the higher the solver iterations will be. Supposed to let shards move a bit around close to the broken constraints and make potentally more cracks visible, in case you predefined an impact location with the point cloud.

Use Automerge(WIP)

This automatically hides the inner geometry for constrained objects as long as the constraints are not broken. Useful for breaking glass objects to hide the cracks. If cracks are visible at start, make sure to refresh the according object. If you experience missing faces, do the following:

  1. Let the simulation run until the endframe, so that the simulation cache is filled completely (important). If you dont do this, unexpected behavior might occur. To recover from this, refresh the rigidbody modifier cache (Hit Refresh Button)
  2. Jump back to the start frame (e.g. Frame 1)
  3. Pull the timeline back a bit (e.g. to Frame 0).
  4. Now, if you let the cached simulation run again from the beginning, all faces should be there.

Automerge Distance(WIP)

Maximum Distance of verts which will be merged after hiding the inner geometry. Is supposed to close gaps between shards whose constraints have not been broken yet.

Cluster Breaking Threshold

This sets the threshold between members of the same cluster, as defined by the explode modifier, It is usually higher, because this way the object will break apart to the given clusters instead to single shards. Can be lowered to destroy the clusters themselves too.

Rigidbody Fracture Modifier System

This system allows to fracture mesh objects without creating lots of shard objects which would clutter up the scene. Its all stored at object level. There are currently two modifiers implemented. There is one Voronoi Explode Modifier and a RigidBody Modifier. Voronoi modifier fractures an object, Rigidbody splits a passed mesh to islands (not necessarily from voronoi, can be array modifier as well e.g. and creates rigidbodies for each island. If rigidbody modifier is stacked below voronoi modifier, you can simulate fractured rigidbodies.

Voronoi Explode Modifier

The actual fracture is performed by the voronoi modifier which caches its results internally in a sequence of voronoi cells. The mesh vertices are grouped by the cells, which hold references to them for quick manipulation of the global mesh, if the cell moves. Each cell can be associated to the closest particle, which allows even clusters of cells being moved as one optically. Or you can associate each cell exactly with its centroid particle, if Particle System was chosen as point source and Emit Continously is set. This modifier always updates the positions of the cells according to the particles, but the fracture process itself is only performed on certain changes or on hitting the refresh button. Fracture results are cached as bmesh and sequence of voronoi cells, since this fracture process is expensive, especially when boolean intersection (needed for all non cuboid objects, so almost always) is involved. At the moment for fracturing the library voro++ is used which returns their results as a text file. This will be read from the modifier and meshes are built up accordingly.

Rigid Body Modifier

The second modifier can convert any mesh to independent mesh islands, structure is similar to voronoi cells. But in this case an existing mesh is split by loose parts to mesh islands instead of objects. Each mesh island will be associated with an rigidbody object and those will all be added to the rigidbody world automatically as well. Those shards can coexist in the simulation with "regular, one-piece" rigidbody objects. The Pointcache uses a linear rigidbody index and a conversion map to find the correct object and the correct mesh island inside it. When the mesh island is found, its position/rotation will be updated and propagated to each vertex of the global mesh it holds references on. The mesh split process can be expensive too and will be performed on request only, not each time the modifier is called. So this modifier also caches its results as a bmesh and a sequence of mesh islands, and if constraints are generated, those are stored as well. Constraints will be generated between meshislands which share vertices, basically. The shared vertices are search for the mesh islands which are sorted by distance. If shared vertices are found, a constraint between the two meshislands is built and will be added to the corresponding rigidbody objects in the rigidbody world too. The feature Automerge, which tries to eliminate invisible inner geometry automatically, uses those shared vertices too and determines which faces of different mesh islands are adjacent to each other and selects those.

Permanent storage (disabled for now, a huge performance eater)

Regenerating modifier result data can take some time especially if many shards are to be built. So a "reduced bmesh" format is used to store the result meshes of each modifier, since it uses bmesh for in memory caching already. This SubMesh or SMesh stores vertex coordinates, and edge/face/loop indexes only, but it is still faster to rebuild a bmesh from this as from scratch, this means voronoi raw data and mesh island separation if both modifiers are stacked. So a few new DNA struct types (SMesh, SMVert, SMEdge, SMLoop and SMFace) were defined, along with conversion functions from and to bmesh.

Visualization of the rigidbody fracture system


Link to source code repository