Particle attachments

Quite often you´ll want to "glue" part of a ObiActor (rope, cloth or softbody) to another object. This can be easily achieved by using an attachment.

To create an attachment, select the actor you want to attach and look for ObiParticleAttachment in the Add Component menu. All attachments take two inputs:

Target: Transform we want to attach the actor to.
Particle group: The particle group you want to keep attached to the target. For cloth and softbodies, you can define new particle groups in the blueprint editor. Ropes and rods automatically generate a new group for each control point in the blueprint's path.

Particles affected by more than one attachment will follow the attachment that was updated last. The update order for attachment is undefined.

It's important to realize that attachments do not move the particle group to the position of the target object, nor the target object to the position of the particle group. Moving the particle group to the target's position would collapse all particles into a single point, and would result in a kickback effect once the particles spring back to their original positions. Moving the target could cause a whole palette of issues depending on your game logic.

Instead, particles in the group are attached at their current position relative to the target object. This makes it simple to work with multiple particles, and ensures smooth attachments with no initial "jumps" or sudden motions.

If you want particles attached at a specific position other than their position at the time of creating the attachment, you can use the particles API to set their position at runtime before creating the attachment. See scripting attachments for some sample code that does this.

Static vs Dynamic

There's two types of attachment, that behave very differently: static and dynamic.

Static attachments

Static attachments entirely deactivate dynamics for the particles in the group, and drive them using the target transform instead. You can think of this as parenting the particles to the target. This is very inexpensive and ensures perfect attachments that do not drift or separate.

However, since no dynamics are involved in a static attachment -no forces, velocities or accelerations-, statically attaching an actor to a rigidbody will cause the actor to blindy follow the rigidbody's transform. The rigidbody will behave exactly in the same way it would if no actor was attached to it. The technical name for this kind of behavior is one-way coupling.

Dynamic attachments

By using dynamic attachments, you allow the particles to be fully simulated and exchange impulses with rigidbodies. This means the actor will be affected by the rigidbody's movements, and the rigidbody will in turn be affected by the actor. The technical name for this kind of behavior is two-way coupling.

Internally, dynamic attachments use pin constraints. Read the pin constraints section for a bit more info on pin constraints.

Dynamic attachments have a couple of extra parameters:

Compliance: Constraint compliance in meters/Newton. A value of zero will strive to make the attachment as rigid as possible, given the current simulation budget (timestep size and pin constraint iteration count). High values will make the attachment more flexible.
Break threshold: Maximum force (in Newtons) that the attachment can resist without breaking.

When using dynamic attachments, try make sure the mass ratio between the particles and the attached rigidbody is reasonably small. Don't pin 1 gram particles to a 100 kg rigidbody, the result will be unstable and cause stutter and jittering motions unless your timestep size is very small.

You can use dynamic attachments to suspend rigidbodies from a rope or piece of cloth or rope. You can use this to create lamps, cranes, etc.

Some actors such as ObiRod or ObiSoftbody make use of oriented particles. In this case dynamic attachments will let you constraint both particle positions and orientations.

Tips and tricks

Here's some helpful tips that will improve your understanding of attachments:

Constraining orientation

Infinite lines pass trough one point in space. However, only one line passes trough two points. In our everyday life, this means that objects held in place by just one point are free to rotate around it. However, once we attach two points the object is unable to rotate anymore:

This simple fact can be exploited to constrain the orientation of any actor, regardless of it using oriented particles (rods, softbodies) or not (ropes, cloth). For instance if you want to attach a rope to a wall, using just one attachment will allow the rope to rotate around it and may look limp. Attaching two nearby control points restricts rotation and forces the rope to meet the wall at a specific angle.

Rope attached to the wall by just one control point.

Rope attached to the wall by two control points.

The two control points attached to the wall.

The same method can be generalized and applied to cloth and softbodies too: for instance if you attach a row of particles in a square cloth, it will be free to rotate around it in a hinge-like fashion. Attaching two rows disallows rotation.

Pulling objects

A common need is to use cloth or ropes to pull an object around or at least restrict its movement (for instance a character chained up to a post). For this to work properly, the attachment(s) used between the object and the rope/cloth must be dynamic, and the object must be a rigidbody. If the attachment is static, the rope/cloth won't apply any forces to the object, and if the object is not a rigidbody, it won't be able to feel the forces applied on it by the rope/cloth.

This also has implications on the method used to allow the player to control/move the object: if you directly set its transform's position, you're essentially overwriting the results of physics simulation. So in addition to using a rigidbody, you need to move it by modifying its velocity: using AddForce, or changing rigidbody.velocity manually.

Rope untangling game, where pegs are rigidbodies using dynamic attachments moved by applying an acceleration towards the mouse cursor: once ropes are fully taut, pegs can't stretch them as the rope applies a force on the peg.

Same game, but attachments are static. Ropes don't apply any forces on the pegs, so they just stretch indefinitely. As ropes stretch, gaps open between the particles in them and they are able to pass trough each other.

Attachments inside colliders

When attaching 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 the attachment and collisions fight each other. This results in jittering and/or an undesired offset in the attachment position, because particles cannot simultaneously be inside and outside the collider. If the attachment is dynamic, results will be even worse as this setup causes a force feedback loop between the particles and the rigibody with largely undefined behavior.

Rope dynamically attached to a collider. The attachment's 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, so they "win".

The solution is to use categories and masks to filter out collisions between the pinned particle and the collider. See the collisions page for more information on how to set up collision filtering. By setting the particles and collider to different categories and disallowing collisions between them, no contacts will be generated between them and collisions will not interfere with attachments.

Collisions are filtered out and the attachment can do its job uninterrupted.