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.
Allow/Disallow a static body to be switched to kinematic/dynamic.
Changes the allowed degrees of freedom. You can use a combination of following bits:
DOF_TRANSLATION_X
DOF_TRANSLATION_Y
DOF_TRANSLATION_Z
DOF_ROTATION_X
DOF_ROTATION_Y
DOF_ROTATION_Z
DOF_ALL
Constant number, representing a degree of freedom.
Specifies, whether a body can go to sleep or not.
true: allow sleepingfalse: do not allow to go sleepBoolean, telling if a body may go to sleep
Sets angular damping factor. The formula used:
dw/dt = -factor * w
factor must be between 0 and 1 but is usually close to 0.
Factor number.
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.
returns a number, representing a collision group this body belongs to. If
no group is set, returns -1;
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:
SHAPE_BOX and SHAPE_CYLINDER.Number, representing the convex radius.
Allows to turn on/off debug draw for this body. Only works with a debug build.
Boolean to enable/disable a debug draw.
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.
Boolean, telling whether to consider scene depth.
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).
Number, representing the density of this collision shape.
Sets friction. Dimensionless number, usually between 0 and 1:
0: no friction1: friction force equals force that presses the two bodies togetherNote: bodies can have negative friction, but the combined friction should never go below zero.
Friction scalar.
Changes the gravity factor of a body.
Gravity factor to multiply.
Updates the filtering group bit. Value is ignored, if JoltInitSettings.bitFiltering is not set.
Unsigned integer.
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).
Number, representing radians of the threshold angle.
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.
Number, representing amount of compression bits.
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.
Number, representing a block size.
Offsets the position of the HeightField, which is a surface defined by:
hfOffset + hfScale * (x, hfHeightSamples[y * hfSampleCount + x], y)
where x and y are integers in the range x and y e [0, hfSampleCount - 1].
Vec3 with position offset.
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).
Integer number, representing the unique body index.
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.
Number, representing inertia factor.
Changes the isometry update method between rendering frontend and physics backend. This only affects automatic updates of active bodies every frame. Static and sleeping bodies are not updated.
For example, if you have many kinematic bodies that you rarely change position for, you would want to disable the isometry update so you don't burn CPU cycles every frame, and do it manually by setting the entity position and teleporting the body when needed only.
ISOMETRY_DEFAULT: frontend will tell backend where a kinematic body is and backend will
will tell frontend where a dynamic body is.ISOMETRY_FRONT_TO_BACK: frontend will tell backend where the body is.ISOMETRY_BACK_TO_FRONT: backend will tell frontend where the body is.ISOMETRY_NONE: no automatic isometry update.Integer, representing update type.
entity.addComponent('body', {
motionType: MOTION_TYPE_KINEMATIC,
objectLayer: OBJ_LAYER_MOVING,
isometryUpdate: ISOMETRY_NONE
});
// 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);
Specifies if the body is a sensor or not.
true: changes a body into a sensorfalse: changes a body into a rigid bodyBoolean, telling if this body is a sensor.
World space linear velocity of the center of mass of this body.
Vec3, representing the current linear velocity of this body.
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.
Linear velocity Vec3 (m/s per axis) to set this body to.
Updates the filtering mask bit. Value is ignored, if JoltInitSettings.bitFiltering is not set.
Unsigned integer.
A center of mass offset in local space of the body. Does not move the shape.
Vec3 with center of mass offset.
Sets maximum angular velocity a body can reach. Use setAngularVelocityClamped to not go over this limit.
Maximum angular velocity scalar (rad/s).
Sets maximum linear velocity a body can reach. Use setLinearVelocityClamped to not go over this limit.
Maximum linear velocity scalar (m/s).
Mesh is used when shape is SHAPE_MESH or SHAPE_CONVEX_HULL.
null, when no
mesh is used.PlayCanvas Mesh instance.
Changes the body motion quality. Following constants available:
MOTION_QUALITY_DISCRETE
MOTION_QUALITY_LINEAR_CAST
Use linear cast (CCD) for fast moving objects, in other cases prefer discrete one since it is cheaper.
Quality constant.
Number, representing motion quality constant.
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
OBJ_LAYER_MOVING
Where:
OBJ_LAYER_NON_MOVING = 0OBJ_LAYER_MOVING = 1Layer number.
Used only if OMP_MASS_AND_INERTIA_PROVIDED is selected for overrideMassProperties.
Backend will create inertia matrix from the given position.
Vec3 with position that is used for this body inertia calculation.
Used only if OMP_MASS_AND_INERTIA_PROVIDED is selected for overrideMassProperties.
Backend will create inertia matrix from the given rotation.
Quat with rotation that is used for this body inertia calculation.
Used only if OMP_CALCULATE_INERTIA or OMP_MASS_AND_INERTIA_PROVIDED is selected for
overrideMassProperties.
Number, representing the mass of this body, when the mass is not calculated automatically.
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
OMP_CALCULATE_MASS_AND_INERTIA
OMP_MASS_AND_INERTIA_PROVIDED
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.
Number, representing the mass calculation method constant.
Read-only. Current position of the body (not of the center of mass).
Vec3 with the current position of this body.
Sets render asset as a collider. Note:
SHAPE_MESH or SHAPE_CONVEX_HULL in order for the render asset
to be used.Render asset or its id number.
Restitution of the body.
Number, representing restitution factor for this body.
Sets body restitution. Dimensionless number, usually between 0 and 1:
0: completely inelastic collision response1: completely elastic collision responseNote: bodies can have negative restitution but the combined restitution should never go below zero.
Restitution scalar.
Read-only. Current rotation of the body.
Quat, representing the current rotation of this body.
Changes the shape type. Following constants available:
SHAPE_EMPTY
SHAPE_PLANE
SHAPE_BOX
SHAPE_CAPSULE
SHAPE_TAPERED_CAPSULE
SHAPE_CYLINDER
SHAPE_TAPERED_CYLINDER
SHAPE_SPHERE
SHAPE_MESH
SHAPE_CONVEX_HULL
SHAPE_HEIGHTFIELD
SHAPE_STATIC_COMPOUND
SHAPE_MUTABLE_COMPOUND
Shape type number.
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.
If set, will return a number, representing the sub group this body belongs
to. Otherwise, will return -1;
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.
Boolean, telling if the entity scale is applied on this collision shape.
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.
Boolean, telling if motion state is enabled for this body.
Enables/Disables a motion state for this body.
Boolean to enable/disable the motion state.
Adds an angular impulse to the center of mass.
Angular impulse vector.
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.
Force scalar value on X axis.
Force scalar value on Y axis.
Force scalar value on Z axis.
OptionaloffsetX: number = 0Force scalar offset on X axis.
OptionaloffsetY: number = 0Force scalar offset on Y axis.
OptionaloffsetZ: number = 0Force scalar offset on Z axis.
OptionalisOffsetLocal: number = falseSpecifies if offset is in world or local space.
Same as addImpulse, but accepts scalars, instead of vectors.
Impulse scalar value on X axis.
Impulse scalar value on Y axis.
Impulse scalar value on Z axis.
OptionaloffsetX: number = 0Impulse scalar offset on X axis.
OptionaloffsetY: number = 0Impulse scalar offset on Y axis.
OptionaloffsetZ: number = 0Impulse scalar offset on Z axis.
OptionalisOffsetLocal: number = falseSpecifies if offset is in world or local space.
Allows to add a shape to a mutable compound shape.
The index of a shape to add. It can be created by createShape.
OptionallocalPos: Vec3 = Vec3.ZEROLocal position of the shape.
OptionallocalRot: Quat = Quat.IDENTITYLocal rotation of the shape.
OptionaluserData: number = 0User defined unsigned integer.
Adds a torque (unit: N) for the next physics time step. Will reset after the physics completes a step.
Torque vector.
Applies an impulse to the body that simulates fluid buoyancy and drag.
Position of the fluid surface in world space.
Normal of the fluid surface (should point up).
The buoyancy factor for the body:
= 1: neutral body< 1: sinks> 1: floatsLinear drag factor that slows down the body when in the fluid
(approx. 0.5).
Angular drag factor that slows down rotation when the body is
in the fluid (approx. 0.01).
The average velocity of the fluid (in m/s) in which the body resides.
Clamps angular velocity according to the limit set by maxAngularVelocity.
Clamps linear velocity according to the limit set by maxLinearVelocity.
Fire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optionalarg1: anyFirst argument that is passed to the event handler.
Optionalarg2: anySecond argument that is passed to the event handler.
Optionalarg3: anyThird argument that is passed to the event handler.
Optionalarg4: anyFourth argument that is passed to the event handler.
Optionalarg5: anyFifth argument that is passed to the event handler.
Optionalarg6: anySixth argument that is passed to the event handler.
Optionalarg7: anySeventh argument that is passed to the event handler.
Optionalarg8: anyEighth argument that is passed to the event handler.
Self for chaining.
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
Allows to modify a child shape of a mutable compound shape.
The child shape index. Children indices are zero based and have no gaps.
OptionallocalPos: Vec3 = Vec3.ZEROLocal position of the shape.
OptionallocalRot: Quat = Quat.IDENTITYLocal rotation of the shape.
OptionalshapeIndex: number = -1The index of a shape to add. It can be created by createShape.
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.
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Optionalname: stringName of the event to unbind.
Optionalcallback: HandleEventCallbackFunction to be unbound.
Optionalscope: objectScope that was used as the this when the event is fired.
Self for chaining.
const handler = () => {};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optionalscope: objectObject to use as 'this' when the event is fired, defaults to current this.
Can be used for removing event in the future.
Attach an event handler to an event. This handler will be removed after being fired once.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optionalscope: objectObject to use as 'this' when the event is fired, defaults to current this.
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.
The index of a child shape to remove.
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.
Angular velocity vector.
Set to indicate that the gyroscopic force should be applied to this body (aka Dzhanibekov effect, see Tennis Racket Theorem.
Boolean, whether to apply gyroscopic force
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.
Boolean, telling if we want kinematics contactact non-dynamic bodies.
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.
Collision group number. Use -1 to disable.
Sub group number. Use -1 to disable.
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.
State boolean
Set world space linear velocity of the center of mass, will make sure the value is clamped against the maximum linear velocity.
Linear velocity vector.
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.
Number of velocity steps.
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.
Number of velocity steps.
Allows changing the current shape to a custom one.
Note: once set, you won't be able to destroy this shape using destroyShape. The shape will be destroyed when either the body gets destroyed, or when you change it to another shape.
The index of a shape to add. It can be created by createShape.
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.
Position scalar value on X axis.
Position scalar value on Y axis.
Position scalar value on Z axis.
Optionalrx: number = 0Rotation scalar value on X axis.
Optionalry: number = 0Rotation scalar value on Y axis.
Optionalrz: number = 0Rotation scalar value on Z axis.
Optionalrw: number = 1Rotation scalar value on W axis.
Body Component description.