pmndrs
yarn add @react-three/cannonReact hooks for cannon-es. Use this in combination with react-three-fiber.
- [x] Doesn't block the main thread, runs in a web worker
- [x] Supports instancing out of the box
- [x] Least amount of friction you'll ever experience with a physics rig ... 🙈
Demos
Check out all of our examples at https://cannon.pmnd.rs
The code for the examples lives in ../react-three-cannon-examples
How it works
- Get all the imports that you need.
import { Physics, useBox, ... } from '@react-three/cannon'- Create a physics world.
<Physics>{/* Physics related objects in here please */}</Physics>- Pick a shape that suits your objects contact surface, it could be a box, plane, sphere, etc. Give it a mass, too.
const [ref, api] = useBox(() => ({ mass: 1 }))- Take your object, it could be a mesh, line, gltf, anything, and tie it to the reference you have just received. Et voilà, it will now be affected by gravity and other objects inside the physics world.
<mesh ref={ref} geometry={...} material={...} />- You can interact with it by using the api, which lets you apply positions, rotations, velocities, forces and impulses.
useFrame(({ clock }) => api.position.set(Math.sin(clock.getElapsedTime()) * 5, 0, 0))- You can use the body api to subscribe to properties to get updates on each frame.
const velocity = useRef([0, 0, 0])
useEffect(() => {
const unsubscribe = api.velocity.subscribe((v) => (velocity.current = v))
return unsubscribe
}, [])Simple example
Let's make a cube falling onto a plane. You can play with a sandbox here.
import { Canvas } from '@react-three/fiber'
import { Physics, usePlane, useBox } from '@react-three/cannon'
function Plane(props) {
const [ref] = usePlane(() => ({ rotation: [-Math.PI / 2, 0, 0], ...props }))
return (
<mesh ref={ref}>
<planeGeometry args={[100, 100]} />
</mesh>
)
}
function Cube(props) {
const [ref] = useBox(() => ({ mass: 1, position: [0, 5, 0], ...props }))
return (
<mesh ref={ref}>
<boxGeometry />
</mesh>
)
}
ReactDOM.render(
<Canvas>
<Physics>
<Plane />
<Cube />
</Physics>
</Canvas>,
document.getElementById('root'),
)Debug
You can debug your scene using the cannon-es-debugger. This will show you how cannon "sees" your scene. Do not use this in production as it will pull in cannon-es a second time!
import { Physics, Debug } from '@react-three/cannon'
ReactDOM.render(
<Canvas>
<Physics>
<Debug color="black" scale={1.1}>
{/* children */}
</Debug>
</Physics>
</Canvas>,
document.getElementById('root'),
)Api
Exports
function Physics({
allowSleep = false,
axisIndex = 0,
broadphase = 'Naive',
defaultContactMaterial = { contactEquationStiffness: 1e6 },
gravity = [0, -9.81, 0],
isPaused = false,
iterations = 5,
maxSubSteps = 10,
quatNormalizeFast = false,
quatNormalizeSkip = 0,
shouldInvalidate = true,
// Maximum amount of physics objects inside your scene
// Lower this value to save memory, increase if 1000 isn't enough
size = 1000,
solver = 'GS',
stepSize = 1 / 60,
tolerance = 0.001,
}: React.PropsWithChildren<ProviderProps>): JSX.Element
function Debug({ color = 'black', scale = 1 }: DebugProps): JSX.Element
function usePlane(
fn: GetByIndex<PlaneProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useBox(
fn: GetByIndex<BoxProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useCylinder(
fn: GetByIndex<CylinderProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useHeightfield(
fn: GetByIndex<HeightfieldProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useParticle(
fn: GetByIndex<ParticleProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useSphere(
fn: GetByIndex<SphereProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useTrimesh(
fn: GetByIndex<TrimeshProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useConvexPolyhedron(
fn: GetByIndex<ConvexPolyhedronProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useCompoundBody(
fn: GetByIndex<CompoundBodyProps>,
fwdRef?: React.Ref<THREE.Object3D>,
deps?: React.DependencyList,
): Api
function useRaycastVehicle(
fn: () => RaycastVehicleProps,
fwdRef?: React.Ref<THREE.Object3D>,
deps: React.DependencyList[] = [],
): [React.RefObject<THREE.Object3D>, RaycastVehiclePublicApi]
function usePointToPointConstraint(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: PointToPointConstraintOpts,
deps: React.DependencyList = [],
): ConstraintApi
function useConeTwistConstraint(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: ConeTwistConstraintOpts,
deps: React.DependencyList = [],
): ConstraintApi
function useDistanceConstraint(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: DistanceConstraintOpts,
deps: React.DependencyList = [],
): ConstraintApi
function useHingeConstraint(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: HingeConstraintOpts,
deps: React.DependencyList = [],
): ConstraintApi
function useLockConstraint(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: LockConstraintOpts,
deps: React.DependencyList = [],
): ConstraintApi
function useSpring(
bodyA: React.Ref<THREE.Object3D>,
bodyB: React.Ref<THREE.Object3D>,
optns: SpringOptns,
deps: React.DependencyList = [],
): void
function useRaycastClosest(
options: RayOptions,
callback: (e: RayhitEvent) => void,
deps: React.DependencyList = [],
): void
function useRaycastAny(
options: RayOptions,
callback: (e: RayhitEvent) => void,
deps: React.DependencyList = [],
): void
function useRaycastAll(
options: RayOptions,
callback: (e: RayhitEvent) => void,
deps: React.DependencyList = [],
): void
function useContactMaterial(
materialA: MaterialOptions,
materialB: MaterialOptions,
options: ContactMaterialOptions,
deps: React.DependencyList = [],
): voidReturned api
type WorkerApi = {
[K in AtomicName]: AtomicApi<K>
} & {
[K in VectorName]: VectorApi
} & {
applyForce: (force: Triplet, worldPoint: Triplet) => void
applyImpulse: (impulse: Triplet, worldPoint: Triplet) => void
applyLocalForce: (force: Triplet, localPoint: Triplet) => void
applyLocalImpulse: (impulse: Triplet, localPoint: Triplet) => void
applyTorque: (torque: Triplet) => void
quaternion: QuaternionApi
rotation: VectorApi
scaleOverride: (scale: Triplet) => void
sleep: () => void
wakeUp: () => void
}
interface PublicApi extends WorkerApi {
at: (index: number) => WorkerApi
}
type Api = [React.RefObject<THREE.Object3D>, PublicApi]
type AtomicName =
| 'allowSleep'
| 'angularDamping'
| 'collisionFilterGroup'
| 'collisionFilterMask'
| 'collisionResponse'
| 'fixedRotation'
| 'isTrigger'
| 'linearDamping'
| 'mass'
| 'material'
| 'sleepSpeedLimit'
| 'sleepTimeLimit'
| 'userData'
type AtomicApi<K extends AtomicName> = {
set: (value: AtomicProps[K]) => void
subscribe: (callback: (value: AtomicProps[K]) => void) => () => void
}
type QuaternionApi = {
set: (x: number, y: number, z: number, w: number) => void
copy: ({ w, x, y, z }: Quaternion) => void
subscribe: (callback: (value: Quad) => void) => () => void
}
type VectorName = 'angularFactor' | 'angularVelocity' | 'linearFactor' | 'position' | 'velocity'
type VectorApi = {
set: (x: number, y: number, z: number) => void
copy: ({ x, y, z }: Vector3 | Euler) => void
subscribe: (callback: (value: Triplet) => void) => () => void
}
type ConstraintApi = [
React.RefObject<THREE.Object3D>,
React.RefObject<THREE.Object3D>,
{
enable: () => void
disable: () => void
},
]
type HingeConstraintApi = [
React.RefObject<THREE.Object3D>,
React.RefObject<THREE.Object3D>,
{
enable: () => void
disable: () => void
enableMotor: () => void
disableMotor: () => void
setMotorSpeed: (value: number) => void
setMotorMaxForce: (value: number) => void
},
]
type SpringApi = [
React.RefObject<THREE.Object3D>,
React.RefObject<THREE.Object3D>,
{
setStiffness: (value: number) => void
setRestLength: (value: number) => void
setDamping: (value: number) => void
},
]
interface RaycastVehiclePublicApi {
applyEngineForce: (value: number, wheelIndex: number) => void
setBrake: (brake: number, wheelIndex: number) => void
setSteeringValue: (value: number, wheelIndex: number) => void
sliding: {
subscribe: (callback: (sliding: boolean) => void) => void
}
}Props
type InitProps = {
allowSleep?: boolean
axisIndex?: 0 | 1 | 2
broadphase?: Broadphase
defaultContactMaterial?: ContactMaterialOptions
gravity?: Triplet
iterations?: number
quatNormalizeFast?: boolean
quatNormalizeSkip?: number
solver?: Solver
tolerance?: number
}
type ProviderProps = InitProps & {
isPaused?: boolean
maxSubSteps?: number
shouldInvalidate?: boolean
size?: number
stepSize?: number
}
type AtomicProps = {
allowSleep: boolean
angularDamping: number
collisionFilterGroup: number
collisionFilterMask: number
collisionResponse: number
fixedRotation: boolean
isTrigger: boolean
linearDamping: number
mass: number
material: MaterialOptions
sleepSpeedLimit: number
sleepTimeLimit: number
userData: {}
}
type Broadphase = 'Naive' | 'SAP'
type Triplet = [x: number, y: number, z: number]
type Quad = [x: number, y: number, z: number, w: number]
type VectorProps = Record<VectorName, Triplet>
type BodyProps<T extends any[] = unknown[]> = Partial<AtomicProps> &
Partial<VectorProps> & {
args?: T
onCollide?: (e: CollideEvent) => void
onCollideBegin?: (e: CollideBeginEvent) => void
onCollideEnd?: (e: CollideEndEvent) => void
quaternion?: Quad
rotation?: Triplet
type?: 'Dynamic' | 'Static' | 'Kinematic'
}
type Event = RayhitEvent | CollideEvent | CollideBeginEvent | CollideEndEvent
type CollideEvent = {
op: string
type: 'collide'
body: THREE.Object3D
target: THREE.Object3D
contact: {
// the world position of the point of contact
contactPoint: number[]
// the normal of the collision on the surface of
// the colliding body
contactNormal: number[]
// velocity of impact along the contact normal
impactVelocity: number
// a unique ID for each contact event
id: string
// these are lower-level properties from cannon:
// bi: one of the bodies involved in contact
bi: THREE.Object3D
// bj: the other body involved in contact
bj: THREE.Object3D
// ni: normal of contact relative to bi
ni: number[]
// ri: the point of contact relative to bi
ri: number[]
// rj: the point of contact relative to bj
rj: number[]
}
collisionFilters: {
bodyFilterGroup: number
bodyFilterMask: number
targetFilterGroup: number
targetFilterMask: number
}
}
type CollideBeginEvent = {
op: 'event'
type: 'collideBegin'
target: Object3D
body: Object3D
}
type CollideEndEvent = {
op: 'event'
type: 'collideEnd'
target: Object3D
body: Object3D
}
type RayhitEvent = {
op: string
type: 'rayhit'
body: THREE.Object3D
target: THREE.Object3D
}
type CylinderArgs = [radiusTop?: number, radiusBottom?: number, height?: number, numSegments?: number]
type SphereArgs = [radius: number]
type TrimeshArgs = [vertices: ArrayLike<number>, indices: ArrayLike<number>]
type HeightfieldArgs = [
data: number[][],
options: { elementSize?: number; maxValue?: number; minValue?: number },
]
type ConvexPolyhedronArgs<V extends VectorTypes = VectorTypes> = [
vertices?: V[],
faces?: number[][],
normals?: V[],
axes?: V[],
boundingSphereRadius?: number,
]
interface PlaneProps extends BodyProps {}
interface BoxProps extends BodyProps<Triplet> {} // extents: [x, y, z]
interface CylinderProps extends BodyProps<CylinderArgs> {}
interface ParticleProps extends BodyProps {}
interface SphereProps extends BodyProps<SphereArgs> {}
interface TrimeshProps extends BodyPropsArgsRequired<TrimeshArgs> {}
interface HeightfieldProps extends BodyPropsArgsRequired<HeightfieldArgs> {}
interface ConvexPolyhedronProps extends BodyProps<ConvexPolyhedronArgs> {}
interface CompoundBodyProps extends BodyProps {
shapes: BodyProps & { type: ShapeType }[]
}
interface ConstraintOptns {
maxForce?: number
maxMultiplier?: number
collideConnected?: boolean
wakeUpBodies?: boolean
}
interface PointToPointConstraintOpts extends ConstraintOptns {
pivotA: Triplet
pivotB: Triplet
}
interface ConeTwistConstraintOpts extends ConstraintOptns {
pivotA?: Triplet
axisA?: Triplet
pivotB?: Triplet
axisB?: Triplet
angle?: number
twistAngle?: number
}
interface DistanceConstraintOpts extends ConstraintOptns {
distance?: number
}
interface HingeConstraintOpts extends ConstraintOptns {
pivotA?: Triplet
axisA?: Triplet
pivotB?: Triplet
axisB?: Triplet
}
interface LockConstraintOpts extends ConstraintOptns {}
interface SpringOptns {
restLength?: number
stiffness?: number
damping?: number
worldAnchorA?: Triplet
worldAnchorB?: Triplet
localAnchorA?: Triplet
localAnchorB?: Triplet
}
interface WheelInfoOptions {
radius?: number
directionLocal?: Triplet
suspensionStiffness?: number
suspensionRestLength?: number
maxSuspensionForce?: number
maxSuspensionTravel?: number
dampingRelaxation?: number
dampingCompression?: number
frictionSlip?: number
rollInfluence?: number
axleLocal?: Triplet
chassisConnectionPointLocal?: Triplet
isFrontWheel?: boolean
useCustomSlidingRotationalSpeed?: boolean
customSlidingRotationalSpeed?: number
}
interface RaycastVehicleProps {
chassisBody: React.Ref<THREE.Object3D>
wheels: React.Ref<THREE.Object3D>[]
wheelInfos: WheelInfoOptions[]
indexForwardAxis?: number
indexRightAxis?: number
indexUpAxis?: number
}FAQ
Broadphases
- NaiveBroadphase is as simple as it gets. It considers every body to be a potential collider with every other body. This results in the maximum number of narrowphase checks.
- SAPBroadphase sorts bodies along an axis and then moves down that list finding pairs by looking at body size and position of the next bodies. Control what axis to sort along by setting the axisIndex property.
Types
- A dynamic body is fully simulated. Can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass.
- A static body does not move during simulation and behaves as if it has infinite mass. Static bodies can be moved manually by setting the position of the body. The velocity of a static body is always zero. Static bodies do not collide with other static or kinematic bodies.
- A kinematic body moves under simulation according to its velocity. They do not respond to forces. They can be moved manually, but normally a kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass. Kinematic bodies do not collide with other static or kinematic bodies.