jolt_start

Initializes the native Jolt runtime and creates the managed default physics world.

jolt_start() is the entry point for the high-level API. It initializes Jolt, creates one default world, installs the Default collision layer, and resets all managed registries and fixed-step timing state.

Syntax#

jolt_start([options]);

Returns#

Boolean. true after successful initialization; false if validation, initialization or world creation fails. Read jolt_get_error() immediately.

Basic setup#

// Create event of a persistent physics controller.
if (!jolt_start()) {
    var error = jolt_get_error();
    show_error(error.message, true);
}

Options#

Custom configuration#

jolt_start({
    gravity_x: 0,
    gravity_y: 0,
    gravity_z: -9.81,
    fixed_dt: 1 / 120,
    max_frame_time: 0.2,
    max_steps: 12
});

Validation and return value#

• fixed_dt and max_frame_time must be greater than 0.
• floor(max_steps) must be at least 1.
• Gravity components must convert to finite native float values.
• The function returns true after successful initialization and false when validation, native initialization, or world creation fails.
• Use jolt_get_error() for the high-level error code, message, and context.

State created by start#

• One managed default world and its safe generational handle.
• A Default JoltLayer as the first user collision layer.
• Empty body, cloth, character, shape, compound, constraint, and path registries.
• Empty collision and character-contact event lists and zero dropped-event counters.
• A zeroed time accumulator and simulation-step counter.

Runtime accessors#

jolt_is_started()
jolt_default_world()
jolt_fixed_timestep()
jolt_get_simulation_steps()
jolt_managed_body_count()

Native initialization#

The runtime registers Jolt types, allocates a 10 MiB temporary allocator, and creates a worker pool using hardware thread count minus one, with at least one worker. A failed world creation shuts the native runtime down again so no partial managed session remains.

Low-Level / Advanced API#

jolt_init()
jolt_world_create(gravity_x, gravity_y, gravity_z)
jolt_world_destroy(world)
jolt_shutdown()

The low-level API can own explicit world handles, but then your code is responsible for their entire lifecycle. jolt_shutdown() clears all native worlds. Do not destroy the managed default world behind the high-level runtime.

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.