JoltPhysics - Documentation
‹›
Introduction

Your First Physics Scene

Creates a floor and a falling box using the managed high-level API.

The smallest useful scene needs one controller object. Its Create event starts physics and creates bodies, its Step event advances the world, and its Cleanup event stops the runtime.

1. Create a controller object#

Add one object such as obj_physics_controller to the room. Keep exactly one active owner of the managed world.

2. Create event#

GML
if (!jolt_start()) {
    var error = jolt_get_error();
    show_error(error.message, true);
}

ground = jolt_box_create_static(0, 0, -0.5, 20, 20, 1);
box = jolt_box_create_dynamic(0, 0, 5, 1, 1, 1, {
    mass: 1,
    friction: 0.4,
    restitution: 0.1
});

The ground is centered at Z=-0.5 and has a full height of 1, placing its top surface at Z=0. The Dynamic Box starts above it and falls under the default negative-Z gravity.

3. Step event#

GML
var steps = jolt_update();
if (steps < 0) {
    show_debug_message(jolt_get_error().message);
}

var transform = box.get_transform();
if (!is_undefined(transform)) {
    // Use transform.position and transform.rotation for rendering.
}

4. Cleanup event#

GML
jolt_stop();

Optional debug drawing#

GML
// Create event, after jolt_start()
jolt_debug_enable(true);

// Draw event
jolt_debug_draw();

What happens#

  • jolt_start() creates the default world with gravity {0,0,-9.81}.
  • jolt_box_create_static() creates an immovable floor using full dimensions.
  • jolt_box_create_dynamic() creates a Dynamic body by default.
  • jolt_update() performs the required fixed simulation steps.
  • get_transform() reads the current world-space origin and quaternion.
  • jolt_stop() invalidates the bodies and destroys the world.

Next steps#

After this example works, add body-instance binding, collision layers, contact events, raycasts, and more advanced shapes through their dedicated sections.