Targets and Automatic Return

Automatic return is a physical position drive towards a stored target, which may differ from the default rest position.

target is a canonical value in 0..1. set_target() alone only stores the target; enable the drive with auto_return: true or set_auto_return(true). The body moves towards it physically; creation does not place the body at target.

Return effort#

Factory drive defines max_force in N for linear types or max_torque in N·m for rotary types and joystick; frequency is in Hz and damping is a damping ratio. Values must be finite and nonnegative. Higher frequency makes return stiffer; higher damping reduces oscillation. Limited effort may fail to overcome gravity, loads or resistance. Locking takes precedence over the drive.

Example#

lever = jolt_control_lever({
    auto_return: false,
    drive: {max_torque: 15, frequency: 5, damping: 1}
});
lever.set_target(0.75);
lever.set_auto_return(true);
// Release the drive later; the stored target remains.
lever.set_auto_return(false);

For Joystick, use set_target(x,y) with x²+y²≤1. Enabled return takes priority over scalar/joystick detents. Disable return to use detents alone. Setting a target while locked stores the request and takes effect after unlocking and mechanism update without teleporting.

New related workflows#

• 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.