Class SoftBodyComponent

When this body is created as MOTION_TYPE_STATIC, this setting tells Jolt system to create a MotionProperties object internally, so that the object can be switched to kinematic or dynamic. Use false, if you don't intend to switch the type of this body from static. This is a performance optimization.

Default Value

false
Copy

Specifies if this body go to sleep or not.

Default Value

true
Copy

Specifies, whether a body can go to sleep or not.

• true: allow sleeping
• false: do not allow to go sleep

Which degrees of freedom this body has (can be used to limit simulation to 2D). For example, using DOF_TRANSLATION_X restricts a body to move in world space X axis.

Default Value

DOF_ALL
Copy

Changes the allowed degrees of freedom. You can use a combination of following bits:

DOF_TRANSLATION_X
Copy

DOF_TRANSLATION_Y
Copy

DOF_TRANSLATION_Z
Copy

DOF_ROTATION_X
Copy

DOF_ROTATION_Y
Copy

DOF_ROTATION_Z
Copy

DOF_ALL
Copy

Example

// lock translation to X and Z axis and rotation to Y axis
entity.body.allowedDOFs = DOF_TRANSLATION_X | DOF_TRANSLATION_Z | DOF_ROTATION_Y;
Copy

Tells how quickly a body loses angular velocity.

Default Value

0
Copy

Sets angular damping factor. The formula used:

dw/dt = -factor * w
Copy

factor must be between 0 and 1 but is usually close to 0.

World space angular velocity.

Default Value

Vec3(0, 0, 0) (rad/s)
Copy

Returns a boolean, telling if the position and rotation of this body is updated automatically.

Default Value

false
Copy

Changes the isometry update method:

• true: framework will synchronize entity position/rotation in visual world with a physical body in physics world automatically.
• false: framework expects a user to do it manually.

If false is set, then physics will no longer auto-update entity/body position/rotation.

• Backend will not tell frontend where dynamic body is.
• Frontend will not tell backend where kinematic body is.
• This setting has no effect on a static body.

This is useful, for example, when you have many kinematic objects and you rarely change their isometry. In some cases this is also useful for dynamic bodies, e.g. when their gravity factor is set to zero, and you use moveKinematic to translate it manually.

Example

entity.addComponent('body', {
    motionType: MOTION_TYPE_KINEMATIC,
    objectLayer: OBJ_LAYER_MOVING,
    autoUpdateIsometry: false
});

// then on frame update, or when needed, move both - body and entity
entity.setPosition(newPosition);
entity.body.teleport(newPosition);
// or any of the body movement methods, e.g.
// entity.body.moveKinematic(newPosition, Quat.IDENTITY, time);
Copy

The collision group this body belongs to (determines if two objects can collide). Expensive, so disabled by default. Prefer to use broadphase and object layers instead for filtering.

Default Value

-1 (disabled)
Copy

Internally the convex radius will be subtracted from the half extent, so the total size will not grow with the convex radius. You can increase this value to make the edges of the collision shape rounded.

Note:

• Only used by shapes with sharp edges: SHAPE_BOX and SHAPE_CYLINDER.
• Cannot be changed after the shape is created.

Default Value

0.05 (m)
Copy

Specifies, whether to debug draw the collision shape.

Default Value

false
Copy

Allows to turn on/off debug draw for this body. Only works with a debug build.

Default Value

true
Copy

If debugDraw is enabled, this will specify whether to consider scene depth or not. If set to false, the debug lines will be drawn on top of everything, through other meshes.

Density of the object. Affects the mass of the object, when BodyComponent.overrideMassProperties is set to OMP_CALCULATE_MASS_AND_INERTIA (default, which will auto-calculate the mass using the shape dimensions and this density value).

Default Value

1000 (kg / m^3)
Copy

Friction of the body.

Default Value

0.2
Copy

Sets friction. Dimensionless number, usually between 0 and 1:

• 0: no friction
• 1: friction force equals force that presses the two bodies together

Note: bodies can have negative friction, but the combined friction should never go below zero.

Value to multiply gravity with for this body.

Default Value

1
Copy

Changes the gravity factor of a body.

Collision group bit of an object layer.

Two layers can collide if object1.group and object2.mask is non-zero and object2.group and object1.mask is non-zero. The behavior is similar to that of filtering in e.g. Bullet, Rapier.

Default Value

0
Copy

Updates the filtering group bit. Value is ignored, if JoltInitSettings.bitFiltering is not set.

Half extent for a SHAPE_BOX.

Default Value

Vec3(0.5, 0.5, 0.5) (m per axis)
Copy

Half-height of radius based shapes.

Note: Only used by SHAPE_CAPSULE and SHAPE_CYLINDER.

Default Value

0.5 (m)
Copy

Cosine of the threshold angle. If the angle between the two triangles in HeightField is bigger than this, the edge is active. note that a concave edge is always inactive. Setting this value too small can cause ghost collisions with edges. Setting it too big can cause depenetration artifacts (objects not depenetrating quickly). Valid ranges are between cos(0 degrees) and cos(90 degrees).

Default Value

0.996195 (cos(5 degrees))
Copy

How many bits per sample to use to compress the HeightField. Can be in the range [1, 8]. Note that each sample is compressed relative to the min/max value of its block of hfBlockSize * hfBlockSize pixels so the effective precision is higher. Also note that increasing hfBlockSize saves more memory, than reducing the amount of bits per sample.

Default Value

8
Copy

The HeightField is divided in blocks of hfBlockSize * hfBlockSize * 2 triangles and the acceleration structure culls blocks only, bigger block sizes reduce memory consumption, but also reduce query performance. Sensible values are [2, 8]. Does not need to be a power of 2. Note that at run-time Jolt performs one more grid subdivision, so the effective block size is half of what is provided here.

Default Value

2
Copy

Offsets the position of the HeightField, which is a surface defined by:

hfOffset + hfScale * (x, hfHeightSamples[y * hfSampleCount + x], y)
Copy

where x and y are integers in the range x and y e [0, hfSampleCount - 1].

Default Value

Vec3(0, 0, 0) (m per axis)
Copy

Unique body index. This can change during entity lifecycle, e.g. every time entity is enabled, a new index is assigned and a new body is created. The index is used to map entity to body. Index can be re-used by another component if this component is disabled or destroyed (destroying related body as a result).

Default Value

-1
Copy

When calculating the inertia the calculated inertia will be multiplied by this value. This factor is ignored when overrideMassProperties is set to OMP_MASS_AND_INERTIA_PROVIDED - you are expected to calculate inertia yourself in that case. Cannot be changed after a body is created.

Default Value

1
Copy

Specifies if the component describes a child of a compound shape.

Default Value

false
Copy

If this body is a sensor. A sensor will receive collision callbacks, but will not cause any collision responses and can be used as a trigger volume.

Default Value

false
Copy

Specifies if the body is a sensor or not.

• true: changes a body into a sensor
• false: changes a body into a rigid body

Specifies how quickly the body loses linear velocity. Uses formula:

dv/dt = -c * v.
Copy

c must be between 0 and 1 but is usually close to 0.

Default Value

0
Copy

World space linear velocity of the center of mass of this body.

Default Value

Vec3(0, 0, 0) (m/s)
Copy

Sets linear velocity unclamped. Can be set to be over the allowed maximum. If you want to be sure not to go over allowed max, use setLinearVelocityClamped.

Collision mask bit of an object layer.

Two layers can collide if object1.group and object2.mask is non-zero and object2.group and object1.mask is non-zero. The behavior is similar to that of filtering in e.g. Bullet, Rapier.

Default Value

0
Copy

Updates the filtering mask bit. Value is ignored, if JoltInitSettings.bitFiltering is not set.

A center of mass offset in local space of the body. Does not move the shape.

Default Value

Vec3(0, 0, 0) (m per axis)
Copy

Maximum angular velocity that this body can reach.

Default Value

47.12388980384689 (0.25 * PI * 60.0, rad/s)
Copy

Sets maximum angular velocity a body can reach. Use setAngularVelocityClamped to not go over this limit.

Maximum linear velocity that this body can reach.

Default Value

500 (m/s)
Copy

Sets maximum linear velocity a body can reach. Use setLinearVelocityClamped to not go over this limit.

Mesh is used when shape is SHAPE_MESH or SHAPE_CONVEX_HULL.

Default Value

null
Copy

Motion quality, or how well it detects collisions when it has a high velocity.

Default Value

MOTION_QUALITY_DISCRETE
Copy

Changes the body motion quality. Following constants available:

MOTION_QUALITY_DISCRETE
Copy

MOTION_QUALITY_LINEAR_CAST
Copy

Use linear cast (CCD) for fast moving objects, in other cases prefer discrete one since it is cheaper.

Motion type, determines if the object is static, dynamic or kinematic. You can use the following constants:

MOTION_TYPE_STATIC
Copy

MOTION_TYPE_DYNAMIC
Copy

MOTION_TYPE_KINEMATIC
Copy

Default Value

MOTION_TYPE_STATIC
Copy

The collision layer this body belongs to (determines if two objects can collide).

Default Value

OBJ_LAYER_NON_MOVING
Copy

Changes the object layer that this body belongs to. Allows cheap filtering. Not used, if JoltInitSettings.bitFiltering is provided during system initialization.

You can use the following pre-made ones:

OBJ_LAYER_NON_MOVING
Copy

OBJ_LAYER_MOVING
Copy

Where:

• OBJ_LAYER_NON_MOVING = 0
• OBJ_LAYER_MOVING = 1

Used only if OMP_MASS_AND_INERTIA_PROVIDED is selected for overrideMassProperties. Backend will create inertia matrix from the given position.

Default Value

Vec3(0, 0, 0) (m)
Copy

Used only if OMP_MASS_AND_INERTIA_PROVIDED is selected for overrideMassProperties. Backend will create inertia matrix from the given rotation.

Default Value

Quat(0, 0, 0, 1)
Copy

Used only if OMP_CALCULATE_INERTIA or OMP_MASS_AND_INERTIA_PROVIDED is selected for overrideMassProperties.

Default Value

1 (kg)
Copy

Determines how a body mass and inertia is calculated. By default it uses OMP_CALCULATE_MASS_AND_INERTIA, which tells Jolt to auto-calculate those based the collider shape. You can use following constants:

OMP_CALCULATE_INERTIA
Copy

OMP_CALCULATE_MASS_AND_INERTIA
Copy

OMP_MASS_AND_INERTIA_PROVIDED
Copy

If you select OMP_CALCULATE_INERTIA, you must also specify overrideMass. The inertia will be automatically calculated for you.

If you select OMP_MASS_AND_INERTIA_PROVIDED, you must also specify overrideMass, overrideInertiaPosition and overrideInertiaRotation.

Cannot be changed after the body is created.

Default Value

OMP_CALCULATE_MASS_AND_INERTIA (calculates automatically)
Copy

Read-only. Current position of the body (not of the center of mass).

Default Value

Vec3(0, 0, 0) (m per axis)
Copy

Radius for radius based shapes, like SHAPE_CAPSULE, SHAPE_SPHERE, etc.

Default Value

0.5 (m)
Copy

This field contains the render asset ID, when a render asset is used for collision mesh or a convex hull.

Default Value

null
Copy

Sets render asset as a collider. Note:

• shape must be SHAPE_MESH or SHAPE_CONVEX_HULL in order for the render asset to be used.
• If the render asset has multiple mesh instances, only the mesh from the first mesh instance is used. If you need multiple meshes, consider creating a compound collider.

Restitution of the body.

Sets body restitution. Dimensionless number, usually between 0 and 1:

• 0: completely inelastic collision response
• 1: completely elastic collision response

Note: bodies can have negative restitution but the combined restitution should never go below zero.

Read-only. Current rotation of the body.

Default Value

Quat(0, 0, 0, 1) (identity rotation)
Copy

Current shape type.

Default Value

SHAPE_BOX
Copy

Changes the shape type. Following constants available:

SHAPE_EMPTY
Copy

SHAPE_PLANE
Copy

SHAPE_BOX
Copy

SHAPE_CAPSULE
Copy

SHAPE_TAPERED_CAPSULE
Copy

SHAPE_CYLINDER
Copy

SHAPE_TAPERED_CYLINDER
Copy

SHAPE_SPHERE
Copy

SHAPE_MESH
Copy

SHAPE_CONVEX_HULL
Copy

SHAPE_HEIGHTFIELD
Copy

SHAPE_STATIC_COMPOUND
Copy

SHAPE_MUTABLE_COMPOUND
Copy

Local position offset of the collision shape.

Default Value

Vec3(0, 0, 0) (m per axis)
Copy

Local rotation offset of the collision shape.

Default Value

Quat(0, 0, 0, 1) (identity rotation)
Copy

The collision sub group this body belongs to (determines if two objects can collide). Expensive, so disabled by default. Prefer to use broadphase and object layers instead for filtering.

Default Value

-1 (disabled)
Copy

Applies entity scale on the shape. This makes it easier to adjust the size of the collision shape by simply scaling the entity.

Note: Some shapes do not support non-uniformed scales, like SHAPE_SPHERE. Works best with SHAPE_BOX which you can scale on any axis. Others, like capsule and cone, can't have a different radius on X and Z axis, but allow scaling Y for their height.

Default Value

true
Copy

A motion state for this body. Not used by static bodies.

If the physcs fixed timestep is set lower than the client's browser refresh rate, then browser will have multiple frame updates per single physics simulation step. If you enable motion state for this entity, then the position and rotation will be interpolated, otherwise the entity will visually move only after physics completes a step.

For example, say browser refreshes every 0.1 seconds, and physics step once a second. Without using motion state an entity position will update once every second, when physics update takes place. With motion state enabled, it will update the position/rotation every 0.1 seconds - once a true update (from physics) and 9 times interpolated. This will give a smooth motion of the entity, without having to do expensive physics simulation step every frame.

Default Value

true
Copy

Enables/Disables a motion state for this body.

Adds an angular impulse to the center of mass.

Adds a force (unit: N) at an offset to this body for the next physics time step. Will reset after the physics completes a step.

Same as addForce, but accepts scalars, instead of vectors.

Adds an impulse to the center of mass of the body (unit: kg m/s).

Same as addImpulse, but accepts scalars, instead of vectors.

Allows to add a shape to a mutable compound shape.

Adds a torque (unit: N) for the next physics time step. Will reset after the physics completes a step.

Applies an impulse to the body that simulates fluid buoyancy and drag.

Clamps angular velocity according to the limit set by maxAngularVelocity.

Clamps linear velocity according to the limit set by maxLinearVelocity.

Allows to modify a child shape of a mutable compound shape.

Changes the position and rotation of a dynamic body. Unlike teleport, this method doesn't change the position/rotation instantenously, but instead calculates and sets linear and angular velocities for the body, so it can reach the target position and rotation in the specified delta time. If delta time is set to zero, the engine will use the current fixed timestep value.

Allows to remove a child shape from a mutable compound shape. The children are indexed in order they were added. Indices are zero based and have no gaps. If you remove a child, then the next child takes its index.

For example, if you remove child under index 0, then all children shift there indices, so that the child with index 1, becomes a child with index 0, etc.

Reset the current velocity and accumulated force and torque.

If a body is allowed to sleep, this method will reset the sleep timer. Does not wake up a body that is already sleeping.

Set world space linear velocity of the center of mass, will make sure the value is clamped against the maximum linear velocity.

Set to indicate that the gyroscopic force should be applied to this body (aka Dzhanibekov effect, see Tennis Racket Theorem.

Sets whether kinematic objects can generate contact points against other kinematic or static objects. Note that turning this on can be CPU intensive as much more collision detection work will be done without any effect on the simulation (kinematic objects are not affected by other kinematic/static objects).

This can be used to make sensors detect static objects. Note that the sensor must be kinematic and active for it to detect static objects.

Changes the collision group and sub group this body belongs to. Using collision groups is expensive, so it is disabled by default. Prefer to use broadphase and object layers instead for filtering.

Set to indicate that extra effort should be made to try to remove ghost contacts (collisions with internal edges of a mesh). This is more expensive but makes bodies move smoother over a mesh with convex edges.

Set world space linear velocity of the center of mass, will make sure the value is clamped against the maximum linear velocity.

Used only when this body is dynamic and colliding. Override for the number of solver position iterations to run, 0 means use the default in settings.numPositionSteps. The number of iterations to use is the max of all contacts and constraints in the island.

Used only when this body is dynamic and colliding. Override for the number of solver velocity iterations to run, 0 means use the default in settings.numVelocitySteps. The number of iterations to use is the max of all contacts and constraints in the island.

Intantenous placement of a body to a new position/rotation (i.e. teleport). Will ignore any bodies between old and new position.

Same as teleport, but taking scalars, instead of vectors.