@octanejs/drei 0.0.1

package/src/core/SpotLight.three.tsrx

@@ -0,0 +1,350 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame, useThree } from '@octanejs/three';
+import { useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import * as THREE from 'three';
+import { FullScreenQuad } from 'three-stdlib';
+
+export type SpotLightProps = Omit<ThreeElements['spotLight'], 'ref' | 'children'> & {
+	depthBuffer?: THREE.DepthTexture;
+	attenuation?: number;
+	anglePower?: number;
+	radiusTop?: number;
+	radiusBottom?: number;
+	opacity?: number;
+	color?: string | number;
+	volumetric?: boolean;
+	debug?: boolean;
+	children?: OctaneNode;
+};
+
+class SpotLightMaterial extends THREE.ShaderMaterial {
+	constructor() {
+		super({
+			uniforms: {
+				depth: { value: null },
+				opacity: { value: 1 },
+				attenuation: { value: 2.5 },
+				anglePower: { value: 12 },
+				spotPosition: { value: new THREE.Vector3(0, 0, 0) },
+				lightColor: { value: new THREE.Color('white') },
+				cameraNear: { value: 0 },
+				cameraFar: { value: 1 },
+				resolution: { value: new THREE.Vector2(0, 0) },
+			},
+			transparent: true,
+			depthWrite: false,
+			vertexShader: /* glsl */ `
+        varying vec3 vNormal;
+        varying float vViewZ;
+        varying float vIntensity;
+        uniform vec3 spotPosition;
+        uniform float attenuation;
+
+        #include <common>
+        #include <logdepthbuf_pars_vertex>
+
+        void main() {
+          vNormal = normalize(normalMatrix * normal);
+          vec4 worldPosition = modelMatrix * vec4(position, 1);
+          vec4 viewPosition = viewMatrix * worldPosition;
+          vViewZ = viewPosition.z;
+          vIntensity = 1.0 - saturate(distance(worldPosition.xyz, spotPosition) / attenuation);
+          gl_Position = projectionMatrix * viewPosition;
+          #include <logdepthbuf_vertex>
+        }
+      `,
+			fragmentShader: /* glsl */ `
+        varying vec3 vNormal;
+        varying float vViewZ;
+        varying float vIntensity;
+        uniform vec3 lightColor;
+        uniform float anglePower;
+        uniform sampler2D depth;
+        uniform vec2 resolution;
+        uniform float cameraNear;
+        uniform float cameraFar;
+        uniform float opacity;
+
+        #include <packing>
+        #include <logdepthbuf_pars_fragment>
+
+        float readDepth(sampler2D depthSampler, vec2 uv) {
+          float fragCoordZ = texture(depthSampler, uv).r;
+          #ifdef USE_LOGDEPTHBUF
+            float viewZ = 1.0 - exp2(fragCoordZ * log(cameraFar + 1.0) / log(2.0));
+          #else
+            float viewZ = perspectiveDepthToViewZ(fragCoordZ, cameraNear, cameraFar);
+          #endif
+          return viewZ;
+        }
+
+        void main() {
+          #include <logdepthbuf_fragment>
+          vec3 normal = vec3(vNormal.x, vNormal.y, abs(vNormal.z));
+          float angleIntensity = pow(dot(normal, vec3(0, 0, 1)), anglePower);
+          float intensity = vIntensity * angleIntensity;
+          bool isSoft = resolution[0] > 0.0 && resolution[1] > 0.0;
+          if (isSoft) {
+            vec2 uv = gl_FragCoord.xy / resolution;
+            intensity *= smoothstep(0.0, 1.0, vViewZ - readDepth(depth, uv));
+          }
+          gl_FragColor = vec4(lightColor, intensity * opacity);
+          #include <tonemapping_fragment>
+          #include <colorspace_fragment>
+        }
+      `,
+		});
+	}
+}
+
+const isSpotLight = (child: THREE.Object3D | null): child is THREE.SpotLight =>
+	Boolean((child as THREE.SpotLight | null)?.isSpotLight);
+
+function VolumetricMesh({
+	opacity = 1,
+	radiusTop,
+	radiusBottom,
+	depthBuffer,
+	color = 'white',
+	distance = 5,
+	angle = 0.15,
+	attenuation = 5,
+	anglePower = 5,
+}: Omit<SpotLightProps, 'volumetric'>) @{
+	const mesh = useRef<THREE.Mesh | null>(null);
+	const size = useThree((state) => state.size);
+	const camera = useThree((state) => state.camera);
+	const dpr = useThree((state) => state.viewport.dpr);
+	const [material] = useState(() => new SpotLightMaterial());
+	const [vector] = useState(() => new THREE.Vector3());
+	const top = radiusTop === undefined ? 0.1 : radiusTop;
+	const bottom = radiusBottom === undefined ? angle * 7 : radiusBottom;
+	useFrame(() => {
+		if (!mesh.current) return;
+		material.uniforms.spotPosition.value.copy(mesh.current.getWorldPosition(vector));
+		mesh.current.lookAt((mesh.current.parent as THREE.SpotLight).target.getWorldPosition(vector));
+	});
+	const geom = useMemo(() => {
+		const value = new THREE.CylinderGeometry(top, bottom, distance, 128, 64, true);
+		value.applyMatrix4(new THREE.Matrix4().makeTranslation(0, -distance / 2, 0));
+		value.applyMatrix4(new THREE.Matrix4().makeRotationX(-Math.PI / 2));
+		return value;
+	}, [distance, top, bottom]);
+	<mesh ref={mesh} {...({ geometry: geom, raycast: () => null } as any)}>
+		<primitive
+			object={material}
+			attach="material"
+			uniforms-opacity-value={opacity}
+			uniforms-lightColor-value={color}
+			uniforms-attenuation-value={attenuation}
+			uniforms-anglePower-value={anglePower}
+			uniforms-depth-value={depthBuffer}
+			uniforms-cameraNear-value={camera.near}
+			uniforms-cameraFar-value={camera.far}
+			uniforms-resolution-value={depthBuffer ? [size.width * dpr, size.height * dpr] : [0, 0]}
+		/>
+	</mesh>
+}
+
+function useCommon(
+	spotlight: { current: THREE.SpotLight | null },
+	mesh: { current: THREE.Mesh | null },
+	width: number,
+	height: number,
+	distance: number,
+): void {
+	const [[position, direction]] = useState(() => [new THREE.Vector3(), new THREE.Vector3()]);
+	useLayoutEffect(() => {
+		if (isSpotLight(spotlight.current)) {
+			spotlight.current.shadow.mapSize.set(width, height);
+			spotlight.current.shadow.needsUpdate = true;
+		} else throw new Error('SpotlightShadow must be a child of a SpotLight');
+	}, [spotlight, width, height]);
+	useFrame(() => {
+		if (!spotlight.current || !mesh.current) return;
+		const source = spotlight.current.position;
+		const target = spotlight.current.target.position;
+		direction.copy(target).sub(source);
+		const length = direction.length();
+		direction.normalize().multiplyScalar(length * distance);
+		position.copy(source).add(direction);
+		mesh.current.position.copy(position);
+		mesh.current.lookAt(spotlight.current.target.position);
+	});
+}
+
+interface ShadowMeshProps {
+	distance?: number;
+	alphaTest?: number;
+	scale?: number;
+	map?: THREE.Texture;
+	shader?: string;
+	width?: number;
+	height?: number;
+	children?: OctaneNode;
+	spotlightRef?: { current: THREE.SpotLight | null };
+	debug?: boolean;
+}
+
+const SpotLightShadowContext = createContext<{
+	spotlightRef: { current: THREE.SpotLight | null };
+	debug: boolean;
+} | null>(null);
+
+const defaultSpotlightShadowShader = /* glsl */ `
+varying vec2 vUv;
+
+uniform sampler2D uShadowMap;
+uniform float uTime;
+
+void main() {
+    vec3 color = texture2D(uShadowMap, vUv).xyz;
+    gl_FragColor = vec4(color, 1.);
+}
+`;
+
+function SpotlightShadowWithShader({
+	distance = 0.4,
+	alphaTest = 0.5,
+	map,
+	shader = defaultSpotlightShadowShader,
+	width = 512,
+	height = 512,
+	scale = 1,
+	children,
+	spotlightRef,
+	debug,
+}: ShadowMeshProps) @{
+	const mesh = useRef<THREE.Mesh | null>(null);
+	const parent = useContext(SpotLightShadowContext);
+	const activeSpotlight = spotlightRef ?? parent?.spotlightRef;
+	const activeDebug = debug ?? parent?.debug;
+	useCommon(activeSpotlight!, mesh, width, height, distance);
+	const renderTarget = useMemo(() => new THREE.WebGLRenderTarget(width, height, {
+		format: THREE.RGBAFormat,
+		stencilBuffer: false,
+	}), [width, height]);
+	const uniforms = useRef({ uShadowMap: { value: map }, uTime: { value: 0 } });
+	useEffect(() => { uniforms.current.uShadowMap.value = map; }, [map]);
+	const fsQuad = useMemo(() => new FullScreenQuad(new THREE.ShaderMaterial({
+		uniforms: uniforms.current,
+		vertexShader: /* glsl */ `
+          varying vec2 vUv;
+          void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+          }
+          `,
+		fragmentShader: shader,
+	}) as any), [shader]);
+	useEffect(() => () => {
+		fsQuad.material.dispose();
+		fsQuad.dispose();
+	}, [fsQuad]);
+	useEffect(() => () => renderTarget.dispose(), [renderTarget]);
+	useFrame(({ gl }, delta) => {
+		uniforms.current.uTime.value += delta;
+		gl.setRenderTarget(renderTarget);
+		fsQuad.render(gl as any);
+		gl.setRenderTarget(null);
+	});
+	<mesh ref={mesh} scale={scale} castShadow>
+		<planeGeometry />
+		<meshBasicMaterial
+			transparent
+			side={THREE.DoubleSide}
+			alphaTest={alphaTest}
+			alphaMap={renderTarget.texture}
+			alphaMap-wrapS={THREE.RepeatWrapping}
+			alphaMap-wrapT={THREE.RepeatWrapping}
+			opacity={activeDebug ? 1 : 0}
+		>
+			{children}
+		</meshBasicMaterial>
+	</mesh>
+}
+
+function SpotlightShadowWithoutShader({
+	distance = 0.4,
+	alphaTest = 0.5,
+	map,
+	width = 512,
+	height = 512,
+	scale,
+	children,
+	spotlightRef,
+	debug,
+}: ShadowMeshProps) @{
+	const mesh = useRef<THREE.Mesh | null>(null);
+	const parent = useContext(SpotLightShadowContext);
+	const activeSpotlight = spotlightRef ?? parent?.spotlightRef;
+	const activeDebug = debug ?? parent?.debug;
+	useCommon(activeSpotlight!, mesh, width, height, distance);
+	<mesh ref={mesh} scale={scale} castShadow>
+		<planeGeometry />
+		<meshBasicMaterial
+			transparent
+			side={THREE.DoubleSide}
+			alphaTest={alphaTest}
+			alphaMap={map}
+			alphaMap-wrapS={THREE.RepeatWrapping}
+			alphaMap-wrapT={THREE.RepeatWrapping}
+			opacity={activeDebug ? 1 : 0}
+		>
+			{children}
+		</meshBasicMaterial>
+	</mesh>
+}
+
+export function SpotLightShadow(props: ShadowMeshProps) @{
+	@if (props.shader) {
+		<SpotlightShadowWithShader {...props} />
+	} @else {
+		<SpotlightShadowWithoutShader {...props} />
+	}
+}
+
+export function SpotLight({
+	opacity = 1,
+	radiusTop,
+	radiusBottom,
+	depthBuffer,
+	color = 'white',
+	distance = 5,
+	angle = 0.15,
+	attenuation = 5,
+	anglePower = 5,
+	volumetric = true,
+	debug = false,
+	children,
+	ref: forwardedRef,
+	...props
+}: SpotLightProps & { ref?: ThreeRef<THREE.SpotLight> }) @{
+	const spotlight = useRef<THREE.SpotLight | null>(null);
+	useImperativeHandle((forwardedRef ?? null) as any, () => spotlight.current!, []);
+	<group>
+		@if (debug && spotlight.current) {
+			<spotLightHelper args={[spotlight.current]} />
+		}
+		<spotLight ref={spotlight} angle={angle} color={color} distance={distance} castShadow {...props as any}>
+			@if (volumetric) {
+				<VolumetricMesh
+					debug={debug}
+					opacity={opacity}
+					radiusTop={radiusTop}
+					radiusBottom={radiusBottom}
+					depthBuffer={depthBuffer}
+					color={color}
+					distance={distance}
+					angle={angle}
+					attenuation={attenuation}
+					anglePower={anglePower}
+				/>
+			}
+		</spotLight>
+		<SpotLightShadowContext.Provider value={{ spotlightRef: spotlight, debug }}>
+			{children}
+		</SpotLightShadowContext.Provider>
+	</group>
+}

package/src/core/SpriteAnimator.three.tsrx

@@ -0,0 +1,338 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, type Vector3, useFrame } from '@octanejs/three';
+import {
+	useCallback,
+	useEffect,
+	useImperativeHandle,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import * as THREE from 'three';
+import { Instance, Instances, type InstanceProps, type InstancesProps } from './Instances.three.tsrx';
+import { Billboard } from './scene-motion.three.tsrx';
+import {
+	getFirstFrame,
+	type FrameData,
+	type Size,
+	type SpriteData,
+	useSpriteLoader,
+} from './useSpriteLoader.three.tsrx';
+
+type AnimationEventData = { currentFrameName: string; currentFrame: number };
+type CommonProps<T, U, V> = Pick<T & U & V, keyof T & keyof U & keyof V>;
+type CommonMeshProps = CommonProps<ThreeElements['mesh'], InstanceProps, InstancesProps>;
+
+export type SpriteAnimatorProps = {
+	startFrame?: number;
+	endFrame?: number;
+	fps?: number;
+	frameName?: string;
+	textureDataURL?: string;
+	textureImageURL?: string;
+	loop?: boolean;
+	numberOfFrames?: number;
+	autoPlay?: boolean;
+	animationNames?: string[];
+	onStart?: (data: AnimationEventData) => void;
+	onEnd?: (data: AnimationEventData) => void;
+	onLoopEnd?: (data: AnimationEventData) => void;
+	onFrame?: (data: AnimationEventData) => void;
+	/** @deprecated Use pause={false} instead. */
+	play?: boolean;
+	pause?: boolean;
+	flipX?: boolean;
+	alphaTest?: number;
+	asSprite?: boolean;
+	offset?: number;
+	playBackwards?: boolean;
+	resetOnEnd?: boolean;
+	instanceItems?: Vector3[];
+	maxItems?: number;
+	spriteDataset?: {
+		spriteTexture: THREE.Texture;
+		spriteData: SpriteData | null;
+		aspect: Vector3;
+	} | null;
+	canvasRenderingContext2DSettings?: CanvasRenderingContext2DSettings;
+	roundFramePosition?: boolean;
+	meshProps?: CommonMeshProps;
+	children?: OctaneNode;
+} & Omit<ThreeElements['group'], 'ref' | 'children'>;
+
+type SpriteAnimatorState = {
+	current?: number;
+	offset?: number;
+	imageUrl?: string;
+	hasEnded: boolean;
+	ref: ThreeRef<THREE.Group> | undefined;
+};
+
+type Scale = Vector3;
+
+const context = createContext<SpriteAnimatorState | null>(null);
+
+export function useSpriteAnimator(): SpriteAnimatorState | null {
+	return useContext(context);
+}
+
+function isSpriteData(data: SpriteData | null): data is SpriteData {
+	return data !== null && 'meta' in data && 'frames' in data;
+}
+
+const geometry = /* @__PURE__ */ new THREE.PlaneGeometry(1, 1);
+
+export function SpriteAnimator({
+	startFrame = 0,
+	endFrame,
+	fps = 30,
+	frameName = '',
+	textureDataURL,
+	textureImageURL,
+	loop = false,
+	numberOfFrames = 1,
+	autoPlay = true,
+	animationNames,
+	onStart,
+	onEnd,
+	onLoopEnd,
+	onFrame,
+	play,
+	pause = false,
+	flipX = false,
+	alphaTest = 0,
+	children,
+	asSprite = false,
+	offset,
+	playBackwards = false,
+	resetOnEnd = false,
+	maxItems = 1,
+	instanceItems = [[0, 0, 0]],
+	spriteDataset,
+	canvasRenderingContext2DSettings,
+	roundFramePosition = false,
+	meshProps = {},
+	ref: forwardedRef,
+	...props
+}: SpriteAnimatorProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const ref = useRef<THREE.Group | null>(new THREE.Group());
+	const spriteData = useRef<SpriteData | null>(null);
+	const matRef = useRef<THREE.MeshBasicMaterial | null>(null);
+	const spriteRef = useRef<THREE.Mesh | THREE.InstancedMesh | null>(null);
+	const timerOffset = useRef(window.performance.now());
+	const currentFrame = useRef(startFrame);
+	const currentFrameName = useRef(frameName);
+	const fpsInterval = fps > 0 ? 1000 / fps : 0;
+	const [spriteTexture, setSpriteTexture] = useState(new THREE.Texture());
+	const totalFrames = useRef(0);
+	const [aspect, setAspect] = useState(new THREE.Vector3(1, 1, 1));
+	const flipOffset = flipX ? -1 : 1;
+	const pauseRef = useRef(pause);
+	const pos = useRef(offset);
+	const softEnd = useRef(false);
+	const { spriteObj, loadJsonAndTexture } = useSpriteLoader(
+		null,
+		null,
+		animationNames,
+		numberOfFrames,
+		undefined,
+		canvasRenderingContext2DSettings,
+	);
+	const frameNameRef = useRef(frameName);
+
+	const calculateAspectRatio = (width: number, height: number) => {
+		const result = new THREE.Vector3();
+		result.set(1, height / width, 1);
+		spriteRef.current?.scale.copy(result);
+		return result;
+	};
+
+	const parseSpriteDataLite = useCallback((textureData: THREE.Texture, data: SpriteData | null) => {
+		if (data === null) {
+			if (numberOfFrames) {
+				totalFrames.current = numberOfFrames;
+				if (playBackwards) currentFrame.current = numberOfFrames - 1;
+				spriteData.current = data;
+			}
+		} else {
+			spriteData.current = data;
+			if (Array.isArray(spriteData.current.frames)) totalFrames.current = spriteData.current.frames.length;
+			else if (typeof spriteData.current === 'object' && frameNameRef.current) {
+				totalFrames.current = spriteData.current.frames[frameNameRef.current].length;
+			} else totalFrames.current = 0;
+			if (playBackwards) currentFrame.current = totalFrames.current - 1;
+			const { w, h } = getFirstFrame(spriteData.current?.frames ?? [], frameNameRef.current).sourceSize;
+			setAspect(calculateAspectRatio(w, h));
+			if (matRef.current) matRef.current.map = textureData;
+		}
+		setSpriteTexture(textureData);
+	}, [numberOfFrames, playBackwards]);
+
+	const modifySpritePosition = useCallback((): void => {
+		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 };
+		if (matRef.current?.map) {
+			matRef.current.map.wrapS = matRef.current.map.wrapT = THREE.RepeatWrapping;
+			matRef.current.map.center.set(0, 0);
+			matRef.current.map.repeat.set(flipOffset / (metaInfo.w / frameW), 1 / (metaInfo.h / frameH));
+		}
+		const framesV = (metaInfo.h - 1) / frameH;
+		const frameOffsetY = 1 / framesV;
+		if (matRef.current?.map) {
+			matRef.current.map.offset.x = 0;
+			matRef.current.map.offset.y = 1 - frameOffsetY;
+		}
+		onStart?.({ currentFrameName: frameName ?? '', currentFrame: currentFrame.current });
+	}, [flipOffset, frameName, onStart]);
+
+	const state = useMemo<SpriteAnimatorState>(() => ({
+		current: pos.current,
+		offset: pos.current,
+		imageUrl: textureImageURL,
+		hasEnded: false,
+		ref: forwardedRef,
+	}), [textureImageURL, forwardedRef]);
+
+	useImperativeHandle((forwardedRef ?? null) as any, () => ref.current!, []);
+	useLayoutEffect(() => { pos.current = offset; }, [offset]);
+
+	useEffect(() => {
+		if (spriteDataset) parseSpriteDataLite(spriteDataset.spriteTexture.clone(), spriteDataset.spriteData);
+		else if (textureImageURL && textureDataURL) loadJsonAndTexture(textureImageURL, textureDataURL);
+	}, [loadJsonAndTexture, spriteDataset, textureDataURL, textureImageURL, parseSpriteDataLite]);
+
+	useEffect(() => {
+		if (spriteObj) parseSpriteDataLite(spriteObj.spriteTexture.clone(), spriteObj.spriteData);
+	}, [spriteObj, parseSpriteDataLite]);
+
+	useEffect(() => {
+		state.hasEnded = false;
+		if (spriteData.current && playBackwards === true) {
+			currentFrame.current = ((spriteData.current.frames.length as number) ?? 0) - 1;
+		} else currentFrame.current = 0;
+	}, [playBackwards, state]);
+
+	useLayoutEffect(() => { modifySpritePosition(); }, [spriteTexture, flipX, modifySpritePosition]);
+	useEffect(() => { if (autoPlay) pauseRef.current = false; }, [autoPlay]);
+
+	useLayoutEffect(() => {
+		if (currentFrameName.current !== frameName && frameName) {
+			currentFrame.current = 0;
+			currentFrameName.current = frameName;
+			state.hasEnded = false;
+			if (fpsInterval <= 0) currentFrame.current = endFrame || startFrame || 0;
+			if (spriteData.current) {
+				const { w, h } = getFirstFrame(spriteData.current.frames, frameName).sourceSize;
+				setAspect(calculateAspectRatio(w, h));
+			}
+		}
+	}, [frameName, fpsInterval, state, endFrame, startFrame]);
+
+	const calculateFinalPosition = (frameW: number, frameH: number, metaInfo: Size, spriteFrames: FrameData[]) => {
+		const activeOffset = offset === undefined ? state.current : offset;
+		const targetFrame = currentFrame.current;
+		calculateAspectRatio(frameW, frameH);
+		const framesH = roundFramePosition ? Math.round((metaInfo.w - 1) / frameW) : (metaInfo.w - 1) / frameW;
+		const framesV = roundFramePosition ? Math.round((metaInfo.h - 1) / frameH) : (metaInfo.h - 1) / frameH;
+		if (!spriteFrames[targetFrame]) return;
+		const { frame: { x: frameX, y: frameY }, sourceSize: { w: originalSizeX, h: originalSizeY } } = spriteFrames[targetFrame];
+		const frameOffsetX = 1 / framesH;
+		const frameOffsetY = 1 / framesV;
+		if (matRef.current?.map) {
+			matRef.current.map.offset.x = flipOffset > 0
+				? frameOffsetX * (frameX / originalSizeX)
+				: frameOffsetX * (frameX / originalSizeX) - matRef.current.map.repeat.x;
+			matRef.current.map.offset.y = Math.abs(1 - frameOffsetY) - frameOffsetY * (frameY / originalSizeY);
+		}
+		if (activeOffset !== undefined && activeOffset !== null) {
+			let frameIndex = Math.floor(activeOffset * spriteFrames.length);
+			frameIndex = Math.max(0, Math.min(frameIndex, spriteFrames.length - 1));
+			if (isNaN(frameIndex)) frameIndex = 0;
+			currentFrame.current = frameIndex;
+		} else if (playBackwards) currentFrame.current -= 1;
+		else currentFrame.current += 1;
+	};
+
+	const runAnimation = (): void => {
+		if (!isSpriteData(spriteData.current)) return;
+		const { meta: { size: metaInfo }, frames } = spriteData.current;
+		const { w: frameW, h: frameH } = getFirstFrame(frames, frameName).sourceSize;
+		const spriteFrames = Array.isArray(frames) ? frames : frameName ? frames[frameName] : [];
+		const activeEndFrame = endFrame || spriteFrames.length - 1;
+		const activeOffset = offset === undefined ? state.current : offset;
+		if (fpsInterval <= 0) {
+			currentFrame.current = endFrame || startFrame || 0;
+			calculateFinalPosition(frameW, frameH, metaInfo, spriteFrames);
+			return;
+		}
+		const now = window.performance.now();
+		const difference = now - timerOffset.current;
+		if (difference <= fpsInterval) return;
+		const endCondition = playBackwards ? currentFrame.current < 0 : currentFrame.current > activeEndFrame;
+		const onStartCondition = playBackwards ? currentFrame.current === activeEndFrame : currentFrame.current === 0;
+		const manualProgressEndCondition = playBackwards ? currentFrame.current < 0 : currentFrame.current >= activeEndFrame;
+		if (endCondition) {
+			currentFrame.current = loop ? (startFrame ?? 0) : 0;
+			if (playBackwards) currentFrame.current = activeEndFrame;
+			if (loop) onLoopEnd?.({ currentFrameName: frameName ?? '', currentFrame: currentFrame.current });
+			else {
+				onEnd?.({ currentFrameName: frameName ?? '', currentFrame: currentFrame.current });
+				state.hasEnded = !resetOnEnd;
+				if (resetOnEnd) pauseRef.current = true;
+			}
+			if (!loop) return;
+		} else if (onStartCondition) onStart?.({ currentFrameName: frameName ?? '', currentFrame: currentFrame.current });
+		if (activeOffset !== undefined && manualProgressEndCondition) {
+			if (softEnd.current === false) {
+				onEnd?.({ currentFrameName: frameName ?? '', currentFrame: currentFrame.current });
+				softEnd.current = true;
+			}
+		} else softEnd.current = false;
+		if (difference <= fpsInterval) return;
+		timerOffset.current = now - (difference % fpsInterval);
+		calculateFinalPosition(frameW, frameH, metaInfo, spriteFrames);
+	};
+
+	useFrame(() => {
+		if (!spriteData.current?.frames || !matRef.current?.map || pauseRef.current) return;
+		if (!state.hasEnded && (autoPlay || play)) {
+			runAnimation();
+			onFrame?.({ currentFrameName: currentFrameName.current, currentFrame: currentFrame.current });
+		}
+	});
+
+	function multiplyScale(initialScale = new THREE.Vector3(1, 1, 1), newScale: Scale = 1) {
+		if (typeof newScale === 'number') return initialScale.multiplyScalar(newScale);
+		if (Array.isArray(newScale)) return initialScale.multiply(new THREE.Vector3(...newScale));
+		if (newScale instanceof THREE.Vector3) return initialScale.multiply(newScale);
+	}
+
+	<group {...props as any} ref={ref} scale={multiplyScale(aspect, props.scale as Scale | undefined)}>
+		<context.Provider value={state}>
+			@if (asSprite) {
+				<Billboard>
+					<mesh ref={spriteRef as any} scale={1} geometry={geometry} {...meshProps as any}>
+						<meshBasicMaterial premultipliedAlpha={false} toneMapped={false} side={THREE.DoubleSide} ref={matRef} map={spriteTexture} transparent={true} alphaTest={alphaTest ?? 0} />
+					</mesh>
+				</Billboard>
+			} @else {
+				<Instances geometry={geometry} limit={maxItems ?? 1} {...meshProps as any}>
+					<meshBasicMaterial premultipliedAlpha={false} toneMapped={false} side={THREE.DoubleSide} ref={matRef} map={spriteTexture} transparent={true} alphaTest={alphaTest ?? 0} />
+					{(instanceItems ?? [0]).map((item, index) => (
+						<Instance key={index} ref={(instanceItems?.length === 1 ? spriteRef : null) as any} position={item as Vector3} scale={1} {...meshProps as any} />
+					))}
+				</Instances>
+			}
+			{children}
+		</context.Provider>
+	</group>
+}