Merge remote-tracking branch 'origin/feat/main-feature' into feat/main-feature

# Conflicts:
#	src/world/GameMap.tsx

src/components/three/AnimatedModel.tsx

@@ -0,0 +1,190 @@
+/* eslint-disable react-hooks/immutability */
+import { createContext, useRef, useState, useEffect, useCallback } from "react";
+import { useGLTF, useAnimations } from "@react-three/drei";
+import type { AnimationAction } from "three";
+import * as THREE from "three";
+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;
+}
+
+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[];
+}
+
+const AnimatedModelContext = createContext<AnimatedModelContextValue | null>(
+  null,
+);
+
+export { AnimatedModelContext };
+
+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);
+
+  void groupRef;
+  const { scene, animations } = useGLTF(modelPath);
+  const { actions, names, mixer } = useAnimations(animations, scene);
+
+  const [currentAnim, setCurrentAnim] = useState(defaultAnimation);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    if (mixer) {
+      mixer.timeScale = speed;
+    }
+  }, [mixer, 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) => {
+      if (mixer) {
+        mixer.timeScale = newSpeed;
+      }
+    },
+    [mixer],
+  );
+
+  useEffect(() => {
+    if (!autoPlay || names.length === 0) {
+      console.log("[AnimatedModel] No animation found in model");
+      return;
+    }
+
+    console.log(`[AnimatedModel] Available animations: ${names.join(", ")}`);
+
+    let defaultAction = actions[defaultAnimation as string];
+
+    if (!defaultAction && names.length > 0) {
+      console.log(
+        `[AnimatedModel] "${defaultAnimation}" not found, using: ${names[0]}`,
+      );
+      defaultAction = actions[names[0] as string];
+    }
+
+    if (defaultAction) {
+      defaultAction.play();
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setIsReady(true);
+
+      setCurrentAnim(defaultAction.getClip().name);
+      onLoaded?.();
+    } else {
+      console.log("[AnimatedModel] No available animation in actions");
+    }
+  }, [actions, defaultAnimation, names, autoPlay, onLoaded]);
+
+  const contextValue: AnimatedModelContextValue = {
+    play,
+    stop,
+    fadeTo,
+    currentAnimation: currentAnim,
+    isReady,
+    setSpeed,
+    names,
+  };
+
+  useEffect(() => {
+    scene.position.set(...position);
+    scene.rotation.set(
+      (rotation[0] * Math.PI) / 180,
+      (rotation[1] * Math.PI) / 180,
+      (rotation[2] * Math.PI) / 180,
+    );
+    const s =
+      typeof scale === "number" ? [scale, scale, scale] : (scale ?? [1, 1, 1]);
+    scene.scale.set(s[0] ?? 1, s[1] ?? 1, s[2] ?? 1);
+  }, [scene, position, rotation, scale]);
+
+  return (
+    <AnimatedModelContext.Provider value={contextValue}>
+      <primitive object={scene} />
+      {children}
+    </AnimatedModelContext.Provider>
+  );
+}

src/components/three/SimpleModel.tsx

@@ -0,0 +1,42 @@
+import { useGLTF } from "@react-three/drei";
+import type { Vector3Tuple } from "@/types/3d";
+
+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 parsedScale =
+    typeof scale === "number" ? ([scale, scale, scale] as Vector3Tuple) : scale;
+
+  return (
+    <group position={position} rotation={rotation} scale={parsedScale}>
+      {children ?? (
+        <primitive
+          object={scene.clone()}
+          castShadow={castShadow}
+          receiveShadow={receiveShadow}
+        />
+      )}
+    </group>
+  );
+}

src/components/three/index.ts

@@ -0,0 +1,8 @@
+export { AnimatedModel, useAnimatedModel } from "./AnimatedModel";
+export type { AnimatedModelConfig } from "./AnimatedModel";
+
+export { SimpleModel } from "./SimpleModel";
+export type { SimpleModelConfig } from "./SimpleModel";
+
+export { useCharacterAnimation } from "@/hooks/useCharacterAnimation";
+export type { CharacterAnimationConfig } from "@/hooks/useCharacterAnimation";

src/data/docs/docsSections.ts

@@ -67,6 +67,12 @@ export const docGroups: DocGroup[] = [
         subtitle: "Editing workflow",
         meta: "08",
       },
+      {
+        path: "/docs/animation",
+        title: "Animation & 3D Model System",
+        subtitle: "Components and usage",
+        meta: "07",
+      },
     ],
   },
 ];

src/hooks/useCharacterAnimation.ts

@@ -0,0 +1,107 @@
+/* eslint-disable react-hooks/immutability */
+import { useRef, useEffect, useState, useCallback } from "react";
+import { useGLTF, useAnimations } from "@react-three/drei";
+import type { AnimationAction, AnimationMixer } from "three";
+import * as THREE from "three";
+
+export interface CharacterAnimationConfig {
+  modelPath: string;
+  initialAnimation?: string;
+  fadeDuration?: number;
+}
+
+interface UseCharacterAnimationReturn {
+  scene: THREE.Group;
+  actions: { [key: string]: AnimationAction | null };
+  names: string[];
+  mixer: AnimationMixer;
+  groupRef: React.MutableRefObject<THREE.Group | null>;
+  currentAnimation: string;
+  play: (name: string) => void;
+  stop: () => void;
+  fadeTo: (name: string, duration?: number) => void;
+  setAnimationSpeed: (speed: number) => void;
+}
+
+const DEFAULT_FADE_DURATION = 0.3;
+
+export function useCharacterAnimation(
+  config: CharacterAnimationConfig,
+): UseCharacterAnimationReturn {
+  const {
+    modelPath,
+    initialAnimation = "Idle",
+    fadeDuration = DEFAULT_FADE_DURATION,
+  } = config;
+
+  const groupRef = useRef<THREE.Group | null>(null);
+  const { scene, animations } = useGLTF(modelPath);
+  const { actions, names, mixer } = useAnimations(animations, groupRef);
+  const [currentAnimation, setCurrentAnimation] = useState(initialAnimation);
+
+  const play = useCallback(
+    (name: string) => {
+      const action = actions[name];
+      if (action) {
+        Object.values(actions).forEach((a) => {
+          if (a && a !== action) a.fadeOut(fadeDuration);
+        });
+        action.reset().fadeIn(fadeDuration).play();
+        setCurrentAnimation(name);
+      }
+    },
+    [actions, fadeDuration],
+  );
+
+  const stop = useCallback(() => {
+    Object.values(actions).forEach((a) => a?.fadeOut(fadeDuration));
+    const defaultAction = actions[initialAnimation as string];
+    if (defaultAction) {
+      defaultAction.reset().fadeIn(fadeDuration).play();
+      setCurrentAnimation(initialAnimation);
+    }
+  }, [actions, initialAnimation, fadeDuration]);
+
+  const fadeTo = useCallback(
+    (name: string, duration = fadeDuration) => {
+      const targetAction = actions[name];
+      if (targetAction) {
+        Object.values(actions).forEach((a) => {
+          if (a && a !== targetAction) a.fadeOut(duration);
+        });
+        targetAction.reset().fadeIn(duration).play();
+        setCurrentAnimation(name);
+      }
+    },
+    [actions, fadeDuration],
+  );
+
+  const setAnimationSpeed = useCallback(
+    (speed: number) => {
+      if (mixer) {
+        mixer.timeScale = speed;
+      }
+    },
+    [mixer],
+  );
+
+  useEffect(() => {
+    const defaultAction = actions[initialAnimation as string];
+    if (defaultAction) {
+      defaultAction.play();
+    }
+  }, [actions, initialAnimation]);
+
+  return {
+    scene,
+    actions,
+    names,
+    mixer,
+    groupRef,
+    currentAnimation,
+    play,
+    stop,
+    fadeTo,
+    setAnimationSpeed,
+  };
+}

src/pages/docs/animation/page.tsx

@@ -0,0 +1,13 @@
+import animation from "../../../../docs/technical/animation.md?raw";
+import { DocsDocument } from "@/components/docs/DocsDocument";
+
+export function DocsAnimationPage(): React.JSX.Element {
+  return (
+    <DocsDocument
+      content={animation}
+      frContent={animation}
+      meta="07"
+      title="Animation & 3D Model System"
+    />
+  );
+}

src/router.tsx

@@ -7,6 +7,7 @@ import {
 import { HomePage } from "@/pages/page";
 import { EditorPage } from "@/pages/editor/page";
 import {
+  DocsAnimationRoute,
   DocsArchitectureRoute,
   DocsEditorRoute,
   DocsFeaturesRoute,
@@ -49,6 +50,7 @@ const docsChildRoutes = [
   { path: "features", component: DocsFeaturesRoute },
   { path: "main-feature", component: DocsMainFeatureRoute },
   { path: "editor", component: DocsEditorRoute },
+  { path: "animation", component: DocsAnimationRoute },
 ].map(({ path, component }) =>
   createRoute({
     getParentRoute: () => docsRoute,

src/routes/docs/DocsRouteComponents.tsx

@@ -54,6 +54,12 @@ const LazyDocsEditorPage = lazy(() =>
   })),
 );
 
+const LazyDocsAnimationPage = lazy(() =>
+  import("@/pages/docs/animation/page").then((module) => ({
+    default: module.DocsAnimationPage,
+  })),
+);
+
 export function DocsLayoutRoute(): React.JSX.Element {
   return (
     <Suspense fallback={null}>
@@ -125,3 +131,11 @@ export function DocsEditorRoute(): React.JSX.Element {
     </Suspense>
   );
 }
+
+export function DocsAnimationRoute(): React.JSX.Element {
+  return (
+    <Suspense fallback={null}>
+      <LazyDocsAnimationPage />
+    </Suspense>
+  );
+}

src/world/GameMap.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useState, useRef } from "react";
+import type { ReactNode } from "react";
+import { Component, useEffect, useMemo, useRef, useState } from "react";
 import { useGLTF } from "@react-three/drei";
 import * as THREE from "three";
 import { useOctreeGraphNode } from "@/hooks/useOctreeGraphNode";
@@ -11,6 +12,41 @@ interface LoadedMapNode {
   modelUrl: string;
 }
 
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+class ModelErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    console.warn("Failed to load model", error);
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null;
+    }
+
+    return this.props.children;
+  }
+}
+
 interface GameMapProps {
   onOctreeReady: OctreeReadyHandler;
 }
@@ -59,12 +95,10 @@ export function GameMap({ onOctreeReady }: GameMapProps): React.JSX.Element {
   return (
     <group ref={groupRef}>
       {!isLoading &&
-        mapNodes.map((node, index) => (
-          <ModelInstance
-            key={index}
-            node={node.node}
-            modelUrl={node.modelUrl}
-          />
+        mapNodes.map((mapNode, index) => (
+          <ModelErrorBoundary key={index}>
+            <ModelInstance node={mapNode.node} modelUrl={mapNode.modelUrl} />
+          </ModelErrorBoundary>
         ))}
     </group>
   );

src/world/debug/TestScene.tsx

@@ -1,8 +1,9 @@
 import { useRef } from "react";
-import { Physics, RigidBody, CuboidCollider } from "@react-three/rapier";
 import * as THREE from "three";
+import { Physics, RigidBody, CuboidCollider } from "@react-three/rapier";
 import { GrabbableObject } from "@/components/three/GrabbableObject";
 import { TriggerObject } from "@/components/three/TriggerObject";
+import { AnimatedModel } from "@/components/three/AnimatedModel";
 import {
   TEST_SCENE_FLOOR_COLLIDER_HALF_EXTENTS,
   TEST_SCENE_FLOOR_POSITION,
@@ -86,6 +87,13 @@ export function TestScene({
           </mesh>
         </TriggerObject>
       </Physics>
+
+      <AnimatedModel
+        modelPath="/models/elec/model.gltf"
+        defaultAnimation="Idle"
+        position={[0, 0, -5]}
+        scale={1}
+      />
     </>
   );
 }