Current project
Closed model import
Import a static readable BBMOD triangle-list model before freeze(). Require one connected closed manifold shell with consistent winding and no duplicate, degenerate or intersecting faces. Identical float32 positions are welded; gaps are not repaired. Node transforms and initial scale/rotation are baked. x/y/z translate the model origin, not an automatically recentered mesh.
Example#
soft = jolt_soft_body_create_from_model(model_physics, 0, 0, 3, {scale:0.5});
if (!is_undefined(soft)) {
soft.set_mass(2);
soft.set_stiffness(0.6);
soft.set_pressure(50);
soft.set_renderer(o_control_bbmod_renderer.renderer);
}Usage and limits#
Limits: 4096 welded particles, 8192 triangles, shortest edge at least 0.002 m. Collision thickness cannot exceed half the shortest edge. Primary UV and material groups survive; skinning, vertex colors, UV2 and batch IDs are rejected. The source model stays unchanged.
This is a pressurized shell, not automatic volumetric tetrahedralization. Configure mass, stiffness and pressure after creation. Optional detailed visuals, named/spatial attachments, Carry, local forces and wind use the shared Soft Body API.
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
- Volumetric soft box
- 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_from_model | jolt_soft_body_create_from_model(model,x=0,y=0,z=0,settings=undefined) | Creates a closed model as JoltBBMODModel or returns undefined. Loaded static BBMOD_Model before freeze(), no bones, triangle-list, at most 4096 welded vertices/8192 triangles. Node transforms and options scale (default 1, magnitude 1e-5..10000), rotation_x/y/z (0°) are baked once. Position is world-space, default 0. Does not take ownership of the model or its materials. Closed: mass=2, stiffness=.8, pressure=50, damping=.2; cloth: mass=1, stretch=.9, bend=.3, pressure=0, damping=.1. Shared friction=.5, gravity_factor=1, thickness=.01 (fitted to the shortest edge when omitted), default layer. |
| JoltBBMODModel.add_force | JoltBBMODModel.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. |
| JoltBBMODModel.destroy | JoltBBMODModel.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. |
| JoltBBMODModel.draw | JoltBBMODModel.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. |
| JoltBBMODModel.get_collision_thickness | JoltBBMODModel.get_collision_thickness() | Current particle radius in m; undefined for an invalid wrapper, inspect native errors separately. |
| JoltBBMODModel.get_damping | JoltBBMODModel.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. |
| JoltBBMODModel.get_friction | JoltBBMODModel.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. |
| JoltBBMODModel.get_gravity_factor | JoltBBMODModel.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. |
| JoltBBMODModel.get_layer | JoltBBMODModel.get_layer() | Returns a numeric layer handle, not a JoltLayer; undefined for an invalid wrapper. |
| JoltBBMODModel.get_mass | JoltBBMODModel.get_mass() | Total mass: current numeric value in kg. Failure: undefined; an invalid object is not a zero measurement. |
| JoltBBMODModel.get_native_handle | JoltBBMODModel.get_native_handle() | Valid soft-body handle, otherwise 0. Not a JoltBody handle for rigid-body methods. |
| JoltBBMODModel.get_position | JoltBBMODModel.get_position() | World mean particle position {x, y, z} in m, not a rigid transform; undefined for an invalid wrapper. |
| JoltBBMODModel.get_pressure | JoltBBMODModel.get_pressure() | Internal pressure of a closed surface: current numeric value in N/m². Failure: undefined; an invalid object is not a zero measurement. Open model cloth has no pressure; nonzero settings are rejected. |
| JoltBBMODModel.get_vertex_position | JoltBBMODModel.get_vertex_position(index) | Integer index 0 ≤ index < vertex_count. Returns world {x, y, z} in m, undefined for an invalid index/wrapper. |
| JoltBBMODModel.get_volume | JoltBBMODModel.get_volume() | Volume in m³ from current deformation; open model cloth returns 0. undefined for invalid object or read failure. |
| JoltBBMODModel.is_valid | JoltBBMODModel.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. |
| JoltBBMODModel.render | JoltBBMODModel.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. |
| JoltBBMODModel.set_collision_thickness | JoltBBMODModel.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. |
| JoltBBMODModel.set_damping | JoltBBMODModel.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. |
| JoltBBMODModel.set_debug | JoltBBMODModel.set_debug(v) | Enables diagnostic drawing, default false; returns true. Does not change physics or object lifetime. |
| JoltBBMODModel.set_friction | JoltBBMODModel.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. |
| JoltBBMODModel.set_gravity_factor | JoltBBMODModel.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. |
| JoltBBMODModel.set_layer | JoltBBMODModel.set_layer(layer) | JoltLayer or positive integer layer handle; the layer must exist in this world. Boolean. Does not modify the layer collision matrix. |
| JoltBBMODModel.set_mass | JoltBBMODModel.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. |
| JoltBBMODModel.set_material | JoltBBMODModel.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. |
| JoltBBMODModel.set_pressure | JoltBBMODModel.set_pressure(v) | Internal pressure of a closed surface: finite number 0..1000000 N/m²; default 1000 Sphere, 50 closed model, 0 open model cloth. Returns true on acceptance, false for an invalid input or object. Updates the live object. Open model cloth has no pressure; nonzero settings are rejected. |
| JoltBBMODModel.set_renderer | JoltBBMODModel.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. |
| JoltBBMODModel.set_visible | JoltBBMODModel.set_visible(value) | Input coerced to Boolean, default true. Returns Boolean success. Hides rendering without disabling physics. |
| JoltBBMODModel.update_mesh | JoltBBMODModel.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. |