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 5123.
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.
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.
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, enable "use distance fields" and assign the distance field you wish to use. That's it!.