Convex decomposition splits a concave mesh into convex collision parts. It is an approximation: check the returned threshold flag before accepting the result.
dotnet add package RecursiveAI.OnePhysics dotnet add package RecursiveAI.OnePhysics.Tools
Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics.Physics3D; using RecursiveAI.OnePhysics.Tools; // Tetrahedron with one face dented inward. Vector3F[] points = [new(0,0,0), new(2,0,0), new(0,2,0), new(0,0,2), new(0.3f,0.3f,0.3f)]; int[] triangles = [0,2,1, 0,1,3, 0,3,2, 1,2,4, 2,3,4, 3,1,4]; var parts = ConvexDecomposer.Decompose( points, triangles, new() { MaxConcavity = 0.1f }); var world = new PhysicsWorld3D(); world.AddCompound(parts.ToCompoundParts()); Console.WriteLine($"Hulls: {parts.Hulls.Count}"); Console.WriteLine($"Threshold met: {parts.ThresholdMet}"); Console.WriteLine($"Solid hit: {world.RaycastAny( new(-1, 0.1, 0.1), new(1, 0, 0), 3)}");
Prints:
Hulls: 8 Threshold met: True Solid hit: True
Unzip the example, then dotnet run.
The full program
The snippet at the top dents one face of a tetrahedron inward, uses a concavity threshold of 0.1, and confirms that the returned parts meet it. The full program instead builds an L-shaped prism from twelve vertices, decomposes it, and casts through both an arm and its empty notch. All input geometry is defined inline.
using RecursiveAI.OneMath; using RecursiveAI.OnePhysics; using RecursiveAI.OnePhysics.Physics3D; using RecursiveAI.OnePhysics.Tools; // An L-shaped prism: six points on each end, z = 0 and 1. Vector3F[] vertices = [ new(0,0,0), new(2,0,0), new(2,1,0), new(1,1,0), new(1,2,0), new(0,2,0), new(0,0,1), new(2,0,1), new(2,1,1), new(1,1,1), new(1,2,1), new(0,2,1)]; int[] caps = [0,1,3, 1,2,3, 0,3,5, 3,4,5]; var indices = new List<int>(); for (int i = 0; i < caps.Length; i += 3) { indices.AddRange([caps[i+2], caps[i+1], caps[i]]); indices.AddRange([caps[i]+6, caps[i+1]+6, caps[i+2]+6]); } for (int i = 0; i < 6; i++) { int next = (i + 1) % 6; indices.AddRange([i, next, next+6, i, next+6, i+6]); } var result = ConvexDecomposer.Decompose(vertices, indices.ToArray(), new ConvexDecompositionOptions { Resolution = 24, MaxHulls = 8 }); var world = new PhysicsWorld3D(); world.AddCompound(result.ToCompoundParts(), type: BodyType.Static); Console.WriteLine($"Hulls: {result.Hulls.Count}"); Console.WriteLine($"Threshold met: {result.ThresholdMet}"); Console.WriteLine($"Solid hit: {world.RaycastAny( new Vector3D(0.5, 0.5, 2), new Vector3F(0, 0, -1), 3)}"); Console.WriteLine($"Notch hit: {world.RaycastAny( new Vector3D(1.5, 1.5, 2), new Vector3F(0, 0, -1), 3)}");
Hulls: 2 Threshold met: True Solid hit: True Notch hit: False
Invalid input or options throw GeometryToolException; a valid result can still have ThresholdMet set to false.
Variations
Cap the result at one hull. Append this to the full program. It returns a collider, but the requested concavity threshold is not met.
var coarse = ConvexDecomposer.Decompose(vertices, indices.ToArray(), new ConvexDecompositionOptions { MaxHulls = 1, Resolution = 24 }); Console.WriteLine($"Hulls: {coarse.Hulls.Count}"); Console.WriteLine($"Threshold met: {coarse.ThresholdMet}");
Hulls: 1 Threshold met: False
Related recipes
- Simulate a volumetric soft body in C#
- Create a polygon collider from a sprite outline in C#
- Stream static collision tiles in C#
The short answer
Call ConvexDecomposer.Decompose from RecursiveAI.OnePhysics.Tools, then pass ToCompoundParts() to PhysicsWorld3D.AddCompound. The returned convex hulls become children of one rigid body. Check ThresholdMet: producing a set of hulls is not the same as meeting the requested approximation quality.
The full example uses a closed L-shaped prism. A ray through an arm hits; a ray through the notch misses. That distinction is the reason to decompose rather than replacing the entire concave model with one convex hull.
How do you use convex decomposition in C#?
Supply vertex coordinates and triangle indices. The full program spells out both end caps and the six side walls of its prism; it does not load an external model or depend on an editor. The tools package performs the authoring operation, and the main physics package builds and queries the resulting body.
ToCompoundParts() keeps the decomposition as parts of one body. For a moving object, use a dynamic compound as the snippet at the top does. For the stationary query example, use BodyType.Static. Creating a separate dynamic body for every hull would describe independent objects, not one rigid concave object.
Run decomposition when authoring or loading geometry, then retain the resulting collision representation. It is geometry processing, not an operation that must be repeated on every simulation step. The authoring-tool specification describes how the mesh is cleaned, voxelized and split.
Can a convex mesh collider match a concave mesh exactly?
A single convex hull cannot preserve an inward notch. Multiple hulls can preserve useful concavities, but this decomposer is approximate. Its voxel grid limits the smallest feature it finds to about one cell. Increasing Resolution changes that sampling; it is not a promise of exact correspondence to every source triangle.
The default options permit sixteen hulls, use a concavity threshold of 0.01 and cap each hull at sixty-four vertices. The full example explicitly selects a resolution and hull budget rather than relying on all defaults. Judge the settings with collision queries at the openings your application needs, not just with the hull count.
ThresholdMet is false when a remaining part exceeds the concavity threshold. This can happen when the hull budget is exhausted or no valid split remains. The one-hull variation demonstrates a valid return value that is unsuitable if preserving the L’s notch is required. Do not silently treat that flag as success.
What algorithm does convex decomposition use?
The documented implementation cleans the mesh, classifies a voxel grid, and repeatedly splits the worst concave part. It builds convex hulls from the resulting parts and simplifies hulls exceeding the vertex limit. The returned hulls are ordered by creation, and the documented tie-breaking rules make the result independent of thread count.
Inputs must contain triangles with valid indices and finite coordinates. The specification allows at most 2^24 vertices and triangles, with coordinate magnitudes at most 2^21. Decomposition rejects a mesh when cleaning leaves no triangles or when its smallest bounding-box extent is below 10^-5 of its largest. A flat drawing is therefore not a substitute for a 3D solid: use polygon decomposition for a 2D outline.