Bodies

Compound Shapes

Combines locally transformed child shapes into one JoltBody.

Children share velocity, motion type, layer, sensor state, mass, and body handle. Unlike separate bodies connected by Fixed Constraints, a Compound is one indivisible rigid shape and is usually simpler and cheaper for a fixed composite object.

Builder#

var compound = jolt_compound();

An active jolt_start() is required. It returns a JoltCompound builder, not a JoltBody, and accepts 1..64 child shapes.

Supported children#

compound.add_box(local_x, local_y, local_z,
                 width, depth, height, rotation=undefined)
compound.add_sphere(local_x, local_y, local_z,
                    radius, rotation=undefined)
compound.add_capsule(local_x, local_y, local_z,
                     height, radius, rotation=undefined)
compound.add_cylinder(local_x, local_y, local_z,
                      height, radius, rotation=undefined)
compound.add_tapered_capsule(local_x, local_y, local_z,
    height, top_radius, bottom_radius, rotation=undefined)
compound.add_tapered_cylinder(local_x, local_y, local_z,
    height, top_radius, bottom_radius, rotation=undefined)
compound.add_convex(local_x, local_y, local_z, points, rotation=undefined)
compound.add_mesh(local_x, local_y, local_z, vertices, indices, rotation=undefined)
compound.add_heightfield(local_x, local_y, local_z, heights, width, height,
    cell_size, cell_size_y=undefined, rotation=undefined)
compound.add_plane(local_x, local_y, local_z, normal_x, normal_y, normal_z,
    half_extent=1000, rotation=undefined)
compound.add_shape(jolt_shape, local_x, local_y, local_z, rotation=undefined)

local_x/y/z are child centres relative to the compound origin. Dimensions match standalone creators. rotation accepts a quaternion or Euler degrees. add_shape accepts a live reusable JoltShape from the same world; Native retains its own ShapeRefC, so the source handle can be destroyed safely.

Creating the body#

compound.create_dynamic(x, y, z, options=undefined)
compound.create_static(x, y, z, options=undefined)
compound.create_kinematic(x, y, z, options=undefined)

x,y,z is the world origin and child transforms compose with the body transform. Convex children support Dynamic/Static/Kinematic; Mesh, HeightField, and Plane support Static only. The builder is reusable and created bodies remain valid after builder/source-shape destruction.

Properties, collisions, and debug#

mass recalculates mass and inertia for the full Dynamic compound. Layer, sensor, friction, and user_data are shared; there are no child-specific public values. Contacts and raycasts return the resulting JoltBody handle, not a child object or ID. Debug draw composes the body and each stored child transform.

Low-Level / Advanced API#

jolt_world_compound_create(world)
jolt_world_compound_destroy(world, compound_handle)
jolt_world_compound_add_child(world, compound_handle, shape_type,
    size_x, size_y, size_z, local_x, local_y, local_z,
    qx, qy, qz, qw)
jolt_world_compound_add_shape(world, compound_handle, shape_handle,
    local_x, local_y, local_z, qx, qy, qz, qw)
jolt_world_compound_body_create(world, compound_handle, motion_type,
    x, y, z, qx=0, qy=0, qz=0, qw=1)

shape_type is BOX, SPHERE, CAPSULE, or CYLINDER.
Box size_x/y/z are native half extents.
Sphere size_x is radius.
Capsule size_x is straight-section half height and size_y is radius.
Cylinder size_x is half height and size_y is radius.
Low-level functions return numeric handles or 1/0, not JoltCompound/JoltBody.

Example#

var shape = jolt_compound();
shape.add_box(0, 0, 0, 2.4, 0.8, 0.6, {x:0, y:0, z:12});
shape.add_sphere(1.35, 0, 0.45, 0.55);

var body = shape.create_dynamic(0, 0, 5, {mass:2.5, friction:0.6});

// The body stays valid after its builder is destroyed.
shape.destroy();

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.

Symbol / owner	Signature	Operation contract
jolt_compound	jolt_compound()	Creates an empty JoltCompound builder in managed world, undefined on error. Builder is not yet a body; add children and use create_*.
JoltCompound._add	JoltCompound._add(shape, shape_type, x, y, z, size_x, size_y, size_z, dimensions, rotation)	Implementation helper, not recommended application syntax. _add transports primitive dimensions and records child metadata; _add_owned_shape adds a temporary resource and always releases it, preserving failure diagnostics. Boolean result.
JoltCompound._add_owned_shape	JoltCompound._add_owned_shape(shape, x, y, z, rotation, context)	Implementation helper, not recommended application syntax. _add transports primitive dimensions and records child metadata; _add_owned_shape adds a temporary resource and always releases it, preserving failure diagnostics. Boolean result.
JoltCompound._create	JoltCompound._create(motion, x, y, z, options)	JoltBody/undefined from a nonempty builder, XYZ defaults 0, Body options/COM offset. Children snapshot; options failure removes the new body. _create is an implementation delegate; prefer motion-specific create_*.
JoltCompound.add_box	JoltCompound.add_box(x, y, z, width, depth, height, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_capsule	JoltCompound.add_capsule(x, y, z, height, radius, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_convex	JoltCompound.add_convex(x, y, z, points, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_cylinder	JoltCompound.add_cylinder(x, y, z, height, radius, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_heightfield	JoltCompound.add_heightfield(x, y, z, heights, width, height, cell_size, cell_size_y = undefined, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_mesh	JoltCompound.add_mesh(x, y, z, vertices, indices, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_plane	JoltCompound.add_plane(x, y, z, normal_x, normal_y, normal_z, half_extent = 1000, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_shape	JoltCompound.add_shape(shape, x, y, z, rotation = undefined)	Boolean; live same-world JoltShape, local XYZ m and optional quaternion/Euler° struct. Native retains its own reference; source shape can then be destroyed.
JoltCompound.add_sphere	JoltCompound.add_sphere(x, y, z, radius, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_tapered_capsule	JoltCompound.add_tapered_capsule(x, y, z, height, top_radius, bottom_radius, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.add_tapered_cylinder	JoltCompound.add_tapered_cylinder(x, y, z, height, top_radius, bottom_radius, rotation = undefined)	Boolean addition of a child at local XYZ m with optional XYZW or XYZ° rotation. Dimensions/data and validation match corresponding jolt_shape_* (box full dimensions). Mesh/Heightfield/Plane make the entire compound Static-only. Does not modify previously created bodies.
JoltCompound.create_dynamic	JoltCompound.create_dynamic(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined from a nonempty builder, XYZ defaults 0, Body options/COM offset. Children snapshot; options failure removes the new body. _create is an implementation delegate; prefer motion-specific create_*.
JoltCompound.create_kinematic	JoltCompound.create_kinematic(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined from a nonempty builder, XYZ defaults 0, Body options/COM offset. Children snapshot; options failure removes the new body. _create is an implementation delegate; prefer motion-specific create_*.
JoltCompound.create_static	JoltCompound.create_static(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined from a nonempty builder, XYZ defaults 0, Body options/COM offset. Children snapshot; options failure removes the new body. _create is an implementation delegate; prefer motion-specific create_*.
JoltCompound.destroy	JoltCompound.destroy()	Boolean wrapper/world validity, handle or0; destroy Boolean idempotently destroys builder, not previously created bodies.
JoltCompound.get_native_handle	JoltCompound.get_native_handle()	Boolean wrapper/world validity, handle or0; destroy Boolean idempotently destroys builder, not previously created bodies.
JoltCompound.is_valid	JoltCompound.is_valid()	Boolean wrapper/world validity, handle or0; destroy Boolean idempotently destroys builder, not previously created bodies.