Pin constraints

By now you know that Obi particles can be fixed in the actor's local space, so they don´t move at all relative to the actor. However if you parent the ObiCloth object to a rigidbody, all fixed particles will just mimic the rigidbody movements without exerting any forces upon it. Which means, cloth will react to the rigid body movement but the rigidbody won't react at all to the cloth.

Enter pin constraints. Pin constraints allow you to attach cloth particles to a rigidbody, stablishing a two-way energy exchange channel: particle movements will affect the rigidbody, and rigidbody movements will affect the particle.

A good example is a wind-driven ship. The sails should follow the movement of the ship, but they also have to be able to propel the ship when the wind blows. So a good idea is to attach the sails to the ship using pin constraints.

Using pin constraints to create a physically simulated sail.

Unlike most other constraint groups, pin constraints aren't usually created by the actor itself. You have to create them manually. To add a new pin constraint, select the particle (or particles) you wish to pin to a ObiCollider, and then, in the Pin Constraints component inspector, click "Add Pin Constraint". A new constraint(s) will be added to the selected particle(s). Then, you can assign a ObiCollider to each constraint.

There's only one parameter for pin constraints, and that is their offset. This is a Vector3 value, which determines the pinning position of the pinned particle in the rigidbody's local space. By default, the offset property of the pin constraint is automatically calculated to keep the relative position of particle and rigidbody at the moment of pinning. You can manually adjust this value for each pin constraint if you need.

If the offset is inside the collider's volume, make sure your collider's layer and the actor's collision group are the same to avoid collisions and pin constraints fighting each other.

Two particles pinned to a capsule.

Pin constraints and collisions

When pinning a particle very close to or inside a collider (so that they overlap), if you have collision constraints enabled you can encounter a situation in which both constraints fight each other. This results in jittering and/or an undesired offset in the pin position, because the collision and pin constraint cannot be met simultaneously.

Rope pinned to a collider. The pin constraint (shown in cyan) tries to keep the particle inside the collider, but the collision constraint tries to keep it *outside*. Collisions have higher priority than pin constraints, so they "win". The red numbers in the collider/particles are their phase values.

The solution is to use phases to filter out collisions between the pinned particle and the collider. See the collisions page for more information on how to set up collision phases. By setting the particle phase value to the same as the collider's, no contacts will be generated between them and collisions will not interfere with the pin constraint.

By setting the first two particle's phase values to the same phase as the collider's, collisions are filtered out and the pin constraint can do its job uninterrupted.