box3d/docs/compound.md

158 lines
5.4 KiB
Markdown
Raw Normal View History

# 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`.
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.
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
`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
```c
typedef struct b3Compound {
uint64_t version; // versioned against the mesh/hull formats
int byteCount; // total size when serialized
// tree offsets and counts, child arrays, material table
// ... (treat as opaque)
} b3Compound;
```
`version` is a compile-time constant (`B3_COMPOUND_VERSION`) that incorporates
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.
## Serialization
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.
Validate bytes at runtime before using them (zero-copy; bytes must remain in
scope and must not be modified while a shape uses them):
```c
const b3CompoundData* compound = b3ValidateCompound(bytes, byteCount);
if (compound == NULL)
{
// wrong version, wrong size, or corrupt offsets
}
```
`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.
## 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);
```
Do not call `b3DestroyCompound` on a compound validated from bytes with
`b3ValidateCompound` — free the byte buffer instead.