@react-three/cannon
    TypeScript icon, indicating that this package has built-in type declarations

    4.6.1 • Public • Published

    Build Status Version Downloads Discord Shield

    Imgur

    yarn add @react-three/cannon
    

    React 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 ./examples

    How it works

    1. Get all the imports that you need.
    import { Physics, useBox, ... } from '@react-three/cannon'
    1. Create a physics world.
    <Physics>{/* Physics related objects in here please */}</Physics>
    1. 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 }))
    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={...} />
    1. 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))
    1. 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',
      children,
      defaultContactMaterial = { contactEquationStiffness: 1e6 },
      gravity = [0, -9.81, 0],
      iterations = 5,
      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',
      step = 1 / 60,
      tolerance = 0.001,
    }: 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 = [],
    ): void

    Returned 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
      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 ProviderProps = React.PropsWithChildren<{
      shouldInvalidate?: boolean
      gravity?: Triplet
      tolerance?: number
      step?: number
      iterations?: number
      allowSleep?: boolean
      broadphase?: Broadphase
      axisIndex?: number
      defaultContactMaterial?: {
        friction?: number
        restitution?: number
        contactEquationStiffness?: number
        contactEquationRelaxation?: number
        frictionEquationStiffness?: number
        frictionEquationRelaxation?: number
      }
      size?: 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.

    Install

    npm i @react-three/cannon

    DownloadsWeekly Downloads

    18,843

    Version

    4.6.1

    License

    MIT

    Unpacked Size

    2.66 MB

    Total Files

    30

    Last publish

    Collaborators

    • bjornstar
    • codynova
    • drcmda
    • marcofugaro
    • stockhuman