@react-three/drei 8.18.9 → 9.0.0-beta.2

package/README.md

@@ -4,13 +4,13 @@
 [![Downloads](https://img.shields.io/npm/dt/@react-three/drei.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@react-three/drei)
 [![Discord Shield](https://img.shields.io/discord/740090768164651008?style=flat&colorA=000000&colorB=000000&label=discord&logo=discord&logoColor=ffffff)](https://discord.gg/poimandres)
 
-A growing collection of useful helpers and fully functional, ready-made abstractions for [react-three-fiber](https://github.com/pmndrs/react-three-fiber). If you make a component that is generic enough to be useful to others, think about making it available here through a PR!
+A growing collection of useful helpers and fully functional, ready-made abstractions for [@react-three/fiber](https://github.com/pmndrs/react-three-fiber). If you make a component that is generic enough to be useful to others, think about making it available here through a PR!
 
 ```bash
 npm install @react-three/drei
 ```
 
-:point_right: this package is using the stand-alone [`three-stdlib`](https://github.com/pmndrs/three-stdlib) instead of [`three/examples/jsm`](https://github.com/mrdoob/three.js/tree/dev/examples/jsm). :point_left:
+:point_right: this package is using the stand-alone [`three-stdlib`](https://github.com/pmndrs/three-stdlib) instead of [`three/examples/jsm`](https://github.com/mrdoob/three.js/tree/master/examples/jsm). :point_left:
 
 ### Basic usage:
 
@@ -65,8 +65,6 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#effects">Effects</a></li>
           <li><a href="#gradienttexture">GradientTexture</a></li>
           <li><a href="#edges">Edges</a></li>
-          <li><a href="#trail">Trail</a></li>
-          <li><a href="#clone">Clone</a></li>
           <li><a href="#useanimations">useAnimations</a></li>
         </ul>
         <li><a href="#shaders">Shaders</a></li>
@@ -101,8 +99,6 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#useaspect">useAspect</a></li>
           <li><a href="#usecursor">useCursor</a></li>
           <li><a href="#useintersect">useIntersect</a></li>
-          <li><a href="#useboxprojectedenv">useBoxProjectedEnv</a></li>
-          <li><a href="#useTrail">useTrail</a></li>
         </ul>
         <li><a href="#loading">Loaders</a></li>
         <ul>
@@ -163,7 +159,6 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#stage">Stage</a></li>
           <li><a href="#backdrop">Backdrop</a></li>
           <li><a href="#environment">Environment</a></li>
-          <li><a href="#lightformer">Lightformer</a></li>
           <li><a href="#spotlight">SpotLight</a></li>
           <li><a href="#shadow">Shadow</a></li>
           <li><a href="#contactshadows">ContactShadows</a></li>
@@ -184,7 +179,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/camera-perspectivecamera--perspective-camera-scene-st)
 
-A responsive [THREE.PerspectiveCamera](https://threejs.org/docs/index.html#api/en/cameras/PerspectiveCamera) that can set itself as the default.
+A responsive [THREE.PerspectiveCamera](https://threejs.org/docs/#api/en/cameras/PerspectiveCamera) that can set itself as the default.
 
 ```jsx
 <PerspectiveCamera makeDefault {...props} />
@@ -209,7 +204,7 @@ You can also drive it manually, it won't be responsive and you have to calculate
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/camera-orthographiccamera--orthographic-camera-scene-st)
 
-A responsive [THREE.OrthographicCamera](https://threejs.org/docs/index.html#api/en/cameras/OrthographicCamera) that can set itself as the default.
+A responsive [THREE.OrthographicCamera](https://threejs.org/docs/#api/en/cameras/OrthographicCamera) that can set itself as the default.
 
 ```jsx
 <OrthographicCamera makeDefault {...props}>
@@ -221,7 +216,7 @@ A responsive [THREE.OrthographicCamera](https://threejs.org/docs/index.html#api/
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/camera-cubecamera--default-story)
 
-A [THREE.CubeCamera](https://threejs.org/docs/index.html#api/en/cameras/CubeCamera) that returns its texture as a render-prop. It makes children invisible while rendering to the internal buffer so that they are not included in the reflection.
+A [THREE.CubeCamera](https://threejs.org/docs/#api/en/cameras/CubeCamera) that returns its texture as a render-prop. It makes children invisible while rendering to the internal buffer so that they are not included in the reflection.
 
 Using the `frames` prop you can control if this camera renders indefinitively or statically (a given number of times).
 If you have two static objects in the scene, make it `frames={2}` for instance, so that both objects get to "see" one another in the reflections, which takes multiple renders.
@@ -240,15 +235,15 @@ If you have moving objects, unset the prop and use a smaller `resolution` instea
 
 # Controls
 
-If available controls have damping enabled by default, they manage their own updates, remove themselves on unmount, are compatible with the `invalidateFrameloop` canvas-flag. They inherit all props from their underlying [THREE controls](https://github.com/mrdoob/three.js/tree/dev/examples/jsm/controls).
+If available controls have damping enabled by default, they manage their own updates, remove themselves on unmount, are compatible with the `invalidateFrameloop` canvas-flag. They inherit all props from their underlying [THREE controls](https://github.com/mrdoob/three.js/tree/master/examples/jsm/controls).
 
-Some controls allow you to set `makeDefault`, similar to, for instance, PerspectiveCamera. This will set react-three-fiber's `controls` field in the root store. This can make it easier in situations where you want controls to be known and other parts of the app could respond to it. Some drei controls already take it into account, like CameraShake, Gizmo and TransformControls.
+Some controls allow you to set `makeDefault`, similar to, for instance, PerspectiveCamera. This will set @react-three/fiber's `controls` field in the root store. This can make it easier in situations where you want controls to be known and other parts of the app could respond to it. Some drei controls already take it into account, like CameraShake, Gizmo and TransformControls.
 
 Drei currently exports OrbitControls [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/controls-orbitcontrols--orbit-controls-story), MapControls [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/controls-mapcontrols--map-controls-scene-st), TrackballControls, ArcballControls, FlyControls, DeviceOrientationControls, PointerLockControls [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/controls-pointerlockcontrols--pointer-lock-controls-scene-st), FirstPersonControls [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/controls-firstpersoncontrols--first-person-controls-story)
 
 All controls react to the default camera. If you have a `<PerspectiveCamera makeDefault />` in your scene, they will control it. If you need to inject an imperative camera or one that isn't the default, use the `camera` prop: `<OrbitControls camera={MyCamera} />`.
 
-PointerLockControls additionally supports a `selector` prop, which enables the binding of `click` event handlers for control activation to other elements than `document` (e.g. a 'Click here to play' button). All elements matching the `selector` prop will activate the controls. It will also center raycast events by default, so regular onPointerOver/etc events on meshes will continue to work.
+PointerLockControls additionally supports a `selector` prop, which enables the binding of `click` event handlers for control activation to other elements than `document` (e.g. a 'Click here to play' button). All elements matching the `selector` prop will activate the controls.
 
 # TransformControls
 
@@ -258,7 +253,7 @@ PointerLockControls additionally supports a `selector` prop, which enables the b
   <a href="https://codesandbox.io/s/btsbj"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/btsbj/screenshot.png" alt="Tranform controls"/></a>
 </p>
 
-An abstraction around [THREE.TransformControls](https://threejs.org/docs/index.html?q=transfor#examples/en/controls/TransformControls).
+An abstraction around [THREE.TransformControls](https://threejs.org/docs/#examples/en/controls/TransformControls).
 
 You can wrap objects which then receive a transform gizmo.
 
@@ -369,7 +364,7 @@ Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentati
   rotation={[0, 0, 0]} // Default rotation
   polar={[0, Math.PI / 2]} // Vertical limits
   azimuth={[-Infinity, Infinity]} // Horizontal limits
-  config={{ mass: 1, tension: 170, friction: 26 }} // Spring config
+  config = { mass: 1, tension: 170, friction: 26 } // Spring config
 >
   <mesh />
 </PresentationControls>
@@ -377,12 +372,12 @@ Semi-OrbitControls with spring-physics, polar zoom and snap-back, for presentati
 
 # Shapes
 
-[Buffer-geometry](https://threejs.org/docs/index.html#api/en/core/BufferGeometry) short-cuts for Plane, Box, Sphere, Circle, Cone, Cylinder, Tube, Torus, TorusKnot, Ring, Tetrahedron, Polyhedron, Icosahedron, Octahedron, Dodecahedron, Extrude, Lathe.
+[Buffer-geometry](https://threejs.org/docs/#api/en/core/BufferGeometry) short-cuts for Plane, Box, Sphere, Circle, Cone, Cylinder, Tube, Torus, TorusKnot, Ring, Tetrahedron, Polyhedron, Icosahedron, Octahedron, Dodecahedron, Extrude, Lathe.
 
 ```jsx
 <Plane args={[2, 2]} />
 <Sphere>
-  <meshBasicMaterial attach="material" color="hotpink" />
+  <meshBasicMaterial color="hotpink" />
 </Sphere>
 ```
 
@@ -392,7 +387,7 @@ A box buffer geometry with rounded corners, done with extrusion.
 
 ```jsx
 <RoundedBox args={[1, 1, 1]} radius={0.05} smoothness={4} {...meshProps}>
-  <meshPhongMaterial attach="material" color="#f3f3f3" wireframe />
+  <meshPhongMaterial color="#f3f3f3" wireframe />
 </RoundedBox>
 ```
 
@@ -440,7 +435,7 @@ function Foo() {
   <a href="https://codesandbox.io/s/yup2o"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/yup2o/screenshot.png" alt="Demo"/></a>
 </p>
 
-Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, using [troika-3d-text](https://github.com/protectwise/troika/tree/master/packages/troika-3d-text). All of troikas props are valid!
+Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, using [troika-3d-text](https://github.com/protectwise/troika/tree/master/packages/troika-3d-text). All of troikas props are valid! Text is suspense-based!
 
 ```jsx
 <Text color="black" anchorX="center" anchorY="middle">
@@ -448,14 +443,6 @@ Hi-quality text rendering w/ signed distance fields (SDF) and antialiasing, usin
 </Text>
 ```
 
-Text will suspend while loading the font data, but in order to completely avoid FOUC you can pass the characters it needs to render.
-
-```jsx
-<Text font={fontUrl} characters="abcdefghijklmnopqrstuvwxyz0123456789!">
-  hello world!
-</Text>
-```
-
 #### Line
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-line--basic-line)
@@ -542,7 +529,7 @@ Renders a THREE.Line2 using THREE.CubicBezierCurve3 for interpolation.
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-positionalaudio--positional-audio-scene-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
 
-A wrapper around [THREE.PositionalAudio](https://threejs.org/docs/index.html#api/en/audio/PositionalAudio). Add this to groups or meshes to tie them to a sound that plays when the camera comes near.
+A wrapper around [THREE.PositionalAudio](https://threejs.org/docs/#api/en/audio/PositionalAudio). Add this to groups or meshes to tie them to a sound that plays when the camera comes near.
 
 ```jsx
 <PositionalAudio
@@ -595,11 +582,11 @@ Make sure to set the `makeDefault` prop on your controls, in that case you do no
 
 #### Effects
 
-Abstraction around threes own [EffectComposer](https://threejs.org/docs/index.html#examples/en/postprocessing/EffectComposer).
+Abstraction around threes own [EffectComposer](https://threejs.org/docs/#examples/en/postprocessing/EffectComposer).
 
 ```jsx
 <Effects multisamping={8} renderIndex={1} disableGamma={false} disableRenderPass={false}>
-  <lUTPass attachArray="passes" lut={texture3D} />
+  <lUTPass attach="passes" lut={texture3D} />
 </Effects>
 ```
 
@@ -630,7 +617,7 @@ A declarative THREE.Texture which attaches to "map" by default. You can use this
   <a href="https://codesandbox.io/s/ny3p4"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/ny3p4/screenshot.png" alt="Demo"/></a>
 </p>
 
-Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/index.html?q=EdgesGeometry#api/en/geometries/EdgesGeometry). It pulls the geometry automatically from its parent, optionally you can ungroup it and give it a `geometry` prop. You can give it children, for instance a custom material.
+Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/#api/en/geometries/EdgesGeometry). It pulls the geometry automatically from its parent, optionally you can ungroup it and give it a `geometry` prop. You can give it children, for instance a custom material.
 
 ```jsx
 <mesh>
@@ -644,94 +631,6 @@ Abstracts [THREE.EdgesGeometry](https://threejs.org/docs/index.html?q=EdgesGeome
 </mesh>
 ```
 
-#### Trail
-
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-trail--use-trail-st)
-
-A declarative, `three.MeshLine` based Trails implementation. You can attach it to any mesh and it will give it a beautiful trail.
-
-Props defined bellow with their default values.
-
-```jsx
-<Trail
-  width={0.2} // Width of the line
-  color={'hotpink'} // Color of the line
-  length={1} // Length of the line
-  decay={1} // How fast the line fades away
-  local={false} // Wether to use the target's world or local positions
-  stride={0} // Min distance between previous and current point
-  interval={1} // Number of frames to wait before next calculation
-  target={undefined} // Optional target. This object will produce the trail.
-  attenuation={(width) => width} // A function to define the width in each point along it.
->
-  {/* If `target` is not defined, Trail will use the first `Object3D` child as the target. */}
-  <mesh>
-    <sphereGeometry />
-    <meshBasicMaterial />
-  </mesh>
-
-  {/* You can optionally define a custom meshLineMaterial to use. */}
-  {/* <meshLineMaterial color={"red"} /> */}
-</Trail>
-```
-
-👉 Inspired by [TheSpite's Codevember 2021 #9](https://spite.github.io/codevember-2021/9/)
-
-#### Clone
-
-<p>
-  <a href="https://codesandbox.io/s/42glz0"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/42glz0/screenshot.png" alt="Demo"/></a>
-</p>
-
-Declarative abstraction around THREE.Object3D.clone. This is useful when you want to create a shallow copy of an existing fragment (and Object3D, Groups, etc) into your scene, for instance a group from a loaded GLTF. This clone is now re-usable, but it will still refer to the original geometries and materials.
-
-```ts
-<Clone
-  /** Any pre-existing THREE.Object3D (groups, meshes, ...), or an array of objects */
-  object: THREE.Object3D | THREE.Object3D[]
-  /** Children will be placed within the object, or within the group that holds arrayed objects */
-  children?: React.ReactNode
-  /** Can clone materials and/or geometries deeply (default: false) */
-  deep?: boolean | 'materialsOnly' | 'geometriesOnly'
-  /** The property keys it will shallow-clone (material, geometry, visible, ...) */
-  keys?: string[]
-  /** Can either spread over props or fill in JSX children, applies to every mesh within */
-  inject?: MeshProps | React.ReactNode | ((object: THREE.Object3D) => React.ReactNode)
-  /** Short access castShadow, applied to every mesh within */
-  castShadow?: boolean
-  /** Short access receiveShadow, applied to every mesh within */
-  receiveShadow?: boolean
-/>
-```
-
-You create a shallow clone by passing a pre-existing object to the `object` prop.
-
-```jsx
-const { nodes } = useGLTF(url)
-return (
-  <Clone object={nodes.table} />
-```
-
-Or, multiple objects:
-
-```jsx
-<Clone object={[nodes.foo, nodes.bar]} />
-```
-
-You can dynamically insert objects, these will apply to anything that isn't a group or a plain object3d (meshes, lines, etc):
-
-```jsx
-<Clone object={nodes.table} inject={<meshStandardMaterial color="green" />} />
-```
-
-Or make inserts conditional:
-
-```jsx
-<Clone object={nodes.table} inject={
-  {(object) => (object.name === 'table' ? <meshStandardMaterial color="green" /> : null)}
-} />
-```
-
 #### useAnimations
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-useanimations--use-animations-st)
@@ -740,7 +639,7 @@ Or make inserts conditional:
   <a href="https://codesandbox.io/s/pecl6"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/pecl6/screenshot.png" alt="Demo"/></a>
 </p>
 
-A hook that abstracts [AnimationMixer](https://threejs.org/docs/index.html#api/en/animation/AnimationMixer).
+A hook that abstracts [AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer).
 
 ```jsx
 const { nodes, materials, animations } = useGLTF(url)
@@ -771,7 +670,7 @@ return <primitive object={scene} />
   <a href="https://codesandbox.io/s/l900i"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/l900i/screenshot.png" alt="Demo"/></a>
 </p>
 
-Easily add reflections and/or blur to any mesh. It takes surface roughness into account for a more realistic effect. This material extends from [THREE.MeshStandardMaterial](https://threejs.org/docs/index.html?q=meshsta#api/en/materials/MeshStandardMaterial) and accepts all its props.
+Easily add reflections and/or blur to any mesh. It takes surface roughness into account for a more realistic effect. This material extends from [THREE.MeshStandardMaterial](https://threejs.org/docs/#api/en/materials/MeshStandardMaterial) and accepts all its props.
 
 ```jsx
 <mesh>
@@ -809,8 +708,8 @@ This material makes your geometry wobble and wave around. It was taken from the
 
 ```jsx
 <mesh>
-  <boxBufferGeometry attach="geometry" />
-  <MeshWobbleMaterial attach="material" factor={1} speed={10} />
+  <boxGeometry />
+  <MeshWobbleMaterial factor={1} speed={10} />
 </mesh>
 ```
 
@@ -826,14 +725,14 @@ This material makes your geometry distort following simplex noise.
 
 ```jsx
 <mesh>
-  <boxBufferGeometry attach="geometry" />
-  <MeshDistortMaterial attach="material" distort={1} speed={10} />
+  <boxGeometry />
+  <MeshDistortMaterial distort={1} speed={10} />
 </mesh>
 ```
 
 #### PointMaterial
 
-Antialiased round dots. It takes the same props as regular THREE.PointsMaterial
+An antialiased round dot that always keeps the same size.
 
 ```jsx
 <points>
@@ -849,7 +748,7 @@ Antialiased round dots. It takes the same props as regular THREE.PointsMaterial
   <a href="https://codesandbox.io/s/dh2jc"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/dh2jc/screenshot.png" alt="Demo"/></a>
 </p>
 
-Injects [percent closer soft shadows (pcss)](https://threejs.org/examples/?q=pcss#webgl_shadowmap_pcss) into threes shader chunk.
+Injects [percent closer soft shadows (pcss)](https://threejs.org/examples/#webgl_shadowmap_pcss) into threes shader chunk.
 
 ```jsx
 softShadows({
@@ -872,7 +771,7 @@ softShadows({
 Creates a THREE.ShaderMaterial for you with easier handling of uniforms, which are also automatically declared as setter/getters on the object.
 
 ```jsx
-import { extend } from 'react-three-fiber'
+import { extend } from '@react-three/fiber'
 import glsl from 'babel-plugin-glsl/macro'
 
 const ColorShiftMaterial = shaderMaterial(
@@ -900,7 +799,7 @@ extend({ ColorShiftMaterial })
 
 // in your component
 <mesh>
-  <colorShiftMaterial attach="material" color="hotpink" time={1} />
+  <colorShiftMaterial color="hotpink" time={1} />
 </mesh>
 ```
 
@@ -910,7 +809,7 @@ extend({ ColorShiftMaterial })
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/modifiers-curvemodifier)
 
-Given a curve will replace the children of this component with a mesh that move along said curve calling the property `moveAlongCurve` on the passed ref. Uses [three's Curve Modifier](https://threejs.org/examples/?q=curve#webgl_modifier_curve)
+Given a curve will replace the children of this component with a mesh that move along said curve calling the property `moveAlongCurve` on the passed ref. Uses [three's Curve Modifier](https://threejs.org/examples/#webgl_modifier_curve)
 
 ```jsx
 const curveRef = useRef()
@@ -920,7 +819,7 @@ const curve = React.useMemo(() => new THREE.CatmullRomCurve3([...handlePos], tru
 return (
   <CurveModifier ref={curveRef} curve={curve}>
     <mesh>
-      <boxBufferGeometry args={[10, 10]} />
+      <boxGeometry args={[10, 10]} />
     </mesh>
   </CurveModifier>
 )
@@ -1147,7 +1046,7 @@ useHelper(condition && mesh, BoxHelper, 'red') // you can passe false instead of
 
 This hook uses [DetectGPU by @TimvanScherpenzeel](https://github.com/TimvanScherpenzeel/detect-gpu), wrapped into suspense, to determine what tier should be assigned to the user's GPU.
 
-👉 This hook CAN be used outside the react-three-fiber `Canvas`.
+👉 This hook CAN be used outside the @react-three/fiber `Canvas`.
 
 ```jsx
 function App() {
@@ -1174,7 +1073,7 @@ const scale = useAspect(
 )
 return (
   <mesh scale={scale}>
-    <planeBufferGeometry />
+    <planeGeometry />
     <meshBasicMaterial map={imageTexture} />
 ```
 
@@ -1197,63 +1096,13 @@ return (
   <a href="https://codesandbox.io/s/gsm1y"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/gsm1y/screenshot.png" alt="Demo"/></a>
 </p>
 
-A very cheap frustum check that gives you a reference you can observe in order to know if the object has entered the view or is outside of it. This relies on [THREE.Object3D.onBeforeRender](https://threejs.org/docs/index.html?q=obj#api/en/core/Object3D.onBeforeRender) so it only works on objects that are effectively rendered, like meshes, lines, sprites. It won't work on groups, object3d's, bones, etc.
+A very cheap frustum check that gives you a reference you can observe in order to know if the object has entered the view or is outside of it. This relies on [THREE.Object3D.onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender) so it only works on objects that are effectively rendered, like meshes, lines, sprites. It won't work on groups, object3d's, bones, etc.
 
 ```jsx
 const ref = useIntersect((visible) => console.log('object is visible', visible))
 return <mesh ref={ref} />
 ```
 
-#### useBoxProjectedEnv
-
-<p>
-  <a href="https://codesandbox.io/s/s006f"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/s006f/screenshot.png" alt="Demo"/></a>
-</p>
-
-The cheapest possible way of getting reflections in threejs. This will box-project the current environment map onto a plane. It returns an object that you need to spread over its material. The spread object contains a ref, onBeforeCompile and customProgramCacheKey. If you combine it with drei/CubeCamera you can "film" a single frame of the environment and feed it to the material, thereby getting realistic reflections at no cost. Align it with the position and scale properties.
-
-```jsx
-const projection = useBoxProjectedEnv(
-  [0, 0, 0], // Position
-  [1, 1, 1] // Scale
-)
-
-<CubeCamera frames={1}>
-  {(texture) => (
-    <mesh>
-      <planeGeometry />
-      <meshStandardMaterial envMap={texture} {...projection} />
-    </mesh>
-  )}
-</CubeCamera>
-```
-
-#### useTrail
-
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-trail--use-trail-st)
-
-A hook to obtain an array of points that make up a [Trail](#trail). You can use this array to drive your own `MeshLine` or make a trail out of anything you please.
-
-Note: The hook returns a ref (`MutableRefObject<Vector3[]>`) this means updates to it will not trigger a re-draw, thus keeping this cheap.
-
-```js
-const points = useTrail(
-  target, // Required target object. This object will produce the trail.
-  {
-    length, // Length of the line
-    decay, // How fast the line fades away
-    local, // Wether to use the target's world or local positions
-    stride, // Min distance between previous and current point
-    interval, // Number of frames to wait before next calculation
-  }
-)
-
-// To use...
-useFrame(() => {
-  meshLineRef.current.position.setPoints(points.current)
-})
-```
-
 # Loading
 
 #### Loader
@@ -1397,7 +1246,7 @@ const envMap = useCubeTexture(['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png',
   <a href="https://codesandbox.io/s/i6t0j"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/i6t0j/screenshot.png" alt="Demo"/></a>
 </p>
 
-A wrapper around [THREE.InstancedMesh](https://threejs.org/docs/index.html?q=instan#api/en/objects/InstancedMesh). This allows you to define hundreds of thousands of objects in a single draw call, but declaratively!
+A wrapper around [THREE.InstancedMesh](https://threejs.org/docs/#api/en/objects/InstancedMesh). This allows you to define hundreds of thousands of objects in a single draw call, but declaratively!
 
 ```jsx
 <Instances
@@ -1482,19 +1331,34 @@ function Model({ url }) {
 
 #### Points
 
-A wrapper around [THREE.Points](https://threejs.org/docs/index.html?q=points#api/en/objects/Points). It has the same api and properties as Instances.
+A wrapper around [THREE.Points](https://threejs.org/docs/#api/en/objects/Points). It has the same api and properties as Instances.
 
 ```jsx
 <Points
   limit={1000} // Optional: max amount of items (for calculating buffer size)
   range={1000} // Optional: draw-range
 >
-  <pointsMaterial vertexColors />
+  <pointsMaterial />
   <Point position={[1, 2, 3]} color="red" onClick={onClick} onPointerOver={onPointerOver} ... />
   // As many as you want, make them conditional, mount/unmount them, lazy load them, etc ...
 </Points>
 ```
 
+If you have a material that supports vertex colors (like drei/PointMaterial) you can have individual colors!
+
+```jsx
+<Points>
+  <PointMaterial />
+  <Point color="hotpink" />
+```
+
+Otherwise use any material you like:
+
+```jsx
+<Points>
+  <pointsMaterial vertexColors size={10} />
+```
+
 If you just want to use buffers for position, color and size, you can use the alternative API:
 
 ```jsx
@@ -1546,7 +1410,7 @@ useFrame(() => {
   <a href="https://codesandbox.io/s/12nmp"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/12nmp/screenshot.png" alt="Demo"/></a>
 </p>
 
-A wrapper around [THREE.LOD](https://threejs.org/docs/index.html#api/en/objects/LOD) (Level of detail).
+A wrapper around [THREE.LOD](https://threejs.org/docs/#api/en/objects/LOD) (Level of detail).
 
 ```jsx
 <Detailed distances={[0, 10, 20]} {...props}>
@@ -1558,7 +1422,7 @@ A wrapper around [THREE.LOD](https://threejs.org/docs/index.html#api/en/objects/
 
 #### Preload
 
-The WebGLRenderer will compile materials only when they hit the frustrum, which can cause jank. This component precompiles the scene using [gl.compile](https://threejs.org/docs/index.html#api/en/renderers/WebGLRenderer.compile) which makes sure that your app is responsive from the get go.
+The WebGLRenderer will compile materials only when they hit the frustrum, which can cause jank. This component precompiles the scene using [gl.compile](https://threejs.org/docs/#api/en/renderers/WebGLRenderer.compile) which makes sure that your app is responsive from the get go.
 
 By default gl.compile will only preload visible objects, if you supply the `all` prop, it will circumvent that. With the `scene` and `camera` props you could also use it in portals.
 
@@ -1592,7 +1456,7 @@ A very fast, but often good-enough bounds-only raycast for meshes. You can use t
 
 #### AdaptiveDpr
 
-Drop this component into your scene and it will cut the pixel-ratio on regress according to the canvas's performance min/max settings. This allows you to temporarily reduce visual quality in exchange for more performance, for instance when the camera moves (look into drei's controls regress flag). Optionally, you can set the canvas to a pixelated filter, which would be even faster.
+Drop this component into your scene and it will cut the pixel-ratio on [regress](#) according to the canvases perrformance min/max settings. This allows you to temporarily reduce visuals for more performance, for instance when the camera moves (look into drei's controls `regress` flag). Optionally you can set the canvas to a pixelated filter, which would be even faster.
 
 ```jsx
 <AdaptiveDpr pixelated />
@@ -1625,7 +1489,7 @@ useBVH(mesh)
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-center--default-story)
 
-Calculates a boundary box and centers its children accordingly. `alignTop` adjusts it so that it sits flush on y=0.
+Calculates a boundary box and centers its children accordingly. `alignTop` makes adjusts it so that it's sits flush on y=0.
 
 ```jsx
 <Center alignTop>
@@ -1639,10 +1503,10 @@ Calculates a boundary box and centers its children accordingly. `alignTop` adjus
   <a href="https://codesandbox.io/s/rz2g0"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/rz2g0/screenshot.png" alt="Demo"/></a>
 </p>
 
-Calculates a boundary box and centers the camera accordingly. If you are using controls, make sure to pass them the `makeDefault` prop. `fit` fits the current view on first render. `clip` sets the cameras near/far planes. `observe` will optionally use r3f's resize-observer to refresh bounds on resize.
+Calculates a boundary box and centers the camera accordingly. If you are using controls, make sure to pass them the `makeDefault` prop. `fit` fits the current view on first render. `clip` sets the cameras near/far planes.
 
 ```jsx
-<Bounds fit clip observe damping={6} margin={1.2}>
+<Bounds fit clip damping={6} margin={1.2}>
   <mesh />
 </Bounds>
 ```
@@ -1772,7 +1636,7 @@ A cheap canvas-texture-based circular gradient.
   <a href="https://codesandbox.io/s/qxjoj"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/qxjoj/screenshot.png" alt="Demo"/></a>
 </p>
 
-A [contact shadow](https://threejs.org/examples/?q=con#webgl_shadow_contact) implementation, facing upwards (positive Y) by default. `scale` can be a positive number or a 2D array `[x: number, y: number]`.
+A [contact shadow](https://threejs.org/examples/#webgl_shadow_contact) implementation, facing upwards (positive Y) by default. `scale` can be a positive number or a 2D array `[x: number, y: number]`.
 
 ```jsx
 <ContactShadows opacity={1} scale={10} blur={1} far={10} resolution={256} />
@@ -1816,9 +1680,6 @@ function Foo() {
 
 <p>
   <a href="https://codesandbox.io/s/t4l0f"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/t4l0f/screenshot.png" alt="Demo"/></a>
-  <a href="https://codesandbox.io/s/mih0lx"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/mih0lx/screenshot.png" alt="Demo"/></a>
-  <a href="https://codesandbox.io/s/e662p3"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/e662p3/screenshot.png" alt="Demo"/></a>
-  <a href="https://codesandbox.io/s/lwo219"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/lwo219/screenshot.png" alt="Demo"/></a>
 </p>
 
 Sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`, unless a custom scene has been passed. A selection of [presets](src/helpers/environment-assets.ts) from [HDRI Haven](https://hdrihaven.com/) are available for convenience. If you pass an array of files it will use THREE.CubeTextureLoader.
@@ -1827,11 +1688,11 @@ Sets up a global cubemap, which affects the default `scene.environment`, and opt
 
 ```jsx
 <Environment
-  background={false} // can be true, false or "only" (which only sets the background) (default: false)
+  background={false}
   files={['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']}
   path="/"
   preset={null}
-  scene={undefined} // adds the ability to pass a custom THREE.Scene, can also be a ref
+  scene={undefined} // adds the ability to pass a custom THREE.Scene
 />
 ```
 
@@ -1841,60 +1702,6 @@ If you provide a single string it will use THREE.RGBELoader.
 <Environment files="file.hdr" />
 ```
 
-If you already have a cube texture you can pass it directly:
-
-```jsx
-<CubeCamera>{(texture) => <Environment map={texture} />}</CubeCamera>
-```
-
-If you provide children you can even render a custom environment. It will render the contents into an off-buffer and film a single frame with a cube camera (whose props you can configure: near=1, far=1000, resolution=256).
-
-```jsx
-<Environment background near={1} far={1000} resolution={256}>
-  <mesh scale={100}>
-    <sphereGeometry args={[1, 64, 64]} />
-    <meshBasicMaterial map={texture} side={THREE.BackSide} />
-  </mesh>
-</Environment>
-```
-
-You can even mix a generic HDRI environment into a custom one with either the `preset` or the `files` prop.
-
-```jsx
-return (
-  <Environment background near={1} far={1000} resolution={256} preset="warehouse">
-    <mesh />
-```
-
-Declarative environment content can also animate with the `frames` prop, the envmap can be live. Give it a low resolution and this will happen at very little cost
-
-```jsx
-return (
-  <Environment frames={Infinity} resolution={256}>
-    <Float>
-      <mesh />
-    </Float>
-```
-
-#### Lightformer
-
-<p>
-  <a href="https://codesandbox.io/s/lwo219"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/lwo219/screenshot.png" alt="Demo"/></a>
-</p>
-
-This component draws flat rectangles, circles or rings, mimicking the look of a light-former. You can set the output `intensity`, which will effect emissiveness once you put it into an HDRI `<Environment>`, where it mostly belong. It will act like a real light without the expense, you can have as many as you want.
-
-```jsx
-<Environment>
-  <Lightformer
-    form="rect" // circle | ring | rect (optional, default = rect)
-    intensity={1} // power level (optional = 1)
-    color="white" // (optional = white)
-    scale={[10, 5]} // Scale it any way you prefer (optional = [1, 1])
-    target={[0, 0, 0]} // Target position (optional = undefined)
-  />
-```
-
 #### Sky
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-sky--sky-st)
@@ -1903,7 +1710,7 @@ This component draws flat rectangles, circles or rings, mimicking the look of a
   <a href="https://codesandbox.io/s/vkgi6"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/vkgi6/screenshot.png" alt="Demo"/></a>
 </p>
 
-Adds a [sky](https://threejs.org/examples/webgl_shaders_sky.html) to your scene.
+Adds a [sky](https://threejs.org/examples/#webgl_shaders_sky) to your scene.
 
 ```jsx
 <Sky distance={450000} sunPosition={[0, 1, 0]} inclination={0} azimuth={0.25} {...props} />