Convex decomposition

Convex decomposition splits a concave mesh into several convex pieces that together approximate its shape. Physics engines collide convex shapes far more cheaply than arbitrary triangle meshes, so decomposition is how an archway, a chair or a broken wall gets collision that is both fast and fairly accurate.

The V-HACD library describes the problem: one convex hull approximates a concave shape poorly and causes false collisions, while a set of "near" convex parts gives a much better fit and stays fast enough for real time (GitHub: V-HACD: Volumetric Hierarchical Approximate…).

#How it works

Every method follows the same idea: cut the mesh into parts, wrap each part in a convex hull, and stop when the hulls fit closely enough. The settings decide how many parts you get and how tightly each one fits.

Three stone arches. Left, one orange hull covers the whole arch and fills the opening. Centre, three orange pieces follow the arch with some overhang into the opening. Right, seven thinner pieces follow the arch closely. — More pieces, tighter fit. Each piece is the convex hull of one slice of the arch, so it bridges the inner curve with a straight edge; thinner slices leave less overhang into the opening.Diagram by the handbook author

The arch shows the trade-off. One hull blocks the doorway. Three hulls open it, but each still bulges a little into the opening. Seven hulls follow the curve closely, at more than twice the cost of three. Most automatic tools let you choose a point on this curve with two kinds of setting: a limit on the number of hulls and a tolerance for how concave a piece may be before it is split again.

#The tools

Tool	Where	Main settings	Notes
V-HACD	Open-source library (GitHub)	Maximum hull count (default 32)	Its author calls the default 32 hulls "often way too high"; the project is archived and recommends CoACD
CoACD	Open-source (MIT), Python via `pip install coacd`, C++ and a Unity package (GitHub)	Concavity threshold (default 0.05, range 0.01–1), optional maximum hull count, preprocessing resolution, optional vertex limit per hull	SIGGRAPH 2022 research; aims to keep the input's collision behaviour with fewer parts
Unreal Engine	Static Mesh Editor, Auto Convex Collision (Epic Developer Community documentation)	Hull Count, Max Hull Verts, Hull Precision (number of voxels)	"The higher these values, the more precise your collision mesh will be, but also the more complex"
Godot	Import dock, Physics, Shape Type: Decompose Convex (Godot Engine documentation); or the `-convcolonly` suffix (Godot Engine documentation)	A Precision preset, or Advanced options	Higher precision means slower generation and more CPU cost during simulation
Unity	Mesh Collider with Convex ticked (Unity Manual); CoACD's Unity package for multiple pieces (GitHub)	—	Convex mesh colliders are "limited to 255 triangles"

CoACD's threshold works the other way round from a hull count: a higher threshold gives a coarser result (GitHub: CoACD: Approximate Convex Decomposition for…). Since April 2026 it can also read the threshold in metres, which makes values easier to reason about across assets of different sizes (GitHub: CoACD: Approximate Convex Decomposition for…).

The first step of a comparison in Epic's Auto Convex Collision how-to, at the tool's default settings. Compare how closely the hulls follow the mesh with the maximum-settings result below.Epic Games, Unreal Engine documentation Always load external media on this site

The same mesh after raising the Auto Convex Collision values to the maximum the tool allows. The hulls follow the shape more closely; Epic notes that higher values give more precise but also more complex collision (Epic Developer Community documentation: Setting Up Collisions With Static Meshes in…).Epic Games, Unreal Engine documentation Always load external media on this site

Different viewsAutomatic decomposition or hand-made pieces?

Automatic tools are improving and save time. CoACD's authors designed their method to preserve collision behaviour with fewer components (GitHub: CoACD: Approximate Convex Decomposition for…), and Epic's own chair example ends with Auto Convex Collision after primitives fail (Epic Developer Community documentation: Setting Up Collisions With Static Meshes in…). For hundreds of props, building hulls by hand for each one is rarely practical.

Automatic results need checking. Epic's FBX pipeline documentation warns that "Breaking up a non-convex mesh into convex primitives is a complex operation, and can give unpredictable results" (Epic Developer Community documentation: FBX Static Mesh Pipeline in Unreal Engine). V-HACD's author says the default hull count is "often way too high" (GitHub: V-HACD: Volumetric Hierarchical Approximate…), so accepting defaults can waste performance.

In practice: decompose automatically for physics props and background clutter, then inspect the result. Build pieces by hand, as UCX_ meshes in Unreal (see collision meshes), for doorways, stairs and anything the player walks through or climbs. The convex hull page compares the two approaches on a single prop.

#Common mistakes

Accepting the default hull count. Start low and raise it only where the fit fails (GitHub: V-HACD: Volumetric Hierarchical Approximate…).
Decomposing what a box would cover. A crate or a wall needs one box, not twelve hulls; see collision meshes.
Feeding in broken meshes. CoACD preprocesses meshes to make them manifold before decomposing (GitHub: CoACD: Approximate Convex Decomposition for…), a hint that holes and loose parts confuse these tools. Clean the input first; see manifold and non-manifold geometry.
Ignoring engine limits. Unity's convex colliders stop at 255 triangles (Unity Manual: Mesh collider component reference), so simplify dense pieces.
Never looking at the result. Always open the collision view and walk the player capsule through.

convex hull · collision meshes · player collision capsule · manifold and non-manifold geometry · decimation

#Further reading and watching

CoACD on GitHub

the current open-source decomposition tool, with parameters explained and links to the SIGGRAPH 2022 paper. Advanced, free.

WebAdvancedFree

V-HACD on GitHub

the older, widely integrated library, with a clear explanation of why decomposition is more accurate than a single hull. Advanced, free.

WebAdvancedFree

Epic: Setting Up Collisions With Static Meshes

K-DOP and Auto Convex Collision on a worked chair example. Beginner, free.

DocsBeginnerFree

Godot: Advanced Import Settings

collision shape types and decomposition precision in the import dock. Beginner, free.

DocsBeginnerFree

References

Khaled Mamou and contributors · V-HACD: Volumetric Hierarchical Approximate Convex Decomposition · GitHub · tool · accessed 2026-10-21

Xinyue Wei, Minghua Liu, Zhan Ling and Hao Su · CoACD: Approximate Convex Decomposition for 3D Meshes with Collision-Aware Concavity and Tree Search · GitHub (paper in ACM Transactions on Graphics 41(4), 2022), 2022 · tool · accessed 2026-10-21

Epic Games · Setting Up Collisions With Static Meshes in Unreal Engine · Epic Developer Community documentation, 2026 · docs · accessed 2026-10-21

Godot Engine contributors · Advanced Import Settings · Godot Engine documentation (source on GitHub), 2026 · docs · accessed 2026-10-21

Godot Engine contributors · Node type customization using name suffixes · Godot Engine documentation (source on GitHub), 2026 · docs · accessed 2026-10-21

Unity Technologies · Mesh collider component reference · Unity Manual, 2026 · docs · accessed 2026-10-21

Epic Games · FBX Static Mesh Pipeline in Unreal Engine · Epic Developer Community documentation, 2026 · docs · accessed 2026-10-21

Also consulted