Utility Scripts · Physical Controls

Lifecycle, Errors and Diagnostics

Correct ownership, error handling and a few diagnostic checks keep controls safe when their machinery is removed.

Item	Meaning / default
control.destroy()	Removes its moving body, mechanism, resistance and Fixed. Does not destroy the parent. Repeated calls are safe.
Destroying the parent / body / main constraint	Cascades into invalidation and removal of the whole control.
jolt_stop()	Stops the managed world and invalidates its resources.
control.is_valid()	Checks current validity, not merely whether the GML struct exists.
control.data / control.body.data	Two separate gameplay structs; control data is not automatically copied onto the body.

Example#

control = jolt_control_wheel();
if (is_undefined(control)) {
    var error = jolt_get_error();
    show_debug_message(error.context + ": " + error.message);
    exit;
}
if (!control.set_phase_motor({phase: 0.25})) {
    show_debug_message(jolt_get_error().message);
}
// Before later use, if the parent may have been removed:
if (control.is_valid()) {
    var pose = control.get_transform();
}

Factories return undefined on error, setters true/false. Numeric and configuration getters generally return undefined on error; booleans return false and get_detent() returns −1. Sentinels may also have normal meanings, so read the error immediately when a result is unexpected. Another API call may replace it.

When behaviour is unexpected#

Item	Meaning / default
The control does not return	Check auto_return and sufficient drive effort; Button defaults to false.
A detent does not engage	Disable return or a higher priority; check units and the capture area.
Motor enabled but not moving	Read active/mode, locking and captured detents; then check torque and load.
Moves the wrong way	Button/Slider travel along −Z, Pull Handle along +Z. Output inversion only reverses the number.
Graphics drift	Use moving get_transform(), the correct mesh origin and the full quaternion.
Wheel/Crank step error	Check timestep and angular bounds in Angle, Turns, Phase and Zero.

// Create
jolt_debug_enable(true);
// Draw End
jolt_debug_draw(JOLT_DEBUG_SHAPES | JOLT_DEBUG_CONSTRAINTS | JOLT_DEBUG_CENTER_OF_MASS);

Mouse interaction with controls

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
JoltControl.destroy	JoltControl.destroy()	is_valid Boolean checks native and can invalidate the wrapper; destroy Boolean idempotently removes the owned mechanism (body and constraint), not the parent.
JoltControl.is_valid	JoltControl.is_valid()	is_valid Boolean checks native and can invalidate the wrapper; destroy Boolean idempotently removes the owned mechanism (body and constraint), not the parent.

Lifecycle, Errors and Diagnostics

Example#

When behaviour is unexpected#

New related workflows#

Verified operation contracts#