@routevn/creator-model 1.2.0 → 1.2.2

package/package.json

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

package/src/index.js

@@ -5,9 +5,4 @@ export {
   validatePayload,
   validateState,
 } from "./model.js";
-export {
-  SYSTEM_VARIABLE_GROUPS,
-  SYSTEM_VARIABLE_IDS,
-  getSystemVariableDefinitions,
-  isSystemVariableId,
-} from "./systemVariables.js";
+export { RUNTIME_FIELD_IDS, isRuntimeFieldId } from "./runtimeFields.js";

package/src/model.js

@@ -15,7 +15,7 @@ import {
   isPlainObject,
   removeTreeNode,
 } from "./helpers.js";
-import { isSystemVariableId } from "./systemVariables.js";
+import { isRuntimeFieldId } from "./runtimeFields.js";
 
 const COLLECTION_KEYS = [
   "scenes",
@@ -25,6 +25,7 @@ const COLLECTION_KEYS = [
   "sounds",
   "videos",
   "animations",
+  "particles",
   "characters",
   "fonts",
   "transforms",
@@ -45,9 +46,11 @@ const normalizeStateCollections = (state) => {
     return state;
   }
 
-  const missingCollectionKeys = ["spritesheets", "controls"].filter(
-    (key) => state[key] === undefined,
-  );
+  const missingCollectionKeys = [
+    "spritesheets",
+    "particles",
+    "controls",
+  ].filter((key) => state[key] === undefined);
 
   if (missingCollectionKeys.length === 0) {
     return state;
@@ -117,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",
@@ -135,6 +138,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container",
   "rect",
   "sprite",
+  "particle",
   "spritesheet-animation",
   "text",
   "text-revealing",
@@ -255,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\[(.+)\]$/;
 
@@ -277,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],
     };
   }
 
@@ -2224,6 +2229,141 @@ const validateTransformItems = ({ items, path, errorFactory }) => {
   }
 };
 
+const validateParticleModules = ({ modules, path, errorFactory }) => {
+  if (!isPlainObject(modules)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
+  }
+
+  if (!isPlainObject(modules.emission)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.emission must be an object`,
+    );
+  }
+
+  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 validateParticleItems = ({ items, path, errorFactory }) => {
+  for (const [itemId, item] of Object.entries(items)) {
+    const itemPath = `${path}.${itemId}`;
+
+    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,
@@ -2316,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'`,
         );
       }
 
@@ -2801,6 +2941,7 @@ const validateLayoutElementData = ({
     "step",
     "initialValue",
     "variableId",
+    "particleId",
     "fragmentLayoutId",
     "paginationMode",
     "paginationVariableId",
@@ -2900,6 +3041,7 @@ const validateLayoutElementData = ({
     "text",
     "resourceId",
     "animationName",
+    "particleId",
     "imageId",
     "hoverImageId",
     "clickImageId",
@@ -2948,6 +3090,18 @@ const validateLayoutElementData = ({
     }
   }
 
+  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(
@@ -3299,6 +3453,7 @@ const validateLayoutElementItems = ({ items, path, errorFactory }) => {
           "revealEffect",
           "resourceId",
           "animationName",
+          "particleId",
           "imageId",
           "hoverImageId",
           "clickImageId",
@@ -4293,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({
@@ -4458,6 +4624,7 @@ const validateCollection = ({ collection, path }) => {
     }
   } else if (
     path === "state.files" ||
+    path === "state.particles" ||
     path === "state.transforms" ||
     path === "state.variables" ||
     path === "state.textStyles" ||
@@ -5124,6 +5291,29 @@ export const assertInvariants = ({ state }) => {
     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,
@@ -5154,6 +5344,19 @@ export const assertInvariants = ({ state }) => {
           }
         }
 
+        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",
@@ -7014,6 +7217,185 @@ const validateTransformCreateData = ({ data, errorFactory }) => {
   }
 };
 
+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",
+        "width",
+        "height",
+        "seed",
+        "modules",
+      ],
+      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.width !== undefined &&
+    (!isFiniteNumber(data.width) || data.width <= 0)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.width must be a positive finite number when provided",
+    );
+  }
+
+  if (
+    data.height !== undefined &&
+    (!isFiniteNumber(data.height) || data.height <= 0)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.height must be a positive finite number when provided",
+    );
+  }
+
+  if (
+    data.seed !== undefined &&
+    data.seed !== null &&
+    !isFiniteNumber(data.seed)
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      "payload.data.seed must be a finite number when provided",
+    );
+  }
+
+  if (data.modules !== undefined) {
+    {
+      const result = validateParticleModules({
+        modules: data.modules,
+        path: "payload.data.modules",
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
 const validateTransformUpdateData = ({ data, errorFactory }) => {
   {
     const result = validateAllowedKeys({
@@ -7124,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'",
       );
     }
 
@@ -7190,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",
     );
   }
 };
@@ -8130,6 +8512,22 @@ const validateVisualElementReferenceTargets = ({
     }
   }
 
+  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") {
@@ -12950,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",
@@ -14960,7 +15415,8 @@ export const processCommand = ({ state, command }) => {
     const shouldMaterializeNormalizedState =
       typeof command?.type === "string" &&
       (command.type.startsWith("control.") ||
-        command.type.startsWith("spritesheet."));
+        command.type.startsWith("spritesheet.") ||
+        command.type.startsWith("particle."));
 
     if (!isPlainObject(command)) {
       return invalidPrecondition("command must be an object");

package/src/runtimeFields.js

@@ -0,0 +1,22 @@
+export const RUNTIME_FIELD_IDS = Object.freeze([
+  "dialogueTextSpeed",
+  "autoForwardDelay",
+  "skipUnseenText",
+  "skipTransitionsAndAnimations",
+  "soundVolume",
+  "musicVolume",
+  "muteAll",
+  "saveLoadPagination",
+  "menuPage",
+  "menuEntryPoint",
+  "autoMode",
+  "skipMode",
+  "dialogueUIHidden",
+  "isLineCompleted",
+]);
+
+const RUNTIME_FIELD_ID_SET = new Set(RUNTIME_FIELD_IDS);
+
+export const isRuntimeFieldId = (value) => {
+  return typeof value === "string" && RUNTIME_FIELD_ID_SET.has(value);
+};

package/src/systemVariables.js

@@ -1,69 +0,0 @@
-export const SYSTEM_VARIABLE_GROUPS = Object.freeze([
-  {
-    id: "routeEngine",
-    name: "Route Engine",
-    variables: Object.freeze([
-      {
-        id: "_skipUnseenText",
-        name: "Skip Unseen Text",
-        scope: "global-device",
-        type: "boolean",
-        default: false,
-        description:
-          "When enabled, skip mode can continue through lines the player has not viewed yet.",
-      },
-      {
-        id: "_dialogueTextSpeed",
-        name: "Dialogue Text Speed",
-        scope: "global-device",
-        type: "number",
-        default: 50,
-        description:
-          "Controls the default dialogue text speed stored for this device.",
-      },
-      {
-        id: "_currentSaveLoadPagination",
-        name: "Current Save/Load Pagination",
-        scope: "context",
-        type: "number",
-        default: 0,
-        description:
-          "The current save/load pagination index. Resolves to 0, 1, 2, 3, and so on for the active save/load page.",
-      },
-      {
-        id: "_currentMenuPage",
-        name: "Current Menu Page",
-        scope: "context",
-        type: "string",
-        default: "",
-        description:
-          "The current menu page id for the active UI flow. Typical values include options, save, load, and history.",
-      },
-      {
-        id: "_menuEntryPoint",
-        name: "Menu Entry Point",
-        scope: "context",
-        type: "string",
-        default: "",
-        description:
-          "Indicates how the current menu flow was opened. Typical values include title and read.",
-      },
-    ]),
-  },
-]);
-
-export const SYSTEM_VARIABLE_IDS = Object.freeze(
-  SYSTEM_VARIABLE_GROUPS.flatMap((group) =>
-    (group.variables || []).map((variable) => variable.id),
-  ),
-);
-
-const SYSTEM_VARIABLE_ID_SET = new Set(SYSTEM_VARIABLE_IDS);
-
-export const isSystemVariableId = (value) => {
-  return typeof value === "string" && SYSTEM_VARIABLE_ID_SET.has(value);
-};
-
-export const getSystemVariableDefinitions = () => {
-  return SYSTEM_VARIABLE_GROUPS.flatMap((group) => group.variables || []);
-};