refactor: organize three components by domain

src/components/three/models/AnimatedModel.tsx

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useGLTF, useAnimations } from "@react-three/drei";
+import type { AnimationAction } from "three";
+import * as THREE from "three";
+import {
+  AnimatedModelContext,
+  type AnimatedModelContextValue,
+} from "@/components/three/models/useAnimatedModel";
+import type { Vector3Tuple } from "@/types/three";
+
+export interface AnimatedModelConfig {
+  modelPath: string;
+  animations?: string[];
+  defaultAnimation?: string;
+  position?: Vector3Tuple;
+  rotation?: Vector3Tuple;
+  scale?: Vector3Tuple | number;
+  fadeDuration?: number;
+  speed?: number;
+  autoPlay?: boolean;
+  onLoaded?: () => void;
+  onAnimationEnd?: (animationName: string) => void;
+}
+
+interface AnimatedModelProps extends AnimatedModelConfig {
+  children?: React.ReactNode;
+}
+
+export function AnimatedModel({
+  modelPath,
+  defaultAnimation = "Idle",
+  position = [0, 0, 0],
+  rotation = [0, 0, 0],
+  scale = 1,
+  fadeDuration = 0.3,
+  speed = 1,
+  autoPlay = true,
+  onLoaded,
+  onAnimationEnd,
+  children,
+}: AnimatedModelProps): React.JSX.Element {
+  const groupRef = useRef<THREE.Group>(null);
+  const { scene, animations } = useGLTF(modelPath);
+  const model = useMemo(() => scene.clone(true), [scene]);
+  const { actions, names, mixer } = useAnimations(animations, groupRef);
+
+  const [currentAnim, setCurrentAnim] = useState(defaultAnimation);
+  const isReady = names.length > 0;
+
+  useEffect(() => {
+    Object.values(actions).forEach((action) => {
+      action?.setEffectiveTimeScale(speed);
+    });
+  }, [actions, speed]);
+
+  useEffect(() => {
+    const handleFinished = (e: { action: AnimationAction }) => {
+      const clipName = e.action.getClip().name;
+      onAnimationEnd?.(clipName);
+    };
+
+    if (mixer) {
+      mixer.addEventListener("finished", handleFinished);
+      return () => {
+        mixer.removeEventListener("finished", handleFinished);
+      };
+    }
+  }, [mixer, onAnimationEnd]);
+
+  const play = useCallback(
+    (name: string, fade = fadeDuration) => {
+      const action = actions[name];
+      if (action) {
+        Object.values(actions).forEach((a) => {
+          if (a && a !== action) a.fadeOut(fade);
+        });
+        action.reset().fadeIn(fade).play();
+        setCurrentAnim(name);
+      }
+    },
+    [actions, fadeDuration],
+  );
+
+  const stop = useCallback(
+    (fade = fadeDuration) => {
+      Object.values(actions).forEach((a) => a?.fadeOut(fade));
+      const defaultAction = actions[defaultAnimation];
+      if (defaultAction) {
+        defaultAction.reset().fadeIn(fade).play();
+        setCurrentAnim(defaultAnimation);
+      }
+    },
+    [actions, defaultAnimation, fadeDuration],
+  );
+
+  const fadeTo = useCallback(
+    (name: string, fade = fadeDuration) => {
+      const action = actions[name];
+      if (action) {
+        Object.values(actions).forEach((a) => {
+          if (a && a !== action) a.fadeOut(fade);
+        });
+        action.reset().fadeIn(fade).play();
+        setCurrentAnim(name);
+      }
+    },
+    [actions, fadeDuration],
+  );
+
+  const setSpeed = useCallback(
+    (newSpeed: number) => {
+      Object.values(actions).forEach((action) => {
+        action?.setEffectiveTimeScale(newSpeed);
+      });
+    },
+    [actions],
+  );
+
+  useEffect(() => {
+    if (!autoPlay || names.length === 0) {
+      return;
+    }
+
+    let defaultAction = actions[defaultAnimation as string];
+
+    if (!defaultAction && names.length > 0) {
+      defaultAction = actions[names[0] as string];
+    }
+
+    if (defaultAction) {
+      defaultAction.play();
+      onLoaded?.();
+    }
+  }, [actions, defaultAnimation, names, autoPlay, onLoaded]);
+
+  const contextValue: AnimatedModelContextValue = {
+    play,
+    stop,
+    fadeTo,
+    currentAnimation: currentAnim,
+    isReady,
+    setSpeed,
+    names,
+  };
+
+  const parsedScale =
+    typeof scale === "number" ? ([scale, scale, scale] as Vector3Tuple) : scale;
+
+  return (
+    <AnimatedModelContext.Provider value={contextValue}>
+      <group
+        ref={groupRef}
+        position={position}
+        rotation={rotation}
+        scale={parsedScale}
+      >
+        <primitive object={model} />
+      </group>
+      {children}
+    </AnimatedModelContext.Provider>
+  );
+}

src/components/three/models/ExplodableModel.tsx

@@ -0,0 +1,105 @@
+import type { ReactNode } from "react";
+import { Component, useEffect, useMemo } from "react";
+import { useFrame } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+import { ExplodedModel } from "@/utils/ExplodedModel";
+import type { Vector3Tuple } from "@/types/three";
+
+interface ModelErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface ModelErrorBoundaryState {
+  hasError: boolean;
+}
+
+class ModelErrorBoundary extends Component<
+  ModelErrorBoundaryProps,
+  ModelErrorBoundaryState
+> {
+  constructor(props: ModelErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(): ModelErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    console.warn("Failed to load explodable model", error);
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) return this.props.fallback ?? null;
+    return this.props.children;
+  }
+}
+
+interface ExplodableModelInnerProps {
+  modelPath: string;
+  split: boolean;
+  position?: Vector3Tuple;
+  rotation?: Vector3Tuple;
+  scale?: number | Vector3Tuple;
+  splitDistance?: number;
+}
+
+export function ExplodableModel(
+  props: ExplodableModelInnerProps,
+): React.JSX.Element {
+  return (
+    <ModelErrorBoundary
+      key={props.modelPath}
+      fallback={<MissingModelFallback position={props.position} />}
+    >
+      <ExplodableModelInner {...props} />
+    </ModelErrorBoundary>
+  );
+}
+
+function ExplodableModelInner({
+  modelPath,
+  split,
+  position = [0, 0, 0],
+  rotation = [0, 0, 0],
+  scale = 1,
+  splitDistance = 1.2,
+}: ExplodableModelInnerProps): React.JSX.Element {
+  const { scene } = useGLTF(modelPath);
+  const model = useMemo(() => scene.clone(true), [scene]);
+  const explodedModel = useMemo(
+    () => new ExplodedModel(model, { distance: splitDistance }),
+    [model, splitDistance],
+  );
+  const parsedScale =
+    typeof scale === "number" ? ([scale, scale, scale] as Vector3Tuple) : scale;
+
+  useEffect(() => {
+    explodedModel.setSplit(split);
+  }, [explodedModel, split]);
+
+  useFrame((_, delta) => {
+    explodedModel.update(delta);
+  });
+
+  return (
+    <group position={position} rotation={rotation} scale={parsedScale}>
+      <primitive object={model} />
+    </group>
+  );
+}
+
+function MissingModelFallback({
+  position = [0, 0, 0],
+}: {
+  position?: Vector3Tuple;
+}): React.JSX.Element {
+  return (
+    <mesh position={position}>
+      <boxGeometry args={[0.7, 0.7, 0.7]} />
+      <meshStandardMaterial color="#7f1d1d" wireframe />
+    </mesh>
+  );
+}

src/components/three/models/SimpleModel.tsx

@@ -0,0 +1,44 @@
+import { useMemo } from "react";
+import { useGLTF } from "@react-three/drei";
+import type { Vector3Tuple } from "@/types/three";
+
+export interface SimpleModelConfig {
+  modelPath: string;
+  position?: Vector3Tuple;
+  rotation?: Vector3Tuple;
+  scale?: Vector3Tuple | number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+}
+
+interface SimpleModelProps extends SimpleModelConfig {
+  children?: React.ReactNode;
+}
+
+export function SimpleModel({
+  modelPath,
+  position = [0, 0, 0],
+  rotation = [0, 0, 0],
+  scale = 1,
+  castShadow = true,
+  receiveShadow = true,
+  children,
+}: SimpleModelProps): React.JSX.Element {
+  const { scene } = useGLTF(modelPath);
+  const model = useMemo(() => scene.clone(true), [scene]);
+
+  const parsedScale =
+    typeof scale === "number" ? ([scale, scale, scale] as Vector3Tuple) : scale;
+
+  return (
+    <group position={position} rotation={rotation} scale={parsedScale}>
+      {children ?? (
+        <primitive
+          object={model}
+          castShadow={castShadow}
+          receiveShadow={receiveShadow}
+        />
+      )}
+    </group>
+  );
+}

src/components/three/models/useAnimatedModel.ts

@@ -0,0 +1,23 @@
+import { createContext, useContext } from "react";
+
+export interface AnimatedModelContextValue {
+  play: (name: string, fade?: number) => void;
+  stop: (fade?: number) => void;
+  fadeTo: (name: string, fade?: number) => void;
+  currentAnimation: string;
+  isReady: boolean;
+  setSpeed: (speed: number) => void;
+  names: string[];
+}
+
+export const AnimatedModelContext =
+  createContext<AnimatedModelContextValue | null>(null);
+
+export function useAnimatedModel(): AnimatedModelContextValue {
+  const context = useContext(AnimatedModelContext);
+  if (!context) {
+    throw new Error("useAnimatedModel must be used inside AnimatedModel");
+  }
+
+  return context;
+}