Shape Queries

Overlap Queries

The position is the centre of the query shape. Box dimensions are full sizes; capsule height is total tip-to-tip height and must exceed twice its radius. Do not pass a character's foot position as a capsule centre without adding the appropriate height offset.

jolt_overlap_box(x, y, z, width, depth, height, options=undefined)
jolt_overlap_sphere(x, y, z, radius, options=undefined)
jolt_overlap_capsule(x, y, z, height, radius, options=undefined)
jolt_overlap_shape(shape, x, y, z, options=undefined)

API	Contract
clear / overlap	Whether hits are absent/present; meaningful only when error_code is zero.
count / hits	One deepest contact per target body, bounded by the world's 4096-body capacity. No distance ordering is promised.
error_code / error_message	Zero and an empty message on success, including a valid clear result.

var r = jolt_overlap_sphere(0, 0, 2, 0.5);
if (r.error_code == 0) {
    for (var i = 0; i < r.count; ++i) {
        show_debug_message(r.hits[i].penetration_depth);
    }
}

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_overlap_box	jolt_overlap_box(x, y, z, width, depth, height, options = undefined)	Instant overlap without creating a Body, world position m. Box positive full dimensions, sphere radius>0, capsule totalheight>2radius; generic live non-static-only JoltShape. Options rotation XYZW/rotation_euler°(takes precedence), layers/mask/ignore. Returns {clear, overlap, hit, count, hits, error_code, error_message}; clear can be true on failure, so always check error_code.
jolt_overlap_capsule	jolt_overlap_capsule(x, y, z, height, radius, options = undefined)	Instant overlap without creating a Body, world position m. Box positive full dimensions, sphere radius>0, capsule totalheight>2radius; generic live non-static-only JoltShape. Options rotation XYZW/rotation_euler°(takes precedence), layers/mask/ignore. Returns {clear, overlap, hit, count, hits, error_code, error_message}; clear can be true on failure, so always check error_code.
jolt_overlap_shape	jolt_overlap_shape(shape, x, y, z, options = undefined)	Instant overlap without creating a Body, world position m. Box positive full dimensions, sphere radius>0, capsule totalheight>2radius; generic live non-static-only JoltShape. Options rotation XYZW/rotation_euler°(takes precedence), layers/mask/ignore. Returns {clear, overlap, hit, count, hits, error_code, error_message}; clear can be true on failure, so always check error_code.
jolt_overlap_sphere	jolt_overlap_sphere(x, y, z, radius, options = undefined)	Instant overlap without creating a Body, world position m. Box positive full dimensions, sphere radius>0, capsule totalheight>2radius; generic live non-static-only JoltShape. Options rotation XYZW/rotation_euler°(takes precedence), layers/mask/ignore. Returns {clear, overlap, hit, count, hits, error_code, error_message}; clear can be true on failure, so always check error_code.