This page has been translated automatically.
Setting Up Development Environment
High-Level Systems
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
Double Precision Coordinates
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Cloth Body

Cloth body enables physical simulation of textiles, clothing and foliage, as well as sheets of any soft material. It is possible to pin cloth to any body so it would hang like a cape or curtains, and tear it to pieces. Cloth greatly enhances the appearance of dressed characters (otherwise entirely animated) and saves the time of game artists. However, simulation of this type of body is quite costly and it is strongly recommended to use distance optimizations to avoid performance hits.

Cloth body can be assigned only to dynamic mesh objects.

See also

Mesh Requirements

In most cases, it is important that polygon triangulation of the mesh, for which cloth body is generated, is as illustrated! Otherwise, it may not stretch properly and evenly in all directions.

Required mesh triangulation

For example, in 3ds Max mesh topology needs to be edited manually: choose Modify panel > Selection > Edit Edges rollout and click Turn to turn the triangles in a poly.

Mass-Spring Simulation Model

A cloth body is modeled as set of particles in the mesh vertices. Each particle is represented with a sphere shape and is linked together with other particles by inner spring joints that are located along the edges of a cloth mesh. Cloth joints allow to recreate mesh topology, on the one hand, and constrain cloth stretching and folding, on the other.

Particles are characterized by a position, mass and velocity. The total mass of the whole cloth is distributed among them. Particles can be acted upon by a force or an impulse.

Self-collision of the particles and collisions between different cloth bodies are not calculated. However, the cloth can fully interact with environment by colliding with other physical bodies if Collision box is checked. By contact, its behaviour is controlled by such parameters as friction and restitution. It can also selectively participate in physical interaction owing to masks.

Particle Radius

As it was already mentioned, each particle is a sphere with a set radius. That brings the following:

  • Cloth particles use continuous collision detection, so higher values are preferable for more robust behaviour. Collisions between the particles are not calculated and should not be considered when setting a radius. Be careful, however, as particles too big in diameter can provide incorrect interaction with environment (twitching or blowing up of the cloth). Too low radius results in poor collision handling.
  • As cloth particles are approximated with spheres, the cloth never lies flat on the ground or tightly adheres to the surfaces. There is always some gap that corresponds in size to set radius.

An object can fly through the cloth, when the particle radius is small and the cloth is stretched. The reason is that continuous collision detection is performed only for particle spheres located in vertices of cloth mesh.

Joints Solver Iterations

The number of iterations allow to control the accuracy of the solution of cloth inner joints. For example, it may help to avoid twitching of cloth.

  • The minimum value of 1 means the joints are solved once per physics frame. Solving is performed in a random order to provide more predictable stretching results.
  • Low number of iterations results in faster simulation. At the same time, it is more prone to stretching and gives cloth more elastic appearance.
  • The higher the iteration count, the more accurately constrains are solved and the stiffer the simulated cloth is. Increased number of iterations is considerably expensive and at some point ceases to bring a noticeable benefit of increased accuracy, so it is reasonable to remain within cost-effectiveness limit.

Stretching and Folding

A cloth may be deformed by stretching and folding. These deformations are controlled with joint constraints of two types: linear restitution and angular restitution. With these types of constraints, it is possible to obtain the desired look and feel of the cloth and simulate a variety of different deformable materials ranging from a stiff carton to soft lycra.

Linear Restitution

Linear restitution determines how far the cloth particles can be stretched apart from each other. It enforces cloth joints to restore the distance that was between the vertices of the original mesh:

  • By the maximum value of 1, the particles spring back with great force and the cloth is hard to stretch. It gives the effect of stiff non-stretch cloth, e.g. linen or tweed.
  • The lower the value, the more easily the particles are moved away from each other and the more stretchable and elastic the cloth is. For example, nylon or spandex.
  • 0 and near zero values are not allowed because they cause unstable simulation and blowing up of the cloth.

Angular Restitution

Angular restitution determines the possible angle between cloth triangles that are formed by particles. It constrains the folding of the cloth by enforcing joints to keep the angle that was between triangles of the original mesh:

  • By the maximum value of 1, the angles tend to be retained and the cloth resists folding. The cloth appears to be stiff and wrinkle-free (for example, paper). Be careful, however, the maximum value may provide unsteady behaviour.
  • By the minimum value of 0, the cloth can be easily folded and bent in any direction, regardless of the original topology of the mesh.

If the cloth is too stretchy and rubbery, try one of the following:
  • Set linear restitution to 1.
  • Increase the number of joints solver iterations.
  • Use the mesh with fewer vertices.

Rigidity of Motion

Rigidity parameter allows to additionally constrain motion of the cloth so it would be more stiff and inflexible. For that purpose, linear and angular velocities of each of the particle in a cloth are corrected according to the total velocities interpolated for all the particles.

  • By the minimum value of 0, all cloth particles move independently and the cloth is elastic, flexible and easily deformable.
  • By the maximum value of 1, particles movement is uniform and steady. As a result, the cloth is stiffer and less prone to deformation.


When the cloth is stretched beyond its elastic limit or folded, it tears and shreds into pieces. Tearing is caused by applying the force or collision with a physical body, and depends on the cloth stiffness (controlled by linear and angular restitution parameters). For example, imagine the cannonball hitting the sail and leaving the hole in it. The cloth is torn only along the edges of cloth triangles, splitting mesh vertices and duplicating particles.

If torn pieces of cloth fall onto one plane, they cause z-fighting.

Linear Threshold Distance

Linear threshold sets the distance limit for stretching the cloth. When two particles move away from each other further than this limit, joints that connect them break and the tear appears.

  • If set to infinity (inf), the cloth is stretched without tearing.

Angular Threshold Angle

Same as linear threshold, angular threshold represents a maximum angle to fold the cloth relative to its initial state. If cloth triangles are bent any further, the joint break and triangles are separated along the adjacent edge.

  • It is reasonable to set the angular threshold no higher than 180 degrees.
  • If set to infinity (inf), the cloth is folded without tearing.

Attaching the Cloth

I'm Batman!

Cloth attached to animated character

The cloth can be attached to other physical bodies using the dedicated pin joint. In case of rigid bodies (either static or dynamic) and dummy bodies, pinned particles stay fixed in their position and follow transformations of attached objects pulling the cloth with it.

To ensure stable simulation it is important to set appropriate masses of the cloth and the attached body. Unbalanced masses may cause twitching of cloth joints.

Attachment to Skinned Mesh

Convincing simulation of the clothing on a skinned character requires a different approach. To follow bones transformations, each vertex of the cloth that is found in the pin joint area is mapped to the nearest skinned mesh vertex (up to the distance specified by the Threshold parameter). However, it is not recommended to attach the cloth directly to the skinned character, because difference in topologies may result in visual artifacts. Instead of it, it is better to create an identical cloth surface on the skinned mesh character, make it invisible and attach a physical cloth to it.

For example, we need to create a cape that is glued to the shoulders of skinned character while the rest flaps and folds loosely. It is done in the following steps:

  1. When creating a skinned mesh, add a cape surface identical to the cape that the character would wear. It can be either a whole cape, or only its clipped part that needs to be pinned. The latter is preferable when complex clothing is simulated, which requires more flexible control over which parts to simulate physically and which ones to move with skinned character. In our case, it's cloth part over the shoulders.
  2. Add skinned mesh that has a rag doll body assigned. Take notice, the cape surface should be enabled.
  3. Add a separate dynamic cloth mesh and synchronize its position with skinned character. Turn off physical simulation and assign cloth body.
  4. Pin cloth body to rag doll body. If the Threshold distance is set low enough, the physical cape will be automatically pinned only to the cape surface (i.e. shoulders). After that, the cape surface is simply disabled and does not provide any load at all.

Distance of simulation

To improve performance and avoid the excessive load, simulation of the cloth can be limited to the specified distance. When the player is out of this area, the cloth stops to be updated and freezes statically. Pin joints also become inactive and cease to attach pinned bodies.

  • If set to infinity (inf), there is no distant-dependent optimization for cloth.

If distant-dependent optimization is used, cloth body should be attached only to static bodies. Otherwise, it may cause visually incorrect behaviour, such as cloth cloak hanging in the air or attached bodies fall loose due to gravity. In case of attaching dynamic objects, use Physics distance.
Last update: 2017-07-03
Build: ()