Current project
Choosing a Soft Body
Procedural and imported cloth are open surfaces. A sphere and closed imported model are pressurized shells. A procedural box has internal particles and tetrahedral volume constraints. Choose by physical behavior rather than visual shape.
Usage and limits#
Start Jolt, create/configure before the first step and register the BBMOD renderer once. Keep the existing jolt_update loop; meshes refresh by physics revision and are reused across render passes. No second physics update is needed for rendering.
Use object setters; public settings factories were removed. get_position averages particle positions. A deformable body has no single rigid rotation describing its entire shape. Shared features include spatial attachments, opt-in Carry, local forces and wind. Self-collision, tearing and Soft Body–Soft Body collision are not supplied.
destroy()/jolt_stop release physics, attachments and owned rendering buffers. Borrowed materials/textures must stay alive until rendering ends; dispose your own source resources afterwards.
API reference#
Public function and method signatures. Call methods on the returned instance; parameters with defaults are optional.
Related guides#
- Migrating existing code
- Soft sphere
- Volumetric soft box
- 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 |
|---|---|---|
| JoltBBMODSoftBody.add_force | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.destroy | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.draw | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.get_collision_thickness | JoltBBMODSoftBody.get_collision_thickness() | Current particle radius in m; undefined for an invalid wrapper, inspect native errors separately. |
| JoltBBMODSoftBody.get_damping | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.get_friction | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.get_gravity_factor | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.get_layer | JoltBBMODSoftBody.get_layer() | Returns a numeric layer handle, not a JoltLayer; undefined for an invalid wrapper. |
| JoltBBMODSoftBody.get_mass | JoltBBMODSoftBody.get_mass() | Total mass: current numeric value in kg. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODSoftBody.get_native_handle | JoltBBMODSoftBody.get_native_handle() | Valid soft-body handle, otherwise 0. Not a JoltBody handle for rigid-body methods. |
| JoltBBMODSoftBody.get_position | JoltBBMODSoftBody.get_position() | World mean particle position {x, y, z} in m, not a rigid transform; undefined for an invalid wrapper. |
| JoltBBMODSoftBody.get_stretch | JoltBBMODSoftBody.get_stretch() | Stretch stiffness: current numeric value in dimensionless units. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODSoftBody.get_vertex_position | JoltBBMODSoftBody.get_vertex_position(index) | Integer index 0 ≤ index < vertex_count. Returns world {x, y, z} in m, undefined for an invalid index/wrapper. |
| JoltBBMODSoftBody.get_volume | JoltBBMODSoftBody.get_volume() | Volume in m³ from current deformation; open model cloth returns 0. undefined for invalid object or read failure. |
| JoltBBMODSoftBody.is_valid | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.render | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_collision_thickness | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_damping | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_debug | JoltBBMODSoftBody.set_debug(v) | Enables diagnostic drawing, default false; returns true. Does not change physics or object lifetime. |
| JoltBBMODSoftBody.set_friction | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_gravity_factor | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_layer | JoltBBMODSoftBody.set_layer(layer) | JoltLayer or positive integer layer handle; the layer must exist in this world. Boolean. Does not modify the layer collision matrix. |
| JoltBBMODSoftBody.set_mass | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_material | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_renderer | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_stretch | JoltBBMODSoftBody.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. |
| JoltBBMODSoftBody.set_visible | JoltBBMODSoftBody.set_visible(value) | Input coerced to Boolean, default true. Returns Boolean success. Hides rendering without disabling physics. |
| JoltBBMODSoftBody.update_mesh | JoltBBMODSoftBody.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. |