Nybble Processing Mainframe

    react-three-cambrian
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.11 • Public • Published

    Version 3.x is out 🎉 🎊 🥳

    Find out here about the changes. TLDR: bugfixes, new features, react-native, better types, very few breaking changes (mostly just useRender -> useFrame and apply -> extend).




    These demos are real, you can click them! They contain the full code, too.

    npm install three react-three-fiber
    

    React-three-fiber is a renderer for Threejs on the web and react-native. Why? Building a dynamic scene graph becomes so much easier when you can break it up into declarative, re-usable, reactive components. It also opens up the ecosystem, you can apply generic packages for state, animation, gestures and so on. This is less of an abstraction and more of a pure reconciler (think react-dom in relation to HTML). It does not target a specific Threejs version nor does it need updates when Threejs alters, adds or removes features, it won't change any specifics or rules, and there are zero limitations.

    What it looks like ...

    Copy the following into a project to get going. Here's the same running in a code sandbox.

    import { Canvas, useFrame } from 'react-three-fiber'
     
    function Thing() {
      const ref = useRef()
      useFrame(() => (ref.current.rotation.z += 0.01))
      return (
        <mesh
          ref={ref}
          onClick={e => console.log('click')}
          onPointerOver={e => console.log('hover')}
          onPointerOut={e => console.log('unhover')}>
          <planeBufferGeometry attach="geometry" args={[1, 1]} />
          <meshBasicMaterial attach="material" color="hotpink" opacity={0.5} transparent />
        </mesh>
      )
    }
     
    <Canvas>
      <Thing />
    </Canvas>

    Canvas

    The Canvas object is your portal into Threejs. It renders Threejs elements, not DOM elements!

    <Canvas
      children                      // Either a function child (which receives stateor regular children
      gl                            // Props that go into the default webGL-renderer
      camera                        // Props that go into the default camera
      raycaster                     // Props that go into the default raycaster
      shadowMap                     // Props that go into gl.shadowMapcan also be set true for PCFsoft
      vr = false                    // Switches renderer to VR modethen uses gl.setAnimationLoop
      orthographic = false          // Creates an orthographic camera if true
      noEvents = false              // Switch off raytracing and event support
      pixelRation = undefined        // You could provide window.devicePixelRatio if you like
      invalidateFrameloop = false   // When true it only renders on changeswhen false it's a game loop
      updateDefaultCamera = true    // Adjusts default camera on size changes
      onCreated                     // Callback when vdom is ready (you can block first render via promise)
      onPointerMissed />            // Response for pointer clicks that have missed a target

    You can give it additional properties like style and className, which will be added to the container (a div) that holds the dom-canvas element.

    Defaults that the canvas component sets up

    Canvas will create a translucent WebGL-renderer with the following properties: antialias, alpha, setClearAlpha(0)

    A default perspective camera: fov: 75, near: 0.1, far: 1000, position.z: 5

    A default orthographic camera if Canvas.orthographic is true: near: 0.1, far: 1000, position.z: 5

    A default shadowMap if Canvas.shadowMap is true: type: PCFSoftShadowMap

    A default scene (into which all the JSX is rendered) and a raycaster.

    You do not have to use any of these objects, look under "receipes" down below if you want to bring your own.

    Objects and properties

    You can use Threejs's entire object catalogue and all properties. When in doubt, always consult the docs.

    You could lay out an object like this:

    <mesh
      visible
      userData={{ test: 'hello' }}
      position={new THREE.Vector3(1, 2, 3)}
      rotation={new THREE.Euler(0, 0, 0)}
      geometry={new THREE.SphereGeometry(1, 16, 16)}
      material={new THREE.MeshBasicMaterial({ color: new THREE.Color('hotpink'), transparent: true })}
    />

    The problem is that all of these properties will always be re-created. Instead, you should define properties declaratively.

    <mesh visible userData={{ test: 'hello' }} position={[1, 2, 3]} rotation={[0, 0, 0]}>
      <sphereGeometry attach="geometry" args={[1, 16, 16]} />
      <meshStandardMaterial attach="material" color="hotpink" transparent />
    </mesh>

    Shortcuts (set)

    All properties that have a .set() method can be given a shortcut. For example THREE.Color.set can take a color string, hence instead of color={new THREE.Color('hotpink')} you can do color="hotpink". Some set methods take multiple arguments (THREE.Vector3.set), so you can pass an array position={[100, 0, 0]}.

    Shortcuts and non-Object3D stow-away

    Stow away non-Object3D primitives (geometries, materials, etc) into the render tree so that they become managed and reactive. They take the same properties they normally would, constructor arguments are passed with args. Using the attach property objects bind automatically to their parent and are taken off it once they unmount.

    You can nest primitive objects, too, which is good for awaiting async textures and such. You could use React-suspense if you wanted!

    <meshBasicMaterial attach="material">
      <texture attach="map" image={img} onUpdate={self => img && (self.needsUpdate = true)} />

    Sometimes attaching isn't enough. For example, this code attaches effects to an array called "passes" of the parent effectComposer. Note the use of attachArray which adds the object to the target array and takes it out on unmount:

    <effectComposer>
      <renderPass attachArray="passes" scene={scene} camera={camera} />
      <glitchPass attachArray="passes" renderToScreen />

    You can also attach to named parent properties using attachObject={[target, name]}, which adds the object and takes it out on unmount. The following adds a buffer-attribute to parent.attributes.position.

    <bufferGeometry attach="geometry">
      <bufferAttribute attachObject={['attributes', 'position']} count={v.length / 3} array={v} itemSize={3} />

    Piercing into nested properties

    If you want to reach into nested attributes (for instance: mesh.rotation.x), just use dash-case:

    <mesh rotation-x={1} material-uniforms-resolution-value={[1 / size.width, 1 / size.height]} />

    Putting already existing objects into the scene-graph

    You can use the primitive placeholder for that. You can still give it properties or attach nodes to it.

    const mesh = new THREE.Mesh()
    return <primitive object={mesh} position={[0, 0, 0]} />

    Using 3rd-party (non THREE namespaced) objects in the scene-graph

    The extend function extends three-fibers catalogue of known native JSX elements.

    import { extend } from 'react-three-fiber'
    import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'
    import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass'
    extend({ EffectComposer, RenderPass })
     
    <effectComposer>
      <renderPass />

    Events

    Threejs objects that implement their own raycast method (meshes, lines, etc) can be interacted with by declaring events on the object. We support pointer events (you need to polyfill them yourself), clicks and wheel-scroll. Events contain the browser event as well as the Threejs event data (object, point, distance, etc).

    Additionally there's a special onUpdate that is called every time the object gets fresh props, which is good for things like self => (self.verticesNeedUpdate = true).

    <mesh
      onClick={e => console.log('click')}
      onWheel={e => console.log('wheel spins')}
      onPointerUp={e => console.log('up')}
      onPointerDown={e => console.log('down')}
      onPointerOver={e => console.log('hover')}
      onPointerOut={e => console.log('unhover')}
      onPointerMove={e => console.log('move')}
      onUpdate={self => console.log('props have been updated')}
    />

    Event data

    ({
      ...DomEvent                   // All the original event data
      ...ThreeEvent                 // All of Three's intersection data
      object: Object3D              // The object that was actually hit
      eventObject: Object3D         // The object that registered the event
      unprojectedPoint: Vector3     // Camera-unprojected point
      ray: Ray                      // The ray that was used to strike the object
      sourceEvent: DomEvent         // A reference to the host event
      delta: number                 // Initial-click delta
    }) => ...

    Propagation and capturing

      onPointerDown={e => {
        // Only the mesh closest to the camera will be processed
        e.stopPropagation()
        // You may optionally capture the target
        e.target.setPointerCapture(e.pointerId)
      }}
      onPointerUp={e => {
        e.stopPropagation()
        // Optionally release capture
        e.target.releasePointerCapture(e.pointerId)
      }}

    Hooks

    Hooks can only be used inside the Canvas element because they rely on context! You cannot expect something like this to work:

    function App() {
      const { size } = useThree() // This will just crash
      return (
        <Canvas>
          <mesh>

    Do this instead:

    function SomeComponent() {
      const { size } = useThree()
      return <mesh />
    }
     
    function App() {
      return (
        <Canvas>
          <SomeComponent />

    useThree(): SharedCanvasContext

    This hooks gives you access to all the basic objects that are kept internally, like the default renderer, scene, camera. It also gives you the current size of the canvas in screen and viewport coordinates.

    import { useThree } from 'react-three-fiber'
     
    const {
      gl,                           // WebGL renderer 
      canvas,                       // canvas the dom element that was created
      scene,                        // Default scene
      camera,                       // Default camera
      size,                         // Bounds of the view (which stretches 100% and auto-adjusts)
      viewport,                     // Bounds of the viewport in 3d units + factor (size/viewport)
      aspect,                       // Aspect ratio (size.width / size.height)
      mouse,                        // Current 2D mouse coordinates
      clock,                        // THREE.Clock (usefull for useFrame deltas)
      invalidate,                   // Invalidates a single frame (for <Canvas invalidateFrameloop />)
      intersect,                    // Calls onMouseMove handlers for objects underneath the cursor
      setDefaultCamera,             // Sets the default camera
    = useThree()

    useFrame(callback: (state, delta) => void, renderPriority: number = 0)

    This hooks calls you back every frame, which is good for running effects, updating controls, etc. You receive the state (same as useThree) and a clock delta. If you supply a render priority greater than zero it will switch off automatic rendering entirely, you can then control rendering yourself. If you have multiple frames with a render priority then they are ordered highest priority last, similar to the web's z-index. Frames are managed, three-fiber will remove them automatically when the component that holds them is unmounted.

    Updating controls:

    import { useFrame } from 'react-three-fiber'
     
    const controls = useRef()
    useFrame(state => controls.current.update())
    return <orbitControls ref={controls} />

    Taking over the render-loop:

    useFrame(({ gl, scene, camera }) => gl.render(scene, camera), 1)

    useResource(optionalRef=undefined)

    When you want to share and re-use resources. useResource creates a ref and re-renders the component when it becomes available next frame.

    import { useResource } from 'react-three-fiber'
     
    const [ref, material] = useResource()
    return (
      <meshBasicMaterial ref={ref} />
      {material && (
        <mesh material={material} />
        <mesh material={material} />
        <mesh material={material} />

    useUpdate(callback, dependencies, optionalRef=undefined)

    When objects need to be updated imperatively.

    import { useUpdate } from 'react-three-fiber'
     
    const ref = useUpdate(
      geometry => {
        geometry.addAttribute('position', getVertices(x, y, z))
        geometry.attributes.position.needsUpdate = true
      },
      [x, y, z] // execute only if these properties change
    )
    return <bufferGeometry ref={ref} />

    useLoader(loader, url, [extensions]) (experimental!)

    This hooks loads assets and suspends for easier fallback- and error-handling. It returns two values, the asset itself and a look-up-table of props. If you need to lay out GLTF's declaratively check out gltfjsx.

    import React, { Suspense } from 'react'
    import { useLoader } from 'react-three-fiber'
    import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'
    import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader'
     
    function Asset({ url }) {
      const [gltf] = useLoader(GLTFLoader, url, loader => {
        const dracoLoader = new DRACOLoader()
        dracoLoader.setDecoderPath('/draco-gltf/')
        loader.setDRACOLoader(dracoLoader)
      })
      return <primitive object={gltf.scene} />
    }
     
    <Suspense fallback={<Cube />}>
      <Asset url="/spaceship.gltf" />
    </Suspense>

    Additional exports

    import {
      addEffect,                    // Adds a global callback which is called each frame
      invalidate,                   // Forces view global invalidation
      apply,                        // Extends the native-object catalogue
      createPortal,                 // Creates a portal (it's a React feature for re-parenting)
      render,                       // Internal: Renders three jsx into a scene
      unmountComponentAtNode,       // Internal: Unmounts root scene
      applyProps,                   // Internal: Sets element properties
    } from 'react-three-fiber'

    Further information

    Recipes and FAQ: /react-three-fiber/recipes.md

    GLTF-to-JSX converter: https://github.com/react-spring/gltfjsx

    Learn-with-jason: https://www.youtube.com/watch?v=1rP3nNY2hTo

    Contributions

    If you like this project, please consider helping out. All contributions are welcome as well as donations to Opencollective, or in crypto:

    BTC: 36fuguTPxGCNnYZSRdgdh6Ea94brCAjMbH

    ETH: 0x6E3f79Ea1d0dcedeb33D3fC6c34d2B1f156F2682

    Sponsors

    Backers

    Thank you to all our backers! 🙏

    Contributors

    This project exists thanks to all the people who contribute.

    Install

    npm i react-three-cambrian

    DownloadsWeekly Downloads

    0

    Version

    0.0.11

    License

    MIT

    Unpacked Size

    287 kB

    Total Files

    43

    Last publish

    Collaborators

    • cambrian