Softbody blueprints

Softbody simulation and rendering are taken care of by two separate components:

ObiSoftbody

Simulates a particle-based representation of a mesh.

ObiSoftbodySkinner

Binds an arbitrary mesh to a ObiSoftbody's particles, so that they move and deform together.

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

The ObiSoftbody component requires a softbody blueprint to get its particle/constraint data from. The blueprint will generate particles at the mesh surface / volume / skeleton (depending on your blueprint settings, see below), and shape matching clusters to hold these particles together.

Creating a blueprint

To create a softbody blueprint, go to Assets->Create->Obi->Softbody surface blueprint, or right-click on a project folder and select Create->Obi->Softbody surface blueprint. This is how the blueprint inspector looks like:

Input Mesh

Mesh used for particle / cluster generation. Any mesh will work, including non-manifold meshes and polygon soups.

Scale

Scale applied to your mesh before using it to generate blueprint data.

Rotation

Rotation applied to your mesh before using it to generate blueprint data.

Once you've provided a mesh, the initially grayed out Generate button at the bottom of the inspector will become usable. Upon pressing this button, particles and clusters will be generated using the parameters you've set for each of the 4 generation stages:

• Surface sampling
• Volume sampling
• Skeleton sampling
• Shape analysis

If you modify any parameter of any of the stages, you will need to click the Generate button again to apply the changes.

Surface sampling

This stage will distribute particles on the surface of your mesh.

Mode

None

No particles will be generated for the surface of the mesh.

Vertices

Particles will be placed at the vertices, allowing little to no particle overlap. Clusters will be generated using the mesh edges, so they will follow the mesh topology as closely as possible. At lower resolutions, particle and cluster placement may not preserve mesh symmetry.

Voxels

The surface of the mesh will be voxelized, one particle placed at the center of each voxel, then projected to the closest point on the surface of the mesh. Clusters will be generated based on voxel adjacency. This guarantees that given a symmetric input mesh centered at the origin, particle and cluster placement will also be symmetric.

Resolution

This controls how fine grained particle sampling will be. Higher resolution values will use more smaller particles. Lower values will use less, larger particles.

Volume sampling

This stage will distribute particles in the volume of your mesh. Note that if your mesh does not enclose any volume, this stage might generate no particles.

Mode

None

No particles will be generated for the volume of the mesh.

Voxels

The volume of the mesh will be voxelized, and particles placed at the center of each voxel. Clusters will be generated using voxel adjacency.

Resolution

This controls how fine grained particle sampling will be. Higher resolution values will use more smaller particles. Lower values will use less, larger particles.

Skeleton sampling

You can optionally ask Obi to generate particles for a character skeleton. These particles can be driven using animation, and in turn affect volume/surface particles around them. This results in what we call a full-body volumetric softbody, or FBVS for short.

Hence, a FBVS is a 3-layer model of a real body: bone particles approximate the skeleton, volume particles approximate the body's fat & muscles, and surface particles approximate skin.

Skeleton

GameObject that contains the skeleton you want to use.

Root Bone

This dropdown lets you select the specific bone in the skeleton's hierarchy used as the root bone.

Bone rotation

Rotation applied to the skeleton before sampling it with particles.

Shape analysis

As a final step, Obi will perform some additional shape analysis of your input mesh. This has two purposes: to adjust the shape and position of your particles to better fit the mesh, and to discard invalid clusters. Shape analysis is performed by voxelizing the mesh, and determining the shape of the local neighborhood around each voxel.

Resolution

This controls how fine voxelization will be. Higher resolution values will make blueprint generation slower, but will yield better quality results.

Max anisotropy

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

Shape Smoothing

Amount of laplacian smoothing applied to particles. Large values can help in representing thin features such as antennaes and limbs with linear particle chains. In the following images, this is most noticeable in the bunny's ears: they get thinner as smoothing increases.

Generation is a process can take quite a while. Once it is done, the initially grayed out Edit button will become usable. Pressing it you will enter the blueprint editor.

Softbody blueprint editor

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

• Particle selection
• Property painting
• Texture import/export

Particle selection

Selection/editing

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:

Off:

All particles will be drawn and selectable.

Back:

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

Front:

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.

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:

Mass:

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

Radius:

Particle radius. Mainly used for collision detection.

Category:

Particle collision category, used to determine when collisions with colliders and other particles should be ignored. For an in-depth explanation, see collisions.

Collides with:

Particle collision mask, used to determine when collisions with colliders and other particles should be ignored. For an in-depth explanation, see collisions.

Color:

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.

Property painting

In property painting mode, you can use brush tools to paint particle properties directly on the surface of the softbody. 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.

Using "Brush mirror axis" and "Brush mirror space" you can mirror brush position in all 3 axis in world space or camera space.

Most properties offer 3 brush modes:

Paint:

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.

Add:

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.

Copy:

Copies values from one property to another. It requires both properties to be scalar values.

Smooth:

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.

Import

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.

Source:

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.

Export

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.

Padding:

Amount of pixel padding added around UVs seams. Ensures accurate values are read at the UV seams when importing values back from the texture.

Render Modes

All three blueprint editor modes (selection, painting and texture import/export) have a "render modes" 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:

Particles:

Particles are fully rendered, showing ther shape, size and color. This uses the same render pipeline as the ObiParticleRenderer runtime component (see particle rendering)

Voxels:

The voxel-based representation used during surface analysis will be rendered.

Mesh:

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.

Shape matching constraints:

Lets you visualize the current shape matching cluster network.

Skeleton:

If a skeleton is being used for blueprint generation, its bones wil be drawn.

Normals:

Particle orientation is visualized as blue normal vectors.

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. If the "automatic property range" option is enabled, the gradient wwill range from the minimum value of the current property to the maximum. Otherwise, you can manually specify the property value range to use when drawing the gradient.