Current project
Volumetric soft box
Position is the center; width/depth/height are full X/Y/Z lengths in metres. Each grid cell has six tetrahedra. Default resolution 4 produces 125 particles and 384 tetrahedra. Resolution is fixed at creation. This type has volume stiffness, not a pressure setter.
Example#
soft = jolt_soft_body_create_box(0, 0, 3, 2, 1, 1, {resolution:4});
if (!is_undefined(soft)) {
soft.set_mass(2);
soft.set_stiffness(0.3);
soft.set_volume_stiffness(0.8);
soft.set_damping(0.5);
soft.set_renderer(o_control_bbmod_renderer.renderer);
}Usage and limits#
Stiffness controls elastic edges; volume stiffness resists volume change. Both range 0..1. Zero means the softest finite compliance, not removal of all constraints; one does not make a rigid body. Higher resolution costs more simulation time. Attachments can include internal particles; Carry grips surface neighborhoods.
Use get_volume for current signed volume, get_position for mean particle position and get_vertex_position(index) for world particle coordinates. Rendering updates through BBMOD and the existing physics loop.
API reference#
Public function and method signatures. Call methods on the returned instance; parameters with defaults are optional.
Related guides#
- Migrating existing code
- Choosing a Soft Body
- Soft sphere
- Closed model import
- Cloth model and named anchors
- Spatial attachments
- Separate visual mesh
- Local force and impulse
- Wind
- Carrying Soft Bodies
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 |
|---|---|---|
| jolt_soft_body_create_box | jolt_soft_body_create_box(x,y,z,width,depth,height,settings=undefined) | Returns JoltBBMODBox or undefined in a running world. Full X/Y/Z dimensions .05..100 m. Options mass=2, stiffness=.3, volume_stiffness=.8, damping=.5, friction=.5, gravity_factor=1, collision_thickness=.02, resolution=4 (integer 1..10), rotation_x/y/z=0°, default layer. Particle count is (resolution+1)^3; thickness ≤ half the smallest dimension. |
| JoltBBMODBox.add_force | JoltBBMODBox.add_force(x,y,z) | Finite world force components x/y/z in N; Boolean. Submits total force to the native soft body, not a local particle selection. Use jolt_soft_body_force for a local effect. |
| JoltBBMODBox.destroy | JoltBBMODBox.destroy() | Boolean, repeatedly true after successful destruction. Removes physics first, then renderer registration, owned meshes/materials, attachments, wind and force helpers. Borrowed materials and host bodies are not destroyed. |
| JoltBBMODBox.draw | JoltBBMODBox.draw() | Renders current deformed geometry if live and visible; no return value. draw aliases render. Do not additionally call these manually when registered with a renderer. |
| JoltBBMODBox.get_collision_thickness | JoltBBMODBox.get_collision_thickness() | Current particle radius in m; undefined for an invalid wrapper, inspect native errors separately. |
| JoltBBMODBox.get_damping | JoltBBMODBox.get_damping() | Linear damping: current numeric value in 1/s. Failure: undefined (invalid wrapper); inspect native errors separately; an invalid object is not a zero measurement. |
| JoltBBMODBox.get_friction | JoltBBMODBox.get_friction() | Friction coefficient: current numeric value in dimensionless units. Failure: undefined (invalid wrapper); inspect native errors separately; an invalid object is not a zero measurement. |
| JoltBBMODBox.get_gravity_factor | JoltBBMODBox.get_gravity_factor() | Gravity multiplier: current numeric value in dimensionless units. Failure: undefined (invalid wrapper); inspect native errors separately; an invalid object is not a zero measurement. |
| JoltBBMODBox.get_layer | JoltBBMODBox.get_layer() | Returns a numeric layer handle, not a JoltLayer; undefined for an invalid wrapper. |
| JoltBBMODBox.get_mass | JoltBBMODBox.get_mass() | Total mass: current numeric value in kg. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODBox.get_native_handle | JoltBBMODBox.get_native_handle() | Valid soft-body handle, otherwise 0. Not a JoltBody handle for rigid-body methods. |
| JoltBBMODBox.get_position | JoltBBMODBox.get_position() | World mean particle position {x, y, z} in m, not a rigid transform; undefined for an invalid wrapper. |
| JoltBBMODBox.get_stretch | JoltBBMODBox.get_stretch() | Stretch stiffness: current numeric value in dimensionless units. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODBox.get_vertex_position | JoltBBMODBox.get_vertex_position(index) | Integer index 0 ≤ index < vertex_count. Returns world {x, y, z} in m, undefined for an invalid index/wrapper. |
| JoltBBMODBox.get_volume | JoltBBMODBox.get_volume() | Volume in m³ from current deformation; open model cloth returns 0. undefined for invalid object or read failure. |
| JoltBBMODBox.get_volume_stiffness | JoltBBMODBox.get_volume_stiffness() | Volume stiffness: current numeric value in dimensionless units. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODBox.is_valid | JoltBBMODBox.is_valid() | Boolean based on the wrapper, handle and original managed world. Not a native existence query for every particle; do not mix raw destruction with managed ownership. |
| JoltBBMODBox.render | JoltBBMODBox.render() | Renders current deformed geometry if live and visible; no return value. draw aliases render. Do not additionally call these manually when registered with a renderer. |
| JoltBBMODBox.set_collision_thickness | JoltBBMODBox.set_collision_thickness(v) | Particle collision radius in m, finite ≥0. Upper bound: Sphere radius, half the smallest Box dimension, half the shortest model edge. Boolean; default 0.02 Sphere/Box, model 0.01 or a smaller edge-adjusted value when omitted from options. |
| JoltBBMODBox.set_damping | JoltBBMODBox.set_damping(v) | Linear damping: finite number 0..1000 1/s; default 0.1 Sphere, 0.5 Box, 0.2 closed model / 0.1 model cloth. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.set_debug | JoltBBMODBox.set_debug(v) | Enables diagnostic drawing, default false; returns true. Does not change physics or object lifetime. |
| JoltBBMODBox.set_debug_internal | JoltBBMODBox.set_debug_internal(v) | Boolean coercion; enabling also enables ordinary debug. Returns true, without changing physics. |
| JoltBBMODBox.set_friction | JoltBBMODBox.set_friction(v) | Friction coefficient: finite number 0..1000 ; default 0.5. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.set_gravity_factor | JoltBBMODBox.set_gravity_factor(v) | Gravity multiplier: finite number 0..1000 ; default 1. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.set_layer | JoltBBMODBox.set_layer(layer) | JoltLayer or positive integer layer handle; the layer must exist in this world. Boolean. Does not modify the layer collision matrix. |
| JoltBBMODBox.set_mass | JoltBBMODBox.set_mass(v) | Total mass: finite number 0.01..1000000 kg; default 2 (Sphere/Box), 2 closed model / 1 model cloth. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.set_material | JoltBBMODBox.set_material(material) | BBMOD_BaseMaterial or undefined for an automatic owned two-sided material. Boolean; user material is borrowed and not destroyed, a previous owned material is released. |
| JoltBBMODBox.set_renderer | JoltBBMODBox.set_renderer(renderer) | Live BBMOD_BaseRenderer or undefined to detach. Boolean; registers/unregisters this same object, do not additionally register it by hand. Requires a live soft body. |
| JoltBBMODBox.set_stretch | JoltBBMODBox.set_stretch(v) | Stretch stiffness: finite number 0..1 ; default 0.8 Sphere/closed model, 0.3 Box, 0.9 model cloth. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.set_visible | JoltBBMODBox.set_visible(value) | Input coerced to Boolean, default true. Returns Boolean success. Hides rendering without disabling physics. |
| JoltBBMODBox.set_volume_stiffness | JoltBBMODBox.set_volume_stiffness(v) | Volume stiffness: finite number 0..1 ; default 0.8. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltBBMODBox.update_mesh | JoltBBMODBox.update_mesh(force=false) | Boolean success; force=false uses the physics revision cache. force=true forces an update even after manual native stepping. Positions are already world-space; do not apply the body transform again. |