2026-06-10 13:21:14 -07:00
|
|
|
# Compound Shapes
|
|
|
|
|
|
|
|
|
|
A compound is a single immutable shape that aggregates many child primitives —
|
|
|
|
|
spheres, capsules, convex hulls, and triangle meshes — under one internal AABB
|
|
|
|
|
tree. To the simulation it appears as one shape, but collision queries descend
|
|
|
|
|
the internal tree and test individual children, so the cost scales with what is
|
|
|
|
|
actually touched rather than the total child count.
|
|
|
|
|
|
|
|
|
|
## Design Intent
|
|
|
|
|
|
|
|
|
|
Compounds are **static-body only** and **immutable after creation**. They are
|
|
|
|
|
not a runtime mutation primitive. The intended workflow is:
|
|
|
|
|
|
|
|
|
|
1. Author geometry offline (level mesh, terrain tile, building shell).
|
|
|
|
|
2. Bake the compound once with `b3CreateCompound`.
|
2026-10-07 14:48:58 -07:00
|
|
|
3. Write the compound bytes to disk or a streaming cache.
|
|
|
|
|
4. At runtime, load the bytes and check them with `b3ValidateCompound`, then
|
|
|
|
|
attach the compound to a static body.
|
2026-06-10 13:21:14 -07:00
|
|
|
|
|
|
|
|
This makes compounds well-suited to open-world streaming: tiles are baked
|
|
|
|
|
offline, kept in memory as flat byte buffers (which the engine uses directly
|
|
|
|
|
without copying), and attached to static bodies when a region loads, then
|
|
|
|
|
detached when it unloads.
|
|
|
|
|
|
|
|
|
|
Do not use a compound on dynamic or kinematic bodies — `b3CreateCompoundShape`
|
|
|
|
|
enforces static-only attachment.
|
|
|
|
|
|
|
|
|
|
## Building a Compound
|
|
|
|
|
|
|
|
|
|
Fill a `b3CompoundDef` with arrays of child-shape descriptors:
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
// Child type descriptors
|
|
|
|
|
b3CompoundCapsuleDef capsuleDefs[N_CAPSULES];
|
|
|
|
|
b3CompoundHullDef hullDefs[N_HULLS];
|
|
|
|
|
b3CompoundMeshDef meshDefs[N_MESHES];
|
|
|
|
|
b3CompoundSphereDef sphereDefs[N_SPHERES];
|
|
|
|
|
|
|
|
|
|
// Fill capsuleDefs[i].capsule, .material ...
|
|
|
|
|
// Fill hullDefs[i].hull, .transform, .material ...
|
|
|
|
|
// Fill meshDefs[i].meshData, .transform, .scale, .materials, .materialCount ...
|
|
|
|
|
// Fill sphereDefs[i].sphere, .material ...
|
|
|
|
|
|
|
|
|
|
b3CompoundDef def;
|
|
|
|
|
def.capsules = capsuleDefs; def.capsuleCount = N_CAPSULES;
|
|
|
|
|
def.hulls = hullDefs; def.hullCount = N_HULLS;
|
|
|
|
|
def.meshes = meshDefs; def.meshCount = N_MESHES;
|
|
|
|
|
def.spheres = sphereDefs; def.sphereCount = N_SPHERES;
|
|
|
|
|
|
|
|
|
|
b3Compound* compound = b3CreateCompound(&def);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`b3CreateCompound` clones all input data into the compound. The source arrays
|
|
|
|
|
can be freed immediately after the call.
|
|
|
|
|
|
|
|
|
|
Mesh children share the mesh pointer rather than cloning triangle data — the
|
2026-09-25 14:56:44 -07:00
|
|
|
`b3MeshData` must remain valid for the lifetime of the compound. A compound's
|
|
|
|
|
shared material table holds at most 64K unique materials.
|
2026-06-10 13:21:14 -07:00
|
|
|
|
|
|
|
|
## The b3Compound Structure
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
typedef struct b3Compound {
|
2026-10-07 14:48:58 -07:00
|
|
|
uint64_t version; // versioned against the mesh/hull formats
|
2026-06-10 13:21:14 -07:00
|
|
|
int byteCount; // total size when serialized
|
2026-10-07 14:48:58 -07:00
|
|
|
// tree offsets and counts, child arrays, material table
|
2026-06-10 13:21:14 -07:00
|
|
|
// ... (treat as opaque)
|
|
|
|
|
} b3Compound;
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`version` is a compile-time constant (`B3_COMPOUND_VERSION`) that incorporates
|
2026-10-07 14:48:58 -07:00
|
|
|
the mesh and hull format versions. A version mismatch at load time means the
|
|
|
|
|
bytes were baked with a different engine version and cannot be used.
|
2026-06-10 13:21:14 -07:00
|
|
|
|
|
|
|
|
## Serialization
|
|
|
|
|
|
2026-10-07 14:48:58 -07:00
|
|
|
A compound is a single flat blob that contains no pointers. Everything inside it
|
|
|
|
|
is addressed by byte offset from the start of the struct, so the bytes are
|
|
|
|
|
position independent. Write `compound->byteCount` bytes starting at the compound
|
|
|
|
|
address to disk. A plain `memcpy`, file read, or memory map of those bytes is a
|
|
|
|
|
valid compound, and no fixup step is needed.
|
2026-06-10 13:21:14 -07:00
|
|
|
|
2026-10-07 14:48:58 -07:00
|
|
|
Validate bytes at runtime before using them (zero-copy; bytes must remain in
|
|
|
|
|
scope and must not be modified while a shape uses them):
|
2026-06-10 13:21:14 -07:00
|
|
|
|
|
|
|
|
```c
|
2026-10-07 14:48:58 -07:00
|
|
|
const b3CompoundData* compound = b3ValidateCompound(bytes, byteCount);
|
|
|
|
|
if (compound == NULL)
|
|
|
|
|
{
|
|
|
|
|
// wrong version, wrong size, or corrupt offsets
|
|
|
|
|
}
|
2026-06-10 13:21:14 -07:00
|
|
|
```
|
|
|
|
|
|
2026-10-07 14:48:58 -07:00
|
|
|
`b3ValidateCompound` never modifies the bytes. It returns `NULL` unless the
|
|
|
|
|
version matches, `byteCount` equals the size stored in the compound, and the tree
|
|
|
|
|
node array lies fully inside the buffer. On success it returns the
|
|
|
|
|
input address. Multiple static bodies can use the same byte buffer
|
|
|
|
|
simultaneously (instancing), since the compound itself holds no per-body state.
|
2026-06-10 13:21:14 -07:00
|
|
|
|
|
|
|
|
## Attaching to a Static Body
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
b3BodyDef bodyDef = b3DefaultBodyDef();
|
|
|
|
|
bodyDef.type = b3_staticBody;
|
|
|
|
|
bodyDef.position = tileOrigin;
|
|
|
|
|
b3BodyId bodyId = b3CreateBody(worldId, &bodyDef);
|
|
|
|
|
|
|
|
|
|
b3ShapeDef shapeDef = b3DefaultShapeDef();
|
|
|
|
|
b3ShapeId shapeId = b3CreateCompoundShape(bodyId, &shapeDef, compound);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`b3CreateCompoundShape` asserts that the body is static.
|
|
|
|
|
|
|
|
|
|
## Querying a Compound
|
|
|
|
|
|
|
|
|
|
Compute the world AABB:
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
b3AABB aabb = b3ComputeCompoundAABB(compound, bodyTransform);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Query child shapes by AABB:
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
typedef bool b3CompoundQueryFcn(const b3Compound* compound, int childIndex, void* context);
|
|
|
|
|
|
|
|
|
|
b3QueryCompound(compound, queryAABB, MyChildCallback, ctx);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Access a specific child by index:
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
b3ChildShape child = b3GetCompoundChild(compound, childIndex);
|
|
|
|
|
// child.type tells you capsule / hull / mesh / sphere
|
|
|
|
|
// child.transform is the child's local transform within the compound
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Individual typed accessors are also available:
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
b3CompoundCapsule cc = b3GetCompoundCapsule(compound, i);
|
|
|
|
|
b3CompoundHull ch = b3GetCompoundHull(compound, i);
|
|
|
|
|
b3CompoundMesh cm = b3GetCompoundMesh(compound, i);
|
|
|
|
|
b3CompoundSphere cs = b3GetCompoundSphere(compound, i);
|
|
|
|
|
const b3SurfaceMaterial* mats = b3GetCompoundMaterials(compound);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Teardown
|
|
|
|
|
|
|
|
|
|
Destroy a live compound (not needed if you are using the byte-buffer path, where
|
|
|
|
|
you manage the buffer lifetime yourself):
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
b3DestroyCompound(compound);
|
|
|
|
|
```
|
|
|
|
|
|
2026-10-07 14:48:58 -07:00
|
|
|
Do not call `b3DestroyCompound` on a compound validated from bytes with
|
|
|
|
|
`b3ValidateCompound` — free the byte buffer instead.
|