@routevn/creator-model 1.1.12 → 1.2.2

package/src/model.js

@@ -15,15 +15,17 @@ import {
   isPlainObject,
   removeTreeNode,
 } from "./helpers.js";
-import { isSystemVariableId } from "./systemVariables.js";
+import { isRuntimeFieldId } from "./runtimeFields.js";
 
 const COLLECTION_KEYS = [
   "scenes",
   "files",
   "images",
+  "spritesheets",
   "sounds",
   "videos",
   "animations",
+  "particles",
   "characters",
   "fonts",
   "transforms",
@@ -44,14 +46,25 @@ const normalizeStateCollections = (state) => {
     return state;
   }
 
-  if (state.controls !== undefined) {
+  const missingCollectionKeys = [
+    "spritesheets",
+    "particles",
+    "controls",
+  ].filter((key) => state[key] === undefined);
+
+  if (missingCollectionKeys.length === 0) {
     return state;
   }
 
-  return {
+  const nextState = {
     ...state,
-    controls: createEmptyCollectionState(),
   };
+
+  missingCollectionKeys.forEach((key) => {
+    nextState[key] = createEmptyCollectionState();
+  });
+
+  return nextState;
 };
 const isString = (value) => typeof value === "string";
 const isHexColor = (value) =>
@@ -107,7 +120,7 @@ const ANIMATION_EASING_KEYS = [
   "easeOutElastic",
   "easeInOutElastic",
 ];
-const VARIABLE_SCOPE_KEYS = ["context", "global-device", "global-account"];
+const VARIABLE_SCOPE_KEYS = ["context", "device", "account"];
 const VARIABLE_TYPE_KEYS = ["string", "number", "boolean"];
 const LAYOUT_TYPE_KEYS = [
   "normal",
@@ -125,6 +138,8 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container",
   "rect",
   "sprite",
+  "particle",
+  "spritesheet-animation",
   "text",
   "text-revealing",
   "slider",
@@ -145,7 +160,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container-ref-confirm-dialog-ok",
   "container-ref-confirm-dialog-cancel",
 ];
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -244,20 +259,12 @@ const invalidInvariant = (message, details = {}) =>
   });
 
 const isVariableReferenceTarget = (state, variableId) => {
-  if (isSystemVariableId(variableId)) {
-    return true;
-  }
-
   const variable = state.variables.items[variableId];
   return isPlainObject(variable) && variable.type !== "folder";
 };
 
-const LAYOUT_CONDITION_TARGET_SET = new Set([
-  "item.savedAt",
-  "isLineCompleted",
-  "autoMode",
-  "skipMode",
-]);
+const LAYOUT_ITEM_TARGET_SET = new Set(["item.savedAt"]);
+const RUNTIME_TARGET_DOT_PATTERN = /^runtime\.([A-Za-z_$][A-Za-z0-9_$]*)$/;
 const VARIABLE_TARGET_DOT_PATTERN = /^variables\.([A-Za-z_$][A-Za-z0-9_$]*)$/;
 const VARIABLE_TARGET_BRACKET_PATTERN = /^variables\[(.+)\]$/;
 
@@ -266,10 +273,19 @@ const parseLayoutConditionTarget = (target) => {
     return undefined;
   }
 
-  if (LAYOUT_CONDITION_TARGET_SET.has(target)) {
+  if (LAYOUT_ITEM_TARGET_SET.has(target)) {
+    return {
+      kind: "item",
+      target,
+    };
+  }
+
+  const runtimeMatch = target.match(RUNTIME_TARGET_DOT_PATTERN);
+  if (runtimeMatch && isRuntimeFieldId(runtimeMatch[1])) {
     return {
       kind: "runtime",
       target,
+      runtimeId: runtimeMatch[1],
     };
   }
 
@@ -853,6 +869,207 @@ const validateImageItems = ({ items, path, errorFactory }) => {
   }
 };
 
+const validateSpritesheetAnimationMap = ({
+  animations,
+  path,
+  errorFactory,
+}) => {
+  if (!isPlainObject(animations)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
+  }
+
+  for (const [animationName, animation] of Object.entries(animations)) {
+    const animationPath = `${path}.${animationName}`;
+
+    if (!isNonEmptyString(animationName)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath} must use a non-empty animation name`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: animation,
+        allowedKeys: ["frames", "animationSpeed", "loop"],
+        path: animationPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!Array.isArray(animation.frames)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.frames must be an array`,
+      );
+    }
+
+    for (let index = 0; index < animation.frames.length; index += 1) {
+      const frame = animation.frames[index];
+      if (!Number.isInteger(frame) || frame < 0) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${animationPath}.frames.${index} must be an integer greater than or equal to 0`,
+        );
+      }
+    }
+
+    if (
+      animation.animationSpeed !== undefined &&
+      !isFiniteNumber(animation.animationSpeed)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.animationSpeed must be a finite number when provided`,
+      );
+    }
+
+    if (animation.loop !== undefined && typeof animation.loop !== "boolean") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${animationPath}.loop must be a boolean when provided`,
+      );
+    }
+  }
+
+  return VALID_RESULT;
+};
+
+const validateSpritesheetItems = ({ items, path, errorFactory }) => {
+  for (const [itemId, item] of Object.entries(items)) {
+    const itemPath = `${path}.${itemId}`;
+
+    if (item?.type !== "folder" && item?.type !== "spritesheet") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.type must be 'folder' or 'spritesheet'`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item,
+        allowedKeys:
+          item.type === "folder"
+            ? ["id", "type", "name", "description"]
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "thumbnailFileId",
+                "fileId",
+                "fileType",
+                "fileSize",
+                "sheetWidth",
+                "sheetHeight",
+                "frameCount",
+                "width",
+                "height",
+                "jsonData",
+                "animations",
+              ],
+        path: itemPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(item.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must be a non-empty string`,
+      );
+    }
+
+    if (item.id !== itemId) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must match item key '${itemId}'`,
+      );
+    }
+
+    if (!isNonEmptyString(item.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.name must be a non-empty string`,
+      );
+    }
+
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
+    if (item.type === "spritesheet") {
+      if (
+        item.thumbnailFileId !== undefined &&
+        !isNonEmptyString(item.thumbnailFileId)
+      ) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.thumbnailFileId must be a non-empty string when provided`,
+        );
+      }
+
+      if (!isNonEmptyString(item.fileId)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.fileId must be a non-empty string`,
+        );
+      }
+
+      if (item.fileType !== undefined && !isString(item.fileType)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.fileType must be a string when provided`,
+        );
+      }
+
+      for (const key of [
+        "fileSize",
+        "sheetWidth",
+        "sheetHeight",
+        "frameCount",
+        "width",
+        "height",
+      ]) {
+        if (item[key] !== undefined && !isFiniteNumber(item[key])) {
+          return invalidFromErrorFactory(
+            errorFactory,
+            `${itemPath}.${key} must be a finite number when provided`,
+          );
+        }
+      }
+
+      if (!isPlainObject(item.jsonData)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${itemPath}.jsonData must be an object`,
+        );
+      }
+
+      {
+        const result = validateSpritesheetAnimationMap({
+          animations: item.animations,
+          path: `${itemPath}.animations`,
+          errorFactory,
+        });
+        if (result?.valid === false) {
+          return result;
+        }
+      }
+    }
+  }
+};
+
 const validateSoundItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
@@ -1141,16 +1358,57 @@ const validateAnimationKeyframes = ({ keyframes, path, errorFactory }) => {
   }
 };
 
+const validateAutoTweenProperty = ({ auto, path, errorFactory }) => {
+  {
+    const result = validateAllowedKeys({
+      value: auto,
+      allowedKeys: ["duration", "easing"],
+      path,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!("duration" in auto)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.duration is required`,
+    );
+  }
+
+  if (!isFiniteNumber(auto.duration) || auto.duration < 1) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.duration must be a finite number >= 1`,
+    );
+  }
+
+  if (
+    auto.easing !== undefined &&
+    !ANIMATION_EASING_KEYS.includes(auto.easing)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.easing must be a supported Route Graphics easing`,
+    );
+  }
+};
+
 const validateTweenProperty = ({
   config,
   path,
   allowEmptyKeyframes = false,
+  allowAuto = false,
   errorFactory,
 }) => {
   {
     const result = validateAllowedKeys({
       value: config,
-      allowedKeys: ["initialValue", "keyframes"],
+      allowedKeys: allowAuto
+        ? ["initialValue", "keyframes", "auto"]
+        : ["initialValue", "keyframes"],
       path,
       errorFactory,
     });
@@ -1159,10 +1417,20 @@ const validateTweenProperty = ({
     }
   }
 
-  if (!("keyframes" in config)) {
+  const hasKeyframes = "keyframes" in config;
+  const hasAuto = "auto" in config;
+
+  if (!hasKeyframes && !hasAuto) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.keyframes or ${path}.auto is required`,
+    );
+  }
+
+  if (hasKeyframes && hasAuto) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path}.keyframes is required`,
+      `${path}.keyframes and ${path}.auto cannot both be defined`,
     );
   }
 
@@ -1176,6 +1444,28 @@ const validateTweenProperty = ({
     );
   }
 
+  if (hasAuto) {
+    if (config.initialValue !== undefined) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.initialValue is not supported when ${path}.auto is defined`,
+      );
+    }
+
+    {
+      const result = validateAutoTweenProperty({
+        auto: config.auto,
+        path: `${path}.auto`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    return;
+  }
+
   {
     const result = validateAnimationKeyframes({
       keyframes: config.keyframes,
@@ -1201,6 +1491,7 @@ const validateTweenDefinition = ({
   path,
   unsupportedMessage,
   allowEmptyKeyframes = false,
+  allowAuto = false,
   errorFactory,
 }) => {
   if (!isPlainObject(tween)) {
@@ -1229,6 +1520,7 @@ const validateTweenDefinition = ({
         config,
         path: propertyPath,
         allowEmptyKeyframes,
+        allowAuto,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1547,6 +1839,8 @@ const validateAnimationDefinition = ({ animation, path, errorFactory }) => {
         allowedProperties: UPDATE_TWEEN_PROPERTY_KEYS,
         path: `${path}.tween`,
         unsupportedMessage: "is not a supported update tween property",
+        allowEmptyKeyframes: true,
+        allowAuto: true,
         errorFactory,
       });
       if (result?.valid === false) {
@@ -1935,36 +2229,171 @@ const validateTransformItems = ({ items, path, errorFactory }) => {
   }
 };
 
-const validateVariableTypedValue = ({
-  value,
-  variableType,
-  path,
-  errorFactory,
-}) => {
-  if (variableType === "string" && !isString(value)) {
-    return invalidFromErrorFactory(errorFactory, `${path} must be a string`);
+const validateParticleModules = ({ modules, path, errorFactory }) => {
+  if (!isPlainObject(modules)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
   }
 
-  if (variableType === "number" && !isFiniteNumber(value)) {
+  if (!isPlainObject(modules.emission)) {
     return invalidFromErrorFactory(
       errorFactory,
-      `${path} must be a finite number`,
+      `${path}.emission must be an object`,
     );
   }
 
-  if (variableType === "boolean" && typeof value !== "boolean") {
-    return invalidFromErrorFactory(errorFactory, `${path} must be a boolean`);
+  if (!isPlainObject(modules.appearance)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.appearance must be an object`,
+    );
+  }
+
+  if (modules.movement !== undefined && !isPlainObject(modules.movement)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.movement must be an object when provided`,
+    );
+  }
+
+  if (modules.bounds !== undefined && !isPlainObject(modules.bounds)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.bounds must be an object when provided`,
+    );
   }
 };
 
-const validateVariableItems = ({ items, path, errorFactory }) => {
+const validateParticleItems = ({ items, path, errorFactory }) => {
   for (const [itemId, item] of Object.entries(items)) {
     const itemPath = `${path}.${itemId}`;
-    const variableType = item?.type;
 
-    if (
-      variableType !== "folder" &&
-      !VARIABLE_TYPE_KEYS.includes(variableType)
+    if (item?.type !== "folder" && item?.type !== "particle") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.type must be 'folder' or 'particle'`,
+      );
+    }
+
+    {
+      const result = validateAllowedKeys({
+        value: item,
+        allowedKeys:
+          item.type === "folder"
+            ? ["id", "type", "name", "description"]
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "width",
+                "height",
+                "seed",
+                "modules",
+              ],
+        path: itemPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(item.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must be a non-empty string`,
+      );
+    }
+
+    if (item.id !== itemId) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must match item key '${itemId}'`,
+      );
+    }
+
+    if (!isNonEmptyString(item.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.name must be a non-empty string`,
+      );
+    }
+
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
+    if (item.type !== "particle") {
+      continue;
+    }
+
+    if (!isFiniteNumber(item.width) || item.width <= 0) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.width must be a positive finite number`,
+      );
+    }
+
+    if (!isFiniteNumber(item.height) || item.height <= 0) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.height must be a positive finite number`,
+      );
+    }
+
+    if (item.seed !== undefined && !isFiniteNumber(item.seed)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.seed must be a finite number when provided`,
+      );
+    }
+
+    {
+      const result = validateParticleModules({
+        modules: item.modules,
+        path: `${itemPath}.modules`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
+const validateVariableTypedValue = ({
+  value,
+  variableType,
+  path,
+  errorFactory,
+}) => {
+  if (variableType === "string" && !isString(value)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be a string`);
+  }
+
+  if (variableType === "number" && !isFiniteNumber(value)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be a finite number`,
+    );
+  }
+
+  if (variableType === "boolean" && typeof value !== "boolean") {
+    return invalidFromErrorFactory(errorFactory, `${path} must be a boolean`);
+  }
+};
+
+const validateVariableItems = ({ items, path, errorFactory }) => {
+  for (const [itemId, item] of Object.entries(items)) {
+    const itemPath = `${path}.${itemId}`;
+    const variableType = item?.type;
+
+    if (
+      variableType !== "folder" &&
+      !VARIABLE_TYPE_KEYS.includes(variableType)
     ) {
       return invalidFromErrorFactory(
         errorFactory,
@@ -2027,7 +2456,7 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
       if (!VARIABLE_SCOPE_KEYS.includes(item.scope)) {
         return invalidFromErrorFactory(
           errorFactory,
-          `${itemPath}.scope must be 'context', 'global-device', or 'global-account'`,
+          `${itemPath}.scope must be 'context', 'device', or 'account'`,
         );
       }
 
@@ -2486,6 +2915,8 @@ const validateLayoutElementData = ({
     "textStyle",
     "displaySpeed",
     "revealEffect",
+    "resourceId",
+    "animationName",
     "imageId",
     "hoverImageId",
     "clickImageId",
@@ -2510,6 +2941,7 @@ const validateLayoutElementData = ({
     "step",
     "initialValue",
     "variableId",
+    "particleId",
     "fragmentLayoutId",
     "paginationMode",
     "paginationVariableId",
@@ -2607,6 +3039,9 @@ const validateLayoutElementData = ({
 
   for (const key of [
     "text",
+    "resourceId",
+    "animationName",
+    "particleId",
     "imageId",
     "hoverImageId",
     "clickImageId",
@@ -2633,6 +3068,40 @@ const validateLayoutElementData = ({
     }
   }
 
+  if (data.type === "spritesheet-animation") {
+    if (
+      (!allowPartial || data.resourceId !== undefined) &&
+      !isNonEmptyString(data.resourceId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.resourceId must be a non-empty string`,
+      );
+    }
+
+    if (
+      (!allowPartial || data.animationName !== undefined) &&
+      !isNonEmptyString(data.animationName)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.animationName must be a non-empty string`,
+      );
+    }
+  }
+
+  if (data.type === "particle") {
+    if (
+      (!allowPartial || data.particleId !== undefined) &&
+      !isNonEmptyString(data.particleId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path}.particleId must be a non-empty string`,
+      );
+    }
+  }
+
   if (data.conditionalOverrides !== undefined) {
     if (!Array.isArray(data.conditionalOverrides)) {
       return invalidFromErrorFactory(
@@ -2982,6 +3451,9 @@ const validateLayoutElementItems = ({ items, path, errorFactory }) => {
           "textStyle",
           "displaySpeed",
           "revealEffect",
+          "resourceId",
+          "animationName",
+          "particleId",
           "imageId",
           "hoverImageId",
           "clickImageId",
@@ -3888,6 +4360,17 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
+  } else if (path === "state.spritesheets") {
+    {
+      const result = validateSpritesheetItems({
+        items: collection.items,
+        path: `${path}.items`,
+        errorFactory: createStateValidationError,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
   } else if (path === "state.files") {
     {
       const result = validateFileItems({
@@ -3965,6 +4448,17 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
+  } else if (path === "state.particles") {
+    {
+      const result = validateParticleItems({
+        items: collection.items,
+        path: `${path}.items`,
+        errorFactory: createStateValidationError,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
   } else if (path === "state.variables") {
     {
       const result = validateVariableItems({
@@ -4061,6 +4555,18 @@ const validateCollection = ({ collection, path }) => {
         return result;
       }
     }
+  } else if (path === "state.spritesheets") {
+    {
+      const result = validateGenericFolderOwnership({
+        nodes: collection.tree,
+        items: collection.items,
+        path: `${path}.tree`,
+        folderLabel: "folder spritesheet item",
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
   } else if (path === "state.sounds") {
     {
       const result = validateSoundTreeFolderOwnership({
@@ -4118,6 +4624,7 @@ const validateCollection = ({ collection, path }) => {
     }
   } else if (
     path === "state.files" ||
+    path === "state.particles" ||
     path === "state.transforms" ||
     path === "state.variables" ||
     path === "state.textStyles" ||
@@ -4417,6 +4924,43 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
+  for (const [spritesheetId, spritesheet] of Object.entries(
+    state.spritesheets.items,
+  )) {
+    if (spritesheet.type !== "spritesheet") {
+      continue;
+    }
+
+    const result = validateFileReference({
+      state,
+      fileId: spritesheet.fileId,
+      path: "spritesheet.fileId",
+      details: { spritesheetId, fileId: spritesheet.fileId },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!result.valid) {
+      return result;
+    }
+
+    if (spritesheet.thumbnailFileId === undefined) {
+      continue;
+    }
+
+    const thumbnailResult = validateFileReference({
+      state,
+      fileId: spritesheet.thumbnailFileId,
+      path: "spritesheet.thumbnailFileId",
+      details: {
+        spritesheetId,
+        thumbnailFileId: spritesheet.thumbnailFileId,
+      },
+      errorFactory: createInvariantValidationError,
+    });
+    if (!thumbnailResult.valid) {
+      return thumbnailResult;
+    }
+  }
+
   for (const [soundId, sound] of Object.entries(state.sounds.items)) {
     if (sound.type !== "sound") {
       continue;
@@ -4708,6 +5252,68 @@ export const assertInvariants = ({ state }) => {
     return VALID_RESULT;
   };
 
+  const assertSpritesheetAnimationReference = ({
+    ownerIdField,
+    ownerId,
+    ownerLabel,
+    elementId,
+    targetId,
+    animationName,
+  }) => {
+    const spritesheet = state.spritesheets?.items?.[targetId];
+    if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
+      return invalidInvariant(
+        `${ownerLabel} element resourceId must reference an existing non-folder spritesheet`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "resourceId",
+          targetId,
+        },
+      );
+    }
+
+    if (
+      !isNonEmptyString(animationName) ||
+      !isPlainObject(spritesheet.animations?.[animationName])
+    ) {
+      return invalidInvariant(
+        `${ownerLabel} element animationName must reference an existing spritesheet animation`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "animationName",
+          targetId: animationName,
+        },
+      );
+    }
+
+    return VALID_RESULT;
+  };
+
+  const assertParticleReference = ({
+    ownerIdField,
+    ownerId,
+    ownerLabel,
+    elementId,
+    targetId,
+  }) => {
+    const particle = state.particles?.items?.[targetId];
+    if (!isPlainObject(particle) || particle.type === "folder") {
+      return invalidInvariant(
+        `${ownerLabel} element particleId must reference an existing non-folder particle`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "particleId",
+          targetId,
+        },
+      );
+    }
+
+    return VALID_RESULT;
+  };
+
   const assertElementReferencesForCollection = ({
     items,
     ownerIdField,
@@ -4720,6 +5326,37 @@ export const assertInvariants = ({ state }) => {
       }
 
       for (const [elementId, element] of Object.entries(owner.elements.items)) {
+        if (
+          element.type === "spritesheet-animation" ||
+          element.resourceId !== undefined ||
+          element.animationName !== undefined
+        ) {
+          const result = assertSpritesheetAnimationReference({
+            ownerIdField,
+            ownerId,
+            ownerLabel,
+            elementId,
+            targetId: element.resourceId,
+            animationName: element.animationName,
+          });
+          if (!result.valid) {
+            return result;
+          }
+        }
+
+        if (element.type === "particle" || element.particleId !== undefined) {
+          const result = assertParticleReference({
+            ownerIdField,
+            ownerId,
+            ownerLabel,
+            elementId,
+            targetId: element.particleId,
+          });
+          if (!result.valid) {
+            return result;
+          }
+        }
+
         for (const field of [
           "imageId",
           "hoverImageId",
@@ -5460,7 +6097,234 @@ const validateImageUpdateData = ({ data, errorFactory }) => {
   }
 };
 
-const validateSoundCreateData = ({ data, errorFactory }) => {
+const validateSpritesheetCreateData = ({ data, errorFactory }) => {
+  if (!isPlainObject(data)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must be an object",
+    );
+  }
+
+  if (data.type !== "folder" && data.type !== "spritesheet") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.type must be 'folder' or 'spritesheet'",
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys:
+        data.type === "folder"
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "thumbnailFileId",
+              "fileId",
+              "fileType",
+              "fileSize",
+              "sheetWidth",
+              "sheetHeight",
+              "frameCount",
+              "width",
+              "height",
+              "jsonData",
+              "animations",
+            ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (data.type === "spritesheet") {
+    if (
+      data.thumbnailFileId !== undefined &&
+      !isNonEmptyString(data.thumbnailFileId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.thumbnailFileId must be a non-empty string when provided",
+      );
+    }
+
+    if (!isNonEmptyString(data.fileId)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.fileId must be a non-empty string",
+      );
+    }
+
+    if (data.fileType !== undefined && !isString(data.fileType)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.fileType must be a string when provided",
+      );
+    }
+
+    for (const key of [
+      "fileSize",
+      "sheetWidth",
+      "sheetHeight",
+      "frameCount",
+      "width",
+      "height",
+    ]) {
+      if (data[key] !== undefined && !isFiniteNumber(data[key])) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `payload.data.${key} must be a finite number`,
+        );
+      }
+    }
+
+    if (!isPlainObject(data.jsonData)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.jsonData must be an object",
+      );
+    }
+
+    {
+      const result = validateSpritesheetAnimationMap({
+        animations: data.animations,
+        path: "payload.data.animations",
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
+const validateSpritesheetUpdateData = ({ data, errorFactory }) => {
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys: [
+        "name",
+        "description",
+        "thumbnailFileId",
+        "fileId",
+        "fileType",
+        "fileSize",
+        "sheetWidth",
+        "sheetHeight",
+        "frameCount",
+        "width",
+        "height",
+        "jsonData",
+        "animations",
+      ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (Object.keys(data).length === 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must include at least one updatable field",
+    );
+  }
+
+  if (data.name !== undefined && !isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string when provided",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (
+    data.thumbnailFileId !== undefined &&
+    !isNonEmptyString(data.thumbnailFileId)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.thumbnailFileId must be a non-empty string when provided",
+    );
+  }
+
+  if (data.fileId !== undefined && !isNonEmptyString(data.fileId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.fileId must be a non-empty string when provided",
+    );
+  }
+
+  if (data.fileType !== undefined && !isString(data.fileType)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.fileType must be a string when provided",
+    );
+  }
+
+  for (const key of [
+    "fileSize",
+    "sheetWidth",
+    "sheetHeight",
+    "frameCount",
+    "width",
+    "height",
+  ]) {
+    if (data[key] !== undefined && !isFiniteNumber(data[key])) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `payload.data.${key} must be a finite number`,
+      );
+    }
+  }
+
+  if (data.jsonData !== undefined && !isPlainObject(data.jsonData)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.jsonData must be an object when provided",
+    );
+  }
+
+  if (data.animations !== undefined) {
+    const result = validateSpritesheetAnimationMap({
+      animations: data.animations,
+      path: "payload.data.animations",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+};
+
+const validateSoundCreateData = ({ data, errorFactory }) => {
   if (!isPlainObject(data)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -6230,11 +7094,234 @@ const validateAnimationCreateData = ({ data, errorFactory }) => {
   }
 };
 
-const validateAnimationUpdateData = ({ data, errorFactory }) => {
+const validateAnimationUpdateData = ({ data, errorFactory }) => {
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys: ["name", "description", "animation"],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (Object.keys(data).length === 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must include at least one updatable field",
+    );
+  }
+
+  if (data.name !== undefined && !isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string when provided",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (data.animation !== undefined) {
+    {
+      const result = validateAnimationDefinition({
+        animation: data.animation,
+        path: "payload.data.animation",
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
+const validateTransformCreateData = ({ data, errorFactory }) => {
+  if (!isPlainObject(data)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must be an object",
+    );
+  }
+
+  if (data.type !== "folder" && data.type !== "transform") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.type must be 'folder' or 'transform'",
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys:
+        data.type === "folder"
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "x",
+              "y",
+              "scaleX",
+              "scaleY",
+              "anchorX",
+              "anchorY",
+              "rotation",
+            ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (data.type === "transform") {
+    for (const key of [
+      "x",
+      "y",
+      "scaleX",
+      "scaleY",
+      "anchorX",
+      "anchorY",
+      "rotation",
+    ]) {
+      if (!isFiniteNumber(data[key])) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `payload.data.${key} must be a finite number`,
+        );
+      }
+    }
+  }
+};
+
+const validateParticleCreateData = ({ data, errorFactory }) => {
+  if (!isPlainObject(data)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data must be an object",
+    );
+  }
+
+  if (data.type !== "folder" && data.type !== "particle") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.type must be 'folder' or 'particle'",
+    );
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: data,
+      allowedKeys:
+        data.type === "folder"
+          ? ["type", "name", "description"]
+          : [
+              "type",
+              "name",
+              "description",
+              "width",
+              "height",
+              "seed",
+              "modules",
+            ],
+      path: "payload.data",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  if (!isNonEmptyString(data.name)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.name must be a non-empty string",
+    );
+  }
+
+  if (data.description !== undefined && !isString(data.description)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.description must be a string when provided",
+    );
+  }
+
+  if (data.type !== "particle") {
+    return;
+  }
+
+  if (!isFiniteNumber(data.width) || data.width <= 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.width must be a positive finite number",
+    );
+  }
+
+  if (!isFiniteNumber(data.height) || data.height <= 0) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.height must be a positive finite number",
+    );
+  }
+
+  if (
+    data.seed !== undefined &&
+    data.seed !== null &&
+    !isFiniteNumber(data.seed)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.seed must be a finite number when provided",
+    );
+  }
+
+  {
+    const result = validateParticleModules({
+      modules: data.modules,
+      path: "payload.data.modules",
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+};
+
+const validateParticleUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
       value: data,
-      allowedKeys: ["name", "description", "animation"],
+      allowedKeys: [
+        "name",
+        "description",
+        "width",
+        "height",
+        "seed",
+        "modules",
+      ],
       path: "payload.data",
       errorFactory,
     });
@@ -6264,90 +7351,46 @@ const validateAnimationUpdateData = ({ data, errorFactory }) => {
     );
   }
 
-  if (data.animation !== undefined) {
-    {
-      const result = validateAnimationDefinition({
-        animation: data.animation,
-        path: "payload.data.animation",
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
-    }
-  }
-};
-
-const validateTransformCreateData = ({ data, errorFactory }) => {
-  if (!isPlainObject(data)) {
-    return invalidFromErrorFactory(
-      errorFactory,
-      "payload.data must be an object",
-    );
-  }
-
-  if (data.type !== "folder" && data.type !== "transform") {
+  if (
+    data.width !== undefined &&
+    (!isFiniteNumber(data.width) || data.width <= 0)
+  ) {
     return invalidFromErrorFactory(
       errorFactory,
-      "payload.data.type must be 'folder' or 'transform'",
+      "payload.data.width must be a positive finite number when provided",
     );
   }
 
-  {
-    const result = validateAllowedKeys({
-      value: data,
-      allowedKeys:
-        data.type === "folder"
-          ? ["type", "name", "description"]
-          : [
-              "type",
-              "name",
-              "description",
-              "x",
-              "y",
-              "scaleX",
-              "scaleY",
-              "anchorX",
-              "anchorY",
-              "rotation",
-            ],
-      path: "payload.data",
-      errorFactory,
-    });
-    if (result?.valid === false) {
-      return result;
-    }
-  }
-
-  if (!isNonEmptyString(data.name)) {
+  if (
+    data.height !== undefined &&
+    (!isFiniteNumber(data.height) || data.height <= 0)
+  ) {
     return invalidFromErrorFactory(
       errorFactory,
-      "payload.data.name must be a non-empty string",
+      "payload.data.height must be a positive finite number when provided",
     );
   }
 
-  if (data.description !== undefined && !isString(data.description)) {
+  if (
+    data.seed !== undefined &&
+    data.seed !== null &&
+    !isFiniteNumber(data.seed)
+  ) {
     return invalidFromErrorFactory(
       errorFactory,
-      "payload.data.description must be a string when provided",
+      "payload.data.seed must be a finite number when provided",
     );
   }
 
-  if (data.type === "transform") {
-    for (const key of [
-      "x",
-      "y",
-      "scaleX",
-      "scaleY",
-      "anchorX",
-      "anchorY",
-      "rotation",
-    ]) {
-      if (!isFiniteNumber(data[key])) {
-        return invalidFromErrorFactory(
-          errorFactory,
-          `payload.data.${key} must be a finite number`,
-        );
+  if (data.modules !== undefined) {
+    {
+      const result = validateParticleModules({
+        modules: data.modules,
+        path: "payload.data.modules",
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
       }
     }
   }
@@ -6463,7 +7506,7 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
     if (!VARIABLE_SCOPE_KEYS.includes(data.scope)) {
       return invalidFromErrorFactory(
         errorFactory,
-        "payload.data.scope must be 'context', 'global-device', or 'global-account'",
+        "payload.data.scope must be 'context', 'device', or 'account'",
       );
     }
 
@@ -6529,7 +7572,7 @@ const validateVariableUpdateData = ({ data, errorFactory }) => {
   if (data.scope !== undefined && !VARIABLE_SCOPE_KEYS.includes(data.scope)) {
     return invalidFromErrorFactory(
       errorFactory,
-      "payload.data.scope must be 'context', 'global-device', or 'global-account' when provided",
+      "payload.data.scope must be 'context', 'device', or 'account' when provided",
     );
   }
 };
@@ -7433,6 +8476,58 @@ const validateVisualElementReferenceTargets = ({
   state,
   errorFactory,
 }) => {
+  if (
+    data.type === "spritesheet-animation" ||
+    data.resourceId !== undefined ||
+    data.animationName !== undefined
+  ) {
+    const spritesheet = state.spritesheets?.items?.[data.resourceId];
+    if (!isPlainObject(spritesheet) || spritesheet.type === "folder") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element resourceId must reference an existing non-folder spritesheet`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "resourceId",
+          targetId: data.resourceId,
+        },
+      );
+    }
+
+    if (
+      !isNonEmptyString(data.animationName) ||
+      !isPlainObject(spritesheet.animations?.[data.animationName])
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element animationName must reference an existing spritesheet animation`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "animationName",
+          targetId: data.animationName,
+        },
+      );
+    }
+  }
+
+  if (data.type === "particle" || data.particleId !== undefined) {
+    const particle = state.particles?.items?.[data.particleId];
+    if (!isPlainObject(particle) || particle.type === "folder") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${ownerLabel} element particleId must reference an existing non-folder particle`,
+        {
+          [ownerIdField]: ownerId,
+          elementId,
+          field: "particleId",
+          targetId: data.particleId,
+        },
+      );
+    }
+  }
+
   if (data.imageId !== undefined) {
     const image = state.images.items[data.imageId];
     if (!isPlainObject(image) || image.type === "folder") {
@@ -8246,6 +9341,30 @@ const findReferencedFileUsage = ({ state, fileId }) => {
     }
   }
 
+  for (const [spritesheetId, spritesheet] of Object.entries(
+    state.spritesheets.items,
+  )) {
+    if (spritesheet.type !== "spritesheet") {
+      continue;
+    }
+
+    if (spritesheet.fileId === fileId) {
+      return {
+        kind: "spritesheet",
+        field: "fileId",
+        ownerId: spritesheetId,
+      };
+    }
+
+    if (spritesheet.thumbnailFileId === fileId) {
+      return {
+        kind: "spritesheet",
+        field: "thumbnailFileId",
+        ownerId: spritesheetId,
+      };
+    }
+  }
+
   for (const [soundId, sound] of Object.entries(state.sounds.items)) {
     if (sound.type !== "sound") {
       continue;
@@ -8439,6 +9558,108 @@ const COMMAND_DEFINITIONS = [
       }
     },
   }),
+  ...createFolderedCollectionCommandDefinitions({
+    familyName: "spritesheet",
+    collectionKey: "spritesheets",
+    idField: "spritesheetId",
+    itemLabel: "spritesheet item",
+    createDataValidator: validateSpritesheetCreateData,
+    updateDataValidator: validateSpritesheetUpdateData,
+    createItem: ({ payload }) => ({
+      id: payload.spritesheetId,
+      type: payload.data.type,
+      name: payload.data.name,
+      ...(payload.data.description !== undefined
+        ? {
+            description: payload.data.description,
+          }
+        : {}),
+      ...(payload.data.type === "spritesheet"
+        ? {
+            fileId: payload.data.fileId,
+            ...(payload.data.thumbnailFileId !== undefined
+              ? {
+                  thumbnailFileId: payload.data.thumbnailFileId,
+                }
+              : {}),
+            ...(payload.data.fileType !== undefined
+              ? {
+                  fileType: payload.data.fileType,
+                }
+              : {}),
+            ...(payload.data.fileSize !== undefined
+              ? {
+                  fileSize: payload.data.fileSize,
+                }
+              : {}),
+            ...(payload.data.sheetWidth !== undefined
+              ? {
+                  sheetWidth: payload.data.sheetWidth,
+                }
+              : {}),
+            ...(payload.data.sheetHeight !== undefined
+              ? {
+                  sheetHeight: payload.data.sheetHeight,
+                }
+              : {}),
+            ...(payload.data.frameCount !== undefined
+              ? {
+                  frameCount: payload.data.frameCount,
+                }
+              : {}),
+            ...(payload.data.width !== undefined
+              ? {
+                  width: payload.data.width,
+                }
+              : {}),
+            ...(payload.data.height !== undefined
+              ? {
+                  height: payload.data.height,
+                }
+              : {}),
+            jsonData: structuredClone(payload.data.jsonData),
+            animations: structuredClone(payload.data.animations),
+          }
+        : {}),
+    }),
+    validateCreateState: ({ state, payload }) => {
+      if (payload.data.type !== "spritesheet") {
+        return;
+      }
+
+      return validateReferencedFilesInData({
+        state,
+        data: payload.data,
+        fields: ["fileId", "thumbnailFileId"],
+        details: {
+          spritesheetId: payload.spritesheetId,
+        },
+      });
+    },
+    validateUpdateState: ({ state, payload, currentItem }) => {
+      if (
+        currentItem.type === "folder" &&
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
+      ) {
+        return invalidPrecondition(
+          "folder spritesheet items cannot update spritesheet fields",
+        );
+      }
+
+      if (currentItem.type === "spritesheet") {
+        return validateReferencedFilesInData({
+          state,
+          data: payload.data,
+          fields: ["fileId", "thumbnailFileId"],
+          details: {
+            spritesheetId: payload.spritesheetId,
+          },
+        });
+      }
+    },
+  }),
   {
     type: "story.update",
     validatePayload: ({ payload }) => {
@@ -12127,6 +13348,63 @@ const COMMAND_DEFINITIONS = [
       return state;
     },
   },
+  ...createFolderedCollectionCommandDefinitions({
+    familyName: "particle",
+    collectionKey: "particles",
+    idField: "particleId",
+    itemLabel: "particle item",
+    createDataValidator: validateParticleCreateData,
+    updateDataValidator: validateParticleUpdateData,
+    createItem: ({ payload }) => {
+      const item = {
+        id: payload.particleId,
+        type: payload.data.type,
+        name: payload.data.name,
+      };
+
+      if (payload.data.description !== undefined) {
+        item.description = payload.data.description;
+      }
+
+      if (payload.data.type !== "particle") {
+        return item;
+      }
+
+      item.width = payload.data.width;
+      item.height = payload.data.height;
+      item.modules = structuredClone(payload.data.modules);
+
+      if (payload.data.seed !== undefined && payload.data.seed !== null) {
+        item.seed = payload.data.seed;
+      }
+
+      return item;
+    },
+    updateItem: ({ currentItem, payload }) => {
+      const nextItem = {
+        ...structuredClone(currentItem),
+        ...structuredClone(payload.data),
+      };
+
+      if (payload.data.seed === null) {
+        delete nextItem.seed;
+      }
+
+      return nextItem;
+    },
+    validateUpdateState: ({ payload, currentItem }) => {
+      if (
+        currentItem.type === "folder" &&
+        Object.keys(payload.data).some(
+          (key) => key !== "name" && key !== "description",
+        )
+      ) {
+        return invalidPrecondition(
+          "folder particle items cannot update particle fields",
+        );
+      }
+    },
+  }),
   ...createFolderedCollectionCommandDefinitions({
     familyName: "transform",
     collectionKey: "transforms",
@@ -14134,8 +15412,11 @@ export const validateAgainstState = ({ state, command }) => {
 export const processCommand = ({ state, command }) => {
   return captureValidation(() => {
     const normalizedState = normalizeStateCollections(state);
-    const shouldMaterializeControls =
-      typeof command?.type === "string" && command.type.startsWith("control.");
+    const shouldMaterializeNormalizedState =
+      typeof command?.type === "string" &&
+      (command.type.startsWith("control.") ||
+        command.type.startsWith("spritesheet.") ||
+        command.type.startsWith("particle."));
 
     if (!isPlainObject(command)) {
       return invalidPrecondition("command must be an object");
@@ -14156,7 +15437,7 @@ export const processCommand = ({ state, command }) => {
 
     const nextState = definition.reduce({
       state: structuredClone(
-        shouldMaterializeControls ? normalizedState : state,
+        shouldMaterializeNormalizedState ? normalizedState : state,
       ),
       payload: command.payload,
     });
@@ -14166,7 +15447,7 @@ export const processCommand = ({ state, command }) => {
 
     const finalState =
       nextState === undefined
-        ? shouldMaterializeControls
+        ? shouldMaterializeNormalizedState
           ? normalizedState
           : state
         : nextState;