5.1 KiB
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:
- Author geometry offline (level mesh, terrain tile, building shell).
- Bake the compound once with
b3CreateCompound. - Serialize it to a byte buffer with
b3ConvertCompoundToBytesand store it on disk or in a streaming cache. - At runtime, load the bytes and reconstruct the compound with
b3ConvertBytesToCompound, then attach it to a static body.
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:
// 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
b3MeshData must remain valid for the lifetime of the compound. A compound's
shared material table holds at most 64K unique materials.
The b3Compound Structure
typedef struct b3Compound {
uint64_t version; // versioned against the tree/mesh/hull formats
int byteCount; // total size when serialized
// internal tree, child arrays, material table
// ... (treat as opaque)
} b3Compound;
version is a compile-time constant (B3_COMPOUND_VERSION) that incorporates
the dynamic tree, 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.
Serialization
Convert a live compound to a self-contained byte buffer:
uint8_t* bytes = b3ConvertCompoundToBytes(compound);
// compound is now in an unusable state; its pointers have been nullified.
// Write bytes[0 .. compound->byteCount - 1] to disk.
Reconstruct from bytes at runtime (zero-copy; bytes must remain in scope):
b3Compound* compound = b3ConvertBytesToCompound(bytes, byteCount);
The bytes are mutated in place to fixup internal pointers. Multiple static bodies can use the same byte buffer simultaneously (instancing), since the compound itself holds no per-body state.
Attaching to a Static Body
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:
b3AABB aabb = b3ComputeCompoundAABB(compound, bodyTransform);
Query child shapes by AABB:
typedef bool b3CompoundQueryFcn(const b3Compound* compound, int childIndex, void* context);
b3QueryCompound(compound, queryAABB, MyChildCallback, ctx);
Access a specific child by index:
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:
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):
b3DestroyCompound(compound);
Do not call b3DestroyCompound on a compound reconstructed from bytes with
b3ConvertBytesToCompound — free the byte buffer instead.