Distance Fields

Distance fields are a special collision primitive that can be used with Obi.

To understand why they're useful, consider this: Every time a Obi particle is near a collider, it must calculate the shortest distance to the surface of the collider to determine if it is going to collide with it or not. This calculation can take a lot of time for certain shapes, specially for MeshColliders. Distance fields precalculate and store the shortest distance to the surface of the collider for every point within their bounding box. Particles then only have to query these distance values at runtime, avoiding costly calculations.

Distance fields are similar to 3D textures. Instead of pixels, a distance field is made of nodes. Unlike textures, distance fields are adaptive. This means they have higher resolution (smaller nodes) near the surface of the object or in places where the distance changes often. This greatly reduces their memory footprint.

Front and side cutaway views of a distance field generated from a female statue. Note that the resolution is greater in areas near the surface. Red areas are inside the mesh, gray areas are outside. This distance field only takes up 636 kilobytes and has an effective resolution of 512³.

When should I use distance fields?

Use them for large and complex objects: when using MeshColliders would be too costly, or when approximating the object using primitive colliders (boxes, spheres, capsules) would be unpractical. Good examples would be a large statue covered in cloth or a particularly complex fluid container.

Benefits

Extremely cheap and accurate collision detection against large, intrincate objects.
They are more robust than MeshColliders: distance fields are solid instead of hollow. If a particle gets completely inside the distance field, it will be projected outside and recover from the missed collision.

Limitations

Distance fields only support uniform scaling. If you apply a different scale to each axis, the results will be wrong. Note however that you can still scale the object as long as the scale is the same for all axis.
They cannot be used with deformable meshes (skeletal animation, blendshapes, vertex shader-based deformations, etc).
If your object is meant to be a closed, solid object, ensure the mesh has no holes in it. If it has, collisions against the distance field may behave in unexpected ways.

How to use them

Distance fields are assets. You can create a new distance field by right-clicking on any project folder and selecting "Create->Obi->Obi Distance Field". Once you've created one, select an Input mesh, adjust the Max Error and Max Depth parameters and click Generate.

Max Error: Maximum amount of distance error tolerable. If the difference between the distance stored in a node and the actual distance is above this threshold, the node will be subdivided further to achieve greater accuracy.
Max Depth: Maximum amount of recursive subdivisions that can be performed. A node will not be subdivided more than "Max Depth" times, even if its measured error is above Max Error.

Generating a distance field can take a while, depending on your settings and the density of the mesh. Once the process is completed, you'll see a volumetric preview of your distance field, along with some statistics about it:

You're now ready to use it in your scene! pick any ObiCollider you want to use the distance field for collision detection, and assign the distance field you wish to use. That's it!.

Distance fields will only generate collisions against Obi particles. They will not collide with other objects, for this you need to use Unity's own colliders.

Note that you can combine the use of distance fields for particle collision detection with any Collider component for regular collision detection against other objects.