Scalar and Joystick Detents
Detents capture a control near selected points and hold it with bounded effort.
set_detents(items) replaces the entire list; [] disables it. At most 256 unique points are allowed. get_detents() returns a fresh array and structs; editing them does not alter physics. get_detent() returns a zero-based input-order index, or −1 when no detent owns the motor. Enabled auto_return takes precedence; disable it for detent-only operation.
| Item | Meaning / default |
|---|---|
| Scalar point | {value, capture_range:0.05, release_range:0.10, max_force:10, frequency:12, damping:1} |
| Rotary scalar point | Same struct, but max_torque instead of max_force. value must be in 0..1. |
| Numeric shorthand | [0, 0.5, 1] uses default zones and effort. |
| Joystick point | {x, y, capture_range:0.10, release_range:0.18, max_torque:10, frequency:8, damping:1} |
capture_range and release_range are distances in canonical value space, not metres or degrees. Require release > capture > 0, effort and frequency > 0, damping ≥ 0. Joystick requires points in the unit disc; scalar value and max_force are invalid here. Duplicates, including points that coincide after native conversion, are rejected.
Example#
lever = jolt_control_lever({auto_return: false, detents: [0, 0.5, 1]});
stick = jolt_control_joystick({auto_return: false, detents: [
{x: 0, y: 0},
{x: 0.7, y: 0},
{x: -0.7, y: 0}
]});
var selected = stick.get_detent();
if (selected >= 0) show_debug_message(selected);After capture, a point remains held until the larger release area is left. A fast crossing can capture an intersected capture zone only if the current position is still inside its release area. Equal distances use input order. Getters do not advance selection; a changed list is evaluated during a physics step.
New related workflows#
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.get_detent | JoltControl.get_detent() | Bounded controls/joystick; Wheel/Crank use periodic/absolute. Array of at most256 validated points, [] disables; setter Boolean. Getter returns detached array, get_detent original-order index or -1 (also on error). |
| JoltControl.get_detents | JoltControl.get_detents() | Bounded controls/joystick; Wheel/Crank use periodic/absolute. Array of at most256 validated points, [] disables; setter Boolean. Getter returns detached array, get_detent original-order index or -1 (also on error). |
| JoltControl.set_detents | JoltControl.set_detents(items) | Bounded controls/joystick; Wheel/Crank use periodic/absolute. Array of at most256 validated points, [] disables; setter Boolean. Getter returns detached array, get_detent original-order index or -1 (also on error). |