Architecture

Let's take a quick look at Obi's core components and the role they play:

ObiSolver

A solver is a component that performs physics simulation. Solvers expose a few global simulation parameters such as gravity, inertia scale, or velocity damping, as well as global parameters for all constraints in the solver. Each solver will simulate all child actors it finds in its hierarchy, for this it can use multiple backends (Obi 5.5 and up only).

ObiUpdater

An updater is a component that advances the simulation of one or multiple solvers, keeping them in sync with Unity's own physics engine. Several types of updater are included with Obi to cover common use cases, but you can write your own if you need to precisely control the simulation update cycle.

ObiActorBlueprint

A blueprint is an asset that stores a bunch of particles and constraints. It does not perform any simulation or rendering by itself. It's just a data container, not unlike a texture or an audio file. Blueprints are generated from meshes (ObiCloth and ObiSoftbody), curves (ObiRope) or material definitions (ObiFluid).

ObiActor

An actor is a component that instantiates a blueprint inside a solver. All actors must be children of a solver. Multiple actors can share the same blueprint, in fact reusing the same blueprint as much as possible is encouraged. Examples of actors are a rope, a flag, a bouncy jelly, or a water emitter.

Here's a diagram showing a scene with two solvers: one simulating 3 identical cloth pieces, and another one simulating 2 identical ropes:

Each solver maintains several lists or per-particle properties: positions, velocities, radii, etc. Initially, these lists have no elements. Whenever a new actor is added to a solver, these steps take place:

• The actor asks the solver to allocate as many particles as needed by the blueprint. The solver maintains a list of free indices in its internal arrays, and will assign each particle the first free index it can find. This index becomes the particle's solver index. When removing actors from the solver, gaps will appear in the solver's internal particle arrays. Because of this, particles belonging to the same actor might not be adjacent in the solver arrays. A particle with actor index 0 (first particle in the actor's blueprint) might end up in solver index 194, if the first 194 (0-193) particle indices have been allocated.


• The actor makes a copy of all constraints found in the blueprint, and updates their particle references so that they point to the correct solver array positions.


• The number of active particles in the solver is updated.

Once an actor has been added to a solver, it is included in the simulation.