Softbody blueprints

In this page we will learn to generate and edit softbody blueprints.

There are 2 different softbody blueprint flavors. Both blueprint types can be fed to ObiSoftbody actors.

Surface softbody:
Will generate particles over the surface of a mesh, orienting and scaling them to approximate its shape as closely as possible. Resulting visuals are good and relatively cheap to compute, though the simulated result can look "hollow" if the mesh is very thick.

Volume softbody:
The softbody mesh is voxelized, and a particle placed at the center of each voxel. This generates many more particles than a surface softbody as it also generates particles inside of the mesh, but the extra cost can pay off if accurate volumetric effects are required.

To generate a basic softbody blueprint, go to Assets->Create->Obi->Softbody surface/volume blueprint, or right-click on a project folder and select Create->Obi->Softbody surface/volume blueprint.

Softbody simulation and rendering are taken care of by two separate components: ObiSoftbody (simulation) and ObiSoftbodySkinner(rendering). The former generates a particle-based representation of a mesh. The latter skins an arbitrary mesh to that particle-based representation, so that they move and deform together.

Using two separate components lets you decouple simulation and rendering, which is oftentimes very useful. Also please note that you're not forced to have a single ObiSoftbody skinner for each ObiSoftbody. You can skin multiple meshes to a single softbody, using multiple ObiSoftbodySkinners.

Generating a blueprint

Softbody blueprints take a mesh as input. Any mesh will work, including non-manifold meshes and polygon soups.

When you press the Generate button in the blueprint inspector, particles will be generated using the mesh surface or volume (depending on the softbody type), then shape matching clusters will be generated. The cluster network is what holds the particles together, and simulates elasticity and plasticity. Let's take a look at all parameters that control particle and cluster generation:

Input Mesh

The "Input mesh" slot in the softbody component allows us to specify which mesh to use for particle generation.

Particle Radius

Radius of the particles that will be seeded on the surface of the Input Mesh. This is the main parameter that controls the quality/performance ratio of your softbody: a very small radius will result in many particles added to the mesh surface (as many as vertices in the Input Mesh). Larger values will result in coarser sampling of the mesh.

Particle Overlap

Percentage of overlap allowed between particles. Large values will ensure more thorough coverage of the input mesh surface, by means of generating more particles. Values of 0.5-0.7 usually are the coverage/performance sweet spot.

Shape Smoothing

Amount of laplacian smoothing applied to the mesh prior to particle seeding. Large values can help in representing thin features such as antennaes and limbs with linear particle chains.

Anisotropy Neighborhood

Radius around each particle that is considered when calculating the shape and orientation of that particle. Values close to or slightly larger than the Particle Radius give good results.

Max anisotropy

Maximum ratio between the longest axis of a particle and its shortest one. Large values will result in very pronounced ellipsoidal shapes, small values will result in more spherical particles.

Soft cluster radius

Radius around each particle that is considered when linking that particle to the ones around it. Values 2-3 times the Particle Radius usually give good results.

One Sided

If enabled, uses one-sided particles to help with collision detection. While regular particles project overlapping bodies in the direction of the shortest path to the particle's surface, one sided particles use the shortest path to the softbody mesh surface.

Generation is a process can take quite a while. Once it is done, the Edit button will activate. Pressing it you will enter the cloth blueprint editor.

Cloth blueprint editor

There's three main modes in the cloth blueprint editor, that can be acessed using the 3 buttons at the top:

  • Particle selection
  • Property painting
  • Texture import/export

Particle selection


In particle selection mode, you can select particles to modify their properties, create particle groups, and generate tethers. To select particles, click and drag over them in the scene view. To deselect particles, hold the shift key while dragging.

You can change the brush size by dragging the brush size slider. You can change the particle culling mode to one of three options:

All particles will be drawn and selectable.

Particles facing away from the camera won't be drawn nor selectable.

Particles facing towards the camera won't be drawn nor selectable.

There's also a few available tools that operate on the current selection:

Invert selection:
All particles will be drawn and selectable.

Clear selection:
Particles facing away from the camera won't be drawn nor selectable.

Optimize selection:
Delete all selected particles that share no constraints with any unselected particle. This is useful when you intend to attach a group of particles to a transform, and want to get rid of those that won't contribute to the simulation after being attached.

Prior to optimization.
After optimizing the selection, only selected particles that share constraints with unselected ones remain.

Remove selection:
Delete all selected particles.
Restore removed:
Will bring back all particles deleted as a result of optimization or removal.

You can get/set any property of the currently selected particles:

Particle mass. Determines how the particle behaves when involved in any constraint (collision, distance, bending...) with another particle or a rigidbody.

Particle radius. Mainly used for collision detection.

Particle phase, used to determine when collisions with rigidbodies and other particles should be ignored. For an in-depth explanation, see collisions.
Particle color. Useful to store additional info, or to be used in custom rendering.

Particle groups

You can group together particles that have a special role or significance to you. For instance, you could create a group out of the 4 particles at the corners of a rectangular cloth sheet, to be able to later hang it from another object. Groups are mainly used when creating particle attachments, but can also be acessed at runtime in custom scripts.

To create a new group from the current selection, simply press the "+" button at the bottom right corner of the list. To delete a group, select it from the list and click "-". You can also select all particles in the group by clicking the select button (multi-selection of groups using the shift key also works), and you can replace the particles with the current selection by clicking set.


All three blueprint editor modes (selection, painting and texture import/export) have a visualization options section. Here, you can change the render mode which determines the elements that should be drawn in the scene view. Some of the options are:

Only the particle selection handles are rendered.

All render modes are enabled at once.

Particles are fully rendered, showing ther shape, size and color. This uses the same render pipeline as the ObiParticleRenderer runtime component (see particle rendering)
The source mesh used to generate the blueprint is rendered. The currently selected particle property is used to drive vertex colors. You can use the range options in the visualization section (see below) to determine how property values are mapped to colors.
Multiple constraint render modes let you visualize the constraints in your blueprint.

When the mesh render mode is active, the currently selected property (mass, radius, etc...) is mapped to a color gradient and used to draw the mesh. By default, the minimum and maximum property values are calculated and used to map values to a color gradient.

Property painting

In property painting mode, you can use brush tools to paint particle properties directly on the surface of the cloth. Enabling the mesh render mode is recommended to work when painting.

The brush has a inner and an outer radius. The brush opacity within the inner radius can be set by changing the brush opacity value. The opacity smoothly decays outside the inner radius, reaching zero at the outer radius.

Most properties offer 3 brush modes:

Displaces the current property values towards the one set in the proprerty field. The brush opacity determines the speed at which the values shift towards the target one.

Adds the value set in the property field to the property values in the mesh. Again, the brush opacity determines the speed at which the values are changed. You can hold shift in the keyboard to subtract instead of add.

Smooths out the property values.

Selection mask

If there are some particles currently selected, you can enable selection mask. When the selection mask is active, the paint brush will only act upon the selecte particles. This is useful if you only want to paint some parts of the mesh.

Texture import/export

You can import/export any property to a texture using these tools.


When loading property values from a texture, we need know how to map pixel values to property values. Obi maps linearly from the 0-255 pixel value range to a user-defined property value range.

Texture used to read property values from.

Source channel:
While some properties (such as color) use up all 4 texture channels (red, green, blue and alpha), most properties (mass, radius...) are floating point values, so only one texture channel is needed to store/retrieve them. Using this dropdown you can select which channel to read values from.

Min value:
Property value read from pixels with a value of 0.
Max value:
Property value read from pixels with a value of 255.


When exporting color properties, all 4 texture channels are used. When exporting floating point properties, the maximum property value in the mesh is mapped to white pixels (255) and the minimum value to black pixels (0). Values are always stored in the red texture channel.

Texture width:
Width of the texture in pixels.

Texture height:
Height of the texture in pixels.

Amount of pixel padding added around UVs seams. Ensures accurate values are read at the UV seams when importing values back from the texture.
Particle radii exported with no padding.
Particle radii exported with a padding of 16 pixels.