Collision Layers

Groups bodies and controls which groups are allowed to collide.

Layers are world-scoped JoltLayer values backed by a symmetric 32×32 collision matrix. Every managed world starts with the Default layer, and every new pair is enabled until explicitly disabled.

High-Level API#

jolt_default_layer()
jolt_layer_create(name)
jolt_layer_set_collision(layer_a, layer_b, enabled)

body.set_layer(layer)
body.get_layer()

JoltLayer#

Creation rules#

• Call jolt_start() before creating a layer.
• A world supports at most 32 user layers including Default.
• Names must be non-empty, unique within the world, and at most 63 bytes in the native representation.
• jolt_layer_create() returns a JoltLayer or undefined.
• Layers are invalidated by jolt_stop() and cannot be reused in a new world.

Assigning a layer#

var player_layer = jolt_layer_create("Player");
var world_layer = jolt_layer_create("World");

var player = jolt_capsule_create_dynamic(0, 0, 2, 1.8, 0.4, {layer: player_layer});
player.set_layer(world_layer);
var current = player.get_layer();

A body accepts a layer at creation through options.layer or later through set_layer(). The JoltLayer must be valid and belong to the same world. Changing a non-Static body's layer activates it so broad-phase state is refreshed.

Collision matrix#

jolt_layer_set_collision(player_layer, world_layer, true);
jolt_layer_set_collision(player_layer, player_layer, false);

The matrix is symmetric: changing A↔B also changes B↔A. Self-pairs can be enabled or disabled. New layers initially collide with every active layer.

Low-Level / Advanced API#

Low-level calls use numeric handles and return numeric 1/0 or a handle. JoltLayer is the safer managed representation.

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.