Physical Scale

Creates a real physics load-cell platform and measures the load carried by its fixed support.

jolt_scale_create creates an owned Dynamic box platform and fixes it to the world with an internal Fixed Constraint. After each completed physics step, the helper reads the constraint's solved linear reaction impulse, projects it onto a chosen load axis and divides by the fixed timestep to obtain force. It is not an overlap query and it does not add the masses of touching bodies.

Physical principle#

objects and applied forces
        ↓
Dynamic box platform
        ↓
Fixed Constraint reaction
        ↓
force along load direction

• The platform is Dynamic so ordinary Jolt contacts and friction can transfer forces into it.
• The internal Fixed Constraint holds the platform at its creation pose and carries the applied load into the fixed world.
• The solver's accumulated linear impulse is divided by physics-step time, producing force in newtons when the project uses consistent metre-kilogram-second units.
• Only the non-negative component along direction is reported. A force acting against the selected positive load axis is clamped to zero.
• The platform's own theoretical gravity load is subtracted automatically, so a newly created empty scale begins close to zero.

Syntax#

scale = jolt_scale_create(-6.5, -3.1, 0.3, 3.0, 1.8, 0.05);
scale.set_smoothing(0.2);
scale.set_enabled(true);
scale.set_direction(0, 0, 1);

Arguments#

Scale options#

Useful body options#

Creation example#

scale = jolt_scale_create(-6.5, -3.1, 0.3, 3.0, 1.8, 0.05);
scale.set_smoothing(0.2);
scale.set_enabled(true);
scale.set_direction(0, 0, 1);

Reading the scale#

// Call jolt_update() first so a completed physics step exists.
jolt_update(delta_time / 1000000);

if (scale.is_valid()) {
    var kilograms = scale.get_weight();
    var force_newtons = scale.get_force();

    if (!jolt_has_error()) {
        draw_text(32, 32, string_format(kilograms, 0, 2) + " kg");
        draw_text(32, 52, string_format(force_newtons, 0, 1) + " N");
    }
}

• Readings update only after a successfully completed physics step. Repeated getters in the same step return the same sample.
• get_force() and get_weight() return smoothed values suitable for UI.
• get_raw_force() and get_raw_weight() return the latest unsmoothed physics-step sample for diagnostics or impact logic.
• Getter failure returns a safe numeric zero and records a normal high-level error; do not treat zero as proof that an invalid scale is unloaded.

Public methods#

Tare and containers#

// Place the empty container on the platform and wait until it settles.
if (keyboard_check_pressed(ord("T"))) {
    if (!scale.tare()) {
        show_debug_message(jolt_get_error().message);
    }
}

• A newly created scale subtracts only the owned platform's theoretical gravity load.
• tare() replaces that baseline with the complete reaction measured at the time of the call, which is useful for containers and fixtures.
• Call tare only after the load has settled. Taring during an impact or acceleration makes that transient force the new zero.
• Changing direction recalculates the theoretical platform baseline and clears raw and smoothed readings; tare again when a container should remain excluded.

Smoothing#

• Smoothing is an exponential low-pass filter measured in elapsed physics time, so render framerate does not change its response.
• A larger time constant produces a steadier but slower display. Values around 0.1 to 0.3 seconds are a practical UI starting point.
• Zero makes the smoothed reading immediately equal to the latest raw sample.
• Use raw force to inspect short impact peaks; use smoothed weight for readable labels and dashboards.

Load direction#

• The default {0,0,1} measures upward support reaction on a normal horizontal platform.
• The vector is stored in the platform's fixed local reference frame and normalized by the native implementation.
• Only the positive projected reaction is reported. Choose the sign so the expected support force points along the axis.
• get_weight() still divides by reference_gravity for horizontal or angled axes, so its kg value remains force-equivalent rather than object mass.

Ownership and lifecycle#

• The scale owns its Dynamic platform and internal Fixed Constraint.
• scale.destroy() invalidates scale.body and removes both native resources.
• Manually destroying scale.body atomically invalidates the scale and removes its internal constraint.
• The platform has sleeping disabled so the solver produces a fresh constraint reaction even after a load stands still for a long time.
• jolt_stop() cleans up live scales as part of managed world teardown.
• Use scale.body for normal data, layer, friction, debug drawing and visual-transform access, but do not destroy it separately unless the entire scale should be removed.

Physical interpretation and limitations#

• A stack contributes through the forces actually transmitted to the platform; upper bodies do not need direct contact with it.
• When an object is supported by two platforms, each scale reports only its share of the reaction.
• Ropes, springs, constraints and applied forces contribute according to the load they transmit through the platform.
• Impacts create temporary peaks that can exceed static weight.
• Solver settling, contact softness, friction and fixed timestep produce small fluctuations; they are expected physics behaviour.
• The scale measures one signed axis and clamps negative reaction. It is not a six-axis force/torque sensor.

Validation and errors#

• Call jolt_start() before jolt_scale().
• Position and dimensions must be finite; every dimension must be greater than zero.
• mass and reference_gravity must be finite and positive.
• smoothing must be finite and non-negative; enabled must be Boolean.
• direction must be a struct with finite x, y and z forming a non-zero vector.
• Creation returns undefined on failure. Mutating methods return false; numeric getters return 0 and get_direction() returns undefined when an error occurs.
• Read jolt_get_error() immediately after a failed managed call before another Jolt operation replaces it.

Low-Level / Advanced API#

jolt_world_scale_create(world, x, y, z, width, depth, height, mass, reference_gravity)
jolt_world_scale_destroy(world, scale_handle)
jolt_world_scale_is_valid(world, scale_handle)
jolt_world_scale_get(world, scale_handle, property)
jolt_world_scale_tare(world, scale_handle)
jolt_world_scale_set_smoothing(world, scale_handle, seconds)
jolt_world_scale_set_enabled(world, scale_handle, enabled)
jolt_world_scale_set_direction(world, scale_handle, x, y, z)

Legacy / Deprecated API#

jolt_scale(x,y,z,width,depth,height,options) remains a compatibility factory sharing the same implementation. Use this path for creation-only reference_gravity. New factory defaults: mass=20 kg, reference_gravity=9.81 m/s², smoothing=0.15 s, enabled=true, direction={x:0,y:0,z:1}. Ordinary body parameters follow the unchanged creation path.

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.

Complete API declarations#

Declarations match the production GML sources. A value after = marks an optional argument. This is a signature inventory; the guide sections describe meaning, units and limitations. The type before a dot identifies the method owner, not a global function.