@routevn/creator-model 1.13.2 → 1.14.0

package/README.md

@@ -106,6 +106,22 @@ Design rules:
 - random ids across RouteVN should use `nanoid` with the RouteVN base58 variant;
   deterministic derived tokens such as partition hashes are a separate case
 
+## Animation Camera Tracks
+
+Animation resources may explicitly group synchronized position and scale tracks
+with `cameraTracks: ["update"]`, or `["prev", "next"]` for transitions.
+Each listed side must contain `x`, `y`, `scaleX`, and `scaleY` keyframe
+tracks with matching timing/easing and start-value presence, absolute values,
+and positive scales. Track initial values are optional; they must be numeric
+on all four tracks or omitted from all four to use the target's existing pose.
+Translation tracks cannot coexist with Camera on the same side.
+
+This authoring marker does not alter the runtime animation format. Existing
+animations without the marker remain separate tracks; no grouping is inferred.
+An update may use `cameraTracks: []` to remove grouping. Updates to animation
+data are validated with the resource's retained grouping unless it is replaced
+in the same command.
+
 ## Font Weight Metadata
 
 Font resources may store extracted weight capabilities in three flat fields:
@@ -354,8 +370,17 @@ Audio effects are foldered resources stored in `audioEffects.items` and
   },
   audioEffect: {
     type: "transition",
-    prev: { fade: { duration: 600, easing: "easeInOutSine" } },
-    next: { fade: { duration: 900, easing: "easeInOutSine" } },
+    prev: {
+      volume: {
+        keyframes: [{ value: 0, duration: 600, easing: "easeInOutSine" }],
+      },
+    },
+    next: {
+      volume: {
+        initialValue: 0,
+        keyframes: [{ value: 100, duration: 900, easing: "easeInOutSine" }],
+      },
+    },
   },
 }
 ```
@@ -365,12 +390,13 @@ transition effect, or a single `target` sound slot for an update effect. Each
 slot is an object containing a `soundId`.
 
 `audioEffect.type` is either `transition` or `update`. Transition effects have
-at least one `prev.fade` or `next.fade`. Update effects tween one or more of
-`volume`, `pan`, and `playbackRate`; each property has non-empty keyframes and
-must finish with an absolute numeric keyframe. That final number becomes the
-persistent BGM property value after the effect finishes. Absolute volume values
-are bounded to `0..100`, pan to `-1..1`, and playback rate to `>= 0`; relative
-keyframes represent unbounded numeric deltas and cannot be final.
+at least one property under `prev` or `next`; update effects place properties
+under `tween`. Both support only `volume`, `pan`, and `playbackRate`. Each
+property has non-empty keyframes and must finish with an absolute numeric
+keyframe. A final `tween` or `next` value becomes the persistent BGM property
+value after the effect finishes. Absolute volume values are bounded to
+`0..100`, pan to `-1..1`, and playback rate to `>= 0`; relative keyframes
+represent unbounded numeric deltas and cannot be final.
 
 ## Current Scope
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routevn/creator-model",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/model.js

@@ -344,7 +344,7 @@ const ANIMATION_EASING_KEYS = [
   "easeOutElastic",
   "easeInOutElastic",
 ];
-const AUDIO_EFFECT_TWEEN_PROPERTY_KEYS = ["volume", "pan", "playbackRate"];
+const AUDIO_EFFECT_PROPERTY_KEYS = ["volume", "pan", "playbackRate"];
 const VARIABLE_SCOPE_KEYS = ["context", "device", "account"];
 const VARIABLE_TYPE_KEYS = ["string", "number", "boolean", "object"];
 const LAYOUT_TYPE_KEYS = [
@@ -408,7 +408,7 @@ const SAVE_LOAD_DATE_FORMATS = new Set([
   "DD MMM YYYY",
   "YYYY年MM月DD日",
 ]);
-export const SCHEMA_VERSION = 13;
+export const SCHEMA_VERSION = 14;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -2345,6 +2345,85 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
   }
 };
 
+// Camera is an authored grouping of four synchronized runtime tween tracks.
+// No grouping is inferred for older animations that omit cameraTracks.
+const validateCameraTracks = ({ value, animation, path, errorFactory }) => {
+  if (value === undefined) return;
+  if (
+    !Array.isArray(value) ||
+    value.some((side) => !["update", "prev", "next"].includes(side)) ||
+    new Set(value).size !== value.length
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be an array of unique update, prev, or next sides`,
+    );
+  }
+  // Partial update payloads are checked against the merged resource below.
+  if (animation === undefined) return;
+  for (const side of value) {
+    const tween = side === "update" ? animation.tween : animation[side]?.tween;
+    const validSide =
+      animation.type === "update" ? side === "update" : side !== "update";
+    const properties = ["x", "y", "scaleX", "scaleY"];
+    const tracks = properties.map((property) => tween?.[property]);
+    if (
+      !validSide ||
+      tracks.some(
+        (track) =>
+          !Array.isArray(track?.keyframes) ||
+          (track.initialValue !== undefined &&
+            !Number.isFinite(track.initialValue)) ||
+          (track.initialValue !== undefined) !==
+            (tracks[0]?.initialValue !== undefined),
+      ) ||
+      tween.translateX !== undefined ||
+      tween.translateY !== undefined
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.${side} requires x, y, scaleX, and scaleY keyframe tracks with matching initial-value presence and no translation tracks`,
+      );
+    }
+    const reference = tracks[0].keyframes;
+    for (const [index, track] of tracks.entries()) {
+      if (
+        track.keyframes.length !== reference.length ||
+        track.keyframes.some((frame, frameIndex) => {
+          const other = reference[frameIndex];
+          return (
+            frame.relative === true ||
+            frame.duration !== other.duration ||
+            (frame.delay ?? 0) !== (other.delay ?? 0) ||
+            (frame.easing ?? "linear") !== (other.easing ?? "linear") ||
+            (frame.startValue !== undefined) !==
+              (other.startValue !== undefined)
+          );
+        })
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path}.${side} requires synchronized absolute keyframes`,
+        );
+      }
+      if (
+        index >= 2 &&
+        ((track.initialValue !== undefined && track.initialValue <= 0) ||
+          track.keyframes.some(
+            (frame) =>
+              frame.value <= 0 ||
+              (frame.startValue !== undefined && frame.startValue <= 0),
+          ))
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path}.${side} requires positive camera scales`,
+        );
+      }
+    }
+  }
+};
+
 const validateAnimationItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
@@ -2370,6 +2449,7 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
                 "tagIds",
                 "thumbnailFileId",
                 "preview",
+                "cameraTracks",
                 "animation",
               ],
         path: itemPath,
@@ -2452,6 +2532,13 @@ const validateAnimationItems = ({ items, path, errorFactory }) => {
           return result;
         }
       }
+      const cameraResult = validateCameraTracks({
+        value: item.cameraTracks,
+        animation: item.animation,
+        path: `${itemPath}.cameraTracks`,
+        errorFactory,
+      });
+      if (cameraResult?.valid === false) return cameraResult;
     }
   }
 };
@@ -2656,23 +2743,23 @@ const validateAudioEffectKeyframes = ({
   }
 };
 
-const validateAudioEffectTween = ({ tween, path, errorFactory }) => {
-  if (!isPlainObject(tween)) {
+const validateAudioEffectPropertyTracks = ({ tracks, path, errorFactory }) => {
+  if (!isPlainObject(tracks)) {
     return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
   }
 
-  if (Object.keys(tween).length === 0) {
+  if (Object.keys(tracks).length === 0) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path} must contain at least one tween property`,
+      `${path} must contain at least one audio property`,
     );
   }
 
-  for (const [property, config] of Object.entries(tween)) {
-    if (!AUDIO_EFFECT_TWEEN_PROPERTY_KEYS.includes(property)) {
+  for (const [property, config] of Object.entries(tracks)) {
+    if (!AUDIO_EFFECT_PROPERTY_KEYS.includes(property)) {
       return invalidFromErrorFactory(
         errorFactory,
-        `${path}.${property} is not a supported audio effect tween property`,
+        `${path}.${property} is not a supported audio effect property`,
       );
     }
 
@@ -2721,141 +2808,6 @@ const validateAudioEffectTween = ({ tween, path, errorFactory }) => {
   }
 };
 
-const validateAudioEffectFade = ({ fade, path, side, errorFactory }) => {
-  if (!isPlainObject(fade)) {
-    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
-  }
-
-  if (Object.hasOwn(fade, "keyframes")) {
-    {
-      const result = validateAllowedKeys({
-        value: fade,
-        allowedKeys: ["initialValue", "keyframes"],
-        path,
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
-    }
-
-    {
-      const result = validateAudioEffectInitialValue({
-        value: fade.initialValue,
-        property: "volume",
-        path: `${path}.initialValue`,
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
-    }
-
-    {
-      const result = validateAudioEffectKeyframes({
-        keyframes: fade.keyframes,
-        property: "volume",
-        path: `${path}.keyframes`,
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
-    }
-
-    for (const [index, keyframe] of fade.keyframes.entries()) {
-      if (keyframe.relative === true) {
-        return invalidFromErrorFactory(
-          errorFactory,
-          `${path}.keyframes[${index}].relative is not supported for transition fades`,
-        );
-      }
-    }
-
-    return;
-  }
-
-  {
-    const result = validateAllowedKeys({
-      value: fade,
-      allowedKeys: ["initialValue", "delay", "duration", "easing"],
-      path,
-      errorFactory,
-    });
-    if (result?.valid === false) {
-      return result;
-    }
-  }
-
-  {
-    const result = validateAudioEffectInitialValue({
-      value: fade.initialValue,
-      property: "volume",
-      path: `${path}.initialValue`,
-      errorFactory,
-    });
-    if (result?.valid === false) {
-      return result;
-    }
-  }
-
-  if (!Object.hasOwn(fade, "duration")) {
-    return invalidFromErrorFactory(
-      errorFactory,
-      `${path}.duration is required`,
-    );
-  }
-
-  if (!isFiniteNumber(fade.duration) || fade.duration < 0) {
-    return invalidFromErrorFactory(
-      errorFactory,
-      `${path}.duration must be a finite number >= 0`,
-    );
-  }
-
-  if (
-    fade.delay !== undefined &&
-    (!isFiniteNumber(fade.delay) || fade.delay < 0)
-  ) {
-    return invalidFromErrorFactory(
-      errorFactory,
-      `${path}.delay must be a finite number >= 0 when provided`,
-    );
-  }
-
-  return validateAudioEffectEasing({
-    value: fade.easing,
-    path: `${path}.easing`,
-    errorFactory,
-  });
-};
-
-const validateAudioEffectTransitionSide = ({
-  side,
-  sideName,
-  path,
-  errorFactory,
-}) => {
-  {
-    const result = validateExactKeys({
-      value: side,
-      expectedKeys: ["fade"],
-      path,
-      errorFactory,
-    });
-    if (result?.valid === false) {
-      return result;
-    }
-  }
-
-  return validateAudioEffectFade({
-    fade: side.fade,
-    path: `${path}.fade`,
-    side: sideName,
-    errorFactory,
-  });
-};
-
 const validateAudioEffectDefinition = ({ audioEffect, path, errorFactory }) => {
   {
     const result = validateAllowedKeys({
@@ -2891,8 +2843,8 @@ const validateAudioEffectDefinition = ({ audioEffect, path, errorFactory }) => {
       );
     }
 
-    return validateAudioEffectTween({
-      tween: audioEffect.tween,
+    return validateAudioEffectPropertyTracks({
+      tracks: audioEffect.tween,
       path: `${path}.tween`,
       errorFactory,
     });
@@ -2917,9 +2869,8 @@ const validateAudioEffectDefinition = ({ audioEffect, path, errorFactory }) => {
       continue;
     }
 
-    const result = validateAudioEffectTransitionSide({
-      side: audioEffect[side],
-      sideName: side,
+    const result = validateAudioEffectPropertyTracks({
+      tracks: audioEffect[side],
       path: `${path}.${side}`,
       errorFactory,
     });
@@ -12396,6 +12347,7 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
               "tagIds",
               "thumbnailFileId",
               "preview",
+              "cameraTracks",
               "animation",
             ],
       path: "payload.data",
@@ -12463,6 +12415,12 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
         return result;
       }
     }
+    return validateCameraTracks({
+      value: data.cameraTracks,
+      animation: data.animation,
+      path: "payload.data.cameraTracks",
+      errorFactory,
+    });
   }
 };
 
@@ -12476,6 +12434,7 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
         "tagIds",
         "thumbnailFileId",
         "preview",
+        "cameraTracks",
         "animation",
       ],
       path: "payload.data",
@@ -12551,6 +12510,12 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
       }
     }
   }
+  return validateCameraTracks({
+    value: data.cameraTracks,
+    animation: data.animation,
+    path: "payload.data.cameraTracks",
+    errorFactory,
+  });
 };
 
 const validateAudioEffectCreateData = ({ data, errorFactory }) => {
@@ -19202,6 +19167,9 @@ const COMMAND_DEFINITIONS = [
         if (payload.data.preview !== undefined) {
           nextAnimation.preview = structuredClone(payload.data.preview);
         }
+        if (payload.data.cameraTracks !== undefined) {
+          nextAnimation.cameraTracks = [...payload.data.cameraTracks];
+        }
         nextAnimation.animation = structuredClone(payload.data.animation);
       }
 
@@ -19271,6 +19239,13 @@ const COMMAND_DEFINITIONS = [
       }
 
       if (currentAnimation.type === "animation") {
+        const cameraResult = validateCameraTracks({
+          value: payload.data.cameraTracks ?? currentAnimation.cameraTracks,
+          animation: payload.data.animation ?? currentAnimation.animation,
+          path: "payload.data.cameraTracks",
+          errorFactory: createPreconditionValidationError,
+        });
+        if (cameraResult?.valid === false) return cameraResult;
         if (payload.data.animation !== undefined) {
           const result = validateAnimationMaskImageReferences({
             state,