Rigid body

The real-time simulation of rigid-bodies subjected to forces and contacts is the main feature of a physics engine for video-games, robotics, or animation.

@tresjs/rapier provides a RigidBody component compatible with the Tresjs ecosystem, with the advantage of making the "bound" between the two worlds (physic world and our 3D scene).

The information on this page is a summary of the RigidBody instance, please check the original Rapier documentation

Basic usage

To use a RigidBody component, import it from @tresjs/rapier and then pass the element you want to attach via slot.

<template>
  <RigidBody>
    <TresMesh :position="[0, 8, 0]">
      <TresTorusGeometry />
      <TresMeshNormalMaterial />
    </TresMesh>
  </RigidBody>
</template>

Types

We can specify which kind of RigidBody type we want. By default is set to Dynamic(see below).

A basic floor example with type fixed:

<template>
  <RigidBody type="fixed">
    <TresMesh :position="[0, 0, 0]">
      <TresPlaneGeometry :args="[20, 20, 20]" :rotate-x="-Math.PI / 2" />
      <TresMeshBasicMaterial color="#f4f4f4" />
    </TresMesh>
  </RigidBody>
</template>

Available types

types	Description
`Dynamic`	Indicates that the body is affected by external forces and contacts.
`Fixed`	Indicates the body cannot move. It acts as if it has an infinite mass and will not be affected by any force.
`KinematicPositionBased`	Indicates that the body position must not be altered by the physics engine.
`KinematicVelocityBased`	Indicates that the body velocity must not be altered by the physics engine.

Both position-based and velocity-based kinematic bodies are mostly the same. Choosing between both is mostly a matter of preference between position-based control and velocity-based control. More info at Rigid-body type

Props

type

RigidBodyType

Default: dynamic - rigidBody type.

collider

ColliderShape | false

Default: cuboid - automatic collider.

gravityScale

number

Default: 1 - gravity for the rigidBody.

additionalMass

number

Default: 0 - add extra mass to the rigidBody.

linearDamping

number

Default: 0 - set the linear damping.

angularDamping

number

Default: 0 - set the angular damping.

dominanceGroup

number

Default: 0 - set the dominance group.

linvel

TresVector3 | THREE.Vector3

Default: x: 0, y: 0, z: 0 - linear velocity.

angvel

TresVector3 | THREE.Vector3

Default: x: 0, y: 0, z: 0 - angular velocity.

enabledRotations

[x: boolean, y: boolean, z: boolean]

Default: {x: true, y: true, z: true } - enable rotations in specific axis.

enabledTranslations

[x: boolean, y: boolean, z: boolean]

Default: {x: true, y: true, z: true } - enable translations in specific axis.

lockTranslations

boolean

Default: false - Lock all translations.

lockRotations

boolean

Default: false - Lock all rotations.

enableCcd

boolean

Default: false - Enable continuous collision detection.

friction

number

Default: 0.5 - The friction coefficient of this collider. (automatic-collider).

mass

number

Default: 1 - Mass of the collider. (automatic-collider).

density

number

Default: 0 - Restitution controls how elastic (aka. bouncy) a contact is. (automatic-collider).

restitution

number

Default: 1 - The collider density. If non-zero the collider's mass and angular inertia will be added. (automatic-collider).

activeCollision

boolean

Default: false - To set the collider receiver/emitter collision events (automatic-collider).

activeCollisionTypes

ActiveCollisionTypes

Default: ActiveCollisionTypes.DEFAULT - Type of the collision event. (automatic-collider).

collisionGroups

number | undefined

Default: undefined - To specify collision groups. (automatic-collider).

activeCollision

boolean

Default: false - To set the collider receiver/emitter collision events (automatic-collider).

activeContactForce

boolean

Default: false - Enables contact-force events. Required to use the @contact-force event. See Contact Force.

The rigidBody instance has many other functions, please check the official docs for a complete list, if you need them, you can useTemplate ref.

Events

collision-enter

(payload: { source: SourceTarget, target: SourceTarget }) => void

Triggered when a collider starts colliding with another collider. Requires activeCollision prop to be set. See Collisions.

collision-exit

(payload: { source: SourceTarget, target: SourceTarget }) => void

Triggered when a collider stops colliding with another collider. Requires activeCollision prop to be set. See Collisions.

intersection-enter

(payload: { source: SourceTarget, target: SourceTarget }) => void

Triggered when a sensor collider starts intersecting another collider. Requires activeCollision and sensor props. See Sensor.

intersection-exit

(payload: { source: SourceTarget, target: SourceTarget }) => void

Triggered when a sensor collider stops intersecting another collider. Requires activeCollision and sensor props. See Sensor.

contact-force

(payload: ContactForcePayload) => void

Triggered every simulation step while two colliders are in contact and the force exceeds the threshold.

Expose object

instance

RigidBody

The RigidBody instance created by Rapier. See API

rigidBodyDesc

RigidBodyDesc

The Rapier rigid-body descriptor used to initialize the body. See API

context

RigidBodyContext

Collider context information (colliderInfos) associated with this rigid body.

group

TresObject3D

Parent Three.js object/group (parentObject) that contains the bound scene node. See API

Physics

The main component for render.

Automatic colliders

Automatically generated colliders that fit your mesh shape when a RigidBody is created, with support for cuboid, ball, capsule, and other preset shapes.