---
title: "Decompose a mesh into convex colliders in C#"
url: https://recursiveai.org/onephysics/cookbook/decompose-mesh-into-convex-colliders/
description: "Turn a concave triangle mesh into convex collider parts in C# with OnePhysics.Tools, then raycast the solid and its empty notch."
version: "1.0.0"
---

# Decompose a mesh into convex colliders in C#

**OnePhysics** is a free, open-source physics library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePhysics.Tools) · [GitHub](https://github.com/recursive-ai-oss/onephysics-csharp) · [Docs](https://recursiveai.org/onephysics/docs/) · [Download example (.zip)](https://recursiveai.org/onephysics/cookbook/decompose-mesh-into-convex-colliders/decompose-mesh-into-convex-colliders.zip)

Convex decomposition splits a concave mesh into convex collision parts. It is an approximation: check the returned threshold flag before accepting the result.

```shell
dotnet add package RecursiveAI.OnePhysics
dotnet add package RecursiveAI.OnePhysics.Tools
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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:

```text
Hulls: 8
Threshold met: True
Solid hit: True
```

Unzip [the example](https://recursiveai.org/onephysics/cookbook/decompose-mesh-into-convex-colliders/decompose-mesh-into-convex-colliders.zip), 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.

```csharp
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)}");
```

```text
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.

```csharp
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}");
```

```text
Hulls: 1
Threshold met: False
```

## Related recipes

- [Simulate a volumetric soft body in C#](https://recursiveai.org/onephysics/cookbook/simulate-volumetric-soft-body/)
- [Create a polygon collider from a sprite outline in C#](https://recursiveai.org/onephysics/cookbook/create-collider-from-sprite-outline/)
- [Stream static collision tiles in C#](https://recursiveai.org/onephysics/cookbook/stream-static-collision-tiles/)

## 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](https://github.com/recursive-ai-oss/onephysics-csharp/blob/11dad30ed91fae25354edb55930c67cc0f71fe25/docs/spec/tools.md#3d-convex-decomposition-convexdecomposer) 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.
