Explosions

One-shot impulse for Dynamic rigid bodies, optionally Characters and local Soft Body vertices.

One-shot jolt_explosion applies immediately. A configured emitter applies only when explode() is called.

Syntax#

jolt_explosion(x, y, z, options=undefined)

Arguments#

Options#

Behaviour and target rules#

• Rigid: Distance is measured to the native center of mass. The impulse is applied at that center, wakes sleeping bodies and does not add artificial off-centre torque.
• Rigid: With falloff disabled, every body inside the radius receives the full impulse. Strength is impulse rather than velocity, so heavier bodies accelerate less.
• Rigid: A direction enables cone filtering. A body at exactly zero distance uses public +Z as a stable radial direction.
• Rigid: Occlusion performs one synchronous raycast per eligible candidate. Sensors do not block it, while solid Static or Kinematic level geometry can block a target even when excluded from layers.
• Rigid: Compound child hits are deduplicated by their owning native body handle.

Return value#

Example#

var result = jolt_explosion(x, y, z, {
    radius: 8,
    strength: 1200,
    falloff: true,
    occlusion: true,
    layers: [layer_dynamic],
    ignore: grenade_body
});

show_debug_message("Affected bodies: " + string(result.affected_count));

Current project integrations#

• Explosions›

Targets and local response#

The rigid branch affects only live non-sensor Dynamic bodies and applies impulse at the center of mass. Character and Soft Body targets are opt-in, default false. Soft Body response is evaluated for free vertices within radius; pinned vertices stay attached. Occlusion tests affected vertices, not one ray for an entire cloth. The same falloff, cone and filters apply.

Configured emitter#

explosion = jolt_explosion_create(0, 0, 0, grenade_body);
explosion.set_radius(5);
explosion.set_strength(800);
explosion.set_include_characters(true);
explosion.set_include_soft_bodies(true);
explosion.set_max_delta_velocity(10);
explosion.set_ignore(grenade_body);
var result = explosion.explode();
explosion.destroy();

With an owner Body, position/rotation are local; without one they are world-space. Setters return Boolean; get_transform returns a transform or undefined and explode returns a result struct even on error (empty). destroy, owner destruction or jolt_stop invalidate it. explode can be repeated while valid. set_layers accepts a live layer or layer array; one-shot options.layers additionally support a numeric mask.

Asset workflow#

explosion = jolt_asset_create_explosion(asset, "explosion", grenade_body);
if (!is_undefined(explosion)) {
    explosion.set_include_characters(true);
    explosion.set_include_soft_bodies(true);
    explosion.explode();
}

The last argument is a live created Body, not a loaded asset. Creating the body does not automatically trigger an explosion. Parameters forward to the same central function. Public names are include_characters/include_soft_bodies; affect_* are not current names.

Emitter API#

Setters return true when accepting a value and false on invalid input; read jolt_get_error() immediately. Configuration applies no force. A successful setter is not an emitter-liveness test: use requires is_valid/get_transform to succeed.

Complete API declarations#

Declarations match the production GML sources. A value after = marks an optional argument. This is a signature inventory; the guide sections describe meaning, units and limitations. The type before a dot identifies the method owner, not a global function.