@react-three/drei 9.68.5 → 9.69.0

package/README.md

@@ -105,6 +105,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#html">Html</a></li>
           <li><a href="#cycleraycast">CycleRaycast</a></li>
           <li><a href="#select">Select</a></li>
+          <li><a href="#spriteanimator">Sprite Animator</a></li>
           <li><a href="#stats">Stats</a></li>
           <li><a href="#wireframe">Wireframe</a></li>
           <li><a href="#usedepthbuffer">useDepthBuffer</a></li>
@@ -2077,6 +2078,69 @@ function Foo() {
   const selected = useSelect()
 ```
 
+#### Sprite Animator
+
+![](https://img.shields.io/badge/-Dom only-red)
+
+<p>
+  <a href="https://codesandbox.io/s/r3f-sprite-animator-s12ijv"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/s12ijv/screenshot.png" alt="Demo"/></a>
+</p>
+
+```tsx
+type Props = {
+  /** The start frame of the animation */
+  startFrame?: number
+  /** The end frame of the animation */
+  endFrame?: number
+  /** The desired frames per second of the animaiton */
+  fps?: number
+  /** The frame identifier to use, has to be one of animationNames */
+  frameName?: string
+  /** The scale factor of the aspect ratio */
+  scaleFactor?: number
+  /** The URL of the texture JSON (if using JSON-Array or JSON-Hash) */
+  textureDataURL?: string
+  /** The URL of the texture image */
+  textureImageURL?: string
+  /** Whether or not the animation should loop */
+  loop?: boolean
+  /** The number of frames of the animation (required if using plain spritesheet without JSON) */
+  numberOfFrames?: number
+  /** Whether or not the animation should auto-start when all assets are loaded */
+  autoPlay?: boolean
+  /** The animation names of the spritesheet (if the spritesheet -with JSON- contains more animation sequences) */
+  animationNames?: Array<string>
+  /** Event callback when the animation starts */
+  onStart?: Function
+  /** Event callback when the animation ends */
+  onEnd?: Function
+  /** Event callback when the animation loops */
+  onLoopEnd?: Function
+  /** Event callback when each frame changes */
+  onFrame?: Function
+  /** Control when the animation runs */
+  play?: boolean
+  /** Control when the animation pauses */
+  pause?: boolean
+}
+```
+
+The SpriteAnimator component provided by drei is a powerful tool for animating sprites in a simple and efficient manner. It allows you to create sprite animations by cycling through a sequence of frames from a sprite sheet image or JSON data.
+Notes:
+The SpriteAnimator component internally uses the useFrame hook from react-three-fiber (r3f) for efficient frame updates and rendering.
+
+```jsx
+<SpriteAnimator
+  position={[-3.5, -2.0, 2.5]}
+  startFrame={0}
+  scaleFactor={0.125}
+  autoPlay={true}
+  loop={true}
+  numberOfFrames={16}
+  textureImageURL={'./alien.png'}
+/>
+```
+
 #### Stats
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/misc-stats--default-story)

package/core/SpriteAnimator.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("react"),r=require("@react-three/fiber"),t=require("three");function n(e){if(e&&e.__esModule)return e;var r=Object.create(null);return e&&Object.keys(e).forEach((function(t){if("default"!==t){var n=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(r,t,n.get?n:{enumerable:!0,get:function(){return e[t]}})}})),r.default=e,Object.freeze(r)}var a=n(e),u=n(t);exports.SpriteAnimator=({startFrame:e,endFrame:t,fps:n,frameName:c,scaleFactor:s,maxScale:o,textureDataURL:f,textureImageURL:i,loop:m,numberOfFrames:l,autoPlay:p,animationNames:h,onStart:w,onEnd:y,onLoopEnd:d,onFrame:S,play:g,pause:x,flipX:b,alphaTest:z,children:F,...A},E)=>{const O=r.useThree((e=>e.viewport)),R=a.useRef(null),[j,v]=a.useState(!1),L=a.useRef(),P=a.useRef(),T=a.useRef(window.performance.now()),M=a.useRef(),N=a.useRef(e||0),k=a.useRef(c||""),_=1e3/(n||30),[q,C]=a.useState(new u.Texture),D=a.useRef(0),[I,U]=a.useState([1,1,1]),W=s||.1,X=b?-1:1;const B=(e,r,t)=>{const n=r*(O.aspect>e/r?O.width/e:O.height/r),a=e*(O.aspect>e/r?O.width/e:O.height/r)*t,u=n*t,c=null!=o?o:1;let s=Math.min(c,a),f=Math.min(c,u);return a>c&&(s=c,f=u/a*c),P.current.scale.set(s,f,1),[s,f,1]};a.useEffect((()=>{if(f&&i)!function(e,r,t){const n=new u.TextureLoader,a=fetch(e).then((e=>e.json())),c=new Promise((e=>{n.load(r,e)}));Promise.all([a,c]).then((e=>{t(e[0],e[1])}))}(f,i,G);else if(i){const e=new u.TextureLoader;new Promise((r=>{e.load(i,r)})).then((e=>{G(null,e)}))}}),[]),a.useLayoutEffect((()=>{J()}),[q]),a.useEffect((()=>{}),[x]),a.useEffect((()=>{k.current!==c&&c&&(N.current=0,k.current=c)}),[c]);const G=(e,r)=>{if(null===e){if(r&&l){const e=r.image.width,t=r.image.height,n=e/l,a=t;if(M.current=r,D.current=l,R.current={frames:[],meta:{version:"1.0",size:{w:e,h:t},scale:"1"}},parseInt(n.toString(),10)===n)for(let e=0;e<l;e++)R.current.frames.push({frame:{x:e*n,y:0,w:n,h:a},rotated:!1,trimmed:!1,spriteSourceSize:{x:0,y:0,w:n,h:a},sourceSize:{w:n,h:t}})}}else if(r){R.current=e,R.current.frames=Array.isArray(e.frames)?e.frames:H(),D.current=Array.isArray(e.frames)?e.frames.length:Object.keys(e.frames).length,M.current=r;const{w:t,h:n}=K(e.frames).sourceSize,a=B(t,n,W);U(a),L.current&&(L.current.map=r)}r.premultiplyAlpha=!1,C(r)},H=()=>{const e={},r=R.current,t=h;if(t)for(let n=0;n<t.length;n++){e[t[n]]=[];for(let a in r.frames){const u=r.frames[a],c=u.frame,s=c.x,o=c.y,f=c.w,i=c.h,m=u.sourceSize.w,l=u.sourceSize.h;"string"==typeof a&&-1!==a.toLowerCase().indexOf(t[n].toLowerCase())&&e[t[n]].push({x:s,y:o,w:f,h:i,frame:c,sourceSize:{w:m,h:l}})}}return e},J=()=>{if(!R.current)return;const{meta:{size:e},frames:r}=R.current,{w:t,h:n}=Array.isArray(r)?r[0].sourceSize:c&&r[c]?r[c][0].sourceSize:{w:0,h:0};L.current.map.wrapS=L.current.map.wrapT=u.RepeatWrapping,L.current.map.center.set(0,0),L.current.map.repeat.set(1*X/(e.w/t),1/(e.h/n));const a=1/((e.h-1)/n);L.current.map.offset.x=0,L.current.map.offset.y=1-a,v(!0),w&&w({currentFrameName:c,currentFrame:N.current})};r.useFrame(((r,n)=>{var a,u;null!=(a=R.current)&&a.frames&&null!=(u=L.current)&&u.map&&(x||(p||g)&&((()=>{const r=window.performance.now(),n=r-T.current,{meta:{size:a},frames:u}=R.current,{w:s,h:o}=K(u).sourceSize,f=Array.isArray(u)?u:c?u[c]:[];let i=0,l=0;const p=t||f.length-1;if(N.current>p&&(N.current=m&&null!=e?e:0,m?null==d||d({currentFrameName:c,currentFrame:N.current}):null==y||y({currentFrameName:c,currentFrame:N.current}),!m))return;if(n<=_)return;T.current=r-n%_,B(s,o,W);const h=(a.w-1)/s,w=(a.h-1)/o,{frame:{x:S,y:g},sourceSize:{w:x,h:b}}=f[N.current],z=1/h,F=1/w;i=X>0?z*(S/x):z*(S/x)-L.current.map.repeat.x,l=Math.abs(1-F)-F*(g/b),L.current.map.offset.x=i,L.current.map.offset.y=l,N.current+=1})(),S&&S({currentFrameName:k.current,currentFrame:N.current})))}));const K=e=>{if(Array.isArray(e))return e[0];if("object"==typeof e&&null!==e){return e[Object.keys(e)[0]][0]}return{w:0,h:0}};return a.createElement("group",A,a.createElement(a.Suspense,{fallback:null},a.createElement("sprite",{ref:P,scale:I},a.createElement("spriteMaterial",{ref:L,map:q,premultipliedAlpha:!1,transparent:!0,alphaTest:null!=z?z:0}))),F)};

package/core/SpriteAnimator.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export declare type SpriteAnimatorProps = {
+    startFrame?: number;
+    endFrame?: number;
+    fps?: number;
+    frameName?: string;
+    scaleFactor?: number;
+    maxScale?: number;
+    textureDataURL?: string;
+    textureImageURL: string;
+    loop?: boolean;
+    numberOfFrames?: number;
+    autoPlay?: boolean;
+    animationNames?: Array<string>;
+    onStart?: Function;
+    onEnd?: Function;
+    onLoopEnd?: Function;
+    onFrame?: Function;
+    play?: boolean;
+    pause?: boolean;
+    flipX?: boolean;
+    position?: Array<number>;
+    alphaTest?: number;
+} & JSX.IntrinsicElements['group'];
+export declare const SpriteAnimator: React.FC<SpriteAnimatorProps>;

package/core/SpriteAnimator.js

@@ -0,0 +1,358 @@
+import * as React from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+
+const SpriteAnimator = ({
+  startFrame,
+  endFrame,
+  fps,
+  frameName,
+  scaleFactor,
+  maxScale,
+  textureDataURL,
+  textureImageURL,
+  loop,
+  numberOfFrames,
+  autoPlay,
+  animationNames,
+  onStart,
+  onEnd,
+  onLoopEnd,
+  onFrame,
+  play,
+  pause,
+  flipX,
+  alphaTest,
+  children,
+  ...props
+}, fref) => {
+  const v = useThree(state => state.viewport);
+  const spriteData = React.useRef(null);
+  const [isJsonReady, setJsonReady] = React.useState(false);
+  const matRef = React.useRef();
+  const spriteRef = React.useRef();
+  const timerOffset = React.useRef(window.performance.now());
+  const textureData = React.useRef();
+  const currentFrame = React.useRef(startFrame || 0);
+  const currentFrameName = React.useRef(frameName || '');
+  const fpsInterval = 1000 / (fps || 30);
+  const [spriteTexture, setSpriteTexture] = React.useState(new THREE.Texture());
+  const totalFrames = React.useRef(0);
+  const [aspect, setAspect] = React.useState([1, 1, 1]);
+  const aspectFactor = scaleFactor || 0.1;
+  const flipOffset = flipX ? -1 : 1;
+
+  function loadJsonAndTextureAndExecuteCallback(jsonUrl, textureUrl, callback) {
+    const textureLoader = new THREE.TextureLoader();
+    const jsonPromise = fetch(jsonUrl).then(response => response.json());
+    const texturePromise = new Promise(resolve => {
+      textureLoader.load(textureUrl, resolve);
+    });
+    Promise.all([jsonPromise, texturePromise]).then(response => {
+      callback(response[0], response[1]);
+    });
+  }
+
+  const calculateAspectRatio = (width, height, factor) => {
+    const adaptedHeight = height * (v.aspect > width / height ? v.width / width : v.height / height);
+    const adaptedWidth = width * (v.aspect > width / height ? v.width / width : v.height / height);
+    const scaleX = adaptedWidth * factor;
+    const scaleY = adaptedHeight * factor;
+    const currentMaxScale = maxScale !== null && maxScale !== void 0 ? maxScale : 1; // Calculate the maximum scale based on the aspect ratio and max scale limit
+
+    let finalMaxScaleW = Math.min(currentMaxScale, scaleX);
+    let finalMaxScaleH = Math.min(currentMaxScale, scaleY); // Ensure that scaleX and scaleY do not exceed the max scale while maintaining aspect ratio
+
+    if (scaleX > currentMaxScale) {
+      finalMaxScaleW = currentMaxScale;
+      finalMaxScaleH = scaleY / scaleX * currentMaxScale;
+    }
+
+    spriteRef.current.scale.set(finalMaxScaleW, finalMaxScaleH, 1);
+    return [finalMaxScaleW, finalMaxScaleH, 1];
+  }; // initial loads
+
+
+  React.useEffect(() => {
+    if (textureDataURL && textureImageURL) {
+      loadJsonAndTextureAndExecuteCallback(textureDataURL, textureImageURL, parseSpriteData);
+    } else if (textureImageURL) {
+      // only load the texture, this is an image sprite only
+      const textureLoader = new THREE.TextureLoader();
+      new Promise(resolve => {
+        textureLoader.load(textureImageURL, resolve);
+      }).then(texture => {
+        parseSpriteData(null, texture);
+      });
+    }
+  }, []);
+  React.useLayoutEffect(() => {
+    modifySpritePosition();
+  }, [spriteTexture]);
+  React.useEffect(() => {
+  }, [pause]);
+  React.useEffect(() => {
+    if (currentFrameName.current !== frameName && frameName) {
+      currentFrame.current = 0;
+      currentFrameName.current = frameName;
+    }
+  }, [frameName]);
+
+  const parseSpriteData = (json, _spriteTexture) => {
+    // sprite only case
+    if (json === null) {
+      if (_spriteTexture && numberOfFrames) {
+        //get size from texture
+        const width = _spriteTexture.image.width;
+        const height = _spriteTexture.image.height;
+        const frameWidth = width / numberOfFrames;
+        const frameHeight = height;
+        textureData.current = _spriteTexture;
+        totalFrames.current = numberOfFrames;
+        spriteData.current = {
+          frames: [],
+          meta: {
+            version: '1.0',
+            size: {
+              w: width,
+              h: height
+            },
+            scale: '1'
+          }
+        };
+
+        if (parseInt(frameWidth.toString(), 10) === frameWidth) {
+          // if it fits
+          for (let i = 0; i < numberOfFrames; i++) {
+            spriteData.current.frames.push({
+              frame: {
+                x: i * frameWidth,
+                y: 0,
+                w: frameWidth,
+                h: frameHeight
+              },
+              rotated: false,
+              trimmed: false,
+              spriteSourceSize: {
+                x: 0,
+                y: 0,
+                w: frameWidth,
+                h: frameHeight
+              },
+              sourceSize: {
+                w: frameWidth,
+                h: height
+              }
+            });
+          }
+        }
+      }
+    } else if (_spriteTexture) {
+      spriteData.current = json;
+      spriteData.current.frames = Array.isArray(json.frames) ? json.frames : parseFrames();
+      totalFrames.current = Array.isArray(json.frames) ? json.frames.length : Object.keys(json.frames).length;
+      textureData.current = _spriteTexture;
+      const {
+        w,
+        h
+      } = getFirstItem(json.frames).sourceSize;
+      const aspect = calculateAspectRatio(w, h, aspectFactor);
+      setAspect(aspect);
+
+      if (matRef.current) {
+        matRef.current.map = _spriteTexture;
+      }
+    }
+
+    _spriteTexture.premultiplyAlpha = false;
+    setSpriteTexture(_spriteTexture);
+  }; // for frame based JSON Hash sprite data
+
+
+  const parseFrames = () => {
+    const sprites = {};
+    const data = spriteData.current;
+    const delimiters = animationNames;
+
+    if (delimiters) {
+      for (let i = 0; i < delimiters.length; i++) {
+        sprites[delimiters[i]] = [];
+
+        for (let innerKey in data['frames']) {
+          const value = data['frames'][innerKey];
+          const frameData = value['frame'];
+          const x = frameData['x'];
+          const y = frameData['y'];
+          const width = frameData['w'];
+          const height = frameData['h'];
+          const sourceWidth = value['sourceSize']['w'];
+          const sourceHeight = value['sourceSize']['h'];
+
+          if (typeof innerKey === 'string' && innerKey.toLowerCase().indexOf(delimiters[i].toLowerCase()) !== -1) {
+            sprites[delimiters[i]].push({
+              x: x,
+              y: y,
+              w: width,
+              h: height,
+              frame: frameData,
+              sourceSize: {
+                w: sourceWidth,
+                h: sourceHeight
+              }
+            });
+          }
+        }
+      }
+    }
+
+    return sprites;
+  }; // modify the sprite material after json is parsed and state updated
+
+
+  const modifySpritePosition = () => {
+    if (!spriteData.current) return;
+    const {
+      meta: {
+        size: metaInfo
+      },
+      frames
+    } = spriteData.current;
+    const {
+      w: frameW,
+      h: frameH
+    } = Array.isArray(frames) ? frames[0].sourceSize : frameName ? frames[frameName] ? frames[frameName][0].sourceSize : {
+      w: 0,
+      h: 0
+    } : {
+      w: 0,
+      h: 0
+    };
+    matRef.current.map.wrapS = matRef.current.map.wrapT = THREE.RepeatWrapping;
+    matRef.current.map.center.set(0, 0);
+    matRef.current.map.repeat.set(1 * flipOffset / (metaInfo.w / frameW), 1 / (metaInfo.h / frameH)); //const framesH = (metaInfo.w - 1) / frameW
+
+    const framesV = (metaInfo.h - 1) / frameH;
+    const frameOffsetY = 1 / framesV;
+    matRef.current.map.offset.x = 0.0; //-matRef.current.map.repeat.x
+
+    matRef.current.map.offset.y = 1 - frameOffsetY;
+    setJsonReady(true);
+    if (onStart) onStart({
+      currentFrameName: frameName,
+      currentFrame: currentFrame.current
+    });
+  }; // run the animation on each frame
+
+
+  const runAnimation = () => {
+    //if (!frameName) return
+    const now = window.performance.now();
+    const diff = now - timerOffset.current;
+    const {
+      meta: {
+        size: metaInfo
+      },
+      frames
+    } = spriteData.current;
+    const {
+      w: frameW,
+      h: frameH
+    } = getFirstItem(frames).sourceSize;
+    const spriteFrames = Array.isArray(frames) ? frames : frameName ? frames[frameName] : [];
+    let finalValX = 0;
+    let finalValY = 0;
+
+    const _endFrame = endFrame || spriteFrames.length - 1;
+
+    if (currentFrame.current > _endFrame) {
+      currentFrame.current = loop ? startFrame !== null && startFrame !== void 0 ? startFrame : 0 : 0;
+
+      if (loop) {
+        onLoopEnd == null ? void 0 : onLoopEnd({
+          currentFrameName: frameName,
+          currentFrame: currentFrame.current
+        });
+      } else {
+        onEnd == null ? void 0 : onEnd({
+          currentFrameName: frameName,
+          currentFrame: currentFrame.current
+        });
+      }
+
+      if (!loop) return;
+    }
+
+    if (diff <= fpsInterval) return;
+    timerOffset.current = now - diff % fpsInterval;
+    calculateAspectRatio(frameW, frameH, aspectFactor);
+    const framesH = (metaInfo.w - 1) / frameW;
+    const framesV = (metaInfo.h - 1) / frameH;
+    const {
+      frame: {
+        x: frameX,
+        y: frameY
+      },
+      sourceSize: {
+        w: originalSizeX,
+        h: originalSizeY
+      }
+    } = spriteFrames[currentFrame.current];
+    const frameOffsetX = 1 / framesH;
+    const frameOffsetY = 1 / framesV;
+    finalValX = flipOffset > 0 ? frameOffsetX * (frameX / originalSizeX) : frameOffsetX * (frameX / originalSizeX) - matRef.current.map.repeat.x;
+    finalValY = Math.abs(1 - frameOffsetY) - frameOffsetY * (frameY / originalSizeY);
+    matRef.current.map.offset.x = finalValX;
+    matRef.current.map.offset.y = finalValY;
+    currentFrame.current += 1;
+  }; // *** Warning! It runs on every frame! ***
+
+
+  useFrame((state, delta) => {
+    var _spriteData$current, _matRef$current;
+
+    if (!((_spriteData$current = spriteData.current) != null && _spriteData$current.frames) || !((_matRef$current = matRef.current) != null && _matRef$current.map)) {
+      return;
+    }
+
+    if (pause) {
+      return;
+    }
+
+    if (autoPlay || play) {
+      runAnimation();
+      onFrame && onFrame({
+        currentFrameName: currentFrameName.current,
+        currentFrame: currentFrame.current
+      });
+    }
+  }); // utils
+
+  const getFirstItem = param => {
+    if (Array.isArray(param)) {
+      return param[0];
+    } else if (typeof param === 'object' && param !== null) {
+      const keys = Object.keys(param);
+      return param[keys[0]][0];
+    } else {
+      return {
+        w: 0,
+        h: 0
+      };
+    }
+  };
+
+  return /*#__PURE__*/React.createElement("group", props, /*#__PURE__*/React.createElement(React.Suspense, {
+    fallback: null
+  }, /*#__PURE__*/React.createElement("sprite", {
+    ref: spriteRef,
+    scale: aspect
+  }, /*#__PURE__*/React.createElement("spriteMaterial", {
+    ref: matRef,
+    map: spriteTexture,
+    premultipliedAlpha: false,
+    transparent: true,
+    alphaTest: alphaTest !== null && alphaTest !== void 0 ? alphaTest : 0.0
+  }))), children);
+};
+
+export { SpriteAnimator };