BBMOD collision integration

Build reusable static mesh collision from BBMOD geometry; use Blender-authored assets for movable bodies.

Verified against the project sources on 19 September 2026.

Syntax#

jolt_shape_mesh_from_bbmod(model, [options], [cache_key]);

Load a BBMOD_Model, start Jolt and extract collision BEFORE model.freeze(). Readable triangle-list buffers and a valid static node hierarchy are required; skeletal/bone data and animated poses are unsupported. The adapter never changes or destroys the source model.

Example#

// Loading phase, after jolt_start():
var model = new BBMOD_Model("level.bbmod");
var collision = jolt_shape_mesh_from_bbmod(model);
if (is_undefined(collision)) {
    show_debug_message(jolt_get_error().message);
} else {
    model.freeze();
    var body = collision.create_static(0, 0, 0);
    // Keep model, collision and body for rendering/reuse.
    // Later: body.destroy(); collision.destroy(); model.destroy();
}

Transforms, caching and lifetime#

Geometry is transformed mesh-local → accumulated node transforms → scale → transform → shape-local; body placement is applied afterwards. There is no additional axis swap. Reflections correct winding automatically; singular transforms are rejected. Static extraction permits 3–65536 unique positions and 1–131072 triangles. Source triangle numbers are not stable native hit IDs.

cache_key identifies the model content revision (up to 198 non-NUL ASCII characters); geometry is not hashed on lookup, so change the key after edits. Options are included in the cache identity. Cache hits can reuse geometry after freezing; misses cannot read frozen buffers. Shapes own copied geometry and remain independent of the visual model. Failures expose jolt_get_error().

Movable bodies#

Author collision shapes in the Blender Asset Editor and create bodies with jolt_asset_create_body(asset, motion, options). You can also assemble a jolt_compound() manually. Automatic model decomposition is not supported.

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.