Explosions
Configure body-local or world-space explosions and fire them explicitly.
Verified against the project sources on 19 September 2026.
Syntax#
jolt_asset_get_explosion_point(asset, point_ref);
jolt_asset_create_explosion(asset, point_ref, body);
jolt_explosion_create(x, y, z, [owner]);Factories return undefined on failure; inspect jolt_get_error() immediately. Authoring lookups return independent validated record copies. A reference is a canonical UUID or an exact, case-sensitive Key. Body owners must be live managed bodies in the current world.
World frame = current Body origin transform × authored local transform. The center of mass is not the authoring origin. Positions use metres and rotations use normalized XYZW quaternions. Refresh snapshots as the body moves.
Blender Explosion Defaults supply radius (default 5 m), directional (false) and full cone angle (90°). Local +Z is forward. set_angle() alone does not enable directionality. Runtime strength defaults to 1000 N·s. Without an owner, jolt_explosion_create uses a world-space point; with an owner it uses body-local coordinates.
Example#
// Create once, using an authored Explosion Point.
blast = jolt_asset_create_explosion(asset, "explosion_01", body_vehicle);
if (!is_undefined(blast)) {
blast.set_ignore(body_vehicle);
blast.set_radius(10);
blast.set_strength(1000);
}
// At the explosion event, BEFORE destroying the owner:
if (!is_undefined(blast)) {
var result = blast.explode();
show_debug_message(result.affected_count);
}Methods#
| API / field | Contract |
|---|---|
| blast.set_ignore(body | undefined) | Exclude one body or clear the filter; owner is not implicitly ignored. |
| blast.set_radius(r) / blast.set_strength(s) | Positive finite radius / impulse strength within runtime bounds. |
| blast.set_position(x,y,z) | Replace the complete local point, or world point without owner. |
| blast.set_rotation(x,y,z,w) / blast.set_rotation_euler(x,y,z) | Unit quaternion / Euler degrees in owner-local space. |
| blast.set_directional(value) / blast.set_angle(degrees) | Boolean mode / full angle in (0,360]. |
| blast.set_direction(x,y,z) | Nonzero direction in the point frame; normalized and enables directional mode. |
| blast.set_falloff(value) / blast.set_occlusion(value) | Linear falloff defaults true; obstacle occlusion defaults false. |
| blast.set_layers(layer_or_array | undefined) | Target layer filter; does not change which obstacles occlude. |
| blast.get_transform() / blast.is_valid() / blast.destroy() | World frame / validity / remove registered configuration. |
| blast.explode() | {affected_count, bodies, entries}; error gives an empty result and diagnostic. |
Setters return Boolean and preserve prior settings on rejection. Each explode() applies one impulse to eligible dynamic non-sensor bodies through the original explosion API. A directional cone selects targets; impulses still point radially outwards. Creation, configuration and drawing never fire an explosion. Destroy registered emitters when finished; owner destruction and jolt_stop() also clean them.
Debug#
JOLT_DEBUG_EXPLOSIONS draws live radius/cone previews. JOLT_DEBUG_SHAPE_QUERIES retains at most three recent explosion records, including world direction, angle and radius at firing time. History no longer follows the owner. Ordinary overlap history is not removed by this explosion-specific limit.
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_asset_get_explosion_point | jolt_asset_get_explosion_point(asset,explosion_point_ref) | Asset + exact key or canonical UUID. Revalidates the mutable asset and returns an independent data record, not a physics object; failure undefined and managed error. |