@react-three/drei 9.96.5 → 9.97.1

package/README.md

@@ -71,6 +71,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#positionalaudio">PositionalAudio</a></li>
           <li><a href="#billboard">Billboard</a></li>
           <li><a href="#screenspace">ScreenSpace</a></li>
+          <li><a href="#screensizer">ScreenSizer</a></li>
           <li><a href="#effects">Effects</a></li>
           <li><a href="#gradienttexture">GradientTexture</a></li>
           <li><a href="#edges">Edges</a></li>
@@ -139,6 +140,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#usevideotexture">useVideoTexture</a></li>
           <li><a href="#usetrailtexture">useTrailTexture</a></li>
           <li><a href="#usefont">useFont</a></li>
+          <li><a href="#usespriteloader">useSpriteLoader</a></li>
         </ul>
         <li><a href="#performance">Performance</a></li>
         <ul>
@@ -214,7 +216,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#environment">Environment</a></li>
           <li><a href="#lightformer">Lightformer</a></li>
           <li><a href="#spotlight">SpotLight</a></li>
-          <li><a href="#spotlightshadows">SpotLightShadows</a></li>
+          <li><a href="#spotlightshadow">SpotLightShadow</a></li>
           <li><a href="#shadow">Shadow</a></li>
           <li><a href="#caustics">Caustics</a></li>
           <li><a href="#contactshadows">ContactShadows</a></li>
@@ -1484,6 +1486,22 @@ Adds a `<group />` that aligns objects to screen space.
 </ScreenSpace>
 ```
 
+#### ScreenSizer
+
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-screensizer--screen-sizer-story)
+
+Adds a `<object3D />` that scales objects to screen space.
+
+```jsx
+<ScreenSizer
+  scale={1} // scale factor
+>
+  <Box
+    args={[100, 100, 100]} // will render roughly as a 100px box
+  />
+</ScreenSizer>
+```
+
 #### GradientTexture
 
 <p>
@@ -2070,9 +2088,9 @@ type MeshTransmissionMaterialProps = JSX.IntrinsicElements['meshPhysicalMaterial
   /* Distortion, default: 0 */
   distortion?: number
   /* Distortion scale, default: 0.5 */
-  distortionScale: number
+  distortionScale?: number
   /* Temporal distortion (speed of movement), default: 0.0 */
-  temporalDistortion: number
+  temporalDistortion?: number
   /** The scene rendered into a texture (use it to share a texture between materials), default: null  */
   buffer?: THREE.Texture
   /** transmissionSampler, you can use the threejs transmission sampler texture that is
@@ -2572,6 +2590,8 @@ type Props = {
   instanceItems?: any[]
   /** The max number of items to instance (optional) */
   maxItems?: number
+  /** External parsed sprite data, usually from useSpriteLoader ready for use */
+  spriteDataset?: any
 }
 ```
 
@@ -2580,8 +2600,9 @@ The SpriteAnimator component provided by drei is a powerful tool for animating s
 Notes:
 
 - The SpriteAnimator component internally uses the useFrame hook from react-three-fiber (r3f) for efficient frame updates and rendering.
-- The sprites should contain equal size frames
+- The sprites (without a JSON file) should contain equal size frames
 - Trimming of spritesheet frames is not yet supported
+- Internally uses the `useSpriteLoader` or can use data from it directly
 
 ```jsx
 <SpriteAnimator
@@ -2598,7 +2619,7 @@ Notes:
 ScrollControls example
 
 ```jsx
-;<ScrollControls damping={0.2} maxSpeed={0.5} pages={2}>
+<ScrollControls damping={0.2} maxSpeed={0.5} pages={2}>
   <SpriteAnimator
     position={[0.0, -1.5, -1.5]}
     startFrame={0}
@@ -2832,7 +2853,7 @@ return (
 
 ![](https://img.shields.io/badge/-Dom only-red)
 
-A small hook that sets the css body cursor according to the hover state of a mesh, so that you can give the use visual feedback when the mouse enters a shape. Arguments 1 and 2 determine the style, the defaults are: onPointerOver = 'pointer', onPointerOut = 'auto'.
+A small hook that sets the css body cursor according to the hover state of a mesh, so that you can give the user visual feedback when the mouse enters a shape. Arguments 1 and 2 determine the style, the defaults are: onPointerOver = 'pointer', onPointerOut = 'auto'.
 
 ```jsx
 const [hovered, set] = useState()
@@ -3234,6 +3255,58 @@ In order to preload you do this:
 useFont.preload('/fonts/helvetiker_regular.typeface.json')
 ```
 
+#### useSpriteLoader
+
+Loads texture and JSON files with multiple or single animations and parses them into appropriate format. These assets can be used by multiple SpriteAnimator components to save memory and loading times.
+
+```jsx
+/** The texture url to load the sprite frames from */
+input?: Url | null,
+/** The JSON data describing the position of the frames within the texture (optional) */
+json?: string | null,
+/** The animation names into which the frames will be divided into (optional) */
+animationNames?: string[] | null,
+/** The number of frames on a standalone (no JSON data) spritesheet (optional)*/
+numberOfFrames?: number | null,
+/** The callback to call when all textures and data have been loaded and parsed */
+onLoad?: (texture: Texture, textureData?: any) => void
+```
+
+```jsx
+const { spriteObj } = useSpriteLoader(
+  'multiasset.png',
+  'multiasset.json',
+
+  ['orange', 'Idle Blinking', '_Bat'],
+  null
+)
+
+<SpriteAnimator
+  position={[4.5, 0.5, 0.1]}
+  autoPlay={true}
+  loop={true}
+  scale={5}
+  frameName={'_Bat'}
+  animationNames={['_Bat']}
+  spriteDataset={spriteObj}
+  alphaTest={0.01}
+  asSprite={false}
+/>
+
+<SpriteAnimator
+  position={[5.5, 0.5, 5.8]}
+  autoPlay={true}
+  loop={true}
+  scale={5}
+  frameName={'Idle Blinking'}
+  animationNames={['Idle Blinking']}
+  spriteDataset={spriteObj}
+  alphaTest={0.01}
+  asSprite={false}
+/>
+```
+
+
 # Performance
 
 #### Instances
@@ -4500,7 +4573,7 @@ function Foo() {
   return <SpotLight depthBuffer={depthBuffer} />
 ```
 
-#### SpotLightShadows
+#### SpotLightShadow
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-spotlight--spotlight-shadows-st)
 
@@ -4512,7 +4585,7 @@ A shadow caster that can help cast shadows of different patterns (textures) onto
 
 ```jsx
 <SpotLight>
-  <SpotLightShadows
+  <SpotLightShadow
     distance={0.4} // Distance between the shadow caster and light
     alphaTest={0.5} // Sets the alpha value to be used when running an alpha test. See Material.alphaTest
     scale={1} //  Scale of the shadow caster plane
@@ -4524,7 +4597,7 @@ A shadow caster that can help cast shadows of different patterns (textures) onto
 </SpotLight>
 ```
 
-An optinal `shader` prop lets you run a custom shader to modify/add effects to your shadow texture. The shader privides the following uniforms and varyings.
+An optional `shader` prop lets you run a custom shader to modify/add effects to your shadow texture. The shader provides the following uniforms and varyings.
 
 | Type                | Name         | Notes                                  |
 | ------------------- | ------------ | -------------------------------------- |

package/core/CameraControls.d.ts

@@ -1,4 +1,4 @@
-import { OrthographicCamera, PerspectiveCamera } from 'three';
+import { EventDispatcher, OrthographicCamera, PerspectiveCamera } from 'three';
 import { ReactThreeFiber } from '@react-three/fiber';
 import CameraControlsImpl from 'camera-controls';
 import { ForwardRefComponent } from '../helpers/ts-utils';
@@ -17,6 +17,6 @@ export type CameraControlsProps = Omit<ReactThreeFiber.Overwrite<ReactThreeFiber
     }) => void;
     events?: boolean;
     regress?: boolean;
-}>, 'ref'>;
+}>, 'ref' | keyof EventDispatcher>;
 export declare const CameraControls: ForwardRefComponent<CameraControlsProps, CameraControlsImpl>;
 export type CameraControls = CameraControlsImpl;

package/core/MeshTransmissionMaterial.d.ts

@@ -8,8 +8,8 @@ type MeshTransmissionMaterialType = Omit<JSX.IntrinsicElements['meshPhysicalMate
     anisotropy?: number;
     anisotropicBlur?: number;
     distortion?: number;
-    distortionScale: number;
-    temporalDistortion: number;
+    distortionScale?: number;
+    temporalDistortion?: number;
     buffer?: THREE.Texture;
     time?: number;
     args?: [samples: number, transmissionSampler: boolean];

package/core/ScreenSizer.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@babel/runtime/helpers/extends"),r=require("@react-three/fiber"),t=require("react"),c=require("react-merge-refs"),a=require("three"),u=require("./calculateScaleFactor.cjs.js");function n(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}function l(e){if(e&&e.__esModule)return e;var r=Object.create(null);return e&&Object.keys(e).forEach((function(t){if("default"!==t){var c=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(r,t,c.get?c:{enumerable:!0,get:function(){return e[t]}})}})),r.default=e,Object.freeze(r)}var o=n(e),f=l(t),i=n(c);const s=new a.Vector3,d=t.forwardRef((({scale:e=1,...c},a)=>{const n=t.useRef(null);return r.useFrame((r=>{const t=n.current;if(!t)return;const c=u.calculateScaleFactor(t.getWorldPosition(s),e,r.camera,r.size);t.scale.setScalar(c*e)})),f.createElement("object3D",o.default({ref:i.default([n,a])},c))}));exports.ScreenSizer=d;

package/core/ScreenSizer.d.ts

@@ -0,0 +1,7 @@
+import { Object3DProps } from '@react-three/fiber';
+import { ForwardRefComponent } from 'helpers/ts-utils';
+import { Object3D } from 'three';
+export interface ScreenSizerProps extends Object3DProps {
+    scale: number;
+}
+export declare const ScreenSizer: ForwardRefComponent<ScreenSizerProps, Object3D>;

package/core/ScreenSizer.js

@@ -0,0 +1,39 @@
+import _extends from '@babel/runtime/helpers/esm/extends';
+import { useFrame } from '@react-three/fiber';
+import * as React from 'react';
+import { forwardRef, useRef } from 'react';
+import mergeRefs from 'react-merge-refs';
+import { Vector3 } from 'three';
+import { calculateScaleFactor } from './calculateScaleFactor.js';
+
+const worldPos = /* @__PURE__ */new Vector3();
+/**
+ * Wraps children in an `Object3D` and attempts to scale from
+ * world units to screen units * scale factor.
+ *
+ * For example, this will render a box of roughly 1x1 pixel size,
+ * independently of how far the camera is.
+ *
+ * ```jsx
+ * <ScreenSizer>
+ *   <Box />
+ * </ScreenSizer>
+ * ```
+ */
+const ScreenSizer = /* @__PURE__ */forwardRef(({
+  scale = 1,
+  ...props
+}, ref) => {
+  const container = useRef(null);
+  useFrame(state => {
+    const obj = container.current;
+    if (!obj) return;
+    const sf = calculateScaleFactor(obj.getWorldPosition(worldPos), scale, state.camera, state.size);
+    obj.scale.setScalar(sf * scale);
+  });
+  return /*#__PURE__*/React.createElement("object3D", _extends({
+    ref: mergeRefs([container, ref])
+  }, props));
+});
+
+export { ScreenSizer };

package/core/SpriteAnimator.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@babel/runtime/helpers/extends"),r=require("react"),t=require("@react-three/fiber"),n=require("three"),a=require("./Instances.cjs.js");function u(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}function c(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)}require("react-merge-refs"),require("react-composer"),require("../helpers/deprecated.cjs.js");var s=u(e),o=c(r),f=c(n);const l=o.createContext(null);const m=o.forwardRef((({startFrame:e,endFrame:r,fps:n,frameName:u,textureDataURL:c,textureImageURL:m,loop:i,numberOfFrames:p,autoPlay:h,animationNames:d,onStart:w,onEnd:y,onLoopEnd:E,onFrame:g,play:x,pause:S,flipX:b,alphaTest:F,children:R,asSprite:j,offset:v,playBackwards:z,resetOnEnd:M,maxItems:A,instanceItems:O,...N},L)=>{const k=o.useRef(),q=o.useRef(null),I=o.useRef(),P=o.useRef(),T=o.useRef(window.performance.now()),C=o.useRef(),D=o.useRef(e||0),_=o.useRef(u||""),B=1e3/(n||30),[U,G]=o.useState(new f.Texture),H=o.useRef(0),[W,X]=o.useState([1,1,1]),J=b?-1:1,[K,Q]=o.useState(null==j||j),V=o.useRef(S),Y=o.useRef(v),Z=o.useRef(!1),$=o.useRef([]);function ee(){}const re=o.useMemo((()=>({current:Y.current,offset:Y.current,imageUrl:m,reset:ee,hasEnded:!1,ref:L})),[m]);o.useImperativeHandle(L,(()=>k.current),[]),o.useLayoutEffect((()=>{Y.current=v}),[v]);const te=(e,r)=>{const t=r/e;return P.current&&P.current.scale.set(1,t,1),[1,t,1]};o.useEffect((()=>{if(c&&m)!function(e,r,t){const n=new f.TextureLoader,a=fetch(e).then((e=>e.json())),u=new Promise((e=>{n.load(r,e)}));Promise.all([a,u]).then((e=>{t(e[0],e[1])}))}(c,m,ne);else if(m){const e=new f.TextureLoader;new Promise((r=>{e.load(m,r)})).then((e=>{ne(null,e)}))}}),[]),o.useEffect((()=>{Q(null==j||j)}),[j]),o.useEffect((()=>{re.hasEnded=!1,q.current&&!0===z?D.current=q.current.frames.length-1:D.current=0}),[z]),o.useLayoutEffect((()=>{ue()}),[U,b]),o.useEffect((()=>{h&&(V.current=!1)}),[h]),o.useEffect((()=>{if(_.current!==u&&u&&(D.current=0,_.current=u,re.hasEnded=!1,ue(),q.current)){const{w:e,h:r}=se(q.current.frames).sourceSize,t=te(e,r);X(t)}}),[u]);const ne=(e,r)=>{if(null===e){if(p){const e=r.image.width,t=r.image.height,n=e/p,a=t;if(C.current=r,H.current=p,z&&(D.current=p-1),q.current={frames:[],meta:{version:"1.0",size:{w:e,h:t},scale:"1"}},parseInt(n.toString(),10)===n)for(let e=0;e<p;e++)q.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{q.current=e,q.current.frames=Array.isArray(e.frames)?e.frames:ae(),H.current=Array.isArray(e.frames)?e.frames.length:Object.keys(e.frames).length,C.current=r,z&&(D.current=H.current-1);const{w:t,h:n}=se(e.frames).sourceSize,a=te(t,n);X(a),I.current&&(I.current.map=r)}if(O)for(var t=0;t<O.length;t++){const e=Object.keys(q.current.frames),r=e[Math.floor(Math.random()*e.length)];$.current.push({key:t,frames:q.current.frames,selectedFrame:r,offset:{x:0,y:0}})}r.premultiplyAlpha=!1,G(r)},ae=()=>{const e={},r=q.current,t=d;if(t){for(let n=0;n<t.length;n++){e[t[n]]=[];for(const a in r.frames){const u=r.frames[a],c=u.frame,s=c.x,o=c.y,f=c.w,l=c.h,m=u.sourceSize.w,i=u.sourceSize.h;-1!==a.toLowerCase().indexOf(t[n].toLowerCase())&&e[t[n]].push({x:s,y:o,w:f,h:l,frame:c,sourceSize:{w:m,h:i}})}}return e}if(u){const e=[];for(const t in r.frames)e.push(r.frames[t]);return e}},ue=()=>{if(!q.current)return;const{meta:{size:e},frames:r}=q.current,{w:t,h:n}=Array.isArray(r)?r[0].sourceSize:u&&r[u]?r[u][0].sourceSize:{w:0,h:0};I.current.map.wrapS=I.current.map.wrapT=f.RepeatWrapping,I.current.map.center.set(0,0),I.current.map.repeat.set(1*J/(e.w/t),1/(e.h/n));const a=1/((e.h-1)/n);I.current.map.offset.x=0,I.current.map.offset.y=1-a,w&&w({currentFrameName:u,currentFrame:D.current})},ce=(e,r,t,n)=>{var a=void 0===v?re.current:v;const u=D.current;let c=0,s=0;te(e,r);const o=(t.w-1)/e,f=(t.h-1)/r;if(!n[u])return;const{frame:{x:l,y:m},sourceSize:{w:i,h:p}}=n[u],h=1/o,d=1/f;if(c=J>0?h*(l/i):h*(l/i)-I.current.map.repeat.x,s=Math.abs(1-d)-d*(m/p),I.current.map.offset.x=c,I.current.map.offset.y=s,null!=a){let e=Math.floor(a*n.length);e=Math.max(0,Math.min(e,n.length-1)),isNaN(e)&&(console.log("nan frame detected"),e=0),D.current=e}else z?D.current-=1:D.current+=1};t.useFrame(((t,n)=>{var a,c;null!=(a=q.current)&&a.frames&&null!=(c=I.current)&&c.map&&(V.current||re.hasEnded||!h&&!x||((()=>{const t=window.performance.now(),n=t-T.current,{meta:{size:a},frames:c}=q.current,{w:s,h:o}=se(c).sourceSize,f=Array.isArray(c)?c:u?c[u]:[],l=r||f.length-1;var m=void 0===v?re.current:v,p=z?D.current<0:D.current>l,h=z?D.current===l:0===D.current,d=z?D.current<0:D.current>=l;if(p){if(D.current=i&&null!=e?e:0,z&&(D.current=l),i?null==E||E({currentFrameName:u,currentFrame:D.current}):(null==y||y({currentFrameName:u,currentFrame:D.current}),m||console.log("will end"),re.hasEnded=!M,M&&(V.current=!0)),!i)return}else h&&(null==w||w({currentFrameName:u,currentFrame:D.current}));void 0!==m&&d?!1===Z.current&&(null==y||y({currentFrameName:u,currentFrame:D.current}),Z.current=!0):Z.current=!1,n<=B||(T.current=t-n%B,ce(s,o,a,f))})(),g&&g({currentFrameName:_.current,currentFrame:D.current})))}));const se=e=>{if(Array.isArray(e))return e[0];if("object"==typeof e&&null!==e){const r=Object.keys(e);return u?e[u][0]:e[r[0]][0]}return{w:0,h:0}};return o.createElement("group",s.default({},N,{ref:k}),o.createElement(l.Provider,{value:re},o.createElement(o.Suspense,{fallback:null},K&&o.createElement("sprite",{ref:P,scale:W},o.createElement("spriteMaterial",{toneMapped:!1,ref:I,map:U,transparent:!0,alphaTest:null!=F?F:0})),!K&&o.createElement(a.Instances,{limit:A},o.createElement("planeGeometry",{args:[1,1]}),o.createElement("meshBasicMaterial",{toneMapped:!1,side:f.DoubleSide,ref:I,map:U,transparent:!0,alphaTest:null!=F?F:0}),(null!=O?O:[0]).map(((e,r)=>{const t=U.clone();return I.current&&$.current[r]&&t.offset.set($.current[r].offset.x,$.current[r].offset.y),o.createElement(a.Instance,{key:r,ref:P,position:e,scale:W},o.createElement("meshBasicMaterial",{toneMapped:!1,side:f.DoubleSide,map:t,transparent:!0,alphaTest:null!=F?F:0}))})))),R))}));exports.SpriteAnimator=m,exports.useSpriteAnimator=function(){return o.useContext(l)};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@babel/runtime/helpers/extends"),r=require("react"),t=require("@react-three/fiber"),n=require("three"),u=require("./Instances.cjs.js"),a=require("./useSpriteLoader.cjs.js");function c(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}function s(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)}require("react-merge-refs"),require("react-composer"),require("../helpers/deprecated.cjs.js");var l=c(e),o=s(r),f=s(n);const i=o.createContext(null);const m=o.forwardRef((({startFrame:e,endFrame:r,fps:n,frameName:c,textureDataURL:s,textureImageURL:m,loop:p,numberOfFrames:d,autoPlay:h,animationNames:y,onStart:E,onEnd:w,onLoopEnd:v,onFrame:b,play:g,pause:x,flipX:F,alphaTest:S,children:j,asSprite:R,offset:M,playBackwards:O,resetOnEnd:A,maxItems:z,instanceItems:N,spriteDataset:q,...L},T)=>{const k=o.useRef(),I=o.useRef(null),D=o.useRef(),P=o.useRef(),_=o.useRef(window.performance.now()),U=o.useRef(e||0),B=o.useRef(c||""),C=1e3/(n||30),[G,H]=o.useState(new f.Texture),J=o.useRef(0),[W,X]=o.useState([1,1,1]),K=F?-1:1,[Q,V]=o.useState(null==R||R),Y=o.useRef(x),Z=o.useRef(M),$=o.useRef(!1),ee=o.useRef([]),{spriteObj:re,loadJsonAndTexture:te}=a.useSpriteLoader(null,null,y,d);function ne(){}const ue=o.useMemo((()=>({current:Z.current,offset:Z.current,imageUrl:m,reset:ne,hasEnded:!1,ref:T})),[m,q]);o.useImperativeHandle(T,(()=>k.current),[]),o.useLayoutEffect((()=>{Z.current=M}),[M]);const ae=(e,r)=>{const t=r/e;return P.current&&P.current.scale.set(1,t,1),[1,t,1]};o.useEffect((()=>{var e;q?ce(null==q||null==(e=q.spriteTexture)?void 0:e.clone(),q.spriteData):te(m,s)}),[q]),o.useEffect((()=>{var e;re&&ce(null==re||null==(e=re.spriteTexture)?void 0:e.clone(),null==re?void 0:re.spriteData)}),[re]),o.useEffect((()=>{V(null==R||R)}),[R]),o.useEffect((()=>{ue.hasEnded=!1,I.current&&!0===O?U.current=I.current.frames.length-1:U.current=0}),[O]),o.useLayoutEffect((()=>{se()}),[G,F]),o.useEffect((()=>{h&&(Y.current=!1)}),[h]),o.useLayoutEffect((()=>{if(B.current!==c&&c&&(U.current=0,B.current=c,ue.hasEnded=!1,I.current)){const{w:e,h:r}=oe(I.current.frames).sourceSize,t=ae(e,r);X(t)}}),[c]);const ce=(e,r=null)=>{if(null===r){if(d){const t=e.image.width,n=e.image.height;J.current=d,O&&(U.current=d-1),I.current={frames:[],meta:{version:"1.0",size:{w:t,h:n},scale:"1"}},I.current.frames=r}}else{I.current=r,J.current=I.current.frames.length,O&&(U.current=J.current-1);const{w:t,h:n}=oe(I.current.frames).sourceSize,u=ae(t,n);X(u),D.current&&(D.current.map=e)}if(N)for(var t=0;t<N.length;t++){const e=Object.keys(I.current.frames),r=e[Math.floor(Math.random()*e.length)];ee.current.push({key:t,frames:I.current.frames,selectedFrame:r,offset:{x:0,y:0}})}H(e)},se=()=>{if(!I.current)return;const{meta:{size:e},frames:r}=I.current,{w:t,h:n}=Array.isArray(r)?r[0].sourceSize:c&&r[c]?r[c][0].sourceSize:{w:0,h:0};D.current.map.wrapS=D.current.map.wrapT=f.RepeatWrapping,D.current.map.center.set(0,0),D.current.map.repeat.set(1*K/(e.w/t),1/(e.h/n));const u=1/((e.h-1)/n);D.current.map.offset.x=0,D.current.map.offset.y=1-u,E&&E({currentFrameName:c,currentFrame:U.current})},le=(e,r,t,n)=>{var u=void 0===M?ue.current:M;const a=U.current;let c=0,s=0;ae(e,r);const l=(t.w-1)/e,o=(t.h-1)/r;if(!n[a])return;const{frame:{x:f,y:i},sourceSize:{w:m,h:p}}=n[a],d=1/l,h=1/o;if(c=K>0?d*(f/m):d*(f/m)-D.current.map.repeat.x,s=Math.abs(1-h)-h*(i/p),D.current.map.offset.x=c,D.current.map.offset.y=s,null!=u){let e=Math.floor(u*n.length);e=Math.max(0,Math.min(e,n.length-1)),isNaN(e)&&(e=0),U.current=e}else O?U.current-=1:U.current+=1};t.useFrame(((t,n)=>{var u,a;null!=(u=I.current)&&u.frames&&null!=(a=D.current)&&a.map&&(Y.current||ue.hasEnded||!h&&!g||((()=>{const t=window.performance.now(),n=t-_.current,{meta:{size:u},frames:a}=I.current,{w:s,h:l}=oe(a).sourceSize,o=Array.isArray(a)?a:c?a[c]:[],f=r||o.length-1;var i=void 0===M?ue.current:M,m=O?U.current<0:U.current>f,d=O?U.current===f:0===U.current,h=O?U.current<0:U.current>=f;if(m){if(U.current=p&&null!=e?e:0,O&&(U.current=f),p?null==v||v({currentFrameName:c,currentFrame:U.current}):(null==w||w({currentFrameName:c,currentFrame:U.current}),ue.hasEnded=!A,A&&(Y.current=!0)),!p)return}else d&&(null==E||E({currentFrameName:c,currentFrame:U.current}));void 0!==i&&h?!1===$.current&&(null==w||w({currentFrameName:c,currentFrame:U.current}),$.current=!0):$.current=!1,n<=C||(_.current=t-n%C,le(s,l,u,o))})(),b&&b({currentFrameName:B.current,currentFrame:U.current})))}));const oe=e=>{if(Array.isArray(e))return e[0];if("object"==typeof e&&null!==e){const r=Object.keys(e);return c?e[c][0]:e[r[0]][0]}return{w:0,h:0}};return o.createElement("group",l.default({},L,{ref:k}),o.createElement(i.Provider,{value:ue},o.createElement(o.Suspense,{fallback:null},Q&&o.createElement("sprite",{ref:P,scale:W},o.createElement("spriteMaterial",{premultipliedAlpha:!1,toneMapped:!1,ref:D,map:G,transparent:!0,alphaTest:null!=S?S:0})),!Q&&o.createElement(u.Instances,{limit:null!=z?z:1},o.createElement("planeGeometry",{args:[1,1]}),o.createElement("meshBasicMaterial",{premultipliedAlpha:!1,toneMapped:!1,side:f.DoubleSide,ref:D,map:G,transparent:!0,alphaTest:null!=S?S:0}),(null!=N?N:[0]).map(((e,r)=>o.createElement(u.Instance,{key:r,ref:P,position:e,scale:W}))))),j))}));exports.SpriteAnimator=m,exports.useSpriteAnimator=function(){return o.useContext(i)};

package/core/SpriteAnimator.d.ts

@@ -5,7 +5,7 @@ export type SpriteAnimatorProps = {
     fps?: number;
     frameName?: string;
     textureDataURL?: string;
-    textureImageURL: string;
+    textureImageURL?: string;
     loop?: boolean;
     numberOfFrames?: number;
     autoPlay?: boolean;
@@ -25,6 +25,7 @@ export type SpriteAnimatorProps = {
     resetOnEnd?: boolean;
     maxItems?: number;
     instanceItems?: any[];
+    spriteDataset?: any;
 } & JSX.IntrinsicElements['group'];
 type SpriteAnimatorState = {
     current: number | undefined;

package/core/SpriteAnimator.js

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { Instances, Instance } from './Instances.js';
+import { useSpriteLoader } from './useSpriteLoader.js';
 
 const context = /*#__PURE__*/React.createContext(null);
 function useSpriteAnimator() {
@@ -34,15 +35,14 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
   resetOnEnd,
   maxItems,
   instanceItems,
+  spriteDataset,
   ...props
 }, fref) => {
   const ref = React.useRef();
   const spriteData = React.useRef(null);
-  //const hasEnded = React.useRef(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);
@@ -55,6 +55,10 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
   const pos = React.useRef(offset);
   const softEnd = React.useRef(false);
   const frameBuffer = React.useRef([]);
+  const {
+    spriteObj,
+    loadJsonAndTexture
+  } = useSpriteLoader(null, null, animationNames, numberOfFrames);
   //
 
   function reset() {}
@@ -65,21 +69,11 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
     reset: reset,
     hasEnded: false,
     ref: fref
-  }), [textureImageURL]);
+  }), [textureImageURL, spriteDataset]);
   React.useImperativeHandle(fref, () => ref.current, []);
   React.useLayoutEffect(() => {
     pos.current = offset;
   }, [offset]);
-  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) => {
     const aspectRatio = height / width;
     if (spriteRef.current) {
@@ -90,18 +84,19 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
 
   // 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);
-      });
+    if (spriteDataset) {
+      var _spriteDataset$sprite;
+      parseSpriteDataLite(spriteDataset == null || (_spriteDataset$sprite = spriteDataset.spriteTexture) == null ? void 0 : _spriteDataset$sprite.clone(), spriteDataset.spriteData);
+    } else {
+      loadJsonAndTexture(textureImageURL, textureDataURL);
+    }
+  }, [spriteDataset]);
+  React.useEffect(() => {
+    if (spriteObj) {
+      var _spriteObj$spriteText;
+      parseSpriteDataLite(spriteObj == null || (_spriteObj$spriteText = spriteObj.spriteTexture) == null ? void 0 : _spriteObj$spriteText.clone(), spriteObj == null ? void 0 : spriteObj.spriteData);
     }
-  }, []);
+  }, [spriteObj]);
   React.useEffect(() => {
     setDisplayAsSprite(asSprite !== null && asSprite !== void 0 ? asSprite : true);
   }, [asSprite]);
@@ -123,12 +118,12 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
       pauseRef.current = false;
     }
   }, [autoPlay]);
-  React.useEffect(() => {
+  React.useLayoutEffect(() => {
     if (currentFrameName.current !== frameName && frameName) {
       currentFrame.current = 0;
       currentFrameName.current = frameName;
       state.hasEnded = false;
-      modifySpritePosition();
+      // modifySpritePosition()
       if (spriteData.current) {
         const {
           w,
@@ -140,17 +135,13 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
     }
   }, [frameName]);
 
-  // parse sprite-data from JSON file (jsonHash or jsonArray)
-  const parseSpriteData = (json, _spriteTexture) => {
-    // sprite only case
-    if (json === null) {
+  // lite version for pre-loaded assets
+  const parseSpriteDataLite = (textureData, frameData = null) => {
+    if (frameData === null) {
       if (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;
+        const width = textureData.image.width;
+        const height = textureData.image.height;
         totalFrames.current = numberOfFrames;
         if (playBackwards) {
           currentFrame.current = numberOfFrames - 1;
@@ -166,48 +157,22 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
             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
-              }
-            });
-          }
-        }
+        spriteData.current.frames = frameData;
       }
     } else {
-      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;
+      spriteData.current = frameData;
+      totalFrames.current = spriteData.current.frames.length;
       if (playBackwards) {
         currentFrame.current = totalFrames.current - 1;
       }
       const {
         w,
         h
-      } = getFirstItem(json.frames).sourceSize;
+      } = getFirstItem(spriteData.current.frames).sourceSize;
       const aspect = calculateAspectRatio(w, h);
       setAspect(aspect);
       if (matRef.current) {
-        matRef.current.map = _spriteTexture;
+        matRef.current.map = textureData;
       }
     }
 
@@ -227,50 +192,7 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
         });
       }
     }
-    _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 (const 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 (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;
-    } else if (frameName) {
-      const spritesArr = [];
-      for (const key in data.frames) {
-        spritesArr.push(data.frames[key]);
-      }
-      return spritesArr;
-    }
+    setSpriteTexture(textureData);
   };
 
   // modify the sprite material after json is parsed and state updated
@@ -310,6 +232,7 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
   // run the animation on each frame
   const runAnimation = () => {
     //if (!frameName) return
+
     const now = window.performance.now();
     const diff = now - timerOffset.current;
     const {
@@ -345,9 +268,6 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
           currentFrameName: frameName,
           currentFrame: currentFrame.current
         });
-        if (!_offset) {
-          console.log('will end');
-        }
         state.hasEnded = resetOnEnd ? false : true;
         if (resetOnEnd) {
           pauseRef.current = true;
@@ -419,7 +339,6 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
       // Ensure the frame index is within the valid range
       frameIndex = Math.max(0, Math.min(frameIndex, spriteFrames.length - 1));
       if (isNaN(frameIndex)) {
-        console.log('nan frame detected');
         frameIndex = 0; //fallback
       }
 
@@ -476,16 +395,18 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
     ref: spriteRef,
     scale: aspect
   }, /*#__PURE__*/React.createElement("spriteMaterial", {
+    premultipliedAlpha: false,
     toneMapped: false,
     ref: matRef,
     map: spriteTexture,
     transparent: true,
     alphaTest: alphaTest !== null && alphaTest !== void 0 ? alphaTest : 0.0
   })), !displayAsSprite && /*#__PURE__*/React.createElement(Instances, {
-    limit: maxItems // Optional: max amount of items (for calculating buffer size)
+    limit: maxItems !== null && maxItems !== void 0 ? maxItems : 1 // Optional: max amount of items (for calculating buffer size)
   }, /*#__PURE__*/React.createElement("planeGeometry", {
     args: [1, 1]
   }), /*#__PURE__*/React.createElement("meshBasicMaterial", {
+    premultipliedAlpha: false,
     toneMapped: false,
     side: THREE.DoubleSide,
     ref: matRef,
@@ -493,23 +414,12 @@ const SpriteAnimator = /* @__PURE__ */React.forwardRef(({
     transparent: true,
     alphaTest: alphaTest !== null && alphaTest !== void 0 ? alphaTest : 0.0
   }), (instanceItems !== null && instanceItems !== void 0 ? instanceItems : [0]).map((item, index) => {
-    const texture = spriteTexture.clone();
-    if (matRef.current && frameBuffer.current[index]) {
-      texture.offset.set(frameBuffer.current[index].offset.x, frameBuffer.current[index].offset.y); // Set the offset for this item
-    }
-
     return /*#__PURE__*/React.createElement(Instance, {
       key: index,
       ref: spriteRef,
       position: item,
       scale: aspect
-    }, /*#__PURE__*/React.createElement("meshBasicMaterial", {
-      toneMapped: false,
-      side: THREE.DoubleSide,
-      map: texture,
-      transparent: true,
-      alphaTest: alphaTest !== null && alphaTest !== void 0 ? alphaTest : 0.0
-    }));
+    });
   }))), children));
 });
 

package/core/calculateScaleFactor.cjs.js

@@ -0,0 +1 @@
+"use strict";function e(e){if(e&&e.__esModule)return e;var t=Object.create(null);return e&&Object.keys(e).forEach((function(r){if("default"!==r){var o=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,o.get?o:{enumerable:!0,get:function(){return e[r]}})}})),t.default=e,Object.freeze(t)}Object.defineProperty(exports,"__esModule",{value:!0});var t=e(require("three"));const r=new t.Vector3,o=new t.Vector3,n=new t.Vector3,c=(e,t,o,n=1)=>{const c=r.set(e.x/o.width*2-1,-e.y/o.height*2+1,n);return c.unproject(t),c};exports.calculateScaleFactor=(e,t,r,u)=>{const a=((e,t,r)=>{const o=r.width/2,n=r.height/2;t.updateMatrixWorld(!1);const c=e.project(t);return c.x=c.x*o+o,c.y=-c.y*n+n,c})(n.copy(e),r,u);let s=0;for(let n=0;n<2;++n){const i=o.copy(a).setComponent(n,a.getComponent(n)+t),l=c(i,r,u,i.z);s=Math.max(s,e.distanceTo(l))}return s};

package/core/calculateScaleFactor.d.ts

@@ -0,0 +1,3 @@
+import { Size } from '@react-three/fiber';
+import * as THREE from 'three';
+export declare const calculateScaleFactor: (point3: THREE.Vector3, radiusPx: number, camera: THREE.Camera, size: Size) => number;

package/core/calculateScaleFactor.js

@@ -0,0 +1,31 @@
+import * as THREE from 'three';
+
+const tV0 = /* @__PURE__ */new THREE.Vector3();
+const tV1 = /* @__PURE__ */new THREE.Vector3();
+const tV2 = /* @__PURE__ */new THREE.Vector3();
+const getPoint2 = (point3, camera, size) => {
+  const widthHalf = size.width / 2;
+  const heightHalf = size.height / 2;
+  camera.updateMatrixWorld(false);
+  const vector = point3.project(camera);
+  vector.x = vector.x * widthHalf + widthHalf;
+  vector.y = -(vector.y * heightHalf) + heightHalf;
+  return vector;
+};
+const getPoint3 = (point2, camera, size, zValue = 1) => {
+  const vector = tV0.set(point2.x / size.width * 2 - 1, -(point2.y / size.height) * 2 + 1, zValue);
+  vector.unproject(camera);
+  return vector;
+};
+const calculateScaleFactor = (point3, radiusPx, camera, size) => {
+  const point2 = getPoint2(tV2.copy(point3), camera, size);
+  let scale = 0;
+  for (let i = 0; i < 2; ++i) {
+    const point2off = tV1.copy(point2).setComponent(i, point2.getComponent(i) + radiusPx);
+    const point3off = getPoint3(point2off, camera, size, point2off.z);
+    scale = Math.max(scale, point3.distanceTo(point3off));
+  }
+  return scale;
+};
+
+export { calculateScaleFactor };