@almadar/ui 5.49.1 → 5.51.0

package/dist/components/game/molecules/three/index.cjs

@@ -2282,6 +2282,200 @@ function preloadFeatures(urls) {
     }
   });
 }
+
+// components/game/organisms/utils/spriteAnimation.ts
+function inferDirection(dx, dy) {
+  if (dx === 0 && dy === 0) return "se";
+  if (dx >= 0 && dy >= 0) return "se";
+  if (dx <= 0 && dy >= 0) return "sw";
+  if (dx >= 0 && dy <= 0) return "ne";
+  return "nw";
+}
+function resolveSheetDirection(facing) {
+  switch (facing) {
+    case "se":
+      return { sheetDir: "se", flipX: false };
+    case "sw":
+      return { sheetDir: "sw", flipX: false };
+    case "ne":
+      return { sheetDir: "sw", flipX: true };
+    case "nw":
+      return { sheetDir: "se", flipX: true };
+  }
+}
+function frameRect(frame, row, columns, frameWidth, frameHeight) {
+  return {
+    sx: frame % columns * frameWidth,
+    sy: row * frameHeight,
+    sw: frameWidth,
+    sh: frameHeight
+  };
+}
+function getCurrentFrameFromDef(def, elapsed) {
+  const frameDuration = 1e3 / def.frameRate;
+  const totalDuration = def.frames * frameDuration;
+  if (def.loop) {
+    const frame2 = Math.floor(elapsed % totalDuration / frameDuration);
+    return { frame: frame2, finished: false };
+  }
+  if (elapsed >= totalDuration) {
+    return { frame: def.frames - 1, finished: true };
+  }
+  const frame = Math.floor(elapsed / frameDuration);
+  return { frame, finished: false };
+}
+
+// components/game/molecules/useUnitSpriteAtlas.ts
+var WALK_HOLD_MS = 600;
+function unitAtlasUrl(unit) {
+  if (unit.spriteSheet) return unit.spriteSheet;
+  const sprite = unit.sprite;
+  if (!sprite) return null;
+  const match = /^(.*-sprite-sheet)(?:-(?:se|sw))?(?:-v\d+)?\.png$/.exec(sprite);
+  if (!match) return null;
+  return `${match[1]}.json`;
+}
+function resolveSheetUrl(atlasUrl, relativeSheetPath) {
+  try {
+    return new URL(relativeSheetPath, atlasUrl).toString();
+  } catch {
+    const base = atlasUrl.slice(0, atlasUrl.lastIndexOf("/") + 1);
+    return `${base}${relativeSheetPath.replace(/^\.\//, "")}`;
+  }
+}
+function useUnitSpriteAtlas(units) {
+  const atlasCacheRef = React11.useRef(/* @__PURE__ */ new Map());
+  const loadingRef = React11.useRef(/* @__PURE__ */ new Set());
+  const [pendingCount, setPendingCount] = React11.useState(0);
+  const [, forceTick] = React11.useState(0);
+  const animStatesRef = React11.useRef(/* @__PURE__ */ new Map());
+  const lastTickRef = React11.useRef(0);
+  const rafRef = React11.useRef(0);
+  const atlasUrls = React11.useMemo(() => {
+    const set = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const url = unitAtlasUrl(unit);
+      if (url) set.add(url);
+    }
+    return [...set];
+  }, [units]);
+  React11.useEffect(() => {
+    const cache = atlasCacheRef.current;
+    const loading = loadingRef.current;
+    const toLoad = atlasUrls.filter((url) => !cache.has(url) && !loading.has(url));
+    if (toLoad.length === 0) return;
+    let cancelled = false;
+    setPendingCount((prev) => prev + toLoad.length);
+    for (const url of toLoad) {
+      loading.add(url);
+      fetch(url).then((res) => res.ok ? res.json() : Promise.reject(new Error(String(res.status)))).then((atlas) => {
+        if (cancelled) return;
+        cache.set(url, atlas);
+      }).catch(() => {
+      }).finally(() => {
+        if (cancelled) return;
+        loading.delete(url);
+        setPendingCount((prev) => Math.max(0, prev - 1));
+        forceTick((n) => n + 1);
+      });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [atlasUrls]);
+  const sheetUrls = React11.useMemo(() => {
+    const urls = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const atlasUrl = unitAtlasUrl(unit);
+      if (!atlasUrl) continue;
+      const atlas = atlasCacheRef.current.get(atlasUrl);
+      if (!atlas) continue;
+      for (const rel of Object.values(atlas.sheets)) {
+        if (rel) urls.add(resolveSheetUrl(atlasUrl, rel));
+      }
+    }
+    return [...urls];
+  }, [units, pendingCount]);
+  React11.useEffect(() => {
+    const hasAtlasUnits = units.some((u) => unitAtlasUrl(u) !== null);
+    if (!hasAtlasUnits) return;
+    let running = true;
+    const tick = (ts) => {
+      if (!running) return;
+      const last = lastTickRef.current || ts;
+      const delta = ts - last;
+      lastTickRef.current = ts;
+      const states = animStatesRef.current;
+      const currentIds = /* @__PURE__ */ new Set();
+      for (const unit of units) {
+        if (unitAtlasUrl(unit) === null) continue;
+        currentIds.add(unit.id);
+        let state = states.get(unit.id);
+        if (!state) {
+          state = { animation: "idle", direction: "se", elapsed: 0, walkHold: 0, prev: null };
+          states.set(unit.id, state);
+        }
+        const posX = unit.position?.x ?? unit.x ?? 0;
+        const posY = unit.position?.y ?? unit.y ?? 0;
+        if (state.prev) {
+          const dx = posX - state.prev.x;
+          const dy = posY - state.prev.y;
+          if (dx !== 0 || dy !== 0) {
+            state.animation = "walk";
+            state.direction = inferDirection(dx, dy);
+            state.walkHold = WALK_HOLD_MS;
+          } else if (state.animation === "walk") {
+            state.walkHold -= delta;
+            if (state.walkHold <= 0) state.animation = "idle";
+          }
+        }
+        state.prev = { x: posX, y: posY };
+        state.elapsed += delta;
+      }
+      for (const id of states.keys()) {
+        if (!currentIds.has(id)) states.delete(id);
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      running = false;
+      cancelAnimationFrame(rafRef.current);
+      lastTickRef.current = 0;
+    };
+  }, [units]);
+  const resolveUnitFrame = React11.useCallback((unitId) => {
+    const unit = units.find((u) => u.id === unitId);
+    if (!unit) return null;
+    const atlasUrl = unitAtlasUrl(unit);
+    if (!atlasUrl) return null;
+    const atlas = atlasCacheRef.current.get(atlasUrl);
+    if (!atlas) return null;
+    const state = animStatesRef.current.get(unitId);
+    const animation = state?.animation ?? "idle";
+    const direction = state?.direction ?? "se";
+    const elapsed = state?.elapsed ?? 0;
+    const def = atlas.animations[animation] ?? atlas.animations.idle;
+    if (!def) return null;
+    const { sheetDir, flipX } = resolveSheetDirection(direction);
+    const rel = atlas.sheets[sheetDir] ?? atlas.sheets.se ?? atlas.sheets.sw;
+    if (!rel) return null;
+    const sheetUrl = resolveSheetUrl(atlasUrl, rel);
+    const isIdle = animation === "idle";
+    const frame = isIdle ? 0 : getCurrentFrameFromDef(def, elapsed).frame;
+    const rect = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
+    return {
+      sheetUrl,
+      sx: rect.sx,
+      sy: rect.sy,
+      sw: rect.sw,
+      sh: rect.sh,
+      flipX,
+      applyBreathing: isIdle
+    };
+  }, [units]);
+  return { sheetUrls, resolveUnitFrame, pendingCount };
+}
 function cn(...inputs) {
   return tailwindMerge.twMerge(clsx.clsx(inputs));
 }
@@ -2305,6 +2499,47 @@ function CameraController({
   }, [camera.position, onCameraChange]);
   return null;
 }
+function UnitSpriteBillboard({
+  sheetUrl,
+  resolveFrame,
+  height = 1.2
+}) {
+  const texture = fiber.useLoader(THREE6__namespace.TextureLoader, sheetUrl);
+  const meshRef = React11.useRef(null);
+  const matRef = React11.useRef(null);
+  const [aspect, setAspect] = React11.useState(1);
+  fiber.useFrame(() => {
+    const frame = resolveFrame();
+    if (!frame || !texture.image) return;
+    const imgW = texture.image.width;
+    const imgH = texture.image.height;
+    if (!imgW || !imgH) return;
+    texture.repeat.set((frame.flipX ? -1 : 1) * (frame.sw / imgW), frame.sh / imgH);
+    texture.offset.set(
+      frame.flipX ? (frame.sx + frame.sw) / imgW : frame.sx / imgW,
+      1 - (frame.sy + frame.sh) / imgH
+    );
+    texture.magFilter = THREE6__namespace.NearestFilter;
+    texture.minFilter = THREE6__namespace.NearestFilter;
+    texture.needsUpdate = true;
+    const nextAspect = frame.sw / frame.sh;
+    if (Math.abs(nextAspect - aspect) > 1e-3) setAspect(nextAspect);
+    if (matRef.current) matRef.current.needsUpdate = true;
+  });
+  return /* @__PURE__ */ jsxRuntime.jsxs("mesh", { ref: meshRef, position: [0, height / 2, 0], children: [
+    /* @__PURE__ */ jsxRuntime.jsx("planeGeometry", { args: [height * aspect, height] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "meshBasicMaterial",
+      {
+        ref: matRef,
+        map: texture,
+        transparent: true,
+        alphaTest: 0.1,
+        side: THREE6__namespace.DoubleSide
+      }
+    )
+  ] });
+}
 var GameCanvas3D = React11.forwardRef(
   ({
     tiles = [],
@@ -2354,8 +2589,10 @@ var GameCanvas3D = React11.forwardRef(
     const controlsRef = React11.useRef(null);
     const [hoveredTile, setHoveredTile] = React11.useState(null);
     const [internalError, setInternalError] = React11.useState(null);
+    const { sheetUrls: atlasSheetUrls, resolveUnitFrame } = useUnitSpriteAtlas(units);
+    const preloadUrls = React11.useMemo(() => [...preloadAssets, ...atlasSheetUrls], [preloadAssets, atlasSheetUrls]);
     const { isLoading: assetsLoading, progress, loaded, total } = useAssetLoader({
-      preloadUrls: preloadAssets,
+      preloadUrls,
       loader: customAssetLoader
     });
     const eventHandlers = useGameCanvas3DEvents({
@@ -2566,6 +2803,8 @@ var GameCanvas3D = React11.forwardRef(
       ({ unit, position }) => {
         const isSelected = selectedUnitId === unit.id;
         const color = unit.faction === "player" ? 4491519 : unit.faction === "enemy" ? 16729156 : 16777028;
+        const hasAtlas = unitAtlasUrl(unit) !== null;
+        const initialFrame = hasAtlas ? resolveUnitFrame(unit.id) : null;
         return /* @__PURE__ */ jsxRuntime.jsxs(
           "group",
           {
@@ -2577,7 +2816,16 @@ var GameCanvas3D = React11.forwardRef(
                 /* @__PURE__ */ jsxRuntime.jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                 /* @__PURE__ */ jsxRuntime.jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
               ] }),
-              unit.modelUrl ? (
+              hasAtlas && initialFrame ? (
+                /* Animated sprite-sheet billboard — single cropped frame, by state */
+                /* @__PURE__ */ jsxRuntime.jsx(drei.Billboard, { children: /* @__PURE__ */ jsxRuntime.jsx(
+                  UnitSpriteBillboard,
+                  {
+                    sheetUrl: initialFrame.sheetUrl,
+                    resolveFrame: () => resolveUnitFrame(unit.id)
+                  }
+                ) })
+              ) : unit.modelUrl ? (
                 /* GLB unit model (box fallback while loading / on error) */
                 /* @__PURE__ */ jsxRuntime.jsx(
                   ModelLoader,
@@ -2631,7 +2879,7 @@ var GameCanvas3D = React11.forwardRef(
           }
         );
       },
-      [selectedUnitId, handleUnitClick]
+      [selectedUnitId, handleUnitClick, resolveUnitFrame]
     );
     const DefaultFeatureRenderer = React11.useCallback(
       ({

package/dist/components/game/molecules/three/index.js

@@ -1,9 +1,9 @@
 import React11, { forwardRef, useRef, useEffect, useImperativeHandle, useState, useMemo, useCallback, createContext, Component, useContext, useSyncExternalStore, useReducer } from 'react';
-import { useThree, useFrame, Canvas, context } from '@react-three/fiber';
+import { useThree, useFrame, Canvas, useLoader, context } from '@react-three/fiber';
 import * as THREE6 from 'three';
 import { Vector3, QuadraticBezierCurve3, MathUtils, Quaternion } from 'three';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { OrbitControls, Grid, Stars, Sparkles, Html, RoundedBox } from '@react-three/drei';
+import { OrbitControls, Billboard, Grid, Stars, Sparkles, Html, RoundedBox } from '@react-three/drei';
 import { createLogger } from '@almadar/logger';
 import { GLTFLoader as GLTFLoader$1 } from 'three/examples/jsm/loaders/GLTFLoader';
 import { OrbitControls as OrbitControls$1 } from 'three/examples/jsm/controls/OrbitControls.js';
@@ -2258,6 +2258,200 @@ function preloadFeatures(urls) {
     }
   });
 }
+
+// components/game/organisms/utils/spriteAnimation.ts
+function inferDirection(dx, dy) {
+  if (dx === 0 && dy === 0) return "se";
+  if (dx >= 0 && dy >= 0) return "se";
+  if (dx <= 0 && dy >= 0) return "sw";
+  if (dx >= 0 && dy <= 0) return "ne";
+  return "nw";
+}
+function resolveSheetDirection(facing) {
+  switch (facing) {
+    case "se":
+      return { sheetDir: "se", flipX: false };
+    case "sw":
+      return { sheetDir: "sw", flipX: false };
+    case "ne":
+      return { sheetDir: "sw", flipX: true };
+    case "nw":
+      return { sheetDir: "se", flipX: true };
+  }
+}
+function frameRect(frame, row, columns, frameWidth, frameHeight) {
+  return {
+    sx: frame % columns * frameWidth,
+    sy: row * frameHeight,
+    sw: frameWidth,
+    sh: frameHeight
+  };
+}
+function getCurrentFrameFromDef(def, elapsed) {
+  const frameDuration = 1e3 / def.frameRate;
+  const totalDuration = def.frames * frameDuration;
+  if (def.loop) {
+    const frame2 = Math.floor(elapsed % totalDuration / frameDuration);
+    return { frame: frame2, finished: false };
+  }
+  if (elapsed >= totalDuration) {
+    return { frame: def.frames - 1, finished: true };
+  }
+  const frame = Math.floor(elapsed / frameDuration);
+  return { frame, finished: false };
+}
+
+// components/game/molecules/useUnitSpriteAtlas.ts
+var WALK_HOLD_MS = 600;
+function unitAtlasUrl(unit) {
+  if (unit.spriteSheet) return unit.spriteSheet;
+  const sprite = unit.sprite;
+  if (!sprite) return null;
+  const match = /^(.*-sprite-sheet)(?:-(?:se|sw))?(?:-v\d+)?\.png$/.exec(sprite);
+  if (!match) return null;
+  return `${match[1]}.json`;
+}
+function resolveSheetUrl(atlasUrl, relativeSheetPath) {
+  try {
+    return new URL(relativeSheetPath, atlasUrl).toString();
+  } catch {
+    const base = atlasUrl.slice(0, atlasUrl.lastIndexOf("/") + 1);
+    return `${base}${relativeSheetPath.replace(/^\.\//, "")}`;
+  }
+}
+function useUnitSpriteAtlas(units) {
+  const atlasCacheRef = useRef(/* @__PURE__ */ new Map());
+  const loadingRef = useRef(/* @__PURE__ */ new Set());
+  const [pendingCount, setPendingCount] = useState(0);
+  const [, forceTick] = useState(0);
+  const animStatesRef = useRef(/* @__PURE__ */ new Map());
+  const lastTickRef = useRef(0);
+  const rafRef = useRef(0);
+  const atlasUrls = useMemo(() => {
+    const set = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const url = unitAtlasUrl(unit);
+      if (url) set.add(url);
+    }
+    return [...set];
+  }, [units]);
+  useEffect(() => {
+    const cache = atlasCacheRef.current;
+    const loading = loadingRef.current;
+    const toLoad = atlasUrls.filter((url) => !cache.has(url) && !loading.has(url));
+    if (toLoad.length === 0) return;
+    let cancelled = false;
+    setPendingCount((prev) => prev + toLoad.length);
+    for (const url of toLoad) {
+      loading.add(url);
+      fetch(url).then((res) => res.ok ? res.json() : Promise.reject(new Error(String(res.status)))).then((atlas) => {
+        if (cancelled) return;
+        cache.set(url, atlas);
+      }).catch(() => {
+      }).finally(() => {
+        if (cancelled) return;
+        loading.delete(url);
+        setPendingCount((prev) => Math.max(0, prev - 1));
+        forceTick((n) => n + 1);
+      });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [atlasUrls]);
+  const sheetUrls = useMemo(() => {
+    const urls = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const atlasUrl = unitAtlasUrl(unit);
+      if (!atlasUrl) continue;
+      const atlas = atlasCacheRef.current.get(atlasUrl);
+      if (!atlas) continue;
+      for (const rel of Object.values(atlas.sheets)) {
+        if (rel) urls.add(resolveSheetUrl(atlasUrl, rel));
+      }
+    }
+    return [...urls];
+  }, [units, pendingCount]);
+  useEffect(() => {
+    const hasAtlasUnits = units.some((u) => unitAtlasUrl(u) !== null);
+    if (!hasAtlasUnits) return;
+    let running = true;
+    const tick = (ts) => {
+      if (!running) return;
+      const last = lastTickRef.current || ts;
+      const delta = ts - last;
+      lastTickRef.current = ts;
+      const states = animStatesRef.current;
+      const currentIds = /* @__PURE__ */ new Set();
+      for (const unit of units) {
+        if (unitAtlasUrl(unit) === null) continue;
+        currentIds.add(unit.id);
+        let state = states.get(unit.id);
+        if (!state) {
+          state = { animation: "idle", direction: "se", elapsed: 0, walkHold: 0, prev: null };
+          states.set(unit.id, state);
+        }
+        const posX = unit.position?.x ?? unit.x ?? 0;
+        const posY = unit.position?.y ?? unit.y ?? 0;
+        if (state.prev) {
+          const dx = posX - state.prev.x;
+          const dy = posY - state.prev.y;
+          if (dx !== 0 || dy !== 0) {
+            state.animation = "walk";
+            state.direction = inferDirection(dx, dy);
+            state.walkHold = WALK_HOLD_MS;
+          } else if (state.animation === "walk") {
+            state.walkHold -= delta;
+            if (state.walkHold <= 0) state.animation = "idle";
+          }
+        }
+        state.prev = { x: posX, y: posY };
+        state.elapsed += delta;
+      }
+      for (const id of states.keys()) {
+        if (!currentIds.has(id)) states.delete(id);
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      running = false;
+      cancelAnimationFrame(rafRef.current);
+      lastTickRef.current = 0;
+    };
+  }, [units]);
+  const resolveUnitFrame = useCallback((unitId) => {
+    const unit = units.find((u) => u.id === unitId);
+    if (!unit) return null;
+    const atlasUrl = unitAtlasUrl(unit);
+    if (!atlasUrl) return null;
+    const atlas = atlasCacheRef.current.get(atlasUrl);
+    if (!atlas) return null;
+    const state = animStatesRef.current.get(unitId);
+    const animation = state?.animation ?? "idle";
+    const direction = state?.direction ?? "se";
+    const elapsed = state?.elapsed ?? 0;
+    const def = atlas.animations[animation] ?? atlas.animations.idle;
+    if (!def) return null;
+    const { sheetDir, flipX } = resolveSheetDirection(direction);
+    const rel = atlas.sheets[sheetDir] ?? atlas.sheets.se ?? atlas.sheets.sw;
+    if (!rel) return null;
+    const sheetUrl = resolveSheetUrl(atlasUrl, rel);
+    const isIdle = animation === "idle";
+    const frame = isIdle ? 0 : getCurrentFrameFromDef(def, elapsed).frame;
+    const rect = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
+    return {
+      sheetUrl,
+      sx: rect.sx,
+      sy: rect.sy,
+      sw: rect.sw,
+      sh: rect.sh,
+      flipX,
+      applyBreathing: isIdle
+    };
+  }, [units]);
+  return { sheetUrls, resolveUnitFrame, pendingCount };
+}
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
@@ -2281,6 +2475,47 @@ function CameraController({
   }, [camera.position, onCameraChange]);
   return null;
 }
+function UnitSpriteBillboard({
+  sheetUrl,
+  resolveFrame,
+  height = 1.2
+}) {
+  const texture = useLoader(THREE6.TextureLoader, sheetUrl);
+  const meshRef = useRef(null);
+  const matRef = useRef(null);
+  const [aspect, setAspect] = useState(1);
+  useFrame(() => {
+    const frame = resolveFrame();
+    if (!frame || !texture.image) return;
+    const imgW = texture.image.width;
+    const imgH = texture.image.height;
+    if (!imgW || !imgH) return;
+    texture.repeat.set((frame.flipX ? -1 : 1) * (frame.sw / imgW), frame.sh / imgH);
+    texture.offset.set(
+      frame.flipX ? (frame.sx + frame.sw) / imgW : frame.sx / imgW,
+      1 - (frame.sy + frame.sh) / imgH
+    );
+    texture.magFilter = THREE6.NearestFilter;
+    texture.minFilter = THREE6.NearestFilter;
+    texture.needsUpdate = true;
+    const nextAspect = frame.sw / frame.sh;
+    if (Math.abs(nextAspect - aspect) > 1e-3) setAspect(nextAspect);
+    if (matRef.current) matRef.current.needsUpdate = true;
+  });
+  return /* @__PURE__ */ jsxs("mesh", { ref: meshRef, position: [0, height / 2, 0], children: [
+    /* @__PURE__ */ jsx("planeGeometry", { args: [height * aspect, height] }),
+    /* @__PURE__ */ jsx(
+      "meshBasicMaterial",
+      {
+        ref: matRef,
+        map: texture,
+        transparent: true,
+        alphaTest: 0.1,
+        side: THREE6.DoubleSide
+      }
+    )
+  ] });
+}
 var GameCanvas3D = forwardRef(
   ({
     tiles = [],
@@ -2330,8 +2565,10 @@ var GameCanvas3D = forwardRef(
     const controlsRef = useRef(null);
     const [hoveredTile, setHoveredTile] = useState(null);
     const [internalError, setInternalError] = useState(null);
+    const { sheetUrls: atlasSheetUrls, resolveUnitFrame } = useUnitSpriteAtlas(units);
+    const preloadUrls = useMemo(() => [...preloadAssets, ...atlasSheetUrls], [preloadAssets, atlasSheetUrls]);
     const { isLoading: assetsLoading, progress, loaded, total } = useAssetLoader({
-      preloadUrls: preloadAssets,
+      preloadUrls,
       loader: customAssetLoader
     });
     const eventHandlers = useGameCanvas3DEvents({
@@ -2542,6 +2779,8 @@ var GameCanvas3D = forwardRef(
       ({ unit, position }) => {
         const isSelected = selectedUnitId === unit.id;
         const color = unit.faction === "player" ? 4491519 : unit.faction === "enemy" ? 16729156 : 16777028;
+        const hasAtlas = unitAtlasUrl(unit) !== null;
+        const initialFrame = hasAtlas ? resolveUnitFrame(unit.id) : null;
         return /* @__PURE__ */ jsxs(
           "group",
           {
@@ -2553,7 +2792,16 @@ var GameCanvas3D = forwardRef(
                 /* @__PURE__ */ jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                 /* @__PURE__ */ jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
               ] }),
-              unit.modelUrl ? (
+              hasAtlas && initialFrame ? (
+                /* Animated sprite-sheet billboard — single cropped frame, by state */
+                /* @__PURE__ */ jsx(Billboard, { children: /* @__PURE__ */ jsx(
+                  UnitSpriteBillboard,
+                  {
+                    sheetUrl: initialFrame.sheetUrl,
+                    resolveFrame: () => resolveUnitFrame(unit.id)
+                  }
+                ) })
+              ) : unit.modelUrl ? (
                 /* GLB unit model (box fallback while loading / on error) */
                 /* @__PURE__ */ jsx(
                   ModelLoader,
@@ -2607,7 +2855,7 @@ var GameCanvas3D = forwardRef(
           }
         );
       },
-      [selectedUnitId, handleUnitClick]
+      [selectedUnitId, handleUnitClick, resolveUnitFrame]
     );
     const DefaultFeatureRenderer = useCallback(
       ({

package/dist/components/game/molecules/useUnitSpriteAtlas.d.ts

@@ -0,0 +1,30 @@
+import type { AssetUrl } from '@almadar/core';
+import type { IsometricUnit } from '../organisms/types/isometric';
+import type { ResolvedFrame } from '../organisms/types/spriteAnimation';
+/**
+ * Resolve the sprite-sheet atlas-JSON URL for a unit.
+ *
+ * An explicit `unit.spriteSheet` wins. Otherwise, when the unit's static
+ * `sprite` points at a directional sheet PNG, derive its sibling atlas JSON by
+ * the deterministic naming convention used in `shared/sprite-sheets/`:
+ * the shared atlas drops the `-se` / `-sw` direction suffix and any `-vN`
+ * variant suffix, then swaps `.png` → `.json`
+ * (`amir-sprite-sheet-se.png` → `amir-sprite-sheet.json`).
+ *
+ * Returns null when no atlas can be resolved (the unit keeps its static draw).
+ */
+export declare function unitAtlasUrl(unit: Pick<IsometricUnit, 'spriteSheet' | 'sprite'>): AssetUrl | null;
+export interface UseUnitSpriteAtlasResult {
+    /** Atlas-JSON URLs successfully loaded — feed these to no one; sheet PNGs are returned below. */
+    sheetUrls: string[];
+    /** Resolve the current single-frame rect for a unit, or null if its atlas isn't loaded. */
+    resolveUnitFrame: (unitId: string) => ResolvedFrame | null;
+    /** Whether any atlas is still loading (drives isLoading / keeps RAF alive). */
+    pendingCount: number;
+}
+/**
+ * Load per-unit sprite atlases and drive single-frame animation.
+ *
+ * @param units - Units to animate. Only units with a `spriteSheet` URL participate.
+ */
+export declare function useUnitSpriteAtlas(units: IsometricUnit[]): UseUnitSpriteAtlasResult;

package/dist/components/game/organisms/types/isometric.d.ts

@@ -51,6 +51,10 @@ export type IsometricUnit = {
     z?: number;
     /** Static sprite URL (used when no sprite sheet animation) */
     sprite?: AssetUrl;
+    /** Sprite-sheet atlas JSON URL (e.g. `.../guardian-sprite-sheet.json`).
+     *  When set, the canvas loads the atlas and crops/animates a single frame
+     *  by animation state instead of drawing the whole sheet. */
+    spriteSheet?: AssetUrl;
     /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
     modelUrl?: AssetUrl;
     /** Unit archetype key for sprite resolution */

package/dist/components/game/organisms/types/spriteAnimation.d.ts

@@ -72,3 +72,27 @@ export interface SpriteSheetUrls {
     /** Southwest-facing sheet URL */
     sw: AssetUrl;
 }
+/**
+ * Parsed sprite-sheet atlas JSON (e.g. `guardian-sprite-sheet.json`).
+ * Sits next to the `.png` sheets and drives the frame rect deterministically.
+ */
+export interface SpriteAtlas {
+    /** Unit archetype key */
+    unit?: string;
+    /** Visual type key */
+    type?: string;
+    /** Width of a single frame in pixels */
+    frameWidth: number;
+    /** Height of a single frame in pixels */
+    frameHeight: number;
+    /** Number of columns (frames per row) */
+    columns: number;
+    /** Number of rows (animations) */
+    rows: number;
+    /** Directions present as physical PNG files */
+    directions: SpriteDirection[];
+    /** Relative PNG sheet paths per direction */
+    sheets: Partial<Record<SpriteDirection, string>>;
+    /** Animation row layout keyed by animation name */
+    animations: Partial<Record<AnimationName, AnimationDef>>;
+}