save direction info on export

Author: Kyonru

src/docs/cli.md

@@ -257,14 +257,27 @@ The JSON `animations` array contains one entry per direction per clip:
 ```json
 {
   "animations": [
-    { "name": "idle_N", "fps": 10, "frames": 8, "frameWidth": 64, "frameHeight": 64, "quads": [...] },
+    { "name": "idle_N", "fps": 10, "frames": 8, "frameWidth": 64, "frameHeight": 64, "workflow": { "workflowId": "topdown-4dir", "workflowLabel": "Top Down 4-directional", "animationName": "idle", "directionLabel": "N" }, "quads": [...] },
     { "name": "idle_E", ... },
     { "name": "idle_S", ... },
     { "name": "idle_W", ... },
     { "name": "walk_N", ... },
     { "name": "walk_E", ... },
     { "name": "walk_S", ... },
     { "name": "walk_W", ... }
+  ],
+  "directionalAnimations": [
+    {
+      "name": "idle",
+      "workflowId": "topdown-4dir",
+      "workflowLabel": "Top Down 4-directional",
+      "directions": [
+        { "label": "N", "animation": "idle_N" },
+        { "label": "E", "animation": "idle_E" },
+        { "label": "S", "animation": "idle_S" },
+        { "label": "W", "animation": "idle_W" }
+      ]
+    }
   ]
 }
 ```

src/docs/workflows.md

@@ -67,7 +67,7 @@ walk_NE
 ...
 ```
 
-These labeled sequences are embedded in the exported JSON/metadata file so your game engine can look them up by name.
+These labeled sequences are embedded in the exported JSON/metadata file so your game engine can look them up by name. Workflow exports also include structured direction metadata: each sequence records its base animation and direction, and `directionalAnimations` groups rows like `walk_N`, `walk_E`, `walk_S`, and `walk_W` under the shared `walk` animation.
 
 ## Tips
 

src/hooks/next/use-export.ts

@@ -12,6 +12,8 @@ import { useSceneStore } from "@/components/panels/scene/store";
 import { useSettingsStore } from "@/store/next/settings";
 import { useImagesStore } from "@/store/next/images";
 import { useSpritePostprocessStore } from "@/store/next/sprite-postprocess";
+import { useModelsStore } from "@/store/next/models";
+import { useEntitiesStore } from "@/store/next/entities";
 import type { ExportFormat } from "@/types/file";
 import { exporters } from "@/utils/exports";
 import { buildZip, getNormalCoverage } from "@/utils/exports/helpers";
@@ -23,6 +25,7 @@ import {
   validateExportRequest,
 } from "@/utils/export-validation";
 import { addExportHistoryEntry } from "@/utils/export-history";
+import { getActiveAnimationSequenceLabel } from "@/utils/animation-sequence-label";
 
 const NORMAL_MAP_EXPORT_FORMATS = new Set<ExportFormat>([
   "spritesheet",
@@ -250,27 +253,38 @@ export const useExport = () => {
       if (!gl) return;
       if (intervalRef.current) clearInterval(intervalRef.current);
 
+      const modelState = useModelsStore.getState();
+      const sequenceLabel =
+        payload?.label ??
+        getActiveAnimationSequenceLabel({
+          animations: modelState.animations,
+          clips: modelState.clips,
+          selectedUuid: useEntitiesStore.getState().selected,
+        }) ??
+        `animation_${lastIndex.current + 1}`;
+      const capturePayload = { ...(payload ?? {}), label: sequenceLabel };
+
       images.current = [];
       normalImages.current = [];
-      activeCaptureRef.current = payload ?? {};
+      activeCaptureRef.current = capturePayload;
 
       intervalRef.current = scheduleInterval(
         captureScreenshotData,
         intervals,
         iterations,
         () => {
           PubSub.emit(EventType.ASSETS_CREATION_PROGRESS, {
-            label: payload?.label,
-            workflowRunId: payload?.workflowRunId,
+            label: capturePayload.label,
+            workflowRunId: capturePayload.workflowRunId,
             capturedFrames: images.current.length,
             expectedFrames: iterations,
           });
         },
         async () => {
           intervalRef.current = null;
           PubSub.emit(EventType.STOP_ASSETS_CREATION, {
-            label: payload?.label,
-            workflowRunId: payload?.workflowRunId,
+            label: capturePayload.label,
+            workflowRunId: capturePayload.workflowRunId,
             capturedFrames: images.current.length,
             expectedFrames: iterations,
             status: "done",
@@ -279,14 +293,15 @@ export const useExport = () => {
 
           addImages(
             Date.now().toString(),
-            payload?.label ?? `animation_${lastIndex.current + 1}`,
+            capturePayload.label,
             images.current.map((img) => img.dataURL),
             exportNormalMap
               ? normalImages.current.map((img) => img.dataURL)
               : undefined,
             exportWidth,
             exportHeight,
             Math.round(1000 / intervals),
+            capturePayload.rowMetadata,
           );
           lastIndex.current += 1;
         },

src/hooks/next/use-workflow.ts

@@ -385,6 +385,15 @@ export const useWorkflow = () => {
           workflowRunId,
           stepIndex: index + 1,
           totalSteps: steps.length,
+          rowMetadata: {
+            workflow: {
+              workflowId: workflow.id,
+              workflowLabel: workflow.label,
+              ...(step.modelUuid ? { modelUuid: step.modelUuid } : {}),
+              animationName: step.animationName,
+              directionLabel: step.directionLabel,
+            },
+          },
         });
 
         const result = await captureDone;

src/lib/events.ts

@@ -3,6 +3,7 @@ import { pubSubEventClient } from "../../devtools/pubsub-event-client";
 import {
   ExportFormats,
   type AtlasOptions,
+  type ExportRowMetadata,
   type ExportFormat,
 } from "@/types/file";
 import type { SpritePostprocessSnapshot } from "@/types/sprite-postprocess";
@@ -80,6 +81,7 @@ export type CaptureStartPayload = {
   workflowRunId?: string;
   stepIndex?: number;
   totalSteps?: number;
+  rowMetadata?: ExportRowMetadata;
 };
 
 export type CaptureStopPayload = {

src/store/next/images.ts

@@ -1,7 +1,7 @@
 import { create } from "zustand";
 import { inspector } from "@kyonru/zustand-inspector";
 import type { SnapshotEnabledStore } from "@/types/ecs";
-import type { ExportRow } from "@/types/file";
+import type { ExportRow, ExportRowMetadata } from "@/types/file";
 
 export interface ImagesState {
   intervals: number;
@@ -26,6 +26,7 @@ interface ImagesActions extends SnapshotEnabledStore<ImagesState> {
     frameWidth: number,
     frameHeight: number,
     fps: number,
+    metadata?: ExportRowMetadata,
   ) => void;
   removeImagesRow: (index: number) => void;
   removeImageFromRow: (index: number, imageIndex: number) => void;
@@ -89,6 +90,7 @@ export const useImagesStore = create<ImagesStore>()(
         frameWidth,
         frameHeight,
         fps,
+        metadata,
       ) =>
         set((state) => ({
           images: [
@@ -101,6 +103,7 @@ export const useImagesStore = create<ImagesStore>()(
               frameWidth,
               frameHeight,
               fps,
+              ...(metadata ? { metadata } : {}),
             },
           ],
         })),

src/types/file.ts

@@ -36,6 +36,30 @@ export interface ExportRow {
   frameWidth: number;
   frameHeight: number;
   fps: number;
+  metadata?: ExportRowMetadata;
+}
+
+export interface ExportRowMetadata {
+  workflow?: ExportRowWorkflowMetadata;
+}
+
+export interface ExportRowWorkflowMetadata {
+  workflowId: string;
+  workflowLabel: string;
+  modelUuid?: string;
+  animationName: string;
+  directionLabel: string;
+}
+
+export interface DirectionalAnimationGroup {
+  name: string;
+  workflowId: string;
+  workflowLabel: string;
+  modelUuid?: string;
+  directions: {
+    label: string;
+    animation: string;
+  }[];
 }
 
 export type ExportContext = {

src/utils/animation-sequence-label.ts

@@ -0,0 +1,48 @@
+interface ClipNameEntry {
+  clip: {
+    name: string;
+  };
+}
+
+interface AnimationSequenceLabelInput {
+  animations: Record<string, string | undefined>;
+  clips: Record<string, ClipNameEntry[] | undefined>;
+  selectedUuid?: string;
+}
+
+function getActiveClipName(
+  input: AnimationSequenceLabelInput,
+  uuid: string | undefined,
+) {
+  if (!uuid) return undefined;
+
+  const animationName = input.animations[uuid];
+  if (!animationName || !animationName.trim() || animationName === "none") {
+    return undefined;
+  }
+
+  const hasMatchingClip = input.clips[uuid]?.some(
+    (entry) => entry.clip.name === animationName,
+  );
+
+  return hasMatchingClip ? animationName : undefined;
+}
+
+export function getActiveAnimationSequenceLabel(
+  input: AnimationSequenceLabelInput,
+) {
+  const selectedAnimationName = getActiveClipName(input, input.selectedUuid);
+  if (selectedAnimationName) return selectedAnimationName;
+
+  const animationNames = new Set<string>();
+
+  for (const uuid of Object.keys(input.animations)) {
+    const animationName = getActiveClipName(input, uuid);
+    if (animationName) animationNames.add(animationName);
+  }
+
+  const names = Array.from(animationNames);
+  if (names.length === 0) return undefined;
+
+  return names.join("_");
+}

src/utils/assets.ts

@@ -1,7 +1,15 @@
 import GIF from "gif.js.optimized";
 import openFile from "../lib/file/opener.web";
 import { toast } from "sonner";
-import type { ExportRow } from "@/types/file";
+import type {
+  DirectionalAnimationGroup,
+  ExportRow,
+  ExportRowWorkflowMetadata,
+} from "@/types/file";
+import {
+  buildDirectionalAnimationGroups,
+  getRowWorkflowMetadata,
+} from "@/utils/export-row-metadata";
 
 export interface SpritesheetOptions {
   spacing: number; // px between frames
@@ -173,8 +181,10 @@ export interface SpritesheetJSON {
     fps: number;
     frameWidth: number;
     frameHeight: number;
+    workflow?: ExportRowWorkflowMetadata;
     quads: { x: number; y: number; w: number; h: number; page?: number }[];
   }[];
+  directionalAnimations?: DirectionalAnimationGroup[];
 }
 
 export const createSpritesheetJSON = (
@@ -200,6 +210,8 @@ export const createSpritesheetJSON = (
 
   let yOffset = margin;
 
+  const directionalAnimations = buildDirectionalAnimationGroups(rows);
+
   return {
     meta: {
       version: "1.0",
@@ -212,12 +224,14 @@ export const createSpritesheetJSON = (
       margin,
     },
     animations: rows.map((row) => {
+      const workflow = getRowWorkflowMetadata(row);
       const animation = {
         name: row.label,
         frames: row.images.length,
         fps: row.fps ?? 12,
         frameWidth: row.frameWidth,
         frameHeight: row.frameHeight,
+        ...(workflow ? { workflow } : {}),
         quads: row.images.map((_, frameIndex) => ({
           x: margin + frameIndex * (row.frameWidth + spacing),
           y: yOffset,
@@ -230,6 +244,7 @@ export const createSpritesheetJSON = (
 
       return animation;
     }),
+    ...(directionalAnimations.length > 0 ? { directionalAnimations } : {}),
   };
 };
 

src/utils/atlas.ts

@@ -1,5 +1,9 @@
 import type { AtlasOptions, ExportFormat, ExportRow } from "@/types/file";
 import type { SpritesheetJSON } from "./assets";
+import {
+  buildDirectionalAnimationGroups,
+  getRowWorkflowMetadata,
+} from "./export-row-metadata";
 
 export const DEFAULT_ATLAS_OPTIONS: AtlasOptions = {
   layout: "rows",
@@ -596,28 +600,41 @@ export function createSpritesheetJSONFromAtlasPlan(
     });
   }
 
+  const directionalAnimations = buildDirectionalAnimationGroups(rows);
+
   return {
     meta,
-    animations: rows.map((row, rowIndex) => ({
-      name: row.label,
-      frames: row.images.length,
-      fps: row.fps ?? 12,
-      frameWidth: Math.max(1, Math.round(row.frameWidth * plan.options.scale)),
-      frameHeight: Math.max(1, Math.round(row.frameHeight * plan.options.scale)),
-      quads: row.images.map((_, frameIndex) => {
-        const placement = placements.get(placementKey(rowIndex, frameIndex));
-        if (!placement) {
-          throw new Error(`Missing atlas placement for ${row.label}:${frameIndex}`);
-        }
-
-        const quad = {
-          x: placement.x,
-          y: placement.y,
-          w: placement.w,
-          h: placement.h,
-        };
-        return multiPage ? { ...quad, page: placement.page } : quad;
-      }),
-    })),
+    animations: rows.map((row, rowIndex) => {
+      const workflow = getRowWorkflowMetadata(row);
+
+      return {
+        name: row.label,
+        frames: row.images.length,
+        fps: row.fps ?? 12,
+        frameWidth: Math.max(1, Math.round(row.frameWidth * plan.options.scale)),
+        frameHeight: Math.max(
+          1,
+          Math.round(row.frameHeight * plan.options.scale),
+        ),
+        ...(workflow ? { workflow } : {}),
+        quads: row.images.map((_, frameIndex) => {
+          const placement = placements.get(placementKey(rowIndex, frameIndex));
+          if (!placement) {
+            throw new Error(
+              `Missing atlas placement for ${row.label}:${frameIndex}`,
+            );
+          }
+
+          const quad = {
+            x: placement.x,
+            y: placement.y,
+            w: placement.w,
+            h: placement.h,
+          };
+          return multiPage ? { ...quad, page: placement.page } : quad;
+        }),
+      };
+    }),
+    ...(directionalAnimations.length > 0 ? { directionalAnimations } : {}),
   };
 }