@m2c2kit/core 0.3.17 → 0.3.18

package/dist/index.js

@@ -1,3 +1,33 @@
+var M2NodeType = /* @__PURE__ */ ((M2NodeType2) => {
+  M2NodeType2["Node"] = "Node";
+  M2NodeType2["Scene"] = "Scene";
+  M2NodeType2["Sprite"] = "Sprite";
+  M2NodeType2["Label"] = "Label";
+  M2NodeType2["TextLine"] = "TextLine";
+  M2NodeType2["Shape"] = "Shape";
+  M2NodeType2["Composite"] = "Composite";
+  M2NodeType2["SoundPlayer"] = "SoundPlayer";
+  M2NodeType2["SoundRecorder"] = "SoundRecorder";
+  return M2NodeType2;
+})(M2NodeType || {});
+
+const M2SoundStatus = {
+  /** Sound was set for lazy loading, and loading has not yet been requested. */
+  Deferred: "Deferred",
+  /** Sound is indicated for fetching, but fetching has not begun. */
+  WillFetch: "WillFetch",
+  /** Sound is being fetched. */
+  Fetching: "Fetching",
+  /** Sound has been fetched. */
+  Fetched: "Fetched",
+  /** Sound is being decoded. */
+  Decoding: "Decoding",
+  /** Sound has fully finished loading and is ready to use. */
+  Ready: "Ready",
+  /** Error occurred in loading. */
+  Error: "Error"
+};
+
 var ActionType = /* @__PURE__ */ ((ActionType2) => {
   ActionType2["Sequence"] = "Sequence";
   ActionType2["Group"] = "Group";
@@ -7,6 +37,9 @@ var ActionType = /* @__PURE__ */ ((ActionType2) => {
   ActionType2["Scale"] = "Scale";
   ActionType2["FadeAlpha"] = "FadeAlpha";
   ActionType2["Rotate"] = "Rotate";
+  ActionType2["Play"] = "Play";
+  ActionType2["Repeat"] = "Repeat";
+  ActionType2["RepeatForever"] = "RepeatForever";
   return ActionType2;
 })(ActionType || {});
 
@@ -44,8 +77,7 @@ Easings.quadraticOut = (t, b, c, d) => {
 };
 Easings.quadraticInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return c / 2 * t * t + b;
+  if (t < 1) return c / 2 * t * t + b;
   t--;
   return -c / 2 * (t * (t - 2) - 1) + b;
 };
@@ -60,8 +92,7 @@ Easings.cubicOut = (t, b, c, d) => {
 };
 Easings.cubicInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return c / 2 * t * t * t + b;
+  if (t < 1) return c / 2 * t * t * t + b;
   t -= 2;
   return c / 2 * (t * t * t + 2) + b;
 };
@@ -76,8 +107,7 @@ Easings.quarticOut = (t, b, c, d) => {
 };
 Easings.quarticInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return c / 2 * t * t * t * t + b;
+  if (t < 1) return c / 2 * t * t * t * t + b;
   t -= 2;
   return -c / 2 * (t * t * t * t - 2) + b;
 };
@@ -92,8 +122,7 @@ Easings.quinticOut = (t, b, c, d) => {
 };
 Easings.quinticInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return c / 2 * t * t * t * t * t + b;
+  if (t < 1) return c / 2 * t * t * t * t * t + b;
   t -= 2;
   return c / 2 * (t * t * t * t * t + 2) + b;
 };
@@ -114,8 +143,7 @@ Easings.exponentialOut = (t, b, c, d) => {
 };
 Easings.exponentialInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return c / 2 * Math.pow(2, 10 * (t - 1)) + b;
+  if (t < 1) return c / 2 * Math.pow(2, 10 * (t - 1)) + b;
   t--;
   return c / 2 * (-Math.pow(2, -10 * t) + 2) + b;
 };
@@ -130,23 +158,11 @@ Easings.circularOut = (t, b, c, d) => {
 };
 Easings.circularInOut = (t, b, c, d) => {
   t /= d / 2;
-  if (t < 1)
-    return -c / 2 * (Math.sqrt(1 - t * t) - 1) + b;
+  if (t < 1) return -c / 2 * (Math.sqrt(1 - t * t) - 1) + b;
   t -= 2;
   return c / 2 * (Math.sqrt(1 - t * t) + 1) + b;
 };
 
-var M2NodeType = /* @__PURE__ */ ((M2NodeType2) => {
-  M2NodeType2["Node"] = "Node";
-  M2NodeType2["Scene"] = "Scene";
-  M2NodeType2["Sprite"] = "Sprite";
-  M2NodeType2["Label"] = "Label";
-  M2NodeType2["TextLine"] = "TextLine";
-  M2NodeType2["Shape"] = "Shape";
-  M2NodeType2["Composite"] = "Composite";
-  return M2NodeType2;
-})(M2NodeType || {});
-
 var ShapeType = /* @__PURE__ */ ((ShapeType2) => {
   ShapeType2["Undefined"] = "Undefined";
   ShapeType2["Rectangle"] = "Rectangle";
@@ -481,357 +497,234 @@ function rotateRectangle(rect, radians, center) {
   return rotated;
 }
 
-class Action {
-  constructor(runDuringTransition = false) {
-    this.startOffset = -1;
-    this.endOffset = -1;
-    this.started = false;
-    this.running = false;
-    this.completed = false;
-    this.runStartTime = -1;
-    this.duration = 0;
-    this.isParent = false;
-    this.isChild = false;
-    this.runDuringTransition = runDuringTransition;
+class Futurable {
+  constructor(value) {
+    /** The numbers, operators, and other Futurables that represent a value. */
+    this.expression = new Array();
+    /** Log a warning to console if a expression is this length. */
+    this.WARNING_EXPRESSION_LENGTH = 32;
+    if (typeof value === "number") {
+      this.pushToExpression(value);
+      return;
+    }
+    if (value === void 0) {
+      this.pushToExpression(Infinity);
+      return;
+    }
+    this.pushToExpression(value);
   }
   /**
-   * Creates an action that will move a node to a point on the screen.
+   * Appends a number or another Futurable to this Futurable's expression.
    *
-   * @param options - {@link MoveActionOptions}
-   * @returns The move action
+   * @remarks This method does a simple array push, but checks the length of
+   * the expression array and warns if it gets "too long." This may indicate
+   * a logic error, unintended recursion, etc. because our use cases will
+   * likely not have expressions that are longer than
+   * `Futural.WARNING_EXPRESSION_LENGTH` elements.
+   *
+   * @param value - value to add to the expression.
    */
-  static move(options) {
-    return new MoveAction(
-      options.point,
-      options.duration,
-      options.easing ?? Easings.linear,
-      options.runDuringTransition ?? false
-    );
+  pushToExpression(value) {
+    if (value === this) {
+      throw new Error(
+        "Cannot add, subtract, or assign a Futurable with itself."
+      );
+    }
+    this.expression.push(value);
+    if (this.expression.length === this.WARNING_EXPRESSION_LENGTH) {
+      console.warn(
+        `Expression length is ${this.WARNING_EXPRESSION_LENGTH} elements. Something may be wrong.`
+      );
+    }
   }
   /**
-   * Creates an action that will wait a given duration before it is considered complete.
+   * Assigns a value, either known or Futurable, to this Futurable.
    *
-   * @param options - {@link WaitActionOptions}
-   * @returns The wait action
+   * @remarks This method clears the current expression.
+   *
+   * @param value - value to assign to this Futurable.
    */
-  static wait(options) {
-    return new WaitAction(
-      options.duration,
-      options.runDuringTransition ?? false
-    );
+  assign(value) {
+    while (this.expression.length > 0) {
+      this.expression.pop();
+    }
+    this.pushToExpression(value);
   }
   /**
-   * Creates an action that will execute a callback function.
+   * Performs addition on this Futurable.
    *
-   * @param options - {@link CustomActionOptions}
-   * @returns The custom action
+   * @remarks This method modifies the Futurable by adding the term(s) to the
+   * Futurable's expression.
+   *
+   * @param terms - terms to add to this Futurable.
+   * @returns the modified Futurable.
    */
-  static custom(options) {
-    return new CustomAction(
-      options.callback,
-      options.runDuringTransition ?? false
-    );
+  add(...terms) {
+    this.appendOperation(Operator.Add, ...terms);
+    return this;
   }
   /**
-   * Creates an action that will scale the node's size.
+   * Performs subtraction on this Futurable.
    *
-   * @remarks Scaling is relative to any inherited scaling, which is multiplicative. For example, if the node's parent is scaled to 2.0 and this node's action scales to 3.0, then the node will appear 6 times as large as original.
+   * @remarks This method modifies the Futurable by subtracting the term(s)
+   * from the Futurable's expression.
    *
-   * @param options - {@link ScaleActionOptions}
-   * @returns The scale action
+   * @param terms - terms to subtract from this Futurable.
+   * @returns the modified Futurable.
    */
-  static scale(options) {
-    return new ScaleAction(
-      options.scale,
-      options.duration,
-      options.runDuringTransition
-    );
+  subtract(...terms) {
+    this.appendOperation(Operator.Subtract, ...terms);
+    return this;
   }
   /**
-   * Creates an action that will change the node's alpha (opacity).
-   *
-   * @remarks Alpha has multiplicative inheritance. For example, if the node's parent is alpha .5 and this node's action fades alpha to .4, then the node will appear with alpha .2.
+   * Adds an operation (an operator and term(s)) to the Futurable's
+   * expression.
    *
-   * @param options - {@link FadeAlphaActionOptions}
-   * @returns The fadeAlpha action
+   * @param operator - Add or Subtract.
+   * @param terms - terms to add to the expression.
    */
-  static fadeAlpha(options) {
-    return new FadeAlphaAction(
-      options.alpha,
-      options.duration,
-      options.runDuringTransition
-    );
+  appendOperation(operator, ...terms) {
+    terms.forEach((term) => {
+      this.pushToExpression(operator);
+      this.pushToExpression(term);
+    });
   }
   /**
-   * Creates an action that will rotate the node.
+   * Gets the numeric value of this Futurable.
    *
-   * @remarks Rotate actions are applied to their children. In addition to this node's rotate action, all ancestors' rotate actions will also be applied.
+   * @remarks This method evaluates the expression of the Futurable and
+   * returns the numeric value. If any of the terms in the expression are
+   * Futurables, it will recursively evaluate them. If any of the terms are
+   * unknown (represented by Infinity), it will return Infinity.
    *
-   * @param options - {@link RotateActionOptions}
-   * @returns The rotate action
+   * @returns the numeric value of this Futurable.
    */
-  static rotate(options) {
-    if (options.byAngle !== void 0 && options.toAngle !== void 0) {
-      throw new Error("rotate Action: cannot specify both byAngle and toAngle");
-    }
-    if (options.byAngle === void 0 && options.toAngle === void 0) {
-      throw new Error("rotate Action: must specify either byAngle or toAngle");
-    }
-    if (options.toAngle === void 0 && options.shortestUnitArc !== void 0) {
-      throw new Error(
-        "rotate Action: shortestUnitArc can only be specified when toAngle is provided"
-      );
-    }
-    if (options.toAngle !== void 0 && options.shortestUnitArc === void 0) {
-      options.shortestUnitArc = true;
+  get value() {
+    let result = 0;
+    const terms = this.expression.flat(Infinity);
+    let sign = 1;
+    for (let i = 0; i < terms.length; i++) {
+      if (typeof terms[i] === "number") {
+        result = result + sign * terms[i];
+        continue;
+      }
+      if (terms[i] instanceof Futurable) {
+        result = result + sign * terms[i].value;
+        continue;
+      }
+      if (terms[i] === Operator.Add) {
+        sign = 1;
+        continue;
+      }
+      if (terms[i] === Operator.Subtract) {
+        sign = -1;
+        continue;
+      }
     }
-    return new RotateAction(
-      options.byAngle,
-      options.toAngle,
-      options.shortestUnitArc,
-      options.duration,
-      options.runDuringTransition
-    );
+    return result;
+  }
+}
+const Operator = {
+  /** Futurable addition operator  */
+  Add: "Add",
+  /** Futurable subtraction operator  */
+  Subtract: "Subtract"
+};
+
+class Action {
+  constructor(runDuringTransition = false) {
+    this.startOffset = new Futurable(0);
+    this.started = false;
+    this.running = false;
+    this._completed = false;
+    /**
+     * Start time of a running action is always known; it is not a `Futurable`.
+     * -1 indicates that the root action has not yet started running.
+     */
+    this.runStartTime = -1;
+    this.duration = new Futurable();
+    this.runDuringTransition = runDuringTransition;
   }
   /**
-   * Creates an array of actions that will be run in order.
+   * Prepares the Action for evaluation.
    *
-   * @remarks The next action will not begin until the current one has finished. The sequence will be considered completed when the last action has completed.
+   * @remarks Calculates start times for all actions in the hierarchy
+   * and returns a copy of the action that is prepared for evaluation during
+   * the update loop.
    *
-   * @param actions - One or more actions that form the sequence
-   * @returns
+   * @param key - optional string to identify an action
+   * @returns action prepared for evaluation
    */
-  static sequence(actions) {
-    const sequence = new SequenceAction(actions);
-    sequence.children = actions;
-    return sequence;
+  initialize(key) {
+    const action = this.clone();
+    this.assignParents(action, action, key);
+    this.propagateRunDuringTransition(action);
+    this.assignDurations(action);
+    this.assignStartOffsets(action);
+    return action;
   }
   /**
-   * Create an array of actions that will be run simultaneously.
-   *
-   * @remarks All actions within the group will begin to run at the same time. The group will be considered completed when the longest-running action has completed.
+   * Parses the action hierarchy and assigns each action its parent and
+   * root action.
    *
-   * @param actions - One or more actions that form the group
-   * @returns
+   * @remarks Uses recursion to handle arbitrary level of nesting parent
+   * actions within parent actions. When this method is called from the
+   * `initialize()` method, the root action is both the `action` and the
+   * `rootAction`. This is because the action is the top-level action in the
+   * hierarchy. When the method calls itself recursively, the `rootAction`
+   * remains the same, but the `action` is a child action or the action of a
+   * repeating action.
+   *
+   * @param action - the action to assign parents to
+   * @param rootAction - top-level action passed to the run method
+   * @param key - optional string to identify an action. The key is assigned
+   * to every action in the hierarchy.
    */
-  static group(actions) {
-    const group = new GroupAction(actions);
-    group.children = actions;
-    return group;
-  }
-  initialize(node, key) {
-    this.assignParents(this, this, key);
-    const actions = this.flattenActions(this);
-    actions.forEach(
-      (action) => action.duration = this.calculateDuration(action)
-    );
-    this.calculateStartEndOffsets(this);
-    const clonedActions = actions.filter(
-      (action) => action.type !== ActionType.Group && action.type !== ActionType.Sequence
-    ).map((action) => {
-      return Action.cloneAction(action, key);
-    });
-    return clonedActions;
-  }
-  static cloneAction(action, key) {
-    let cloned;
-    switch (action.type) {
-      case ActionType.Sequence: {
-        const sequence = action;
-        const sequenceChildren = sequence.children.map(
-          (child) => Action.cloneAction(child, key)
-        );
-        cloned = Action.sequence(sequenceChildren);
-        break;
-      }
-      case ActionType.Group: {
-        const group = action;
-        const groupChildren = group.children.map(
-          (child) => Action.cloneAction(child, key)
-        );
-        cloned = Action.sequence(groupChildren);
-        break;
-      }
-      case ActionType.Move: {
-        const move = action;
-        cloned = Action.move({
-          point: move.point,
-          duration: move.duration,
-          easing: move.easing,
-          runDuringTransition: move.runDuringTransition
-        });
-        break;
-      }
-      case ActionType.Custom: {
-        const code = action;
-        cloned = Action.custom({
-          callback: code.callback,
-          runDuringTransition: code.runDuringTransition
-        });
-        break;
-      }
-      case ActionType.Scale: {
-        const scale = action;
-        cloned = Action.scale({
-          scale: scale.scale,
-          duration: scale.duration,
-          runDuringTransition: scale.runDuringTransition
-        });
-        break;
-      }
-      case ActionType.FadeAlpha: {
-        const fadeAlpha = action;
-        cloned = Action.fadeAlpha({
-          alpha: fadeAlpha.alpha,
-          duration: fadeAlpha.duration,
-          runDuringTransition: fadeAlpha.runDuringTransition
-        });
-        break;
-      }
-      case ActionType.Rotate: {
-        const rotate = action;
-        cloned = Action.rotate({
-          byAngle: rotate.byAngle,
-          toAngle: rotate.toAngle,
-          shortestUnitArc: rotate.shortestUnitArc,
-          duration: rotate.duration,
-          runDuringTransition: rotate.runDuringTransition
-        });
-        break;
-      }
-      case ActionType.Wait: {
-        const wait = action;
-        cloned = Action.wait({
-          duration: wait.duration,
-          runDuringTransition: wait.runDuringTransition
-        });
-        break;
-      }
-      default:
-        throw new Error("unknown action");
-    }
+  assignParents(action, rootAction, key) {
     if (key !== void 0) {
-      cloned.key = key;
-    }
-    cloned.startOffset = action.startOffset;
-    cloned.endOffset = action.endOffset;
-    return cloned;
-  }
-  static evaluateAction(action, node, now, dt) {
-    if (now < action.runStartTime + action.startOffset) {
-      return;
-    }
-    if (now >= action.runStartTime + action.startOffset && now <= action.runStartTime + action.startOffset + action.duration) {
-      action.running = true;
-    } else {
-      action.running = false;
-    }
-    if (action.running === false && action.completed === true) {
-      return;
-    }
-    const elapsed = now - (action.runStartTime + action.startOffset);
-    if (action.type === ActionType.Custom) {
-      const customAction = action;
-      customAction.callback();
-      customAction.running = false;
-      customAction.completed = true;
-    }
-    if (action.type === ActionType.Wait) {
-      const waitAction = action;
-      if (now > action.runStartTime + action.startOffset + action.duration) {
-        waitAction.running = false;
-        waitAction.completed = true;
-      }
-    }
-    if (action.type === ActionType.Move) {
-      const moveAction = action;
-      if (!moveAction.started) {
-        moveAction.dx = moveAction.point.x - node.position.x;
-        moveAction.dy = moveAction.point.y - node.position.y;
-        moveAction.startPoint.x = node.position.x;
-        moveAction.startPoint.y = node.position.y;
-        moveAction.started = true;
-      }
-      if (elapsed < moveAction.duration) {
-        node.position.x = moveAction.easing(
-          elapsed,
-          moveAction.startPoint.x,
-          moveAction.dx,
-          moveAction.duration
-        );
-        node.position.y = moveAction.easing(
-          elapsed,
-          moveAction.startPoint.y,
-          moveAction.dy,
-          moveAction.duration
-        );
-      } else {
-        node.position.x = moveAction.point.x;
-        node.position.y = moveAction.point.y;
-        moveAction.running = false;
-        moveAction.completed = true;
-      }
+      action.key = key;
     }
-    if (action.type === ActionType.Scale) {
-      const scaleAction = action;
-      if (!scaleAction.started) {
-        scaleAction.delta = scaleAction.scale - node.scale;
-        scaleAction.started = true;
-      }
-      if (elapsed < scaleAction.duration) {
-        node.scale = node.scale + scaleAction.delta * (dt / scaleAction.duration);
-      } else {
-        node.scale = scaleAction.scale;
-        scaleAction.running = false;
-        scaleAction.completed = true;
-      }
+    if (this.isParent(action)) {
+      const children = action.children;
+      children.forEach((child) => {
+        child.parent = action;
+      });
+      children.filter((child) => this.isParent(child)).forEach((child) => this.assignParents(child, rootAction, key));
     }
-    if (action.type === ActionType.FadeAlpha) {
-      const fadeAlphaAction = action;
-      if (!fadeAlphaAction.started) {
-        fadeAlphaAction.delta = fadeAlphaAction.alpha - node.alpha;
-        fadeAlphaAction.started = true;
-      }
-      if (elapsed < fadeAlphaAction.duration) {
-        node.alpha = node.alpha + fadeAlphaAction.delta * (dt / fadeAlphaAction.duration);
-      } else {
-        node.alpha = fadeAlphaAction.alpha;
-        fadeAlphaAction.running = false;
-        fadeAlphaAction.completed = true;
+  }
+  /**
+   * Sets the runDuringTransition property based on descendants.
+   *
+   * @remarks This ensures that a parent action has its `runDuringTransition`
+   * property set to true if any of its descendants have their
+   * `runDuringTransition` property set to true. Parent actions do not have a
+   * way for the user to set this property directly; it is inferred (propagated
+   * up) from the descendants.
+   *
+   * @param action to propagate runDuringTransition property to
+   */
+  propagateRunDuringTransition(action) {
+    if (this.isParent(action)) {
+      if (action.descendants.some((child) => child.runDuringTransition)) {
+        action.runDuringTransition = true;
       }
+      action.children.forEach(
+        (child) => this.propagateRunDuringTransition(child)
+      );
     }
-    if (action.type === ActionType.Rotate) {
-      const rotateAction = action;
-      if (!rotateAction.started) {
-        if (rotateAction.byAngle !== void 0) {
-          rotateAction.delta = rotateAction.byAngle;
-        }
-        if (rotateAction.toAngle !== void 0) {
-          rotateAction.toAngle = M2c2KitHelpers.normalizeAngleRadians(
-            rotateAction.toAngle
-          );
-          node.zRotation = M2c2KitHelpers.normalizeAngleRadians(node.zRotation);
-          rotateAction.delta = rotateAction.toAngle - node.zRotation;
-          if (rotateAction.shortestUnitArc === true && Math.abs(rotateAction.delta) > Math.PI) {
-            rotateAction.delta = 2 * Math.PI - Math.abs(rotateAction.delta);
-          }
-        }
-        rotateAction.started = true;
-        rotateAction.finalValue = node.zRotation + rotateAction.delta;
-      }
-      if (elapsed < rotateAction.duration) {
-        node.zRotation = node.zRotation + rotateAction.delta * (dt / rotateAction.duration);
-        if (rotateAction.delta <= 0 && node.zRotation < rotateAction.finalValue) {
-          node.zRotation = rotateAction.finalValue;
-        }
-        if (rotateAction.delta > 0 && node.zRotation > rotateAction.finalValue) {
-          node.zRotation = rotateAction.finalValue;
-        }
-      } else {
-        node.zRotation = rotateAction.finalValue;
-        rotateAction.running = false;
-        rotateAction.completed = true;
-      }
+  }
+  /**
+   * Assigns durations to all actions in the hierarchy.
+   *
+   * @remarks Uses recursion to handle arbitrary level of nesting parent
+   * actions within parent actions.
+   *
+   * @param action - the action to assign durations to
+   */
+  assignDurations(action) {
+    action.duration = this.calculateDuration(action);
+    if (this.isParent(action)) {
+      action.children.forEach((child) => this.assignDurations(child));
     }
   }
   /**
@@ -848,106 +741,553 @@ class Action {
     if (action.type === ActionType.Group) {
       const groupAction = action;
       const duration = groupAction.children.map((child) => this.calculateDuration(child)).reduce((max, dur) => {
-        return Math.max(max, dur);
+        return Math.max(max, dur.value);
       }, 0);
-      return duration;
+      return new Futurable(duration);
     }
     if (action.type === ActionType.Sequence) {
       const sequenceAction = action;
       const duration = sequenceAction.children.map((child) => this.calculateDuration(child)).reduce((sum, dur) => {
-        return sum + dur;
+        return sum + dur.value;
       }, 0);
-      return duration;
+      return new Futurable(duration);
+    }
+    if (this.isRepeating(action)) {
+      return new Futurable();
     }
     return action.duration;
   }
   /**
-   * Update each action's start and end offsets.
+   * Assigns start offsets to all actions in the hierarchy.
    *
    * @remarks Uses recursion to handle arbitrary level of nesting parent
    * actions within parent actions.
    *
-   * @param action that needs assigning start and end offsets
+   * @param action - the action to assign start offsets to
    */
-  calculateStartEndOffsets(action) {
-    let parentStartOffset;
-    if (action.parent === void 0) {
-      parentStartOffset = 0;
-    } else {
-      parentStartOffset = action.parent.startOffset;
-    }
-    if (action.parent?.type === ActionType.Group) {
-      action.startOffset = parentStartOffset;
-      action.endOffset = action.startOffset + action.duration;
-    } else if (action.parent?.type === ActionType.Sequence) {
-      const parent = action.parent;
-      let dur = 0;
-      for (const a of parent.children) {
-        if (a === action) {
-          break;
-        }
-        dur = dur + a.duration;
-      }
-      action.startOffset = parentStartOffset + dur;
-      action.endOffset = action.startOffset + action.duration;
-    } else {
-      action.startOffset = 0;
-      action.endOffset = action.startOffset + action.duration;
-    }
-    if (action.isParent) {
-      action.children?.forEach(
-        (child) => this.calculateStartEndOffsets(child)
-      );
+  assignStartOffsets(action) {
+    action.startOffset = this.calculateStartOffset(action);
+    if (this.isParent(action)) {
+      action.children.forEach((child) => this.assignStartOffsets(child));
     }
   }
   /**
-   * Takes an action hierarchy and flattens to an array of non-nested actions
+   * Calculates the start offset. This is when an action should start,
+   * relative to the start time of its parent (if it has a parent).
    *
-   * @remarks Uses recursion to handle arbitrary level of nesting parent
-   * actions within parent actions
-   *
-   * @param action - the action to flatten
-   * @param actions - the accumulator array of flattened actions. This will be
-   * undefined on the first call, and an array on recursive calls
-   * @returns flattened array of actions
+   * @param action - the action to calculate the start offset for
+   * @returns the start offset as a Futurable
    */
-  flattenActions(action, actions) {
-    if (!actions) {
-      actions = new Array();
-      actions.push(action);
+  calculateStartOffset(action) {
+    if (action.parent === void 0) {
+      return new Futurable(0);
     }
-    if (action.isParent) {
-      const parent = action;
-      const children = parent.children;
-      actions.push(...children);
-      parent.children.filter((child) => child.isParent).forEach((child) => this.flattenActions(child, actions));
+    if (action.parent.type !== ActionType.Sequence) {
+      return action.parent.startOffset;
     }
-    return actions;
+    const startOffset = new Futurable(0);
+    startOffset.add(action.parent.startOffset);
+    for (const siblingAction of action.parent.children) {
+      if (siblingAction === action) {
+        break;
+      }
+      startOffset.add(siblingAction.duration);
+    }
+    return startOffset;
   }
   /**
-   * Parses the action hierarchy and assigns each action its parent and
-   * root action.
+   * Evaluates an action, updating the node's properties as needed.
+   *
+   * @remarks This method is called every frame by the M2Node's `update()`
+   * method.
+   *
+   * @param action - the Action to be evaluated and possibly run
+   * @param node - the `M2Node` that the action will be run on
+   * @param now - the current elapsed time, from `performance.now()`
+   * @param dt - the time since the last frame (delta time)
+   */
+  static evaluateAction(action, node, now, dt) {
+    if (node.involvedInSceneTransition() && !action.runDuringTransition) {
+      return;
+    }
+    if (action.runStartTime === -1) {
+      action.assignRunStartTimes(action, now);
+    }
+    if (now < action.runStartTime + action.startOffset.value) {
+      return;
+    }
+    if (action.shouldBeRunning(now)) {
+      action.running = true;
+    }
+    if (action.isParent(action)) {
+      action.children.forEach((child) => {
+        Action.evaluateAction(child, node, now, dt);
+      });
+      if (!action.isRepeating(action)) {
+        if (!action.started) {
+          action.started = true;
+        }
+        if (action.running && action.completed) {
+          action.running = false;
+        }
+        return;
+      }
+      Action.evaluateRepeatingActions(action, now);
+      return;
+    }
+    if (!action.shouldBeRunning(now)) {
+      action.running = false;
+    }
+    if (action.running === false && action.completed === true) {
+      return;
+    }
+    const elapsed = now - (action.runStartTime + action.startOffset.value);
+    switch (action.type) {
+      case ActionType.Custom:
+        Action.evaluateCustomAction(action);
+        break;
+      case ActionType.Play:
+        Action.evaluatePlayAction(node, action);
+        break;
+      case ActionType.Wait:
+        Action.evaluateWaitAction(action, now);
+        break;
+      case ActionType.Move:
+        Action.evaluateMoveAction(action, node, elapsed);
+        break;
+      case ActionType.Scale:
+        Action.evaluateScaleAction(action, node, elapsed, dt);
+        break;
+      case ActionType.FadeAlpha:
+        Action.evaluateFadeAlphaAction(action, node, elapsed, dt);
+        break;
+      case ActionType.Rotate:
+        Action.evaluateRotateAction(action, node, elapsed, dt);
+        break;
+      default:
+        throw new Error(`Action type not recognized: ${action.type}`);
+    }
+  }
+  static evaluateRepeatingActions(action, now) {
+    if (!action.started) {
+      action.started = true;
+    }
+    if (action.repetitionHasCompleted) {
+      action.completedRepetitions++;
+      const repetitionDuration = action.children[0].duration.value;
+      action.cumulativeDuration = action.cumulativeDuration + repetitionDuration;
+      if (!isFinite(repetitionDuration)) {
+        throw "repetitionDuration is not finite";
+      }
+      if (!action.completed) {
+        action.restartAction(action, now);
+      } else {
+        if (action.type === ActionType.RepeatForever) {
+          throw new Error("RepeatForever action should never complete");
+        }
+        action.duration.assign(action.cumulativeDuration);
+        action.running = false;
+      }
+    }
+  }
+  static evaluateRotateAction(action, node, elapsed, dt) {
+    const rotateAction = action;
+    if (!rotateAction.started) {
+      if (rotateAction.byAngle !== void 0) {
+        rotateAction.delta = rotateAction.byAngle;
+      }
+      if (rotateAction.toAngle !== void 0) {
+        rotateAction.toAngle = M2c2KitHelpers.normalizeAngleRadians(
+          rotateAction.toAngle
+        );
+        node.zRotation = M2c2KitHelpers.normalizeAngleRadians(node.zRotation);
+        rotateAction.delta = rotateAction.toAngle - node.zRotation;
+        if (rotateAction.shortestUnitArc === true && Math.abs(rotateAction.delta) > Math.PI) {
+          rotateAction.delta = 2 * Math.PI - Math.abs(rotateAction.delta);
+        }
+      }
+      rotateAction.started = true;
+      rotateAction.finalValue = node.zRotation + rotateAction.delta;
+    }
+    if (elapsed < rotateAction.duration.value) {
+      node.zRotation = node.zRotation + rotateAction.delta * (dt / rotateAction.duration.value);
+      if (rotateAction.delta <= 0 && node.zRotation < rotateAction.finalValue) {
+        node.zRotation = rotateAction.finalValue;
+      }
+      if (rotateAction.delta > 0 && node.zRotation > rotateAction.finalValue) {
+        node.zRotation = rotateAction.finalValue;
+      }
+    } else {
+      node.zRotation = rotateAction.finalValue;
+      rotateAction.running = false;
+      rotateAction.completed = true;
+    }
+  }
+  static evaluateFadeAlphaAction(action, node, elapsed, dt) {
+    const fadeAlphaAction = action;
+    if (!fadeAlphaAction.started) {
+      fadeAlphaAction.delta = fadeAlphaAction.alpha - node.alpha;
+      fadeAlphaAction.started = true;
+    }
+    if (elapsed < fadeAlphaAction.duration.value) {
+      node.alpha = node.alpha + fadeAlphaAction.delta * (dt / fadeAlphaAction.duration.value);
+    } else {
+      node.alpha = fadeAlphaAction.alpha;
+      fadeAlphaAction.running = false;
+      fadeAlphaAction.completed = true;
+    }
+  }
+  static evaluateScaleAction(action, node, elapsed, dt) {
+    const scaleAction = action;
+    if (!scaleAction.started) {
+      scaleAction.delta = scaleAction.scale - node.scale;
+      scaleAction.started = true;
+    }
+    if (elapsed < scaleAction.duration.value) {
+      node.scale = node.scale + scaleAction.delta * (dt / scaleAction.duration.value);
+    } else {
+      node.scale = scaleAction.scale;
+      scaleAction.running = false;
+      scaleAction.completed = true;
+    }
+  }
+  static evaluateMoveAction(action, node, elapsed) {
+    const moveAction = action;
+    if (!moveAction.started) {
+      moveAction.dx = moveAction.point.x - node.position.x;
+      moveAction.dy = moveAction.point.y - node.position.y;
+      moveAction.startPoint.x = node.position.x;
+      moveAction.startPoint.y = node.position.y;
+      moveAction.started = true;
+    }
+    if (elapsed < moveAction.duration.value) {
+      node.position.x = moveAction.easing(
+        elapsed,
+        moveAction.startPoint.x,
+        moveAction.dx,
+        moveAction.duration.value
+      );
+      node.position.y = moveAction.easing(
+        elapsed,
+        moveAction.startPoint.y,
+        moveAction.dy,
+        moveAction.duration.value
+      );
+    } else {
+      node.position.x = moveAction.point.x;
+      node.position.y = moveAction.point.y;
+      moveAction.running = false;
+      moveAction.completed = true;
+    }
+  }
+  static evaluateWaitAction(action, now) {
+    const waitAction = action;
+    if (now > action.runStartTime + action.startOffset.value + action.duration.value) {
+      waitAction.running = false;
+      waitAction.completed = true;
+    }
+  }
+  static evaluatePlayAction(node, action) {
+    if (node.type !== M2NodeType.SoundPlayer) {
+      throw new Error("Play action can only be used with a SoundPlayer");
+    }
+    const playAction = action;
+    const soundPlayer = node;
+    const soundManager = soundPlayer.game.soundManager;
+    if (!playAction.started) {
+      const m2Sound = soundManager.getSound(soundPlayer.soundName);
+      if (m2Sound.audioBuffer) {
+        const source = soundManager.audioContext.createBufferSource();
+        source.buffer = m2Sound.audioBuffer;
+        source.onended = () => {
+          playAction.running = false;
+          playAction.completed = true;
+          const knownDuration = performance.now() - (action.runStartTime + action.startOffset.value);
+          action.duration.assign(knownDuration);
+        };
+        source.connect(soundManager.audioContext.destination);
+        source.start();
+        playAction.started = true;
+      } else {
+        if (m2Sound.status === M2SoundStatus.Error) {
+          throw new Error(
+            `error loading sound ${m2Sound.soundName} (url ${m2Sound.url})`
+          );
+        }
+        console.warn(
+          `Play action: audio buffer not ready for sound ${soundPlayer.soundName} (url: ${m2Sound.url}); will try next frame`
+        );
+        if (m2Sound.status === M2SoundStatus.Deferred) {
+          soundManager.fetchDeferredSound(m2Sound);
+        }
+      }
+    }
+  }
+  static evaluateCustomAction(action) {
+    const customAction = action;
+    customAction.callback();
+    customAction.running = false;
+    customAction.completed = true;
+  }
+  /**
+   * Assigns RunStartTime to all actions in the hierarchy.
    *
    * @remarks Uses recursion to handle arbitrary level of nesting parent
-   * actions within parent actions
+   * actions within parent actions.
    *
-   * @param action
-   * @param rootAction - top-level action passed to the run method
-   * @param key - optional string to identify an action
+   * @param action - the action to assign RunStartTime to
    */
-  assignParents(action, rootAction, key) {
-    if (key !== void 0) {
-      action.key = key;
+  assignRunStartTimes(action, runStartTime) {
+    action.runStartTime = runStartTime;
+    if (action.isParent(action)) {
+      action.children.forEach((child) => {
+        action.assignRunStartTimes(child, runStartTime);
+      });
     }
-    if (action.isParent) {
-      const parent = action;
-      const children = parent.children;
-      children.forEach((child) => {
-        child.parent = action;
-        child.isChild = true;
+  }
+  /**
+   * Configures action to be run again.
+   *
+   * @remarks This method is called on a repeating action's children when they
+   * need to be run again.
+   *
+   * @param action - action to restart
+   * @param now - current time
+   */
+  restartAction(action, now) {
+    action.runStartTime = now;
+    action.running = true;
+    action.started = true;
+    if (action.type === ActionType.Play) {
+      action.duration = new Futurable();
+    }
+    if (action.isParent(action)) {
+      action.children.forEach((child) => {
+        action.restartAction(child, now);
       });
-      parent.children.filter((child) => child.isParent).forEach((child) => this.assignParents(child, rootAction, key));
+      return;
     }
+    action.completed = false;
+  }
+  /**
+   * Determines if the action should be running.
+   *
+   * @remarks An action should be running if current time is in the interval
+   * [ start time + start offset, start time + start offset + duration ]
+   *
+   * @param now - current time
+   * @returns true if the action should be running
+   */
+  shouldBeRunning(now) {
+    return now >= this.runStartTime + this.startOffset.value && now <= this.runStartTime + this.startOffset.value + this.duration.value;
+  }
+  /**
+   * Creates an action that will move a node to a point on the screen.
+   *
+   * @param options - {@link MoveActionOptions}
+   * @returns The move action
+   */
+  static move(options) {
+    return new MoveAction(
+      options.point,
+      new Futurable(options.duration),
+      options.easing ?? Easings.linear,
+      options.runDuringTransition ?? false
+    );
+  }
+  /**
+   * Creates an action that will wait a given duration before it is considered
+   * complete.
+   *
+   * @param options - {@link WaitActionOptions}
+   * @returns The wait action
+   */
+  static wait(options) {
+    return new WaitAction(
+      new Futurable(options.duration),
+      options.runDuringTransition ?? false
+    );
+  }
+  /**
+   * Creates an action that will execute a callback function.
+   *
+   * @param options - {@link CustomActionOptions}
+   * @returns The custom action
+   */
+  static custom(options) {
+    return new CustomAction(
+      options.callback,
+      options.runDuringTransition ?? false
+    );
+  }
+  /**
+   * Creates an action that will play a sound.
+   *
+   * @remarks This action can only be used with a SoundPlayer node.
+   * It will throw an error if used with any other node type.
+   *
+   * @param options - {@link PlayActionOptions}
+   * @returns The play action
+   */
+  static play(options) {
+    return new PlayAction(options?.runDuringTransition ?? false);
+  }
+  /**
+   * Creates an action that will scale the node's size.
+   *
+   * @remarks Scaling is relative to any inherited scaling, which is
+   * multiplicative. For example, if the node's parent is scaled to 2.0 and
+   * this node's action scales to 3.0, then the node will appear 6 times as
+   * large as original.
+   *
+   * @param options - {@link ScaleActionOptions}
+   * @returns The scale action
+   */
+  static scale(options) {
+    return new ScaleAction(
+      options.scale,
+      new Futurable(options.duration),
+      options.runDuringTransition
+    );
+  }
+  /**
+   * Creates an action that will change the node's alpha (opacity).
+   *
+   * @remarks Alpha has multiplicative inheritance. For example, if the node's
+   * parent is alpha .5 and this node's action fades alpha to .4, then the
+   * node will appear with alpha .2.
+   *
+   * @param options - {@link FadeAlphaActionOptions}
+   * @returns The fadeAlpha action
+   */
+  static fadeAlpha(options) {
+    return new FadeAlphaAction(
+      options.alpha,
+      new Futurable(options.duration),
+      options.runDuringTransition
+    );
+  }
+  /**
+   * Creates an action that will rotate the node.
+   *
+   * @remarks Rotate actions are applied to their children. In addition to this
+   * node's rotate action, all ancestors' rotate actions will also be applied.
+   *
+   * @param options - {@link RotateActionOptions}
+   * @returns The rotate action
+   */
+  static rotate(options) {
+    if (options.byAngle !== void 0 && options.toAngle !== void 0) {
+      throw new Error("rotate Action: cannot specify both byAngle and toAngle");
+    }
+    if (options.byAngle === void 0 && options.toAngle === void 0) {
+      throw new Error("rotate Action: must specify either byAngle or toAngle");
+    }
+    if (options.toAngle === void 0 && options.shortestUnitArc !== void 0) {
+      throw new Error(
+        "rotate Action: shortestUnitArc can only be specified when toAngle is provided"
+      );
+    }
+    if (options.toAngle !== void 0 && options.shortestUnitArc === void 0) {
+      options.shortestUnitArc = true;
+    }
+    return new RotateAction(
+      options.byAngle,
+      options.toAngle,
+      options.shortestUnitArc,
+      new Futurable(options.duration),
+      options.runDuringTransition
+    );
+  }
+  /**
+   * Creates an array of actions that will be run in order.
+   *
+   * @remarks The next action will not begin until the current one has
+   * finished. The sequence will be considered completed when the last action
+   * has completed.
+   *
+   * @param actions - One or more actions that form the sequence
+   * @returns
+   */
+  static sequence(actions) {
+    const sequence = new SequenceAction(actions);
+    sequence.children = actions;
+    return sequence;
+  }
+  /**
+   * Create an array of actions that will be run simultaneously.
+   *
+   * @remarks All actions within the group will begin to run at the same time.
+   * The group will be considered completed when the longest-running action
+   * has completed.
+   *
+   * @param actions - One or more actions that form the group
+   * @returns
+   */
+  static group(actions) {
+    const group = new GroupAction(actions);
+    group.children = actions;
+    return group;
+  }
+  /**
+   * Creates an action that will repeat another action a given number of times.
+   *
+   * @param options - {@link RepeatActionOptions}
+   * @returns The repeat action
+   */
+  static repeat(options) {
+    return new RepeatAction(
+      options.action,
+      options.count,
+      options.runDuringTransition
+    );
+  }
+  /**
+   * Creates an action that will repeat another action forever.
+   *
+   * @remarks A repeat forever action is a special case of a repeat action
+   * where the count is set to infinity.
+   *
+   * @param options - {@link RepeatForeverActionOptions}
+   * @returns The repeat forever action
+   */
+  static repeatForever(options) {
+    return new RepeatForeverAction(options.action, options.runDuringTransition);
+  }
+  /**
+   * Type guard that returns true if the action is a parent action.
+   *
+   * @remarks Parent actions are Group, Sequence, Repeat, and RepeatForever
+   * actions.
+   *
+   * @param action - action to check
+   * @returns true if the action is a parent action
+   */
+  isParent(action) {
+    return action.type === ActionType.Group || action.type === ActionType.Sequence || action.type === ActionType.Repeat || action.type === ActionType.RepeatForever;
+  }
+  /**
+   * Type guard that returns true if the action can repeat.
+   *
+   * @remarks Repeating actions are Repeat and RepeatForever actions.
+   *
+   * @param action - action to check
+   * @returns true if the action is a RepeatAction or RepeatForeverAction
+   */
+  isRepeating(action) {
+    return action.type === ActionType.Repeat || action.type === ActionType.RepeatForever;
+  }
+  // Note: use getter and setter for completed property because we override
+  // them in SequenceAction, GroupAction, RepeatAction, and
+  // RepeatForeverAction.
+  /**
+   * Indicates whether the action has completed.
+   */
+  get completed() {
+    return this._completed;
+  }
+  set completed(value) {
+    this._completed = value;
   }
 }
 class SequenceAction extends Action {
@@ -955,7 +1295,25 @@ class SequenceAction extends Action {
     super();
     this.type = ActionType.Sequence;
     this.children = actions;
-    this.isParent = true;
+  }
+  clone() {
+    const clonedChildren = this.children.map((child) => child.clone());
+    const clonedAction = Action.sequence(clonedChildren);
+    clonedAction.children.forEach((child) => child.key = this.key);
+    clonedAction.key = this.key;
+    return clonedAction;
+  }
+  /**
+   * Indicates whether the action has completed, taking into account all its
+   * child actions.
+   *
+   * @remarks Is read-only for parent actions.
+   */
+  get completed() {
+    return this.children.every((child) => child.completed);
+  }
+  get descendants() {
+    return getParentActionDescendants(this);
   }
 }
 class GroupAction extends Action {
@@ -964,16 +1322,137 @@ class GroupAction extends Action {
     this.type = ActionType.Group;
     this.children = new Array();
     this.children = actions;
-    this.isParent = true;
+  }
+  clone() {
+    const clonedChildren = this.children.map((child) => child.clone());
+    const clonedAction = Action.group(clonedChildren);
+    clonedAction.children.forEach((child) => child.key = this.key);
+    clonedAction.key = this.key;
+    return clonedAction;
+  }
+  /**
+   * Indicates whether the action has completed, taking into account all its
+   * child actions.
+   *
+   * @remarks Is read-only for parent actions.
+   */
+  get completed() {
+    return this.children.every((child) => child.completed);
+  }
+  get descendants() {
+    return getParentActionDescendants(this);
+  }
+}
+class RepeatAction extends Action {
+  constructor(action, count, runDuringTransition = false) {
+    super(runDuringTransition);
+    this.type = ActionType.Repeat;
+    this.completedRepetitions = 0;
+    this.cumulativeDuration = 0;
+    this.children = [action];
+    this.count = count;
+    this.duration = new Futurable();
+  }
+  clone() {
+    if (this.children.length !== 1) {
+      throw new Error("Repeat action must have exactly one child");
+    }
+    const clonedAction = Action.repeat({
+      // RepeatAction always has exactly one child
+      action: this.children[0].clone(),
+      count: this.count,
+      runDuringTransition: this.runDuringTransition
+    });
+    clonedAction.children[0].key = this.key;
+    clonedAction.key = this.key;
+    return clonedAction;
+  }
+  /**
+   * Indicates whether the action has completed, taking into account all its
+   * child actions and the number of repetitions.
+   *
+   * @remarks Is read-only for parent actions.
+   */
+  get completed() {
+    return this.children.every((child) => child.completed) && this.completedRepetitions === this.count;
+  }
+  get descendantsAreCompleted() {
+    return this.children.every((child) => child.completed);
+  }
+  /**
+   * Indicates whether a single repetition of a repeating action has just
+   * completed.
+   *
+   * @returns returns true if a repetition has completed
+   */
+  get repetitionHasCompleted() {
+    return this.running && this.descendantsAreCompleted && !this.completed;
+  }
+  get descendants() {
+    return getParentActionDescendants(this);
+  }
+}
+class RepeatForeverAction extends RepeatAction {
+  constructor(action, runDuringTransition = false) {
+    super(action, Infinity, runDuringTransition);
+    this.type = ActionType.RepeatForever;
+    this.count = Infinity;
+  }
+  clone() {
+    if (this.children.length !== 1) {
+      throw new Error("RepeatForever action must have exactly one child");
+    }
+    const clonedAction = Action.repeatForever({
+      // RepeatForeverAction always has exactly one child
+      action: this.children[0].clone(),
+      runDuringTransition: this.runDuringTransition
+    });
+    clonedAction.children[0].key = this.key;
+    clonedAction.key = this.key;
+    return clonedAction;
   }
 }
+function getParentActionDescendants(parentAction) {
+  const descendants = [];
+  function traverse(action) {
+    if (action.isParent(action)) {
+      for (const child of action.children) {
+        descendants.push(child);
+        traverse(child);
+      }
+    }
+  }
+  traverse(parentAction);
+  return descendants;
+}
 class CustomAction extends Action {
   constructor(callback, runDuringTransition = false) {
     super(runDuringTransition);
     this.type = ActionType.Custom;
     this.callback = callback;
-    this.isParent = false;
-    this.duration = 0;
+    this.duration = new Futurable(0);
+  }
+  clone() {
+    const cloned = Action.custom({
+      callback: this.callback,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
+  }
+}
+class PlayAction extends Action {
+  constructor(runDuringTransition = false) {
+    super(runDuringTransition);
+    this.type = ActionType.Play;
+    this.duration = new Futurable();
+  }
+  clone() {
+    const cloned = Action.play({
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
   }
 }
 class WaitAction extends Action {
@@ -981,21 +1460,37 @@ class WaitAction extends Action {
     super(runDuringTransition);
     this.type = ActionType.Wait;
     this.duration = duration;
-    this.isParent = false;
+  }
+  clone() {
+    const cloned = Action.wait({
+      duration: this.duration.value,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
   }
 }
 class MoveAction extends Action {
   constructor(point, duration, easing, runDuringTransition) {
     super(runDuringTransition);
     this.type = ActionType.Move;
+    this.startPoint = { x: NaN, y: NaN };
     this.dx = 0;
     this.dy = 0;
     this.duration = duration;
     this.point = point;
-    this.isParent = false;
-    this.startPoint = { x: NaN, y: NaN };
     this.easing = easing;
   }
+  clone() {
+    const cloned = Action.move({
+      point: this.point,
+      duration: this.duration.value,
+      easing: this.easing,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
+  }
 }
 class ScaleAction extends Action {
   constructor(scale, duration, runDuringTransition = false) {
@@ -1004,7 +1499,15 @@ class ScaleAction extends Action {
     this.delta = 0;
     this.duration = duration;
     this.scale = scale;
-    this.isParent = false;
+  }
+  clone() {
+    const cloned = Action.scale({
+      scale: this.scale,
+      duration: this.duration.value,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
   }
 }
 class FadeAlphaAction extends Action {
@@ -1014,7 +1517,15 @@ class FadeAlphaAction extends Action {
     this.delta = 0;
     this.duration = duration;
     this.alpha = alpha;
-    this.isParent = false;
+  }
+  clone() {
+    const cloned = Action.fadeAlpha({
+      alpha: this.alpha,
+      duration: this.duration.value,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
   }
 }
 class RotateAction extends Action {
@@ -1027,7 +1538,17 @@ class RotateAction extends Action {
     this.byAngle = byAngle;
     this.toAngle = toAngle;
     this.shortestUnitArc = shortestUnitArc;
-    this.isParent = false;
+  }
+  clone() {
+    const cloned = Action.rotate({
+      byAngle: this.byAngle,
+      toAngle: this.toAngle,
+      shortestUnitArc: this.shortestUnitArc,
+      duration: this.duration.value,
+      runDuringTransition: this.runDuringTransition
+    });
+    cloned.key = this.key;
+    return cloned;
   }
 }
 
@@ -1482,6 +2003,25 @@ class Uuid {
       );
     }
   }
+  /**
+   * Tests if a string is a valid UUID.
+   *
+   * @remarks Will match UUID versions 1 through 8, plus the nil UUID.
+   *
+   * @param uuid - the string to test
+   * @returns true if the string is a valid UUID
+   */
+  static isValid(uuid) {
+    if (!uuid) {
+      return false;
+    }
+    if (uuid === "00000000-0000-0000-0000-000000000000") {
+      return true;
+    }
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      uuid
+    );
+  }
 }
 
 const M2EventType = {
@@ -1529,6 +2069,12 @@ function handleTextOptions(text, options) {
   if (options.fontSize !== void 0) {
     text.fontSize = options.fontSize;
   }
+  if (options.interpolation) {
+    text.interpolation = options.interpolation;
+  }
+  if (options.localize !== void 0) {
+    text.localize = options.localize;
+  }
 }
 function handleInterfaceOptions(node, options) {
   if (node.isDrawable) {
@@ -1552,7 +2098,7 @@ class M2Node {
     this._scale = 1;
     this.alpha = 1;
     this._zRotation = 0;
-    this.isUserInteractionEnabled = false;
+    this._isUserInteractionEnabled = false;
     this.draggable = false;
     this.hidden = false;
     this.layout = {};
@@ -1564,7 +2110,6 @@ class M2Node {
     this.absoluteAlpha = 1;
     this.absoluteAlphaChange = 0;
     this.actions = new Array();
-    this.originalActions = new Array();
     this.eventListeners = new Array();
     this.uuid = Uuid.generate();
     this.needsInitialization = true;
@@ -2131,32 +2676,9 @@ class M2Node {
         } else ;
       }
     }
-    const uncompletedTransitionActions = this.actions.filter(
-      (action) => action.runDuringTransition && !action.completed
+    this.actions.forEach(
+      (action) => Action.evaluateAction(action, this, Globals.now, Globals.deltaTime)
     );
-    const uncompletedRegularActions = this.actions.filter(
-      (action) => !action.runDuringTransition && !action.completed
-    );
-    if (uncompletedTransitionActions.length > 0) {
-      uncompletedTransitionActions.forEach((action) => {
-        if (action.runStartTime === -1) {
-          action.runStartTime = Globals.now;
-        }
-      });
-      uncompletedTransitionActions.forEach(
-        (action) => Action.evaluateAction(action, this, Globals.now, Globals.deltaTime)
-      );
-    }
-    if (!this.involvedInSceneTransition() && uncompletedRegularActions.length > 0) {
-      uncompletedRegularActions.forEach((action) => {
-        if (action.runStartTime === -1) {
-          action.runStartTime = Globals.now;
-        }
-      });
-      uncompletedRegularActions.forEach(
-        (action) => Action.evaluateAction(action, this, Globals.now, Globals.deltaTime)
-      );
-    }
     function getSiblingConstraintUuids(parent, constraints) {
       const uuids = new Array();
       if (constraints === void 0) {
@@ -2239,8 +2761,7 @@ class M2Node {
    * Only needed if the action will be referred to later
    */
   run(action, key) {
-    this.actions.push(...action.initialize(this, key));
-    this.originalActions = this.actions.filter((action2) => action2.runDuringTransition === false).map((action2) => Action.cloneAction(action2, key));
+    this.actions.push(action.initialize(key));
   }
   /**
    * Remove an action from this node. If the action is running, it will be
@@ -2358,6 +2879,12 @@ class M2Node {
   set scale(scale) {
     this._scale = scale;
   }
+  get isUserInteractionEnabled() {
+    return this._isUserInteractionEnabled;
+  }
+  set isUserInteractionEnabled(isUserInteractionEnabled) {
+    this._isUserInteractionEnabled = isUserInteractionEnabled;
+  }
   // from https://medium.com/@konduruharish/topological-sort-in-typescript-and-c-6d5ecc4bad95
   /**
    * For a given directed acyclic graph, topological ordering of the vertices will be identified using BFS
@@ -2372,7 +2899,11 @@ class M2Node {
       }
       edges.forEach((edge) => {
         if (inDegree.has(edge)) {
-          inDegree.set(edge, inDegree.get(edge) + 1);
+          const inDegreeCount = inDegree.get(edge);
+          if (inDegreeCount === void 0) {
+            throw new Error(`Could not find inDegree for edge ${edge}`);
+          }
+          inDegree.set(edge, inDegreeCount + 1);
         } else {
           inDegree.set(edge, 1);
         }
@@ -2387,13 +2918,17 @@ class M2Node {
     while (queue.length > 0) {
       const current = queue.shift();
       if (current === void 0) {
-        throw "bad";
+        throw "current vertex is undefined";
       }
       tSort.push(current);
       if (adjList.has(current)) {
         adjList.get(current)?.forEach((edge) => {
-          if (inDegree.has(edge) && inDegree.get(edge) > 0) {
-            const newDegree = inDegree.get(edge) - 1;
+          const inDegreeCount = inDegree.get(edge);
+          if (inDegreeCount === void 0) {
+            throw new Error(`Could not find inDegree for edge ${edge}`);
+          }
+          if (inDegree.has(edge) && inDegreeCount > 0) {
+            const newDegree = inDegreeCount - 1;
             inDegree.set(edge, newDegree);
             if (newDegree == 0) {
               queue.push(edge);
@@ -3340,6 +3875,9 @@ class Sprite extends M2Node {
           this.paint.setAlphaf(this.absoluteAlpha);
         }
         if (this.m2Image.status === M2ImageStatus.Ready && this.m2Image.canvaskitImage) {
+          if (this.m2Image.isFallback) {
+            this.drawFallbackImageBorder(canvas);
+          }
           canvas.drawImage(this.m2Image.canvaskitImage, x, y, this.paint);
         } else {
           if (this.m2Image.status === M2ImageStatus.Deferred) {
@@ -3380,6 +3918,35 @@ class Sprite extends M2Node {
       }
     });
   }
+  /**
+   * Draws a rectangle border around the image to indicate that a fallback
+   * image is being used.
+   *
+   * @remarks The size of the rectangle is the same as the image, but because
+   * the stroke width of the paint is wider than 1 pixel (see method
+   * `configureImageLocalization()` in `ImageManager.ts`), the rectangle will
+   * be larger than the image and thus be visible.
+   *
+   * @param canvas - CanvasKit canvas to draw on
+   */
+  drawFallbackImageBorder(canvas) {
+    const paint = this.game.imageManager.missingLocalizationImagePaint;
+    if (!paint) {
+      return;
+    }
+    const drawScale = Globals.canvasScale / this.absoluteScale;
+    const rect = this.canvasKit.RRectXY(
+      this.canvasKit.LTRBRect(
+        (this.absolutePosition.x - this.anchorPoint.x * this.size.width * this.absoluteScale) * drawScale,
+        (this.absolutePosition.y - this.anchorPoint.y * this.size.height * this.absoluteScale) * drawScale,
+        (this.absolutePosition.x + this.size.width * this.absoluteScale - this.anchorPoint.x * this.size.width * this.absoluteScale) * drawScale,
+        (this.absolutePosition.y + this.size.height * this.absoluteScale - this.anchorPoint.y * this.size.height * this.absoluteScale) * drawScale
+      ),
+      0,
+      0
+    );
+    canvas.drawRRect(rect, paint);
+  }
 }
 
 class Scene extends M2Node {
@@ -3842,82 +4409,379 @@ const deviceMetadataSchema = {
       description: "WebGL driver vendor and renderer. Taken from WEBGL_debug_renderer_info."
     }
   }
-};
-
-class WebGlInfo {
+};
+
+class WebGlInfo {
+  /**
+   * Returns graphics driver vendor and renderer information.
+   *
+   * @remarks Information is from parameters UNMASKED_VENDOR_WEBGL and
+   * UNMASKED_RENDERER_WEBGL when asking for WEBGL_debug_renderer_info
+   * from the WebGLRenderingContext.
+   *
+   * @returns string
+   */
+  static getRendererString() {
+    const rendererInfoCanvas = document.createElement("canvas");
+    rendererInfoCanvas.id = "webgl-renderer-info-canvas";
+    rendererInfoCanvas.height = 0;
+    rendererInfoCanvas.width = 0;
+    rendererInfoCanvas.hidden = true;
+    document.body.appendChild(rendererInfoCanvas);
+    const gl = rendererInfoCanvas.getContext("webgl");
+    let rendererString = "no webgl context";
+    if (!gl) {
+      return rendererString;
+    }
+    const debugRendererInfo = gl.getExtension("WEBGL_debug_renderer_info");
+    if (debugRendererInfo != null) {
+      rendererString = String(gl.getParameter(debugRendererInfo.UNMASKED_VENDOR_WEBGL)) + ", " + String(gl.getParameter(debugRendererInfo.UNMASKED_RENDERER_WEBGL));
+    } else {
+      rendererString = "no debug renderer info";
+    }
+    rendererInfoCanvas.remove();
+    return rendererString;
+  }
+  /**
+   * Removes the temporary canvas that was created to get WebGL information.
+   */
+  static dispose() {
+    const rendererInfoCanvas = document.getElementById(
+      "webgl-renderer-info-canvas"
+    );
+    if (rendererInfoCanvas) {
+      rendererInfoCanvas.remove();
+    }
+  }
+}
+
+class I18n {
+  /**
+   * The I18n class localizes text and images.
+   *
+   * @param game - game instance
+   * @param options - {@link LocalizationOptions}
+   */
+  constructor(game, options) {
+    this.locale = "";
+    this.fallbackLocale = "en-US";
+    this.baseLocale = "en-US";
+    this.game = game;
+    this._translation = this.mergeAdditionalTranslation(
+      options.translation,
+      options.additionalTranslation
+    ) ?? {};
+    if (this.translation.configuration?.baseLocale) {
+      this.baseLocale = this.translation.configuration.baseLocale;
+    }
+    if (options.missingLocalizationColor) {
+      this.missingLocalizationColor = options.missingLocalizationColor;
+    }
+    if (options.locale) {
+      this.locale = options.locale;
+    }
+    if (options.fallbackLocale) {
+      this.fallbackLocale = options.fallbackLocale;
+    }
+  }
+  /**
+   * Initializes the I18n instance and sets the initial locale.
+   *
+   * @remarks If the game instance has been configured to use a data store,
+   * the previously used locale and fallback locale will be retrieved from the
+   * data store if they have been previously set.
+   */
+  async initialize() {
+    await this.configureInitialLocale();
+  }
+  async configureInitialLocale() {
+    if (this.game.hasDataStores()) {
+      const locale = await this.game.storeGetItem("locale");
+      const fallbackLocale = await this.game.storeGetItem("fallbackLocale");
+      if (typeof locale === "string" && typeof fallbackLocale === "string") {
+        this.locale = locale;
+        this.fallbackLocale = fallbackLocale;
+        return;
+      }
+    }
+    if (this.locale?.toLowerCase() === "auto") {
+      const attemptedLocale = this.getEnvironmentLocale();
+      if (attemptedLocale) {
+        if (this.localeTranslationAvailable(attemptedLocale)) {
+          this.locale = attemptedLocale;
+          if (!this.localeTranslationAvailable(this.fallbackLocale)) {
+            this.fallbackLocale = this.baseLocale;
+          }
+        } else {
+          if (this.fallbackLocale && this.localeTranslationAvailable(this.fallbackLocale)) {
+            console.warn(
+              `auto locale requested, but detected locale ${attemptedLocale} does not have translation. Setting locale to fallback locale ${this.fallbackLocale}`
+            );
+            this.locale = this.fallbackLocale;
+            this.fallbackLocale = this.baseLocale;
+          } else {
+            console.warn(
+              `auto locale requested, but detected locale ${attemptedLocale} does not have translation, and fallback locale does not have translation or was not specified (fallback locale is ${this.fallbackLocale}). Setting locale to base locale ${this.baseLocale}.`
+            );
+            this.locale = this.baseLocale;
+            this.fallbackLocale = this.baseLocale;
+          }
+        }
+      } else {
+        if (this.fallbackLocale && this.localeTranslationAvailable(this.fallbackLocale)) {
+          console.warn(
+            `auto locale requested, but environment cannot detect locale. Setting locale to fallback locale ${this.fallbackLocale}`
+          );
+          this.locale = this.fallbackLocale;
+          this.fallbackLocale = this.baseLocale;
+        } else {
+          console.warn(
+            `auto locale requested, but environment cannot detect locale, and fallback locale does not have translation or was not specified (fallback locale is ${this.fallbackLocale}). Setting locale to base locale ${this.baseLocale}.`
+          );
+          this.locale = this.baseLocale;
+          this.fallbackLocale = this.baseLocale;
+        }
+      }
+    } else {
+      this.locale = this.locale ?? "";
+      if (!this.fallbackLocale) {
+        this.fallbackLocale = this.baseLocale;
+      }
+    }
+  }
+  localeTranslationAvailable(locale) {
+    return this.translation[locale] !== void 0 || locale === this.baseLocale;
+  }
+  switchToLocale(locale) {
+    this.locale = locale;
+    this.game.nodes.filter((node) => node.isText).forEach((node) => node.needsInitialization = true);
+    this.game.imageManager.reinitializeLocalizedImages();
+    if (this.game && this.game.hasDataStores()) {
+      this.game.storeSetItem("locale", this.locale);
+      this.game.storeSetItem("fallbackLocale", this.fallbackLocale);
+    }
+  }
+  /**
+   *
+   * @param key - Translation key
+   * @param interpolation - Interpolation keys and values to replace
+   * placeholders in the translated text
+   * @returns a `TextLocalizationResult` object with the localized text, font
+   * information, and whether the translation is a fallback.
+   */
+  getTextLocalization(key, interpolation) {
+    let localizedText = "";
+    let isFallbackOrMissingTranslation = false;
+    let tf = this.tf(key, interpolation);
+    if (tf?.text !== void 0) {
+      localizedText = tf.text;
+    } else {
+      tf = this.tf(key, {
+        useFallbackLocale: true,
+        ...interpolation
+      });
+      if (tf === void 0 || tf.text === void 0) {
+        localizedText = key;
+      } else {
+        localizedText = tf.text;
+      }
+      isFallbackOrMissingTranslation = true;
+    }
+    return {
+      text: localizedText,
+      fontName: tf?.fontName,
+      fontNames: tf?.fontNames,
+      isFallbackOrMissingTranslation
+    };
+  }
   /**
-   * Returns graphics driver vendor and renderer information.
+   * Returns the translation text for the given key in the current locale.
    *
-   * @remarks Information is from parameters UNMASKED_VENDOR_WEBGL and
-   * UNMASKED_RENDERER_WEBGL when asking for WEBGL_debug_renderer_info
-   * from the WebGLRenderingContext.
+   * @remarks Optional interpolation keys and values can be provided to replace
+   * placeholders in the translated text. Placeholders are denoted by double
+   * curly braces.
    *
-   * @returns string
-   */
-  static getRendererString() {
-    const rendererInfoCanvas = document.createElement("canvas");
-    rendererInfoCanvas.id = "webgl-renderer-info-canvas";
-    rendererInfoCanvas.height = 0;
-    rendererInfoCanvas.width = 0;
-    rendererInfoCanvas.hidden = true;
-    document.body.appendChild(rendererInfoCanvas);
-    const gl = rendererInfoCanvas.getContext("webgl");
-    let rendererString = "no webgl context";
-    if (!gl) {
-      return rendererString;
+   * @param key - key to look up in the translation
+   * @param options - `TranslationOptions`, such as interpolation keys/values
+   * and whether to translate using the fallback locale
+   * @returns the translation text for the key in the current locale, or
+   * undefined if the key is not found
+   *
+   * @example
+   *
+   * ```
+   * const translation: Translation = {
+   *   "en-US": {
+   *     "GREETING": "Hello, {{name}}."
+   *   }
+   * }
+   * ...
+   * i18n.t("GREETING", { name: "World" }); // returns "Hello, World."
+   *
+   * ```
+   */
+  t(key, options) {
+    const { useFallbackLocale, ...interpolationMap } = options ?? {};
+    if (useFallbackLocale !== true) {
+      const t = this.translation[this.locale]?.[key];
+      if (this.isStringOrTextWithFontCustomization(t)) {
+        return this.insertInterpolations(
+          this.getKeyText(t),
+          interpolationMap
+        );
+      }
+      return void 0;
     }
-    const debugRendererInfo = gl.getExtension("WEBGL_debug_renderer_info");
-    if (debugRendererInfo != null) {
-      rendererString = String(gl.getParameter(debugRendererInfo.UNMASKED_VENDOR_WEBGL)) + ", " + String(gl.getParameter(debugRendererInfo.UNMASKED_RENDERER_WEBGL));
-    } else {
-      rendererString = "no debug renderer info";
+    const fallbackT = this.translation[this.fallbackLocale]?.[key];
+    if (this.isStringOrTextWithFontCustomization(fallbackT)) {
+      return this.insertInterpolations(
+        this.getKeyText(fallbackT),
+        interpolationMap
+      );
     }
-    rendererInfoCanvas.remove();
-    return rendererString;
+    return void 0;
   }
   /**
-   * Removes the temporary canvas that was created to get WebGL information.
+   * Returns the translation text and font information for the given key in the
+   * current locale.
+   *
+   * @remarks Optional interpolation keys and values can be provided to replace
+   * placeholders in the translated text. Placeholders are denoted by double
+   * curly braces. See method {@link I18n.t()} for interpolation example.
+   *
+   * @param key - key to look up in the translation
+   * @param options - `TranslationOptions`, such as interpolation keys/values
+   * and whether to translate using the fallback locale
+   * @returns the translation text and font information for the key in the
+   * current locale, or undefined if the key is not found
    */
-  static dispose() {
-    const rendererInfoCanvas = document.getElementById(
-      "webgl-renderer-info-canvas"
-    );
-    if (rendererInfoCanvas) {
-      rendererInfoCanvas.remove();
+  tf(key, options) {
+    const { useFallbackLocale, ...interpolationMap } = options ?? {};
+    if (useFallbackLocale !== true) {
+      const t = this.translation[this.locale]?.[key];
+      if (this.isStringOrTextWithFontCustomization(t)) {
+        const tf = this.getKeyTextAndFont(t, this.locale);
+        if (tf.text) {
+          tf.text = this.insertInterpolations(
+            tf.text,
+            interpolationMap
+          );
+        }
+        return tf;
+      }
+      return void 0;
+    }
+    const fallbackTranslation = this.translation[this.fallbackLocale]?.[key];
+    if (this.isStringOrTextWithFontCustomization(fallbackTranslation)) {
+      const tf = this.getKeyTextAndFont(
+        fallbackTranslation,
+        this.fallbackLocale
+      );
+      if (tf.text) {
+        tf.text = this.insertInterpolations(
+          tf.text,
+          interpolationMap
+        );
+      }
+      return tf;
     }
+    return void 0;
   }
-}
-
-class I18n {
-  constructor(options) {
-    this.locale = "";
-    this.fallbackLocale = "en";
-    this.environmentLocale = this.getEnvironmentLocale();
-    this.options = options;
-    this._translations = this.mergeAdditionalTranslations(
-      options.translations,
-      options.additionalTranslations
-    ) ?? {};
-    if (options.locale.toLowerCase() === "auto") {
-      this.locale = this.environmentLocale;
-      if (!this.locale) {
-        if (options.fallbackLocale) {
-          this.fallbackLocale = options.fallbackLocale;
-          console.warn(
-            `auto locale requested, but environment cannot provide locale. Using fallback locale ${options.fallbackLocale}`
-          );
-        } else {
-          console.warn(
-            `auto locale requested, but environment cannot provide locale. Defaulting to "en".`
-          );
+  getKeyText(t) {
+    if (this.isTextWithFontCustomization(t)) {
+      return t.text;
+    }
+    return t;
+  }
+  getKeyTextAndFont(t, locale) {
+    let fontNames = new Array();
+    if (this.isString(this.translation[locale]?.fontName)) {
+      fontNames.push(this.translation[locale].fontName);
+    } else if (this.isStringArray(this.translation[locale]?.fontName)) {
+      fontNames.push(...this.translation[locale].fontName);
+    } else {
+      fontNames.push("default");
+    }
+    let text;
+    if (this.isTextWithFontCustomization(t)) {
+      text = t.text;
+      if (this.isString(t.additionalFontName)) {
+        fontNames.push(t.additionalFontName);
+      }
+      if (this.isStringArray(t.additionalFontName)) {
+        fontNames.push(...t.additionalFontName);
+      }
+      if (t.overrideFontName) {
+        fontNames.length = 0;
+        if (this.isString(t.overrideFontName)) {
+          fontNames.push(t.overrideFontName);
+        }
+        if (this.isStringArray(t.overrideFontName)) {
+          fontNames.push(...t.overrideFontName);
         }
       }
     } else {
-      this.locale = options.locale;
-      if (options.fallbackLocale) {
-        this.fallbackLocale = options.fallbackLocale;
+      text = t;
+    }
+    fontNames = fontNames.filter((f) => f !== "default");
+    switch (fontNames.length) {
+      case 0:
+        return { text };
+      case 1:
+        return { text, fontName: fontNames[0] };
+      default:
+        return { text, fontNames };
+    }
+  }
+  insertInterpolations(text, options) {
+    if (!options) {
+      return text;
+    }
+    return text.replace(/\{\{(.*?)\}\}/g, (_match, key) => {
+      if (Object.prototype.hasOwnProperty.call(options, key)) {
+        return options[key];
+      } else {
+        throw new Error(
+          `insertInterpolations(): placeholder "${key}" not found. Text was ${text}, provided interpolation was ${JSON.stringify(options)}`
+        );
+      }
+    });
+  }
+  get translation() {
+    return this._translation;
+  }
+  set translation(value) {
+    this._translation = value;
+  }
+  getEnvironmentLocale() {
+    return (navigator.languages && navigator.languages.length ? navigator.languages[0] : navigator.language) ?? "";
+  }
+  mergeAdditionalTranslation(baseTranslation, additionalTranslation) {
+    if (!baseTranslation && !additionalTranslation) {
+      return void 0;
+    }
+    if (!additionalTranslation) {
+      return baseTranslation;
+    }
+    if (!baseTranslation) {
+      return additionalTranslation;
+    }
+    const result = {};
+    const processedLocales = new Array();
+    for (const locale in baseTranslation) {
+      processedLocales.push(locale);
+      result[locale] = {
+        ...baseTranslation[locale],
+        ...additionalTranslation[locale]
+      };
+    }
+    for (const locale in additionalTranslation) {
+      if (processedLocales.includes(locale)) {
+        continue;
       }
+      result[locale] = additionalTranslation[locale];
     }
+    return result;
   }
   static makeLocalizationParameters() {
     const localizationParameters = JSON.parse(
@@ -3932,64 +4796,34 @@ class I18n {
           default: null,
           description: `Locale to use if requested locale translation is not available, or if "auto" locale was requested and environment cannot provide a locale.`
         },
-        missing_translation_font_color: {
+        missing_localization_color: {
           type: ["array", "null"],
           default: null,
-          description: "Font color for strings that are missing translation and use the fallback locale or untranslated string, [r,g,b,a].",
+          description: "Font color for strings that are missing translation and outline color for images that are missing localization, [r,g,b,a].",
           items: {
             type: "number"
           }
         },
-        translations: {
+        translation: {
           type: ["object", "null"],
           default: null,
-          description: "Additional translations for localization."
+          description: "Additional translation for localization."
         }
       })
     );
     return localizationParameters;
   }
-  t(key, useFallback = false) {
-    if (useFallback) {
-      return this._translations[this.fallbackLocale]?.[key];
-    }
-    return this._translations[this.locale]?.[key];
-  }
-  get translations() {
-    return this._translations;
+  isTextWithFontCustomization(value) {
+    return value?.text !== void 0;
   }
-  set translations(value) {
-    this._translations = value;
+  isStringOrTextWithFontCustomization(value) {
+    return typeof value === "string" || this.isTextWithFontCustomization(value);
   }
-  getEnvironmentLocale() {
-    return navigator.languages && navigator.languages.length ? navigator.languages[0] : navigator.language;
+  isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
   }
-  mergeAdditionalTranslations(baseTranslations, additionalTranslations) {
-    if (!baseTranslations && !additionalTranslations) {
-      return void 0;
-    }
-    if (!additionalTranslations) {
-      return baseTranslations;
-    }
-    if (!baseTranslations) {
-      return additionalTranslations;
-    }
-    const result = {};
-    const processedLocales = new Array();
-    for (const locale in baseTranslations) {
-      processedLocales.push(locale);
-      result[locale] = {
-        ...baseTranslations[locale],
-        ...additionalTranslations[locale]
-      };
-    }
-    for (const locale in additionalTranslations) {
-      if (processedLocales.includes(locale)) {
-        continue;
-      }
-      result[locale] = additionalTranslations[locale];
-    }
-    return result;
+  isString(value) {
+    return typeof value === "string";
   }
 }
 
@@ -4041,12 +4875,18 @@ class ImageManager {
       const m2Image = {
         imageName: browserImage.imageName,
         url,
+        originalUrl: url,
+        isFallback: false,
+        localize: browserImage.localize ?? false,
         svgString: browserImage.svgString,
         canvaskitImage: void 0,
         width: browserImage.width,
         height: browserImage.height,
         status: browserImage.lazy ? M2ImageStatus.Deferred : M2ImageStatus.Loading
       };
+      if (m2Image.localize) {
+        this.configureImageLocalization(m2Image);
+      }
       this.images[browserImage.imageName] = m2Image;
       if (m2Image.status === M2ImageStatus.Loading) {
         return this.renderM2Image(m2Image);
@@ -4055,6 +4895,80 @@ class ImageManager {
     });
     await Promise.all(renderImagesPromises);
   }
+  configureImageLocalization(m2Image) {
+    m2Image.fallbackLocalizationUrls = new Array();
+    if (m2Image.originalUrl && this.game.i18n?.locale) {
+      m2Image.status = "Deferred";
+      if (this.game.i18n?.fallbackLocale) {
+        if (this.game.i18n?.fallbackLocale !== this.game.i18n?.baseLocale) {
+          m2Image.fallbackLocalizationUrls.push(
+            this.localizeImageUrl(
+              m2Image.originalUrl,
+              this.game.i18n.fallbackLocale
+            )
+          );
+        }
+      }
+      if (this.game.i18n?.locale === this.game.i18n?.baseLocale) {
+        m2Image.url = m2Image.originalUrl;
+      } else {
+        m2Image.url = this.localizeImageUrl(
+          m2Image.originalUrl,
+          this.game.i18n.locale
+        );
+      }
+      if (m2Image.url !== m2Image.originalUrl) {
+        m2Image.fallbackLocalizationUrls.push(m2Image.originalUrl);
+      }
+      if (this.game.i18n.missingLocalizationColor && !this.missingLocalizationImagePaint) {
+        this.missingLocalizationImagePaint = CanvasKitHelpers.makePaint(
+          this.canvasKit,
+          this.game.i18n.missingLocalizationColor,
+          this.canvasKit.PaintStyle.Stroke,
+          true
+        );
+        this.missingLocalizationImagePaint.setStrokeWidth(4);
+      }
+    }
+  }
+  /**
+   * Localizes the image URL by appending the locale to the image URL,
+   * immediately before the file extension.
+   *
+   * @remarks For example, `https://url.com/file.png` in en-US locale
+   * becomes `https://url.com/file.en-US.png`. A URL without an extension
+   * will throw an error.
+   *
+   * @param url - url of the image
+   * @param locale - locale in format of xx-YY, where xx is the language code
+   * and YY is the country code
+   * @returns localized url
+   */
+  localizeImageUrl(url, locale) {
+    const extensionIndex = url.lastIndexOf(".");
+    if (extensionIndex === -1) {
+      throw new Error("URL does not have an extension");
+    }
+    const localizedUrl = url.slice(0, extensionIndex) + `.${locale}` + url.slice(extensionIndex);
+    return localizedUrl;
+  }
+  /**
+   * Sets an image to be re-rendered within the current locale.
+   */
+  reinitializeLocalizedImages() {
+    Object.keys(this.game.imageManager.images).forEach((imageName) => {
+      const m2Image = this.game.imageManager.images[imageName];
+      if (m2Image.localize) {
+        this.game.imageManager.configureImageLocalization(m2Image);
+      }
+    });
+    const sprites = this.game.nodes.filter(
+      (node) => node.type === M2NodeType.Sprite
+    );
+    sprites.forEach((sprite) => {
+      sprite.needsInitialization = true;
+    });
+  }
   checkImageNamesForDuplicates(browserImages) {
     const findDuplicates = (arr) => arr.filter((item, index) => arr.indexOf(item) != index);
     const duplicateImageNames = findDuplicates(
@@ -4077,7 +4991,26 @@ class ImageManager {
    */
   prepareDeferredImage(image) {
     image.status = M2ImageStatus.Loading;
-    return this.renderM2Image(image);
+    image.isFallback = false;
+    return this.renderM2Image(image).catch(async () => {
+      image.isFallback = true;
+      while (image.fallbackLocalizationUrls?.length) {
+        image.url = image.fallbackLocalizationUrls.shift();
+        try {
+          await this.renderM2Image(image);
+        } catch (error) {
+          if (image.fallbackLocalizationUrls.length === 0) {
+            if (error instanceof Error) {
+              throw error;
+            } else {
+              throw new Error(
+                `prepareDeferredImage(): unable to render image named ${image.imageName}. image source was ${image.svgString ? "svgString" : `url: ${image.url}`}`
+              );
+            }
+          }
+        }
+      }
+    });
   }
   /**
    * Uses the browser to render an image to a CanvasKit Image and make it
@@ -4248,6 +5181,217 @@ class ImageManager {
   }
 }
 
+class SoundManager {
+  constructor(game, baseUrls) {
+    this.sounds = {};
+    this.game = game;
+    this.baseUrls = baseUrls;
+  }
+  get audioContext() {
+    if (!this._audioContext) {
+      if (!navigator.userActivation.hasBeenActive) {
+        throw new Error(
+          "AudioContext cannot be created until user has interacted with the page"
+        );
+      }
+      this._audioContext = new AudioContext();
+    }
+    return this._audioContext;
+  }
+  /**
+   * Loads sound assets during the game initialization.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @remarks Typically, a user won't call this because the m2c2kit
+   * framework will call this automatically. At initialization, sounds can
+   * only be fetched, not decoded because the AudioContext can not yet
+   * be created (it requires a user interaction).
+   *
+   * @param soundAssets - array of SoundAsset objects
+   */
+  initializeSounds(soundAssets) {
+    if (!soundAssets) {
+      return Promise.resolve();
+    }
+    return this.loadSounds(soundAssets);
+  }
+  /**
+   * Loads an array of sound assets and makes them ready for the game.
+   *
+   * @remarks Loading a sound consists of 1) fetching the sound file and 2)
+   * decoding the sound data. The sound is then ready to be played. Step 1
+   * can be done at any time, but step 2 requires an `AudioContext`, which
+   * can only be created after a user interaction. If a play `Action` is
+   * attempted before the sound is ready (either it has not been fetched or
+   * decoded), the play `Action` will log a warning to the console and the
+   * loading process will continue in the background, and the sound will play
+   * when ready. This `loadSounds()` method **does not** have to be awaited.
+   *
+   * @param soundAssets - an array of {@link SoundAsset}
+   * @returns A promise that completes when all sounds have loaded
+   */
+  loadSounds(soundAssets) {
+    if (soundAssets.length === 0) {
+      return Promise.resolve();
+    }
+    soundAssets.forEach((sound) => {
+      let url = sound.url;
+      if (!M2c2KitHelpers.urlHasScheme(sound.url)) {
+        url = M2c2KitHelpers.getUrlFromManifest(
+          this.game,
+          `${this.baseUrls.assets}/${sound.url}`
+        );
+      }
+      const m2Sound = {
+        soundName: sound.soundName,
+        data: void 0,
+        audioBuffer: void 0,
+        url,
+        status: sound.lazy ? M2SoundStatus.Deferred : M2SoundStatus.WillFetch
+      };
+      if (this.sounds[sound.soundName]) {
+        console.warn(
+          `A sound named ${sound.soundName} has already been loaded. It will be replaced.`
+        );
+      }
+      this.sounds[sound.soundName] = m2Sound;
+    });
+    return this.fetchSounds();
+  }
+  async fetchSounds() {
+    const fetchSoundsPromises = Object.values(this.sounds).map((m2Sound) => {
+      if (m2Sound.status === M2SoundStatus.WillFetch) {
+        m2Sound.status = M2SoundStatus.Fetching;
+        return fetch(m2Sound.url).then((response) => {
+          if (!response.ok) {
+            m2Sound.status = M2SoundStatus.Error;
+            throw new Error(
+              `cannot fetch sound ${m2Sound.soundName} at url ${m2Sound.url}: ${response.statusText}`
+            );
+          }
+          return response.arrayBuffer().then((arrayBuffer) => {
+            m2Sound.data = arrayBuffer;
+            m2Sound.status = M2SoundStatus.Fetched;
+            console.log(
+              `\u26AA sound fetched. name: ${m2Sound.soundName}, bytes: ${arrayBuffer.byteLength}`
+            );
+          });
+        });
+      }
+      return Promise.resolve();
+    });
+    await Promise.all(fetchSoundsPromises);
+  }
+  /**
+   * Fetches a m2c2kit sound ({@link M2Sound}) that was previously
+   * initialized with lazy loading.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @param m2Sound - M2Sound to fetch
+   * @returns A promise that completes when sounds have been fetched
+   */
+  fetchDeferredSound(m2Sound) {
+    m2Sound.status = M2SoundStatus.WillFetch;
+    return this.fetchSounds();
+  }
+  /**
+   * Checks if the SoundManager has sounds needing decoding.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @returns true if there are sounds that have been fetched and are waiting
+   * to be decoded (status is `M2SoundStatus.Fetched`)
+   */
+  hasSoundsToDecode() {
+    return Object.values(this.sounds).filter(
+      (sound) => sound.status === M2SoundStatus.Fetched
+    ).length > 0;
+  }
+  /**
+   * Decodes all fetched sounds from bytes to an `AudioBuffer`.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @remarks This method will be called after the `AudioContext` has been
+   * created and if there are fetched sounds waiting to be decoded.
+   *
+   * @returns A promise that completes when all fetched sounds have been decoded
+   */
+  decodeFetchedSounds() {
+    const sounds = Object.values(this.sounds);
+    const decodeSoundsPromises = sounds.filter((sound) => sound.status === M2SoundStatus.Fetched).map((sound) => this.decodeSound(sound));
+    return Promise.all(decodeSoundsPromises);
+  }
+  /**
+   * Decodes a sound from bytes to an `AudioBuffer`.
+   *
+   * @param sound - sound to decode
+   */
+  async decodeSound(sound) {
+    if (!sound.data) {
+      throw new Error(
+        `data is undefined for sound ${sound.soundName} (url ${sound.url})`
+      );
+    }
+    try {
+      sound.status = M2SoundStatus.Decoding;
+      const buffer = await this.audioContext.decodeAudioData(sound.data);
+      sound.audioBuffer = buffer;
+      sound.status = M2SoundStatus.Ready;
+      console.log(
+        `\u26AA sound decoded. name: ${sound.soundName}, duration (seconds): ${buffer.duration}`
+      );
+    } catch {
+      sound.status = M2SoundStatus.Error;
+      throw new Error(
+        `error decoding sound ${sound.soundName} (url: ${sound.url})`
+      );
+    }
+  }
+  /**
+   * Returns a m2c2kit sound ({@link M2Sound}) that has been entered into the
+   * SoundManager.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @remarks Typically, a user won't need to call this because sound
+   * initialization and processing is handled by the framework.
+   *
+   * @param soundName - sound's name as defined in the game's sound assets
+   * @returns a m2c2kit sound
+   */
+  getSound(soundName) {
+    const sound = this.sounds[soundName];
+    if (!sound) {
+      throw new Error(`getSound(): sound ${soundName} not found`);
+    }
+    return sound;
+  }
+  /**
+   * Frees up resources allocated by the SoundManager.
+   *
+   * @internal For m2c2kit library use only
+   *
+   * @remarks This will be done automatically by the m2c2kit library; the
+   * end-user must not call this.
+   */
+  dispose() {
+  }
+  /**
+   * Gets names of sounds entered in the `SoundManager`.
+   *
+   * @remarks These are sounds that the `SoundManager` is aware of. The sounds
+   * may not be ready to play (may not have been fetched or decoded yet).
+   *
+   * @returns array of sound names
+   */
+  getSoundNames() {
+    return Object.keys(this.sounds);
+  }
+}
+
 class Game {
   /**
    * The base class for all games. New games should extend this class.
@@ -4258,6 +5402,7 @@ class Game {
     this.type = ActivityType.Game;
     this.sessionUuid = "";
     this.uuid = Uuid.generate();
+    this.publishUuid = "";
     this.canvasKitWasmVersion = "0.39.1";
     this.beginTimestamp = NaN;
     this.beginIso8601Timestamp = "";
@@ -4295,6 +5440,15 @@ class Game {
      * values in the trial data.
      */
     this.automaticTrialSchema = {
+      study_id: {
+        type: ["string", "null"],
+        description: "The short human-readable text ID of the study (protocol, experiment, or other aggregate) that contains the administration of this activity."
+      },
+      study_uuid: {
+        type: ["string", "null"],
+        format: "uuid",
+        description: "Unique identifier of the study (protocol, experiment, or other aggregate) that contains the administration of this activity."
+      },
       document_uuid: {
         type: "string",
         format: "uuid",
@@ -4303,17 +5457,22 @@ class Game {
       session_uuid: {
         type: "string",
         format: "uuid",
-        description: "Unique identifier for all activities in this administration of the session."
+        description: "Unique identifier for all activities in this administration of the session. This identifier changes each time a new session starts."
       },
       activity_uuid: {
         type: "string",
         format: "uuid",
-        description: "Unique identifier for all trials in this administration of the activity."
+        description: "Unique identifier for all trials in this administration of the activity. This identifier changes each time the activity starts."
       },
       activity_id: {
         type: "string",
         description: "Human-readable identifier of the activity."
       },
+      activity_publish_uuid: {
+        type: "string",
+        format: "uuid",
+        description: "Persistent unique identifier of the activity. This identifier never changes. It can be used to identify the activity across different studies and sessions."
+      },
       activity_version: {
         type: "string",
         description: "Version of the activity."
@@ -4325,20 +5484,48 @@ class Game {
       device_timezone_offset_minutes: {
         type: "integer",
         description: "Difference in minutes between UTC and device timezone. Calculated from Date.getTimezoneOffset()."
+      },
+      locale: {
+        type: ["string", "null"],
+        description: "Locale of the trial. null if the activity does not support localization."
       }
     };
     this.snapshots = new Array();
     if (!options.id || options.id.trim() === "") {
       throw new Error("id is required in GameOptions");
     }
+    if (!Uuid.isValid(options.publishUuid)) {
+      const providedPublishUuid = options.publishUuid ? `Provided publishUuid was ${options.publishUuid}. ` : "";
+      console.warn(
+        `Missing or invalid publishUuid in GameOptions. ${providedPublishUuid}To generate a valid UUID, visit a site such as https://www.uuidgenerator.net/version4`
+      );
+    }
     this.options = options;
     this.name = options.name;
     this.id = options.id;
+    this.publishUuid = options.publishUuid;
     this.freeNodesScene.game = this;
     this.freeNodesScene.needsInitialization = true;
     this.fpsMetricReportThreshold = options.fpsMetricReportThreshold ?? Constants.FPS_METRIC_REPORT_THRESHOLD;
     this.maximumRecordedActivityMetrics = options.maximumRecordedActivityMetrics ?? Constants.MAXIMUM_RECORDED_ACTIVITY_METRICS;
     this.addLocalizationParametersToGameParameters();
+    if (this.options.locale !== void 0) {
+      this.setParameters({ locale: this.options.locale });
+    }
+    if (this.options.fallbackLocale !== void 0) {
+      this.setParameters({ fallback_locale: this.options.fallbackLocale });
+    }
+    if (this.options.missingLocalizationColor) {
+      this.setParameters({
+        missing_localization_color: this.options.missingLocalizationColor
+      });
+    }
+    if (this.options.translation) {
+      this.setParameters({ translation: this.options.translation });
+    }
+    if (this.options.additionalTranslation) {
+      this.setParameters({ translation: this.options.additionalTranslation });
+    }
     if (!this.options.trialSchema) {
       this.options.trialSchema = {};
     }
@@ -4445,14 +5632,17 @@ class Game {
       }
     }
     if (this.isLocalizationRequested()) {
-      const options = this.getLocalizationOptionsFromGameParameters();
-      this.i18n = new I18n(options);
+      const localizationOptions = this.getLocalizationOptionsFromGameParameters();
+      this.i18n = new I18n(this, localizationOptions);
+      await this.i18n.initialize();
     }
     this.fontManager = new FontManager(this, baseUrls);
     this.imageManager = new ImageManager(this, baseUrls);
+    this.soundManager = new SoundManager(this, baseUrls);
     return Promise.all([
       this.fontManager.initializeFonts(this.options.fonts),
-      this.imageManager.initializeImages(this.options.images)
+      this.imageManager.initializeImages(this.options.images),
+      this.soundManager.initializeSounds(this.options.sounds)
     ]);
   }
   /**
@@ -4508,6 +5698,39 @@ class Game {
   set imageManager(imageManager) {
     this._imageManager = imageManager;
   }
+  get soundManager() {
+    if (!this._soundManager) {
+      throw new Error("soundManager is undefined");
+    }
+    return this._soundManager;
+  }
+  set soundManager(soundManager) {
+    this._soundManager = soundManager;
+  }
+  /**
+   * Adds prefixes to a key to ensure that keys are unique across activities
+   * and studies.
+   *
+   * @remarks When a value is saved to the key-value data store, the key must
+   * be prefixed with additional information to ensure that keys are unique.
+   * The prefixes will include the activity id and publish UUID, and possibly
+   * the study id and study UUID, if they are set (this is so that keys are
+   * unique across different studies that might use the same activity).
+   *
+   * @param key - item key to add prefixes to
+   * @returns the item key with prefixes added
+   */
+  addPrefixesToKey(key) {
+    let k = "";
+    if (this.studyId && this.studyUuid) {
+      k = this.studyId.concat(":", this.studyUuid, ":");
+    } else if (this.studyId || this.studyUuid) {
+      throw new Error(
+        `study_id and study_uuid must both be set or unset. Values are study_id: ${this.studyId}, study_uuid: ${this.studyUuid}`
+      );
+    }
+    return k.concat(this.id.concat(this.id, ":", this.publishUuid, ":", key));
+  }
   /**
    * Saves an item to the activity's key-value store.
    *
@@ -4527,9 +5750,12 @@ class Game {
    * @returns key
    */
   storeSetItem(key, value, globalStore = false) {
-    const k = globalStore ? key : this.id.concat(":", key);
-    const activityId = globalStore ? "" : this.id;
-    return this.dataStores[0].setItem(k, value, activityId);
+    const prefixedKey = globalStore ? key : this.addPrefixesToKey(key);
+    return this.dataStores[0].setItem(
+      prefixedKey,
+      value,
+      globalStore ? "" : this.publishUuid
+    );
   }
   /**
    * Gets an item value from the activity's key-value store.
@@ -4549,8 +5775,8 @@ class Game {
    * @returns value of the item
    */
   storeGetItem(key, globalStore = false) {
-    const k = globalStore ? key : this.id.concat(":", key);
-    return this.dataStores[0].getItem(k);
+    const prefixedKey = globalStore ? key : this.addPrefixesToKey(key);
+    return this.dataStores[0].getItem(prefixedKey);
   }
   /**
    * Deletes an item value from the activity's key-value store.
@@ -4569,8 +5795,8 @@ class Game {
    * by any activity. Default is false.
    */
   storeDeleteItem(key, globalStore = false) {
-    const k = globalStore ? key : this.id.concat(":", key);
-    return this.dataStores[0].deleteItem(k);
+    const prefixedKey = globalStore ? key : this.addPrefixesToKey(key);
+    return this.dataStores[0].deleteItem(prefixedKey);
   }
   /**
    * Deletes all items from the activity's key-value store.
@@ -4585,7 +5811,7 @@ class Game {
    * });
    */
   storeClearItems() {
-    return this.dataStores[0].clearItemsByActivityId(this.id);
+    return this.dataStores[0].clearItemsByActivityPublishUuid(this.publishUuid);
   }
   /**
    * Returns keys of all items in the activity's key-value store.
@@ -4603,7 +5829,9 @@ class Game {
    * by any activity. Default is false.
    */
   storeItemsKeys(globalStore = false) {
-    return this.dataStores[0].itemsKeysByActivityId(globalStore ? "" : this.id);
+    return this.dataStores[0].itemsKeysByActivityPublishUuid(
+      globalStore ? "" : this.publishUuid
+    );
   }
   /**
    * Determines if a key exists in the activity's key-value store.
@@ -4623,8 +5851,8 @@ class Game {
    * @returns true if the key exists, false otherwise
    */
   storeItemExists(key, globalStore = false) {
-    const k = globalStore ? key : this.id.concat(":", key);
-    return this.dataStores[0].itemExists(k);
+    const prefixedKey = globalStore ? key : this.addPrefixesToKey(key);
+    return this.dataStores[0].itemExists(prefixedKey);
   }
   get dataStores() {
     if (!this._dataStores) {
@@ -4635,21 +5863,24 @@ class Game {
   set dataStores(dataStores) {
     this._dataStores = dataStores;
   }
+  hasDataStores() {
+    return this._dataStores && this._dataStores.length > 0 || false;
+  }
   getLocalizationOptionsFromGameParameters() {
     const locale = this.getParameter("locale");
     const fallbackLocale = this.getParameterOrFallback(
       "fallback_locale",
       void 0
     );
-    const missingTranslationColor = this.getParameterOrFallback("missing_translation_font_color", void 0);
-    const additionalTranslations = this.getParameterOrFallback("translations", void 0);
-    const translations = this.options.translations;
+    const missingTranslationColor = this.getParameterOrFallback("missing_localization_color", void 0);
+    const additionalTranslation = this.getParameterOrFallback("translation", void 0);
+    const translation = this.options.translation;
     return {
       locale,
       fallbackLocale,
-      missingTranslationFontColor: missingTranslationColor,
-      additionalTranslations,
-      translations
+      missingLocalizationColor: missingTranslationColor,
+      additionalTranslation,
+      translation
     };
   }
   isLocalizationRequested() {
@@ -4662,7 +5893,14 @@ class Game {
         "Empty string in locale. Leave locale undefined or null to prevent localization."
       );
     }
-    return locale !== void 0 && locale !== null;
+    if ((locale === null || locale === void 0) && this.options.translation) {
+      this.setParameters({ locale: this.options.translation.baseLocale });
+      return true;
+    }
+    if ((locale === null || locale === void 0) && this.options.translation === void 0) {
+      return false;
+    }
+    return true;
   }
   setParameters(additionalParameters) {
     const { parameters } = this.options;
@@ -5310,12 +6548,16 @@ class Game {
       }
       this.data.trials.push({
         document_uuid: Uuid.generate(),
+        study_id: this.studyId ?? null,
+        study_uuid: this.studyUuid ?? null,
         session_uuid: this.sessionUuid,
         activity_uuid: this.uuid,
         activity_id: this.options.id,
+        activity_publish_uuid: this.options.publishUuid,
         activity_version: this.options.version,
         device_timezone: Intl?.DateTimeFormat()?.resolvedOptions()?.timeZone ?? "",
         device_timezone_offset_minutes: (/* @__PURE__ */ new Date()).getTimezoneOffset(),
+        locale: this.i18n?.locale ?? null,
         ...emptyTrial,
         device_metadata: this.getDeviceMetadata()
       });
@@ -5411,6 +6653,12 @@ class Game {
    * the appropriate time. It is not triggered automatically.
    */
   trialComplete() {
+    if (this.data.trials[this.trialIndex]?.["locale"]) {
+      this.data.trials[this.trialIndex]["locale"] = this.i18n?.locale ?? null;
+    }
+    if (this.data.trials[this.trialIndex]?.["device_metadata"]) {
+      this.data.trials[this.trialIndex]["device_metadata"] = this.getDeviceMetadata();
+    }
     if (Object.keys(this.staticTrialSchema).length > 0) {
       this.data.trials[this.trialIndex] = {
         ...this.data.trials[this.trialIndex],
@@ -5493,9 +6741,9 @@ class Game {
       // eslint-disable-line @typescript-eslint/no-unused-vars
       fallback_locale,
       // eslint-disable-line @typescript-eslint/no-unused-vars
-      missing_translation_font_color,
+      missing_localization_color,
       // eslint-disable-line @typescript-eslint/no-unused-vars
-      translations,
+      translation,
       // eslint-disable-line @typescript-eslint/no-unused-vars
       ...result
     } = gameParams;
@@ -5515,9 +6763,9 @@ class Game {
       // eslint-disable-line @typescript-eslint/no-unused-vars
       fallback_locale,
       // eslint-disable-line @typescript-eslint/no-unused-vars
-      missing_translation_font_color,
+      missing_localization_color,
       // eslint-disable-line @typescript-eslint/no-unused-vars
-      translations,
+      translation,
       // eslint-disable-line @typescript-eslint/no-unused-vars
       ...result
     } = gameParams;
@@ -5766,6 +7014,9 @@ class Game {
       this.surface.requestAnimationFrame(this.loop.bind(this));
       return;
     }
+    if (this.soundManager.hasSoundsToDecode() && navigator.userActivation.hasBeenActive) {
+      this.soundManager.decodeFetchedSounds();
+    }
     if (this.gameStopRequested) {
       this.surface.deleteLater();
       return;
@@ -5856,7 +7107,9 @@ class Game {
       canvaskitImage: outgoingSceneImage,
       width: this.canvasCssWidth,
       height: this.canvasCssHeight,
-      status: M2ImageStatus.Ready
+      status: M2ImageStatus.Ready,
+      localize: false,
+      isFallback: false
     };
     this.imageManager.addImage(image);
     const spr = new Sprite({
@@ -5895,11 +7148,43 @@ class Game {
       await plugin.initialize(this);
     }
   }
+  /**
+   * Updates active scenes and executes plugins.
+   *
+   */
   update() {
-    this.plugins.filter((p) => p.beforeUpdate !== void 0 && p.disabled !== true).forEach((p) => p.beforeUpdate(this, Globals.deltaTime));
+    this.executeBeforeUpdatePlugins();
+    this.updateScenes();
+    this.executeAfterUpdatePlugins();
+  }
+  /**
+   * Updates all active scenes and their children.
+   */
+  updateScenes() {
     this.scenes.filter((scene) => scene._active).forEach((scene) => scene.update());
     this.freeNodesScene.update();
-    this.plugins.filter((p) => p.afterUpdate !== void 0 && p.disabled !== true).forEach((p) => p.afterUpdate(this, Globals.deltaTime));
+  }
+  /**
+   * Executes all active plugins before scenes are updated.
+   */
+  executeBeforeUpdatePlugins() {
+    this.plugins.filter(
+      (p) => typeof p.beforeUpdate === "function" && p.disabled !== true
+    ).forEach((p) => {
+      if (p.beforeUpdate) {
+        p.beforeUpdate(this, Globals.deltaTime);
+      }
+    });
+  }
+  /**
+   * Executes all active plugins after scenes have been updated.
+   */
+  executeAfterUpdatePlugins() {
+    this.plugins.filter((p) => typeof p.afterUpdate === "function" && p.disabled !== true).forEach((p) => {
+      if (p.afterUpdate) {
+        p.afterUpdate(this, Globals.deltaTime);
+      }
+    });
   }
   draw(canvas) {
     this.scenes.filter((scene) => scene._active).forEach((scene) => scene.draw(canvas));
@@ -6821,9 +8106,12 @@ class Label extends M2Node {
     // public getter/setter is below
     this._fontSize = Constants.DEFAULT_FONT_SIZE;
     // public getter/setter is below
+    this._interpolation = {};
     // Label options
     this._horizontalAlignmentMode = LabelHorizontalAlignmentMode.Center;
-    this._translatedText = "";
+    // public getter/setter is below
+    this._localize = true;
+    this.localizedFontNames = [];
     handleInterfaceOptions(this, options);
     if (options.horizontalAlignmentMode) {
       this.horizontalAlignmentMode = options.horizontalAlignmentMode;
@@ -6839,20 +8127,6 @@ class Label extends M2Node {
     }
   }
   initialize() {
-    const fontManager = this.game.fontManager;
-    if (this.fontName && this.fontNames) {
-      throw new Error("cannot specify both fontName and fontNames");
-    }
-    const requiredFonts = this.getRequiredLabelFonts(fontManager);
-    requiredFonts.forEach((font) => {
-      if (font.status === M2FontStatus.Deferred) {
-        fontManager.prepareDeferredFont(font);
-        return;
-      }
-    });
-    if (!requiredFonts.every((font) => font.status === M2FontStatus.Ready)) {
-      return;
-    }
     let ckTextAlign = this.canvasKit.TextAlign.Center;
     switch (this.horizontalAlignmentMode) {
       case LabelHorizontalAlignmentMode.Center:
@@ -6877,33 +8151,39 @@ class Label extends M2Node {
       this.fontColor[3]
     );
     let textForParagraph;
-    const i18n = this.parentSceneAsNode.game.i18n;
-    if (i18n) {
-      let translated = i18n.t(this.text);
-      if (translated === void 0) {
-        const fallbackTranslated = i18n.t(this.text, true);
-        if (fallbackTranslated === void 0) {
-          translated = this.text;
-        } else {
-          translated = fallbackTranslated;
-        }
-        if (i18n.options.missingTranslationFontColor) {
-          textColor = this.canvasKit.Color(
-            i18n.options.missingTranslationFontColor[0],
-            i18n.options.missingTranslationFontColor[1],
-            i18n.options.missingTranslationFontColor[2],
-            i18n.options.missingTranslationFontColor[3]
-          );
-        }
-      }
-      this._translatedText = translated;
-      textForParagraph = this._translatedText;
-      if (this._translatedText === "") {
-        console.warn(`warning: empty translated text in label "${this.name}"`);
+    const i18n = this.game.i18n;
+    if (i18n && this.localize !== false) {
+      const textLocalization = i18n.getTextLocalization(
+        this.text,
+        this.interpolation
+      );
+      textForParagraph = textLocalization.text;
+      this.localizedFontName = textLocalization.fontName;
+      this.localizedFontNames = textLocalization.fontNames ?? [];
+      if (textLocalization.isFallbackOrMissingTranslation && i18n.missingLocalizationColor) {
+        textColor = this.canvasKit.Color(
+          i18n.missingLocalizationColor[0],
+          i18n.missingLocalizationColor[1],
+          i18n.missingLocalizationColor[2],
+          i18n.missingLocalizationColor[3]
+        );
       }
     } else {
       textForParagraph = this.text;
-      this._translatedText = "";
+    }
+    if (this.fontName && this.fontNames) {
+      throw new Error("cannot specify both fontName and fontNames");
+    }
+    const fontManager = this.game.fontManager;
+    const requiredFonts = this.getRequiredLabelFonts(fontManager);
+    requiredFonts.forEach((font) => {
+      if (font.status === M2FontStatus.Deferred) {
+        fontManager.prepareDeferredFont(font);
+        return;
+      }
+    });
+    if (!requiredFonts.every((font) => font.status === M2FontStatus.Ready)) {
+      return;
     }
     this.paraStyle = new this.canvasKit.ParagraphStyle({
       textStyle: {},
@@ -6999,6 +8279,17 @@ class Label extends M2Node {
    */
   getRequiredLabelFonts(fontManager) {
     let requiredFonts;
+    if (this.game.i18n && this.localize !== false) {
+      if (this.localizedFontName) {
+        requiredFonts = [fontManager.fonts[this.localizedFontName]];
+        return requiredFonts;
+      } else if (this.localizedFontNames.length > 0) {
+        requiredFonts = this.localizedFontNames.map(
+          (font) => fontManager.fonts[font]
+        );
+        return requiredFonts;
+      }
+    }
     if (this.fontName === void 0 && this.fontNames === void 0) {
       requiredFonts = [fontManager.getDefaultFont()];
     } else if (this.fontName !== void 0) {
@@ -7027,8 +8318,13 @@ class Label extends M2Node {
     this._text = text;
     this.needsInitialization = true;
   }
-  get translatedText() {
-    return this._translatedText;
+  get interpolation() {
+    return this._interpolation;
+  }
+  set interpolation(interpolation) {
+    this._interpolation = interpolation;
+    Object.freeze(this._interpolation);
+    this.needsInitialization = true;
   }
   get fontName() {
     return this._fontName;
@@ -7079,6 +8375,13 @@ class Label extends M2Node {
     this._backgroundColor = backgroundColor;
     this.needsInitialization = true;
   }
+  get localize() {
+    return this._localize;
+  }
+  set localize(localize) {
+    this._localize = localize;
+    this.needsInitialization = true;
+  }
   get backgroundPaint() {
     if (!this._backgroundPaint) {
       throw new Error("backgroundPaint cannot be undefined");
@@ -7149,6 +8452,15 @@ class Label extends M2Node {
     super.drawChildren(canvas);
   }
   warmup(canvas) {
+    const i18n = this.game.i18n;
+    if (i18n && this.localize !== false) {
+      const textLocalization = i18n.getTextLocalization(
+        this.text,
+        this.interpolation
+      );
+      this.localizedFontName = textLocalization.fontName;
+      this.localizedFontNames = textLocalization.fontNames ?? [];
+    }
     const requiredFonts = this.getRequiredLabelFonts(this.game.fontManager);
     if (requiredFonts.some((font) => font.status === M2FontStatus.Deferred)) {
       return;
@@ -7918,100 +9230,423 @@ class Shape extends M2Node {
       }
     });
   }
-  warmupFilledCircle(canvas) {
-    if (!this.circleOfRadius) {
-      return;
+  warmupFilledCircle(canvas) {
+    if (!this.circleOfRadius) {
+      return;
+    }
+    this.drawCircleWithCanvasKit(canvas, this.fillColorPaintAntialiased);
+    this.drawCircleWithCanvasKit(canvas, this.fillColorPaintNotAntialiased);
+  }
+  warmupStrokedCircle(canvas) {
+    if (!this.lineWidth || !this.circleOfRadius) {
+      return;
+    }
+    const drawScale = Globals.canvasScale / this.absoluteScale;
+    this.strokeColorPaintAntialiased.setStrokeWidth(this.lineWidth * drawScale);
+    this.drawCircleWithCanvasKit(canvas, this.strokeColorPaintAntialiased);
+    this.strokeColorPaintNotAntialiased.setStrokeWidth(
+      this.lineWidth * drawScale
+    );
+    this.drawCircleWithCanvasKit(canvas, this.strokeColorPaintNotAntialiased);
+  }
+  warmupFilledRectangle(canvas) {
+    this.drawRectangleWithCanvasKit(canvas, this.fillColorPaintAntialiased);
+    this.drawRectangleWithCanvasKit(canvas, this.fillColorPaintNotAntialiased);
+  }
+  warmupStrokedRectangle(canvas) {
+    if (!this.lineWidth || !this.circleOfRadius) {
+      return;
+    }
+    const drawScale = Globals.canvasScale / this.absoluteScale;
+    this.strokeColorPaintAntialiased.setStrokeWidth(this.lineWidth * drawScale);
+    this.drawRectangleWithCanvasKit(canvas, this.strokeColorPaintAntialiased);
+    this.strokeColorPaintNotAntialiased.setStrokeWidth(
+      this.lineWidth * drawScale
+    );
+    this.drawRectangleWithCanvasKit(
+      canvas,
+      this.strokeColorPaintNotAntialiased
+    );
+  }
+  get fillColor() {
+    return this._fillColor;
+  }
+  set fillColor(fillColor) {
+    this._fillColor = fillColor;
+    this.needsInitialization = true;
+  }
+  get strokeColor() {
+    return this._strokeColor;
+  }
+  set strokeColor(strokeColor) {
+    this._strokeColor = strokeColor;
+    this.needsInitialization = true;
+  }
+  get isAntialiased() {
+    return this._isAntialiased;
+  }
+  set isAntialiased(isAntialiased) {
+    this._isAntialiased = isAntialiased;
+    this.needsInitialization = true;
+  }
+  get fillColorPaintAntialiased() {
+    if (!this._fillColorPaintAntialiased) {
+      throw new Error("fillColorPaintAntiAliased is undefined");
+    }
+    return this._fillColorPaintAntialiased;
+  }
+  set fillColorPaintAntialiased(value) {
+    this._fillColorPaintAntialiased = value;
+  }
+  get strokeColorPaintAntialiased() {
+    if (!this._strokeColorPaintAntialiased) {
+      throw new Error("strokeColorPaintAntiAliased is undefined");
+    }
+    return this._strokeColorPaintAntialiased;
+  }
+  set strokeColorPaintAntialiased(value) {
+    this._strokeColorPaintAntialiased = value;
+  }
+  get fillColorPaintNotAntialiased() {
+    if (!this._fillColorPaintNotAntialiased) {
+      throw new Error("fillColorPaintNotAntiAliased is undefined");
+    }
+    return this._fillColorPaintNotAntialiased;
+  }
+  set fillColorPaintNotAntialiased(value) {
+    this._fillColorPaintNotAntialiased = value;
+  }
+  get strokeColorPaintNotAntialiased() {
+    if (!this._strokeColorPaintNotAntialiased) {
+      throw new Error("strokeColorPaintNotAntiAliased is undefined");
+    }
+    return this._strokeColorPaintNotAntialiased;
+  }
+  set strokeColorPaintNotAntialiased(value) {
+    this._strokeColorPaintNotAntialiased = value;
+  }
+}
+
+class SoundPlayer extends M2Node {
+  /**
+   * Node for playing sounds.
+   *
+   * @param options - {@link SoundPlayerOptions}
+   */
+  constructor(options) {
+    super(options);
+    this.type = M2NodeType.SoundPlayer;
+    this.isDrawable = false;
+    this.soundName = options.soundName;
+  }
+  initialize() {
+  }
+  dispose() {
+  }
+  /**
+   * Duplicates a node using deep copy.
+   *
+   * @remarks This is a deep recursive clone (node and children).
+   * The uuid property of all duplicated nodes will be newly created,
+   * because uuid must be unique.
+   *
+   * @param newName - optional name of the new, duplicated node. If not
+   * provided, name will be the new uuid
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  duplicate(newName) {
+    throw new Error("Method not implemented.");
+  }
+}
+
+class SoundRecorder extends M2Node {
+  /**
+   * Node for recording sounds.
+   *
+   * @param options - {@link SoundRecorderOptions}
+   */
+  constructor(options) {
+    super(options);
+    this.type = M2NodeType.SoundRecorder;
+    this.isDrawable = false;
+    this._isRecording = false;
+    this._isPaused = false;
+    this.audioChunks = [];
+    this.timerUuid = "";
+    if (options?.mimeType) {
+      const supportedMimeTypes = this.getMediaRecorderSupportedAudioMimeTypes();
+      if (supportedMimeTypes.includes(options.mimeType)) {
+        this.mimeType = options.mimeType;
+      } else {
+        console.warn(
+          `Unsupported MIME type in SoundRecorderOptions: ${options.mimeType}. Supported types are: ${supportedMimeTypes}.`
+        );
+        if (options.backupMimeTypes) {
+          const backupMimeType = this.getSupportedBackupMimeType(
+            options.backupMimeTypes
+          );
+          if (backupMimeType) {
+            this.mimeType = backupMimeType;
+            console.log(`Using backup MIME type: ${backupMimeType}.`);
+          }
+        }
+      }
+    }
+    if (options?.audioTrackConstraints) {
+      this.audioTrackConstraints = options.audioTrackConstraints;
+    }
+    if (options?.maximumDuration) {
+      this.maximumDuration = options.maximumDuration;
+    }
+  }
+  initialize() {
+  }
+  async start() {
+    if (this.isRecording) {
+      throw new Error(
+        "cannot start SoundRecorder because it is already started."
+      );
+    }
+    const supportedMimeTypes = this.getMediaRecorderSupportedAudioMimeTypes();
+    if (supportedMimeTypes.length === 0) {
+      throw new Error(
+        "SoundRecorder found no supported MIME types for MediaRecorder."
+      );
+    }
+    if (!this.mimeType) {
+      this.mimeType = supportedMimeTypes[0];
+      console.log(`Using MIME type: ${this.mimeType}.`);
+    }
+    let stream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.audioTrackConstraints ? this.audioTrackConstraints : true
+      });
+    } catch (error) {
+      throw new Error("Error getting user media.");
+    }
+    if (!stream) {
+      throw new Error("no stream.");
+    }
+    const audioTracks = stream.getAudioTracks();
+    this.mediaTrackSettings = audioTracks?.map((track) => track.getSettings());
+    this.mediaRecorder = new MediaRecorder(stream, { mimeType: this.mimeType });
+    this.mediaRecorder.ondataavailable = (event) => {
+      this.audioChunks.push(event.data);
+    };
+    this.mediaRecorder.onerror = (event) => {
+      throw new Error(
+        `MediaRecorder error: ${event?.error?.message} ${event?.message}`
+      );
+    };
+    this.mediaRecorder.start();
+    this.beginIso8601Timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    this.timerUuid = Uuid.generate();
+    Timer.startNew(this.timerUuid);
+    this._isRecording = true;
+    this._isPaused = false;
+  }
+  async stop() {
+    if (!this.isRecording) {
+      throw new Error("cannot stop SoundRecorder because it has not started.");
+    }
+    return new Promise((resolve) => {
+      if (!this.mediaRecorder) {
+        throw new Error("no media recorder");
+      }
+      this.mediaRecorder.onstop = async () => {
+        if (!this.mimeType) {
+          throw new Error("no mimeType");
+        }
+        this._isRecording = false;
+        this._isPaused = false;
+        const audioBlob = new Blob(this.audioChunks, {
+          type: this.getMimeTypeWithoutCodecs(this.mimeType)
+        });
+        const audioBase64 = await this.blobToBase64(audioBlob);
+        resolve({
+          mimeType: this.mimeType,
+          beginIso8601Timestamp: this.beginIso8601Timestamp ?? "",
+          endIso8601Timestamp: this.endIso8601Timestamp ?? "",
+          duration: Timer.elapsed(this.timerUuid),
+          audioTrackSettings: this.mediaTrackSettings,
+          audioBase64,
+          audioBlob
+        });
+      };
+      this.mediaRecorder.stop();
+      this.endIso8601Timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      if (!this.isPaused) {
+        Timer.stop(this.timerUuid);
+      }
+    });
+  }
+  pause() {
+    if (!this.isRecording) {
+      throw new Error("cannot pause SoundRecorder because it is not started.");
     }
-    this.drawCircleWithCanvasKit(canvas, this.fillColorPaintAntialiased);
-    this.drawCircleWithCanvasKit(canvas, this.fillColorPaintNotAntialiased);
-  }
-  warmupStrokedCircle(canvas) {
-    if (!this.lineWidth || !this.circleOfRadius) {
-      return;
+    if (this.isPaused) {
+      throw new Error(
+        "cannot pause SoundRecorder because it is already paused."
+      );
     }
-    const drawScale = Globals.canvasScale / this.absoluteScale;
-    this.strokeColorPaintAntialiased.setStrokeWidth(this.lineWidth * drawScale);
-    this.drawCircleWithCanvasKit(canvas, this.strokeColorPaintAntialiased);
-    this.strokeColorPaintNotAntialiased.setStrokeWidth(
-      this.lineWidth * drawScale
-    );
-    this.drawCircleWithCanvasKit(canvas, this.strokeColorPaintNotAntialiased);
-  }
-  warmupFilledRectangle(canvas) {
-    this.drawRectangleWithCanvasKit(canvas, this.fillColorPaintAntialiased);
-    this.drawRectangleWithCanvasKit(canvas, this.fillColorPaintNotAntialiased);
+    this.mediaRecorder?.pause();
+    this._isPaused = true;
+    Timer.stop(this.timerUuid);
   }
-  warmupStrokedRectangle(canvas) {
-    if (!this.lineWidth || !this.circleOfRadius) {
-      return;
+  resume() {
+    if (!this.isRecording) {
+      throw new Error("cannot resume SoundRecorder because it is not started.");
     }
-    const drawScale = Globals.canvasScale / this.absoluteScale;
-    this.strokeColorPaintAntialiased.setStrokeWidth(this.lineWidth * drawScale);
-    this.drawRectangleWithCanvasKit(canvas, this.strokeColorPaintAntialiased);
-    this.strokeColorPaintNotAntialiased.setStrokeWidth(
-      this.lineWidth * drawScale
-    );
-    this.drawRectangleWithCanvasKit(
-      canvas,
-      this.strokeColorPaintNotAntialiased
-    );
-  }
-  get fillColor() {
-    return this._fillColor;
-  }
-  set fillColor(fillColor) {
-    this._fillColor = fillColor;
-    this.needsInitialization = true;
-  }
-  get strokeColor() {
-    return this._strokeColor;
-  }
-  set strokeColor(strokeColor) {
-    this._strokeColor = strokeColor;
-    this.needsInitialization = true;
+    if (!this.isPaused) {
+      throw new Error("cannot resume SoundRecorder because it is not paused.");
+    }
+    this.mediaRecorder?.resume();
+    this._isPaused = false;
+    Timer.start(this.timerUuid);
   }
-  get isAntialiased() {
-    return this._isAntialiased;
+  /** Is the `SoundRecorder` currently recording? */
+  get isRecording() {
+    return this._isRecording;
   }
-  set isAntialiased(isAntialiased) {
-    this._isAntialiased = isAntialiased;
-    this.needsInitialization = true;
+  /** Is the `SoundRecorder` currently paused? */
+  get isPaused() {
+    return this._isPaused;
   }
-  get fillColorPaintAntialiased() {
-    if (!this._fillColorPaintAntialiased) {
-      throw new Error("fillColorPaintAntiAliased is undefined");
+  update() {
+    super.update();
+    if (this.isRecording && !this.isPaused && this.maximumDuration !== void 0 && Timer.elapsed(this.timerUuid) > this.maximumDuration) {
+      this.pause();
+      return;
     }
-    return this._fillColorPaintAntialiased;
   }
-  set fillColorPaintAntialiased(value) {
-    this._fillColorPaintAntialiased = value;
+  /**
+   * Returns an array of supported audio MIME types for MediaRecorder.
+   *
+   * @remarks Adapted from https://stackoverflow.com/a/68236494
+   * License: https://creativecommons.org/licenses/by-sa/4.0/
+   *
+   * @returns
+   */
+  getMediaRecorderSupportedAudioMimeTypes() {
+    const mediaTypes = ["audio"];
+    const containers = [
+      "webm",
+      "ogg",
+      "mp3",
+      "mp4",
+      "x-matroska",
+      "3gpp",
+      "3gpp2",
+      "3gp2",
+      "quicktime",
+      "mpeg",
+      "aac",
+      "flac",
+      "x-flac",
+      "wave",
+      "wav",
+      "x-wav",
+      "x-pn-wav",
+      "not-supported"
+    ];
+    const codecs = [
+      "vp9",
+      "vp9.0",
+      "vp8",
+      "vp8.0",
+      "avc1",
+      "av1",
+      "h265",
+      "h.265",
+      "h264",
+      "h.264",
+      "opus",
+      "vorbis",
+      "pcm",
+      "aac",
+      "mpeg",
+      "mp4a",
+      "rtx",
+      "red",
+      "ulpfec",
+      "g722",
+      "pcmu",
+      "pcma",
+      "cn",
+      "telephone-event",
+      "not-supported"
+    ];
+    return [
+      ...new Set(
+        containers.flatMap(
+          (ext) => mediaTypes.flatMap((mediaType) => [`${mediaType}/${ext}`])
+        )
+      ),
+      ...new Set(
+        containers.flatMap(
+          (ext) => codecs.flatMap(
+            (codec) => mediaTypes.flatMap((mediaType) => [
+              // NOTE: 'codecs:' will always be true (false positive)
+              `${mediaType}/${ext};codecs=${codec}`
+            ])
+          )
+        )
+      ),
+      ...new Set(
+        containers.flatMap(
+          (ext) => codecs.flatMap(
+            (codec1) => codecs.flatMap(
+              (codec2) => mediaTypes.flatMap((mediaType) => [
+                `${mediaType}/${ext};codecs="${codec1}, ${codec2}"`
+              ])
+            )
+          )
+        )
+      )
+    ].filter((variation) => MediaRecorder.isTypeSupported(variation));
   }
-  get strokeColorPaintAntialiased() {
-    if (!this._strokeColorPaintAntialiased) {
-      throw new Error("strokeColorPaintAntiAliased is undefined");
-    }
-    return this._strokeColorPaintAntialiased;
+  blobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onloadend = () => {
+        const base64WithoutPrefix = reader.result?.toString().split(",").pop();
+        if (base64WithoutPrefix === void 0) {
+          throw new Error("base64WithoutPrefix is undefined.");
+        }
+        resolve(base64WithoutPrefix);
+      };
+      reader.onerror = reject;
+      reader.readAsDataURL(blob);
+    });
   }
-  set strokeColorPaintAntialiased(value) {
-    this._strokeColorPaintAntialiased = value;
+  getMimeTypeWithoutCodecs(mimeType) {
+    const match = mimeType.match(/^[^;]+/);
+    return match ? match[0] : "";
   }
-  get fillColorPaintNotAntialiased() {
-    if (!this._fillColorPaintNotAntialiased) {
-      throw new Error("fillColorPaintNotAntiAliased is undefined");
+  getSupportedBackupMimeType(backupMimeTypes) {
+    const supportedMimeTypes = this.getMediaRecorderSupportedAudioMimeTypes();
+    for (const mimeType of backupMimeTypes) {
+      if (supportedMimeTypes.includes(mimeType)) {
+        return mimeType;
+      }
     }
-    return this._fillColorPaintNotAntialiased;
-  }
-  set fillColorPaintNotAntialiased(value) {
-    this._fillColorPaintNotAntialiased = value;
+    return void 0;
   }
-  get strokeColorPaintNotAntialiased() {
-    if (!this._strokeColorPaintNotAntialiased) {
-      throw new Error("strokeColorPaintNotAntiAliased is undefined");
-    }
-    return this._strokeColorPaintNotAntialiased;
+  dispose() {
   }
-  set strokeColorPaintNotAntialiased(value) {
-    this._strokeColorPaintNotAntialiased = value;
+  /**
+   * Duplicates a node using deep copy.
+   *
+   * @remarks This is a deep recursive clone (node and children).
+   * The uuid property of all duplicated nodes will be newly created,
+   * because uuid must be unique.
+   *
+   * @param newName - optional name of the new, duplicated node. If not
+   * provided, name will be the new uuid
+   */
+  duplicate(newName) {
+    throw new Error(`Method not implemented. ${newName}`);
   }
 }
 
@@ -8047,12 +9682,121 @@ class TextLine extends M2Node {
     this._fontColor = Constants.DEFAULT_FONT_COLOR;
     // public getter/setter is below
     this._fontSize = Constants.DEFAULT_FONT_SIZE;
+    // public getter/setter is below
+    this._interpolation = {};
+    this._localize = true;
     this.typeface = null;
-    this._translatedText = "";
+    this.tryMissingTranslationPaint = false;
+    this.textForDraw = "";
+    this.localizedFontNames = [];
     handleInterfaceOptions(this, options);
     this.size.height = this.fontSize;
     this.size.width = options.width ?? NaN;
   }
+  initialize() {
+    const i18n = this.game.i18n;
+    this.tryMissingTranslationPaint = false;
+    if (i18n && this.localize !== false) {
+      const textLocalization = i18n.getTextLocalization(
+        this.text,
+        this.interpolation
+      );
+      this.textForDraw = textLocalization.text;
+      this.localizedFontName = textLocalization.fontName;
+      this.localizedFontNames = textLocalization.fontNames ?? [];
+      if (textLocalization.isFallbackOrMissingTranslation) {
+        this.tryMissingTranslationPaint = true;
+      }
+    } else {
+      this.textForDraw = this.text;
+    }
+    const fontManager = this.game.fontManager;
+    this.fontForDraw = this.getRequiredTextLineFont(fontManager);
+    if (this.fontForDraw.status === M2FontStatus.Deferred) {
+      fontManager.prepareDeferredFont(this.fontForDraw);
+      return;
+    }
+    if (this.fontForDraw.status === M2FontStatus.Loading) {
+      return;
+    }
+    this.createFontPaint(i18n);
+    this.createFont(fontManager);
+    this.needsInitialization = false;
+  }
+  /**
+   * Determines the M2Font object that needs to be ready in order to draw
+   * the TextLine.
+   *
+   * @remarks It needs a FontManager because it may need to look up the
+   * default font.
+   *
+   * @param fontManager - {@link FontManager}
+   * @returns a M2Font object that is required for the TextLine
+   */
+  getRequiredTextLineFont(fontManager) {
+    if (this.game.i18n) {
+      if (this.localizedFontName !== void 0 && this.localizedFontNames.length !== 0 || this.localizedFontNames.length > 1) {
+        throw new Error(
+          `TextLine supports only one font, but multiple fonts are specified in translation.`
+        );
+      }
+      if (this.localizedFontName !== void 0) {
+        return fontManager.fonts[this.localizedFontName];
+      } else if (this.localizedFontNames.length == 1) {
+        return fontManager.fonts[this.localizedFontNames[0]];
+      }
+    }
+    if (this.fontName === void 0) {
+      return fontManager.getDefaultFont();
+    }
+    return fontManager.getFont(this.fontName);
+  }
+  createFontPaint(i18n) {
+    if (this.paint) {
+      this.paint.delete();
+    }
+    this.paint = new this.canvasKit.Paint();
+    if (this.tryMissingTranslationPaint && this.localize !== false) {
+      if (i18n?.missingLocalizationColor) {
+        this.paint.setColor(
+          this.canvasKit.Color(
+            i18n.missingLocalizationColor[0],
+            i18n.missingLocalizationColor[1],
+            i18n.missingLocalizationColor[2],
+            i18n.missingLocalizationColor[3]
+          )
+        );
+      }
+    } else {
+      this.paint.setColor(
+        this.canvasKit.Color(
+          this.fontColor[0],
+          this.fontColor[1],
+          this.fontColor[2],
+          this.fontColor[3]
+        )
+      );
+    }
+    this.paint.setStyle(this.canvasKit.PaintStyle.Fill);
+    this.paint.setAntiAlias(true);
+  }
+  createFont(fontManager) {
+    if (this.fontForDraw) {
+      this.typeface = fontManager.getTypeface(this.fontForDraw.fontName);
+    } else {
+      const fontNames = fontManager.getFontNames();
+      if (fontNames.length > 0) {
+        this.typeface = fontManager.getTypeface(fontNames[0]);
+      }
+    }
+    if (this.font) {
+      this.font.delete();
+    }
+    this.font = new this.canvasKit.Font(
+      this.typeface,
+      this.fontSize * Globals.canvasScale
+    );
+  }
   get text() {
     return this._text;
   }
@@ -8060,9 +9804,6 @@ class TextLine extends M2Node {
     this._text = text;
     this.needsInitialization = true;
   }
-  get translatedText() {
-    return this._translatedText;
-  }
   get fontName() {
     return this._fontName;
   }
@@ -8084,79 +9825,20 @@ class TextLine extends M2Node {
     this._fontSize = fontSize;
     this.needsInitialization = true;
   }
-  update() {
-    super.update();
+  get interpolation() {
+    return this._interpolation;
   }
-  initialize() {
-    const fontManager = this.game.fontManager;
-    const requiredFont = this.getRequiredTextLineFont(fontManager);
-    if (requiredFont.status === M2FontStatus.Deferred) {
-      fontManager.prepareDeferredFont(requiredFont);
-      return;
-    }
-    if (requiredFont.status === M2FontStatus.Loading) {
-      return;
-    }
-    if (this.paint) {
-      this.paint.delete();
-    }
-    this.paint = new this.canvasKit.Paint();
-    this.paint.setColor(
-      this.canvasKit.Color(
-        this.fontColor[0],
-        this.fontColor[1],
-        this.fontColor[2],
-        this.fontColor[3]
-      )
-    );
-    this.paint.setStyle(this.canvasKit.PaintStyle.Fill);
-    this.paint.setAntiAlias(true);
-    const i18n = this.parentSceneAsNode.game.i18n;
-    if (i18n && i18n.options.missingTranslationFontColor) {
-      this.missingTranslationPaint = new this.canvasKit.Paint();
-      this.missingTranslationPaint.setColor(
-        this.canvasKit.Color(
-          i18n.options.missingTranslationFontColor[0],
-          i18n.options.missingTranslationFontColor[1],
-          i18n.options.missingTranslationFontColor[2],
-          i18n.options.missingTranslationFontColor[3]
-        )
-      );
-      this.paint.setStyle(this.canvasKit.PaintStyle.Fill);
-      this.paint.setAntiAlias(true);
-    }
-    if (this.fontName) {
-      this.typeface = fontManager.getTypeface(this.fontName);
-    } else {
-      const fontNames = fontManager.getFontNames();
-      if (fontNames.length > 0) {
-        this.typeface = fontManager.getTypeface(fontNames[0]);
-      }
-    }
-    if (this.font) {
-      this.font.delete();
-    }
-    this.font = new this.canvasKit.Font(
-      this.typeface,
-      this.fontSize * Globals.canvasScale
-    );
-    this.needsInitialization = false;
+  set interpolation(interpolation) {
+    this._interpolation = interpolation;
+    Object.freeze(this._interpolation);
+    this.needsInitialization = true;
   }
-  /**
-   * Determines the M2Font object that needs to be ready in order to draw
-   * the TextLine.
-   *
-   * @remarks It needs a FontManager because it may need to look up the
-   * default font.
-   *
-   * @param fontManager - {@link FontManager}
-   * @returns a M2Font object that is required for the TextLine
-   */
-  getRequiredTextLineFont(fontManager) {
-    if (this.fontName === void 0) {
-      return fontManager.getDefaultFont();
-    }
-    return fontManager.getFont(this.fontName);
+  get localize() {
+    return this._localize;
+  }
+  set localize(localize) {
+    this._localize = localize;
+    this.needsInitialization = true;
   }
   dispose() {
     CanvasKitHelpers.Dispose([this.font, this.typeface, this.paint]);
@@ -8188,6 +9870,9 @@ class TextLine extends M2Node {
     }
     return dest;
   }
+  update() {
+    super.update();
+  }
   draw(canvas) {
     if (this.parent && this.text && !this.needsInitialization) {
       canvas.save();
@@ -8196,50 +9881,29 @@ class TextLine extends M2Node {
       M2c2KitHelpers.rotateCanvasForDrawableNode(canvas, this);
       const x = this.absolutePosition.x * drawScale;
       const y = (this.absolutePosition.y + this.size.height * this.anchorPoint.y * this.absoluteScale) * drawScale;
-      let textForDraw;
-      let paintForDraw = this.paint;
-      const i18n = this.parentSceneAsNode.game.i18n;
-      if (i18n) {
-        let translated = i18n.t(this.text);
-        if (translated === void 0) {
-          const fallbackTranslated = i18n.t(this.text, true);
-          if (fallbackTranslated === void 0) {
-            translated = this.text;
-          } else {
-            translated = fallbackTranslated;
-          }
-          if (this.missingTranslationPaint) {
-            paintForDraw = this.missingTranslationPaint;
-          }
-        }
-        this._translatedText = translated;
-        textForDraw = this._translatedText;
-        if (this._translatedText === "") {
-          console.warn(
-            `warning: empty translated text in TextLine "${this.name}"`
-          );
-        }
-      } else {
-        textForDraw = this.text;
-        this._translatedText = "";
-        if (this.text === "") {
-          console.warn(`warning: empty text in TextLine "${this.name}"`);
-        }
-      }
-      if (paintForDraw === void 0 || this.font === void 0) {
+      if (this.paint === void 0 || this.font === void 0) {
         throw new Error(
           `in TextLine node ${this}, Paint or Font is undefined.`
         );
       }
       if (this.absoluteAlphaChange !== 0) {
-        paintForDraw.setAlphaf(this.absoluteAlpha);
+        this.paint.setAlphaf(this.absoluteAlpha);
       }
-      canvas.drawText(textForDraw, x, y, paintForDraw, this.font);
+      canvas.drawText(this.textForDraw, x, y, this.paint, this.font);
       canvas.restore();
     }
     super.drawChildren(canvas);
   }
   warmup(canvas) {
+    const i18n = this.game.i18n;
+    if (i18n && this.localize !== false) {
+      const textLocalization = i18n.getTextLocalization(
+        this.text,
+        this.interpolation
+      );
+      this.localizedFontName = textLocalization.fontName;
+      this.localizedFontNames = textLocalization.fontNames ?? [];
+    }
     const requiredFont = this.getRequiredTextLineFont(this.game.fontManager);
     if (requiredFont.status === M2FontStatus.Deferred) {
       return;
@@ -8254,7 +9918,7 @@ class TextLine extends M2Node {
   }
 }
 
-console.log("\u26AA @m2c2kit/core version 0.3.17 (ebbdc605)");
+console.log("\u26AA @m2c2kit/core version 0.3.18 (b3a70752)");
 
-export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equals, FadeAlphaAction, FontManager, Game, GlobalVariables, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2EventType, M2ImageStatus, M2Node, M2NodeType, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, RandomDraws, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equals, FadeAlphaAction, FontManager, Game, GlobalVariables, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2EventType, M2ImageStatus, M2Node, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
 //# sourceMappingURL=index.js.map