Collisions

Last update: Obi version 4.1. If you wish to see the manual page for pre-3.2 collisions, go here.

Cloth colliding with terrain and some boxes.

Most of the time, you will want your particles to be able to collide with and react to other elements in your scene: walls, floor, crates, and whatnot. They can also collide with each other! These two types of collisions (against colliders and against other particles) can be controlled independently in Obi. Everything in this section applies to all Obi actors (cloth, ropes, fluid emitters, etc) so it's a quite important topic.

Setting up colliders

Add a ObiCollider component to any collider in your scene to make it work with Obi. You can add this component to SphereColliders, MeshColliders, BoxColliders... pretty much all standard Unity colliders, both 3D and 2D. The only collider type not currently supported by Obi is PolygonCollider2D.

Sometimes you want certain actors, or even only some particles in an actor to ignore a particular collider. You can use phases for this. Each ObiCollider has a "Collision phase" property, and particles have a "Phase" channel that you can set using the particle editor. Only colliders and particles of different phases will collide. Colliders and particles of the same phase will ignore each other. By default, ObiColliders are in phase 0 and particles in phase 1, so they will collide right away.

ObiColliders also allow you to set their collision material and their thickness. Positive thickness values will leave a gap between the collider surface and colliding particles. Negative values will cause particles to "sink" into the collider before actually hitting its surface.

Rope particles colliding with a cube, from left to right: thickness = 0.1, thickness = 0, thickness = -0.05

Note that ObiCollider's thickness parameter is independent of Unity colliders' contactOffset. You can use both to independently adjust collisions with Obi actors and with other colliders.

Rigidbodies

When you add an ObiCollider component to an object, it will look for the first Rigidbody component up its hierarchy and attach an ObiRigidbody component to it. This component allows Obi particles to interact with rigidbodies. If you delete this component, Obi will recreate it automatically the next time you hit "Play".

ObiRigidbody only has one parameter: "Kinematic for particles". Enabling this shields the rigidbody from any forces applied by particles, so it will behave as if no Obi particles were present in the scene. The particles will still "feel" the rigidbody and collide with it, though.

Intercollisions

ObiActors will collide with each other if their particles have different phases, provided that they're both simulated by the same ObiSolver. Particles simulated by different solvers cannot interact with each other, which means actors in different solvers won´t be able to collide with each other.

For instance: if you wish cloth A and cloth B to collide with each other, set A's particles to phase 2, and B's particles to phase 3 (or any other phase except 2!).

Self collisions

To make an actor collide with itself, just enable the "self-collisions" checkbox in its inspector.

Collision constraints

Once you´ve set up collisions, your solver will begin generating collision constraints for particles. Obi uses a collision detection paradigm known as "speculative contacts". This means contact constraints can be generated before any actual collision has taken place between particles, or between colliders and particles. Thanks to this, collisions are accounted for before they actually happen, and tunneling issues (the well known bullet-trough-paper problem existing in most collision engines) are almost non-existant. Contacts are detected and resolved even at high speeds. Also, TOI (time of impact) ordering is not needed if several collisions happen in the same frame.

Some contacts never cease to be "speculative" and they're never actually resolved. Some others eventually progress to a real collision, and collision resolution takes place.

Several contacts can be generated for a given particle in the same frame. Then, speculative contacts must be accounted for and then resolved if they turn out to be actual collisions. However, resolving contacts sequentially (one after another) can unfortunately cause previously resolved contacts to become collisions again. See the following diagram: In step 1, two speculative contacts are generated because according to the orange particle's current velocity, it is almost certain it will collide with the grey collider in the next frame. In step 2, both speculative contacts progress to actual collisions that must be resolved. Step 3 shows how the right collision is resolved first. In step 4 we resolve the left one, but this causes penetration for the right one again. We must solve the right collision a second time (step 5) to ensure no penetration happens for either contact.

All this right, left, right, left... iterative solving causes visual jittering, as we see the particle jump between two configurations until all collisions are resolved (which can take a very high amount of iterations). For this reason, Obi lets you decide (as it does with all constraint groups) how collisions must be resolved: sequentially or in parallel. In parallel mode, all contacts are resolved independently in the same step (as if the others did not exist) and the final correction is calculated as an average of all their individual results. This increases stablity (removing jittering due to unresolved collisions) but decreases convergence speed (achieving zero-penetration takes more iterations) making collisions seem too "soft" when using low iteration counts. See the next diagram:

General rule of thumb: If multiple collisions can happen at once in your scene and jittering is an issue, set your collision constraints evaluation order to "parallel". If jittering is not a problem and/or you need faster convergence, use "sequential" evaluation order. There are separate controls for particle-particle collisions and particle-collider collisions, so you can use different methods for each of them. You can find this settings in the ObiSolver inspector, under "Particle Collision Constraint Parameters" and "Collision Constraint Parameters":

See ObiSolver for more info on sequential vs parallel solving.

Sequential and parallel contact resolution comparison, using just 3 iterations and medium friction.

Collision materials

Once a collision constraint ceases to be an speculative contact and becomes an actual contact (both objects are really in touch with each other), the collision must be resolved in some way. How is it resolved depends on what ObiCollisionMaterials you particles and colliders are using. All Obi actors (cloth, ropes, etc) have a "Material" property that lets you specify which ObiCollisionMaterial will be used by all of that actor's particles. You can also assign collision materials to ObiColliders.

ObiCollisionMaterials are assets, just like Unity's PhysicMaterials. You can right click in your project folders, and select Create->Obi->ObiCollisionMaterial. Here's the material inspector:

Dynamic friction: percentage of relative tangential velocity removed in a collision, once the static friction threshold has been surpassed and the particle is moving relative to the surface. 0 means things will slide as if made of ice, 1 will result in total loss of tangential velocity.
Static friction: percentage of relative tangential velocity removed in a collision. 0 means things will slide as if made of ice, 1 will result in total loss of tangential velocity.
Stickiness: amount of inward normal force applied between objects in a collision. 0 means no force will be applied, 1 will keep objects from separating once they collide.
Stick distance: maximum distance between objects at which sticky forces are applied. Should be kept as small as possible.
Friction combine: How is the friction coefficient calculated when the objects involved in the collision have different coefficients.
Stickiness combine: How is the stickiness coefficient calculated when the objects involved in the collision have different coefficients.
Rolling contacts: Enable this to perform full contact resolution including angular velocities (See the following section ).
Rolling friction: During a rolling contact, the amount of rolling resistance applied (See the following section). Values between 0 and 0.1 are most useful.

In the image above, the red arrow represents the particle's velocity upon collision. This velocity is split in two components: one along the contact normal, and one along the contact tangent. The blue arrow represents the force applied to the particle to cancel its normal velocity, which is always fully applied. The purple arrow is the friction force, which removes a percentage of the tangential velocity component (in the image, 100% of it). The green arrow is the stickiness force.

Heavy ball falling on a very sticky piece of cloth.

Rolling contacts

Regular contacts (both particle-particle and particle-collider) treat particles as simple positions in space, so they won't cause particles to rotate. This simplification allows for very cheap collision response, as only linear velocities are considered. However, you can choose to perform full contact resolution taking angular velocities and particle orientations into account by enabling rolling contacts in the contact material.

When two bodies with different contact materials collide, the full rolling contact equation is used if either of the contact materials have rolling contacts enabled.

Using rolling contacts only makes sense for actors that make use of particle orientations: ObiEmitter (when emitting granulars) and ObiRod. They are incompatible with ObiSoftbody, and will have no visible effect when used with ObiCloth and ObiRope.

Anisotropic (non-aspherical) particles use a simplified contact point calculation algorithm, that won't apply accurate torques when used in conjunction with rolling contacts. For this reason, as far as rolling contacts are concerned anisotropic particles behave as if perfectly spherical.

Regular contacts: angular velocities / orientations are ignored.

Rolling contacts: angular velocities / orientations are honored.

If you enable rolling contacts for a collision material, a new parameter "rolling friction" will appear. Rolling friction acts by appling a torque that opposes the angular velocity of the particles involved in a contact. In real life, perfectly spherical particles would never stop rolling on an inclined plane. However, particles with an irregular surface (such as rocks or pebbles) would stop rolling after a while, due to the unevenness of their surface. This is what rolling friction strives to simulate.

Particles in the left have higher rolling friction than the ones in the right, so they eventually stop rolling even on an inclined plane.

Shock propagation

Shock propagation is a technique that alters particle masses internally during contact resolution, so that particles at the bottom of a pile have higher effective mass that the ones at the top. This results in faster convergence and stabler stacking. You can find this parameter in the ObiSolver inspector, it is applied globally per-solver. Use this when you need an extra "oomph" for your particle-particle contacts, specially when creating piles of granular material.