@m2c2kit/addons 0.3.15 → 0.3.16

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Composite, WebColors, Shape, Label, CanvasKitHelpers, M2EventType, MutablePath, Easings, Story, Transition, TransitionDirection, LabelHorizontalAlignmentMode, Scene, Dimensions, Sprite, Action } from '@m2c2kit/core';
+import { M2c2KitHelpers, Composite, WebColors, Shape, EventStoreMode, Equal, Label, CanvasKitHelpers, M2EventType, Timer, MutablePath, Easings, Story, Transition, TransitionDirection, LabelHorizontalAlignmentMode, Scene, Dimensions, Sprite, Action } from '@m2c2kit/core';
 
 class Grid extends Composite {
   /**
@@ -13,16 +13,16 @@ class Grid extends Composite {
    */
   constructor(options) {
     super(options);
-    this.compositeType = "grid";
+    this.compositeType = "Grid";
     // Grid options
-    // TODO: make getter, setter for these so they can be changed after initial construction
-    this.rows = 0;
-    this.columns = 0;
-    // default Grid is: transparent gray, red lines, line width 1
-    this.gridBackgroundColor = [0, 0, 233, 0.25];
-    this.gridLineColor = WebColors.Red;
-    this.gridLineWidth = 1;
-    this.gridChildren = new Array();
+    this._rows = 0;
+    this._columns = 0;
+    // default Grid is: transparent blue, red lines, line width 1
+    this._gridBackgroundColor = [0, 0, 255, 0.25];
+    this._gridLineColor = WebColors.Red;
+    this._gridLineWidth = 1;
+    this._gridChildren = new Array();
+    this.cellContainers = new Array();
     if (options.size) {
       this.size = options.size;
     } else {
@@ -32,19 +32,19 @@ class Grid extends Composite {
       if (options.rows >= 1) {
         this.rows = options.rows;
       } else {
-        throw new Error("rows must be at least 1");
+        throw new Error("grid rows must be at least 1");
       }
     } else {
-      throw new Error("rows must be specified");
+      throw new Error("grid rows must be specified");
     }
     if (options.columns) {
       if (options.columns >= 1) {
         this.columns = options.columns;
       } else {
-        throw new Error("columns must be at least 1");
+        throw new Error("grid columns must be at least 1");
       }
     } else {
-      throw new Error("columns must be specified");
+      throw new Error("grid columns must be specified");
     }
     if (options.backgroundColor) {
       this.gridBackgroundColor = options.backgroundColor;
@@ -57,56 +57,114 @@ class Grid extends Composite {
     }
     this.cellWidth = this.size.width / this.columns;
     this.cellHeight = this.size.height / this.rows;
+    this.saveNodeNewEvent();
+  }
+  get completeNodeOptions() {
+    return {
+      ...this.options,
+      ...this.getNodeOptions(),
+      ...this.getDrawableOptions(),
+      rows: this.rows,
+      columns: this.columns,
+      size: this.size,
+      backgroundColor: this.gridBackgroundColor,
+      gridLineWidth: this.gridLineWidth,
+      gridLineColor: this.gridLineColor
+    };
   }
   initialize() {
-    super.removeAllChildren();
+    this.descendants.forEach((d) => {
+      if (d.parent === this) {
+        super.removeChild(d);
+      } else {
+        d.parent?.removeChild(d);
+      }
+    });
     this.gridBackground = new Shape({
-      name: "_" + this.name + "-gridBackground",
+      name: "__" + this.name + "-gridRectangle",
       rect: { size: this.size },
-      //size: this.size,
       fillColor: this.gridBackgroundColor,
       strokeColor: this.gridLineColor,
       lineWidth: this.gridLineWidth,
-      isUserInteractionEnabled: this.isUserInteractionEnabled
+      isUserInteractionEnabled: this.isUserInteractionEnabled,
+      suppressEvents: true
     });
-    this.addChild(this.gridBackground);
+    super.addChild(this.gridBackground);
     this.gridBackground.isUserInteractionEnabled = this.isUserInteractionEnabled;
     for (let col = 1; col < this.columns; col++) {
       const verticalLine = new Shape({
-        name: "_" + this.name + "-gridVerticalLine-" + col,
+        name: "__" + this.name + "-gridVerticalLine-" + (col - 1),
         rect: {
           size: { width: this.gridLineWidth, height: this.size.height },
           origin: { x: -this.size.width / 2 + this.cellWidth * col, y: 0 }
         },
-        fillColor: this.gridLineColor
+        fillColor: this.gridLineColor,
+        suppressEvents: true
       });
       this.gridBackground.addChild(verticalLine);
     }
     for (let row = 1; row < this.rows; row++) {
       const horizontalLine = new Shape({
-        name: "_" + this.name + "-gridHorizontalLine-" + row,
+        name: "__" + this.name + "-gridHorizontalLine-" + (row - 1),
         rect: {
           size: { width: this.size.width, height: this.gridLineWidth },
           origin: { x: 0, y: -this.size.height / 2 + this.cellHeight * row }
         },
-        fillColor: this.gridLineColor
+        fillColor: this.gridLineColor,
+        suppressEvents: true
       });
       this.gridBackground.addChild(horizontalLine);
     }
-    if (this.gridChildren) {
+    this.cellContainers = new Array(this.rows).fill([]).map(() => new Array(this.columns));
+    for (let row = 0; row < this.rows; row++) {
+      for (let col = 0; col < this.columns; col++) {
+        const cellContainer = new Shape({
+          name: "__" + this.name + "-gridCellContainer-" + row + "-" + col,
+          rect: {
+            size: { width: this.cellWidth, height: this.cellHeight },
+            origin: {
+              x: -this.size.width / 2 + this.cellWidth * col + this.cellWidth / 2,
+              y: -this.size.height / 2 + this.cellHeight * row + this.cellHeight / 2
+            }
+          },
+          fillColor: WebColors.Transparent,
+          lineWidth: 0,
+          suppressEvents: true
+        });
+        this.gridBackground.addChild(cellContainer);
+        this.cellContainers[row][col] = cellContainer;
+      }
+    }
+    if (this.gridChildren.length > 0) {
       this.gridChildren.forEach((gridChild) => {
         if (!this.cellWidth || !this.cellHeight || !this.gridBackground) {
           throw new Error(
             "cellWidth, cellHeight, or gridBackground undefined or null"
           );
         }
-        const x = -this.size.width / 2 + this.cellWidth / 2 + gridChild.column * this.cellWidth;
-        const y = -this.size.height / 2 + this.cellHeight / 2 + gridChild.row * this.cellHeight;
-        gridChild.node.position = {
-          x: x + gridChild.node.position.x,
-          y: y + gridChild.node.position.y
-        };
-        this.gridBackground.addChild(gridChild.node);
+        if (this.game.eventStore.mode === EventStoreMode.Replay) {
+          const childNode = [
+            ...this.game.nodes,
+            ...this.game.materializedNodes
+          ].find(
+            (n) => (
+              // gridChild.node is the uuid of the child node here!
+              n.uuid === gridChild.node
+            )
+          );
+          if (!childNode) {
+            throw new Error("grid: child node not found");
+          }
+          childNode?.parent?.removeChild(childNode);
+          this.cellContainers[gridChild.row][gridChild.column].addChild(
+            childNode
+          );
+        } else {
+          gridChild.node.parent?.removeChild(gridChild.node);
+          this.cellContainers[gridChild.row][gridChild.column].addChild(
+            gridChild.node
+          );
+        }
       });
     }
     this.needsInitialization = false;
@@ -120,6 +178,60 @@ class Grid extends Composite {
   set gridBackground(gridBackground) {
     this._gridBackground = gridBackground;
   }
+  /**
+   * note: below we do not have getter and setter for size because the getter
+   * and setter in M2Node will handle it.
+   */
+  get rows() {
+    return this._rows;
+  }
+  set rows(rows) {
+    if (Equal.value(this._rows, rows)) {
+      return;
+    }
+    this._rows = rows;
+    this.needsInitialization = true;
+  }
+  get columns() {
+    return this._columns;
+  }
+  set columns(columns) {
+    if (Equal.value(this._columns, columns)) {
+      return;
+    }
+    this._columns = columns;
+    this.needsInitialization = true;
+  }
+  get gridBackgroundColor() {
+    return this._gridBackgroundColor;
+  }
+  set gridBackgroundColor(backgroundColor) {
+    if (Equal.value(this._gridBackgroundColor, backgroundColor)) {
+      return;
+    }
+    this._gridBackgroundColor = backgroundColor;
+    this.needsInitialization = true;
+  }
+  get gridLineWidth() {
+    return this._gridLineWidth;
+  }
+  set gridLineWidth(gridLineWidth) {
+    if (Equal.value(this._gridLineWidth, gridLineWidth)) {
+      return;
+    }
+    this._gridLineWidth = gridLineWidth;
+    this.needsInitialization = true;
+  }
+  get gridLineColor() {
+    return this._gridLineColor;
+  }
+  set gridLineColor(gridLineColor) {
+    if (Equal.value(this._gridLineColor, gridLineColor)) {
+      return;
+    }
+    this._gridLineColor = gridLineColor;
+    this.needsInitialization = true;
+  }
   // all nodes that make up grid are added as children, so they
   // have their own dispose methods
   // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -168,25 +280,49 @@ class Grid extends Composite {
       child.warmup(canvas);
     });
   }
-  // override M2Node.RemoveAllChildren() so that when RemoveAllChildren() is called on a Grid,
-  // it removes only nodes added to the grid cells (what we call grid children), not the grid lines!
   /**
-   * Removes all children from the grid, but retains grid lines.
+   * The child nodes that have been added to the grid.
+   *
+   * @remarks Do not set this property directly. Use the methods for adding
+   * and removing grid children, such as `addAtCell()`, `removeAllAtCell()`,
+   * `removeGridChild()`, and `removeAllGridChildren()`.
    */
-  removeAllChildren() {
+  get gridChildren() {
+    return this._gridChildren;
+  }
+  set gridChildren(gridChildren) {
+    this._gridChildren = gridChildren;
+    this.needsInitialization = true;
+    if (this.game.eventStore.mode === EventStoreMode.Record) {
+      this.savePropertyChangeEvent(
+        "gridChildren",
+        this.gridChildren.map(
+          (gridChild) => ({
+            node: gridChild.node.uuid,
+            row: gridChild.row,
+            column: gridChild.column
+          })
+        )
+      );
+    }
+  }
+  /**
+   * Removes all grid children from the grid.
+   *
+   * @remarks This retains grid lines and grid appearance.
+   */
+  removeAllGridChildren() {
     if (this.gridChildren.length === 0) {
       return;
     }
     while (this.gridChildren.length) {
-      const gridChild = this.gridChildren.pop();
-      if (gridChild) {
-        this.gridBackground.removeChild(gridChild.node);
-      }
+      this.gridChildren = this.gridChildren.slice(0, -1);
     }
     this.needsInitialization = true;
   }
   /**
-   * Adds a node to the grid at the specified row and column position.
+   * Adds a node as a grid child to the grid at the specified row and column
+   * position.
    *
    * @param node - node to add to the grid
    * @param row  - row position within grid to add node; zero-based indexing
@@ -198,49 +334,68 @@ class Grid extends Composite {
         `warning: addAtCell() requested to add node at row ${row}, column ${column}. This is outside the bounds of grid ${this.name}, which is size ${this.rows}x${this.columns}. Note that addAtCell() uses zero-based indexing. AddAtCell() will proceed, but may draw nodes outside the grid`
       );
     }
-    this.gridChildren.push({ node, row, column });
+    this.gridChildren = [
+      ...this.gridChildren,
+      { node, row, column }
+    ];
     this.needsInitialization = true;
   }
   /**
-   * Removes all child nodes at the specified row and column position.
+   * Removes all grid child nodes at the specified row and column position.
    *
-   * @param row - row position within grid at which to remove children; zero-based indexing
-   * @param column - column position within grid at which to remove children; zero-based indexing
+   * @param row - row position within grid at which to remove grid children; zero-based indexing
+   * @param column - column position within grid at which to remove grid children; zero-based indexing
    */
   removeAllAtCell(row, column) {
-    const gridChildrenToRemove = this.gridChildren.filter(
-      (gridChild) => gridChild.row === row && gridChild.column === column
-    );
-    if (gridChildrenToRemove.length === 0) {
-      return;
-    }
-    this.gridBackground.removeChildren(
-      gridChildrenToRemove.map((gridChild) => gridChild.node)
-    );
     this.gridChildren = this.gridChildren.filter(
       (gridChild) => gridChild.row !== row && gridChild.column !== column
     );
     this.needsInitialization = true;
   }
-  // override M2Node.RemoveChild() so that when RemoveChild() is called on a Grid, it removes the
-  // node from the gridBackground rectangle AND our grid's own list of children (in gridChildren)
   /**
-   * Removes the child node from the grid.
+   * Removes the grid child node from the grid.
    *
    * @param node - node to remove
    */
-  removeChild(node) {
-    this.gridBackground.removeChild(node);
+  removeGridChild(node) {
     this.gridChildren = this.gridChildren.filter(
       (gridChild) => gridChild.node != node
     );
     this.needsInitialization = true;
   }
+  // The Grid manages its own children (background, lines, and cell
+  // containers). It is probably a mistake when the user tries to add or remove
+  // these children. The user probably meant to add or remove grid children
+  // instead. Warn the user about this.
+  addChild(child) {
+    console.warn(
+      "Grid.addChild() was called -- did you mean to call addAtCell() instead?"
+    );
+    super.addChild(child);
+  }
+  removeAllChildren() {
+    console.warn(
+      "Grid.removeAllChildren() was called -- did you mean to call removeAllGridChildren() instead?"
+    );
+    super.removeAllChildren();
+  }
+  removeChild(child) {
+    console.warn(
+      "Grid.removeChild() was called -- did you mean to call removeGridChild() instead?"
+    );
+    super.removeChild(child);
+  }
+  removeChildren(children) {
+    console.warn(
+      "Grid.removeChildren() was called -- did you mean to call removeGridChild() instead?"
+    );
+    super.removeChildren(children);
+  }
 }
+M2c2KitHelpers.registerM2NodeClass(Grid);
 
 class Button extends Composite {
-  // todo: add getters/setters so button can respond to changes in its options
-  // todo: add default "behaviors" (?) like button click animation?
+  // TODO: add default "behaviors" (?) like button click animation?
   /**
    * A simple button of rectangle with text centered inside.
    *
@@ -252,12 +407,12 @@ class Button extends Composite {
    */
   constructor(options) {
     super(options);
-    this.compositeType = "button";
+    this.compositeType = "Button";
+    this.isText = true;
     // Button options
     this._backgroundColor = WebColors.Black;
-    this.size = { width: 200, height: 50 };
-    this.cornerRadius = 9;
-    this.fontSize = 20;
+    this._cornerRadius = 9;
+    this._fontSize = 20;
     this._text = "";
     this._fontColor = WebColors.White;
     this._interpolation = {};
@@ -267,6 +422,8 @@ class Button extends Composite {
     }
     if (options.size) {
       this.size = options.size;
+    } else {
+      this.size = { width: 200, height: 50 };
     }
     if (options.cornerRadius !== void 0) {
       this.cornerRadius = options.cornerRadius;
@@ -292,6 +449,19 @@ class Button extends Composite {
     if (options.localize !== void 0) {
       this.localize = options.localize;
     }
+    this.saveNodeNewEvent();
+  }
+  get completeNodeOptions() {
+    return {
+      ...this.options,
+      ...this.getNodeOptions(),
+      ...this.getDrawableOptions(),
+      ...this.getTextOptions(),
+      size: this.size,
+      cornerRadius: this.cornerRadius,
+      backgroundColor: this.backgroundColor,
+      fontNames: this.fontNames
+    };
   }
   initialize() {
     this.removeAllChildren();
@@ -306,19 +476,23 @@ class Button extends Composite {
     );
     this.backgroundPaint.setStyle(this.canvasKit.PaintStyle.Fill);
     const buttonRectangle = new Shape({
+      name: "__" + this.name + "-buttonRectangle",
       rect: { size: this.size },
       cornerRadius: this.cornerRadius,
-      fillColor: this._backgroundColor
+      fillColor: this._backgroundColor,
+      suppressEvents: true
     });
     this.addChild(buttonRectangle);
     const buttonLabel = new Label({
+      name: "__" + this.name + "-buttonLabel",
       text: this.text,
       localize: this.localize,
       interpolation: this.interpolation,
       fontName: this.fontName,
       fontNames: this.fontNames,
       fontSize: this.fontSize,
-      fontColor: this.fontColor
+      fontColor: this.fontColor,
+      suppressEvents: true
     });
     buttonRectangle.addChild(buttonLabel);
     this.needsInitialization = false;
@@ -330,51 +504,101 @@ class Button extends Composite {
     return this._text;
   }
   set text(text) {
+    if (Equal.value(this._text, text)) {
+      return;
+    }
     this._text = text;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("text", text);
   }
   get backgroundColor() {
     return this._backgroundColor;
   }
   set backgroundColor(backgroundColor) {
+    if (Equal.value(this._backgroundColor, backgroundColor)) {
+      return;
+    }
     this._backgroundColor = backgroundColor;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("backgroundColor", backgroundColor);
   }
   get fontColor() {
     return this._fontColor;
   }
   set fontColor(fontColor) {
+    if (Equal.value(this._fontColor, fontColor)) {
+      return;
+    }
     this._fontColor = fontColor;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("fontColor", fontColor);
   }
   get fontName() {
     return this._fontName;
   }
   set fontName(fontName) {
+    if (this._fontName === fontName) {
+      return;
+    }
     this._fontName = fontName;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("fontName", fontName);
   }
   get fontNames() {
     return this._fontNames;
   }
   set fontNames(fontNames) {
+    if (Equal.value(this._fontNames, fontNames)) {
+      return;
+    }
     this._fontNames = fontNames;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("fontNames", fontNames);
+  }
+  get cornerRadius() {
+    return this._cornerRadius;
+  }
+  set cornerRadius(cornerRadius) {
+    if (Equal.value(this._cornerRadius, cornerRadius)) {
+      return;
+    }
+    this._cornerRadius = cornerRadius;
+    this.needsInitialization = true;
+    this.savePropertyChangeEvent("cornerRadius", cornerRadius);
+  }
+  get fontSize() {
+    return this._fontSize;
+  }
+  set fontSize(fontSize) {
+    if (Equal.value(this._fontSize, fontSize)) {
+      return;
+    }
+    this._fontSize = fontSize;
+    this.needsInitialization = true;
+    this.savePropertyChangeEvent("fontSize", fontSize);
   }
   get interpolation() {
     return this._interpolation;
   }
   set interpolation(interpolation) {
+    if (Equal.value(this._interpolation, interpolation)) {
+      return;
+    }
     this._interpolation = interpolation;
     Object.freeze(this._interpolation);
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("interpolation", interpolation);
   }
   get localize() {
     return this._localize;
   }
   set localize(localize) {
+    if (Equal.value(this._localize, localize)) {
+      return;
+    }
     this._localize = localize;
     this.needsInitialization = true;
+    this.savePropertyChangeEvent("localize", localize);
   }
   /**
    * Duplicates a node using deep copy.
@@ -423,6 +647,7 @@ class Button extends Composite {
     });
   }
 }
+M2c2KitHelpers.registerM2NodeClass(Button);
 
 var DialogResult = /* @__PURE__ */ ((DialogResult2) => {
   DialogResult2["Dismiss"] = "Dismiss";
@@ -442,9 +667,9 @@ class Dialog extends Composite {
     this.contentText = "";
     this.positiveButtonText = "";
     this.negativeButtonText = "";
+    this._fontColor = WebColors.White;
     this.zPosition = Number.MAX_VALUE;
     this.hidden = true;
-    this._fontColor = WebColors.White;
     if (!options) {
       return;
     }
@@ -478,7 +703,7 @@ class Dialog extends Composite {
   }
   onDialogResult(callback, options) {
     const eventListener = {
-      type: M2EventType.CompositeCustom,
+      type: M2EventType.Composite,
       compositeType: "DialogResult",
       nodeUuid: this.uuid,
       callback
@@ -494,10 +719,10 @@ class Dialog extends Composite {
     this.removeAllChildren();
     const overlay = new Shape({
       rect: {
-        width: Globals.canvasCssWidth,
-        height: Globals.canvasCssHeight,
-        x: Globals.canvasCssWidth / 2,
-        y: Globals.canvasCssHeight / 2
+        width: m2c2Globals.canvasCssWidth,
+        height: m2c2Globals.canvasCssHeight,
+        x: m2c2Globals.canvasCssWidth / 2,
+        y: m2c2Globals.canvasCssHeight / 2
       },
       fillColor: [0, 0, 0, this.overlayAlpha],
       zPosition: -1,
@@ -507,12 +732,14 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.Composite).forEach((listener) => {
           const dialogEvent = {
-            type: M2EventType.CompositeCustom,
+            type: M2EventType.Composite,
             target: this,
             handled: false,
-            dialogResult: "Dismiss" /* Dismiss */
+            dialogResult: "Dismiss" /* Dismiss */,
+            timestamp: Timer.now(),
+            iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
           };
           listener.callback(dialogEvent);
         });
@@ -523,8 +750,8 @@ class Dialog extends Composite {
       rect: {
         width: 300,
         height: 150,
-        x: Globals.canvasCssWidth / 2,
-        y: Globals.canvasCssHeight / 2
+        x: m2c2Globals.canvasCssWidth / 2,
+        y: m2c2Globals.canvasCssHeight / 2
       },
       cornerRadius: this.cornerRadius,
       fillColor: this.backgroundColor,
@@ -555,12 +782,14 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.Composite).forEach((listener) => {
           const dialogEvent = {
-            type: M2EventType.CompositeCustom,
+            type: M2EventType.Composite,
             target: this,
             handled: false,
-            dialogResult: "Negative" /* Negative */
+            dialogResult: "Negative" /* Negative */,
+            timestamp: Timer.now(),
+            iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
           };
           listener.callback(dialogEvent);
         });
@@ -577,12 +806,14 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.Composite).forEach((listener) => {
           const dialogEvent = {
-            type: M2EventType.CompositeCustom,
+            type: M2EventType.Composite,
             target: this,
             handled: false,
-            dialogResult: "Positive" /* Positive */
+            dialogResult: "Positive" /* Positive */,
+            timestamp: Timer.now(),
+            iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
           };
           listener.callback(dialogEvent);
         });
@@ -606,6 +837,13 @@ class Dialog extends Composite {
     this._fontColor = fontColor;
     this.needsInitialization = true;
   }
+  get hidden() {
+    return this._hidden;
+  }
+  set hidden(hidden) {
+    this._hidden = hidden;
+    this.needsInitialization;
+  }
   /**
    * Duplicates a node using deep copy.
    *
@@ -617,7 +855,7 @@ class Dialog extends Composite {
    * provided, name will be the new uuid
    */
   duplicate(newName) {
-    throw new Error("duplicate not implemented");
+    throw new Error(`duplicate not implemented. ${newName}`);
   }
   update() {
     super.update();
@@ -668,6 +906,7 @@ class DrawPad extends Composite {
      * of all interactions with each DrawPadStroke.
      */
     this.strokes = new Array();
+    this.originalOptions = JSON.parse(JSON.stringify(options));
     if (options.isUserInteractionEnabled === void 0) {
       this.isUserInteractionEnabled = true;
     }
@@ -699,6 +938,15 @@ class DrawPad extends Composite {
     if (options.continuousDrawingOnlyExceptionDistance !== void 0) {
       this.continuousDrawingOnlyExceptionDistance = options.continuousDrawingOnlyExceptionDistance;
     }
+    this.saveNodeNewEvent();
+  }
+  get completeNodeOptions() {
+    return {
+      ...this.options,
+      ...this.getNodeOptions(),
+      ...this.getDrawableOptions(),
+      ...this.originalOptions
+    };
   }
   initialize() {
     this.initializeDrawShape();
@@ -721,7 +969,8 @@ class DrawPad extends Composite {
     if (!this.drawArea) {
       this.drawArea = new Shape({
         rect: { size: this.size },
-        isUserInteractionEnabled: true
+        isUserInteractionEnabled: true,
+        suppressEvents: true
       });
       this.addChild(this.drawArea);
       this.drawArea.onTapDown((e) => {
@@ -765,7 +1014,8 @@ class DrawPad extends Composite {
         type: DrawPadEventType.StrokeStart,
         target: this,
         handled: false,
-        position: e.point
+        position: e.point,
+        ...M2c2KitHelpers.createTimestamps()
       };
       this.strokes.push([
         {
@@ -796,7 +1046,8 @@ class DrawPad extends Composite {
       type: DrawPadEventType.StrokeMove,
       target: this,
       handled: false,
-      position: interpolatedPoint
+      position: interpolatedPoint,
+      ...M2c2KitHelpers.createTimestamps()
     };
     this.strokes[strokeCount - 1].push({
       type: DrawPadEventType.StrokeMove,
@@ -826,7 +1077,8 @@ class DrawPad extends Composite {
         type: DrawPadEventType.StrokeEnd,
         position: this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
         target: this,
-        handled: false
+        handled: false,
+        ...M2c2KitHelpers.createTimestamps()
       };
       this.strokes[strokeCount - 1].push({
         type: DrawPadEventType.StrokeEnd,
@@ -854,7 +1106,8 @@ class DrawPad extends Composite {
         type: DrawPadEventType.StrokeEnd,
         position: this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
         target: this,
-        handled: false
+        handled: false,
+        ...M2c2KitHelpers.createTimestamps()
       };
       this.strokes[strokeCount - 1].push({
         type: DrawPadEventType.StrokeEnd,
@@ -882,7 +1135,8 @@ class DrawPad extends Composite {
         type: DrawPadEventType.StrokeMove,
         target: this,
         handled: false,
-        position: e.point
+        position: e.point,
+        ...M2c2KitHelpers.createTimestamps()
       };
       const strokeCount = this.strokes.length;
       this.strokes[strokeCount - 1].push({
@@ -1037,7 +1291,8 @@ class DrawPad extends Composite {
           node.isStrokeWithinBounds = true;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeEnter,
-            target: node
+            target: node,
+            ...M2c2KitHelpers.createTimestamps()
           };
           this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
@@ -1049,7 +1304,8 @@ class DrawPad extends Composite {
           node.isStrokeWithinBounds = true;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeEnter,
-            target: node
+            target: node,
+            ...M2c2KitHelpers.createTimestamps()
           };
           this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
@@ -1061,7 +1317,8 @@ class DrawPad extends Composite {
           node.isStrokeWithinBounds = false;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeLeave,
-            target: node
+            target: node,
+            ...M2c2KitHelpers.createTimestamps()
           };
           this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
@@ -1072,7 +1329,8 @@ class DrawPad extends Composite {
         node.isStrokeWithinBounds = false;
         const drawPadItemEvent = {
           type: DrawPadItemEventType.StrokeLeave,
-          target: node
+          target: node,
+          ...M2c2KitHelpers.createTimestamps()
         };
         this.raiseDrawPadItemEvent(node, drawPadItemEvent);
       }
@@ -1095,10 +1353,10 @@ class DrawPad extends Composite {
     if (!drawArea) {
       throw new Error("DrawPad.takeScreenshot(): no drawArea");
     }
-    const sx = (drawArea.absolutePosition.x - drawArea.size.width / 2) * Globals.canvasScale;
-    const sy = (drawArea.absolutePosition.y - drawArea.size.height / 2) * Globals.canvasScale;
-    const sw = drawArea.size.width * Globals.canvasScale;
-    const sh = drawArea.size.height * Globals.canvasScale;
+    const sx = (drawArea.absolutePosition.x - drawArea.size.width / 2) * m2c2Globals.canvasScale;
+    const sy = (drawArea.absolutePosition.y - drawArea.size.height / 2) * m2c2Globals.canvasScale;
+    const sw = drawArea.size.width * m2c2Globals.canvasScale;
+    const sh = drawArea.size.height * m2c2Globals.canvasScale;
     const imageInfo = {
       alphaType: this.game.canvasKit.AlphaType.Unpremul,
       colorType: this.game.canvasKit.ColorType.RGBA_8888,
@@ -1237,9 +1495,10 @@ class DrawPad extends Composite {
     this.needsInitialization = true;
   }
   duplicate(newName) {
-    throw new Error("DrawPad.duplicate(): Method not implemented.");
+    throw new Error(`DrawPad.duplicate(): Method not implemented. ${newName}`);
   }
 }
+M2c2KitHelpers.registerM2NodeClass(DrawPad);
 
 class VirtualKeyboard extends Composite {
   /**
@@ -1250,11 +1509,14 @@ class VirtualKeyboard extends Composite {
   constructor(options) {
     super(options);
     this.compositeType = "VirtualKeyboard";
-    this.rowsConfiguration = new Array();
+    this.keyboardRows = new Array();
     this.shiftActivated = false;
     this.keyShapes = new Array();
-    // VirtualKeyboard defaults to being user interactive.
-    this._isUserInteractionEnabled = true;
+    this.keyLabels = new Array();
+    this.originalOptions = JSON.parse(JSON.stringify(options));
+    if (options.isUserInteractionEnabled === void 0) {
+      this._isUserInteractionEnabled = true;
+    }
     this.size = options.size;
     this.position = options.position ?? { x: 0, y: 0 };
     this.keyboardHorizontalPaddingPercent = options.keyboardHorizontalPaddingPercent ?? 0.02;
@@ -1262,11 +1524,12 @@ class VirtualKeyboard extends Composite {
     this.keyHorizontalPaddingPercent = options.keyHorizontalPaddingPercent ?? 0.1;
     this.keyVerticalPaddingPercent = options.keyVerticalPaddingPercent ?? 0.1;
     if (options.rows !== void 0) {
-      this.rowsConfiguration = options.rows.map((row) => {
+      this.keyboardRows = options.rows.map((row) => {
         const internalRow = row.map((key) => {
           if (key instanceof Object && !Array.isArray(key)) {
             const internalKeyConfig = key;
             if (key.keyIconShapeOptions) {
+              key.keyIconShapeOptions.suppressEvents = true;
               internalKeyConfig.keyIcon = new Shape(key.keyIconShapeOptions);
               internalKeyConfig.keyIconShapeOptions = void 0;
             }
@@ -1288,157 +1551,48 @@ class VirtualKeyboard extends Composite {
     this.specialKeyDownColor = options.specialKeyDownColor ?? WebColors.LightSteelBlue;
     this.backgroundColor = options.backgroundColor ?? [242, 240, 244, 1];
     this.showKeyDownPreview = options.showKeyDownPreview ?? true;
+    this.saveNodeNewEvent();
+  }
+  get completeNodeOptions() {
+    return {
+      ...this.options,
+      ...this.getNodeOptions(),
+      ...this.getDrawableOptions(),
+      ...this.originalOptions
+    };
   }
   initialize() {
-    if (this.rowsConfiguration.length === 0) {
-      const numKeys = [
-        ["1", "!"],
-        ["2", "@"],
-        ["3", "#"],
-        ["4", "$"],
-        ["5", "%"],
-        ["6", "^"],
-        ["7", "&"],
-        ["8", "*"],
-        ["9", "("],
-        ["0", ")"]
-      ];
-      const row1 = [
-        "q",
-        "w",
-        "e",
-        "r",
-        "t",
-        "y",
-        "u",
-        "i",
-        "o",
-        "p"
-      ];
-      const row2 = [
-        "a",
-        "s",
-        "d",
-        "f",
-        "g",
-        "h",
-        "j",
-        "k",
-        "l"
-      ];
-      const shiftArrowShapeOptions = {
-        path: {
-          // Public Domain from https://www.freesvg.org
-          pathString: "m288-6.6849e-14 -288 288h144v288h288v-288h144l-288-288z",
-          width: 24
-        },
-        lineWidth: 2,
-        strokeColor: WebColors.Black,
-        fillColor: WebColors.Transparent
-      };
-      const backspaceShapeOptions = {
-        path: {
-          // CC0 from https://www.svgrepo.com
-          pathString: "M10.625 5.09 0 22.09l10.625 17H44.18v-34H10.625zm31.555 32H11.734l-9.375-15 9.375-15H42.18v30zm-23.293-6.293 7.293-7.293 7.293 7.293 1.414-1.414-7.293-7.293 7.293-7.293-1.414-1.414-7.293 7.293-7.293-7.293-1.414 1.414 7.293 7.293-7.293 7.293",
-          width: 24
-        },
-        lineWidth: 1,
-        strokeColor: WebColors.Black,
-        fillColor: WebColors.Red
-      };
-      const row3 = [
-        {
-          code: "Shift",
-          isShift: true,
-          widthRatio: 1.5,
-          keyIcon: new Shape(shiftArrowShapeOptions)
-        },
-        "z",
-        "x",
-        "c",
-        "v",
-        "b",
-        "n",
-        "m",
-        {
-          code: "Backspace",
-          widthRatio: 1.5,
-          keyIcon: new Shape(backspaceShapeOptions)
-        }
-      ];
-      const row4 = [
-        { code: " ", labelText: "SPACE", widthRatio: 5 }
-      ];
-      const keyboardRows = [
-        numKeys,
-        row1,
-        row2,
-        row3,
-        row4
-      ];
-      this.rowsConfiguration = keyboardRows;
-      this.keysPerRow = this.rowsConfiguration.reduce(
+    if (this.game.eventStore.mode === EventStoreMode.Replay) {
+      this._isUserInteractionEnabled = false;
+    }
+    if (this.keyboardRows.length === 0) {
+      this.keyboardRows = this.createDefaultKeyboardRows();
+      this.keysPerRow = this.keyboardRows.reduce(
         (max, row) => Math.max(max, row.length),
         0
       );
-      this.fontSize = this.size.height / this.rowsConfiguration.length / 2.5;
+      this.fontSize = this.size.height / this.keyboardRows.length / 2.5;
     }
     const keyboardRectangle = new Shape({
       rect: { size: this.size },
-      fillColor: this.backgroundColor
+      fillColor: this.backgroundColor,
+      suppressEvents: true
     });
     this.addChild(keyboardRectangle);
-    const rows = this.rowsConfiguration.map((row) => {
-      return row.map((key) => {
-        let widthRatio = 1;
-        const heightRatio = 1;
-        let code;
-        let label;
-        let labelShifted;
-        let keyIcon;
-        let isShift = false;
-        if (typeof key === "string") {
-          code = key;
-          if (this.capitalLettersOnly) {
-            label = code.toUpperCase();
-          } else {
-            label = code;
-          }
-          labelShifted = code.toUpperCase();
-        } else if (Array.isArray(key)) {
-          code = key[0];
-          label = code;
-          labelShifted = key[1];
-        } else {
-          code = key.code;
-          label = key.labelText ?? "";
-          labelShifted = key.labelTextShifted ?? label;
-          widthRatio = key.widthRatio ?? 1;
-          keyIcon = key.keyIcon;
-          isShift = key.isShift ?? false;
-        }
-        return {
-          widthRatio,
-          heightRatio,
-          code,
-          labelText: label,
-          labelTextShifted: labelShifted,
-          keyIcon,
-          isShift
-        };
-      });
-    });
+    const keyboard = this.internalKeyboardRowsToInternalKeyboardConfiguration(
+      this.keyboardRows
+    );
     const keyboardOrigin = {
       x: -keyboardRectangle.size.width / 2,
       y: -keyboardRectangle.size.height / 2
     };
     const keyboardVerticalPadding = (this.keyboardVerticalPaddingPercent ?? 0.025) * this.size.height;
     const keyboardHorizontalPadding = (this.keyboardHorizontalPaddingPercent ?? 0.02) * this.size.width;
-    const keyBoxHeight = (this.size.height - 2 * keyboardVerticalPadding) / rows.length;
+    const keyBoxHeight = (this.size.height - 2 * keyboardVerticalPadding) / keyboard.length;
     const keyBoxWidth = (this.size.width - 2 * keyboardHorizontalPadding) / this.keysPerRow;
     this.keyShapes = [];
-    for (let r = 0; r < rows.length; r++) {
-      const row = rows[r];
+    for (let r = 0; r < keyboard.length; r++) {
+      const row = keyboard[r];
       const rowSumKeyWidths = row.reduce(
         (sum, key) => sum + (key.widthRatio ?? 1),
         0
@@ -1449,7 +1603,7 @@ class VirtualKeyboard extends Composite {
       }
       for (let k = 0; k < row.length; k++) {
         const key = row[k];
-        if (this.hiddenKeys?.split(",").map((s) => s.trim()).includes(key.code)) {
+        if (this.hiddenKeys?.split(",").map((s) => s === " " ? " " : s.trim()).includes(key.code)) {
           continue;
         }
         const keyBoxWidthsSoFar = row.slice(0, k).reduce((sum, key2) => sum + (key2.widthRatio ?? 1), 0) * keyBoxWidth;
@@ -1466,7 +1620,8 @@ class VirtualKeyboard extends Composite {
           position: {
             x: extraPadding + keyboardOrigin.x + keyboardHorizontalPadding + keyBoxWidthsSoFar + (key.widthRatio ?? 1) * keyBoxWidth / 2,
             y: keyboardOrigin.y + keyboardVerticalPadding + r * keyBoxHeight + keyBoxHeight / 2
-          }
+          },
+          suppressEvents: true
         });
         const keyWidth = keyBoxWidth * (key.widthRatio ?? 1) - 2 * this.keyHorizontalPaddingPercent * keyBoxWidth;
         const keyHeight = keyBoxHeight - (key.heightRatio ?? 1) - 2 * this.keyVerticalPaddingPercent * keyBoxHeight;
@@ -1475,164 +1630,50 @@ class VirtualKeyboard extends Composite {
           cornerRadius: 4,
           fillColor: this.keyColor,
           lineWidth: 0,
-          isUserInteractionEnabled: this.isUserInteractionEnabled
+          isUserInteractionEnabled: this.isUserInteractionEnabled,
+          suppressEvents: true
         });
+        keyShape.userData = { code: key.code };
         keyBox.addChild(keyShape);
         this.keyShapes.push(keyShape);
-        keyShape.onTapUp((tapEvent) => {
-          let keyAsString = "";
-          if (!key.isShift) {
-            if (this.shiftActivated) {
-              this.shiftActivated = false;
-              if (this.shiftKeyShape) {
-                this.shiftKeyShape.fillColor = this.keyColor;
-                if (key.keyIcon) {
-                  key.keyIcon.fillColor = WebColors.Transparent;
-                }
-              }
-              rows.flatMap((k2) => k2).forEach((k2) => {
-                if (k2.keyLabel?.text !== void 0) {
-                  k2.keyLabel.text = k2.labelText ?? "";
-                }
-              });
-              keyAsString = key.labelTextShifted ?? key.code;
-            } else {
-              keyAsString = key.labelText ?? key.code;
-            }
-            if (key.code === " " || key.code === "Backspace") {
-              keyAsString = key.code;
-            }
-            keyShape.fillColor = this.keyColor;
-          } else {
-            if (!this.shiftActivated) {
-              keyShape.fillColor = this.keyColor;
-            } else {
-              keyShape.fillColor = this.specialKeyDownColor;
-            }
-            keyAsString = key.code;
-          }
-          letterCircle.hidden = true;
-          if (this.eventListeners.length > 0) {
-            this.eventListeners.filter(
-              (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyUp"
-            ).forEach((listener) => {
-              const virtualKeyboardEvent = {
-                type: M2EventType.CompositeCustom,
-                target: this,
-                handled: false,
-                key: keyAsString,
-                code: key.code,
-                shiftKey: this.shiftActivated,
-                keyTapMetadata: {
-                  size: keyShape.size,
-                  point: tapEvent.point,
-                  buttons: tapEvent.buttons
-                }
-              };
-              listener.callback(virtualKeyboardEvent);
-            });
-          }
-        });
-        keyShape.onTapDown((tapEvent) => {
-          if (key.isShift) {
-            this.shiftActivated = !this.shiftActivated;
-            if (this.shiftActivated) {
-              keyShape.fillColor = this.specialKeyDownColor;
-              if (key.keyIcon) {
-                key.keyIcon.fillColor = WebColors.Black;
-              }
-              rows.flatMap((k2) => k2).forEach((k2) => {
-                if (k2.keyLabel?.text !== void 0) {
-                  k2.keyLabel.text = k2.labelTextShifted ?? k2.labelText ?? "";
-                }
-              });
-            } else {
-              keyShape.fillColor = this.keyColor;
-              if (key.keyIcon) {
-                key.keyIcon.fillColor = WebColors.Transparent;
-              }
-              rows.flatMap((k2) => k2).forEach((k2) => {
-                if (k2.keyLabel?.text !== void 0) {
-                  k2.keyLabel.text = k2.labelText ?? "";
-                }
-              });
-            }
-          }
-          let keyAsString = "";
-          if (key.isShift || key.code === " " || key.code === "Backspace") {
-            keyShape.fillColor = this.specialKeyDownColor;
-            keyAsString = key.code;
-          } else {
-            keyShape.fillColor = this.keyDownColor;
-            if (this.showKeyDownPreview) {
-              letterCircle.hidden = false;
-              letterCircle.position.x = keyBox.position.x;
-              letterCircle.position.y = keyBox.position.y - keyHeight * 1.2;
-              if (this.shiftActivated) {
-                letterCircleLabel.text = key.labelTextShifted ?? key.code;
-              } else {
-                letterCircleLabel.text = key.labelText ?? key.code;
-              }
-            }
-            if (this.shiftActivated) {
-              keyAsString = key.labelTextShifted ?? key.code;
-            } else {
-              keyAsString = key.labelText ?? key.code;
-            }
-          }
-          if (this.eventListeners.length > 0) {
-            this.eventListeners.filter(
-              (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyDown"
-            ).forEach((listener) => {
-              const virtualKeyboardEvent = {
-                type: M2EventType.CompositeCustom,
-                target: this,
-                handled: false,
-                key: keyAsString,
-                code: key.code,
-                shiftKey: this.shiftActivated,
-                keyTapMetadata: {
-                  size: keyShape.size,
-                  point: tapEvent.point,
-                  buttons: tapEvent.buttons
-                }
-              };
-              listener.callback(virtualKeyboardEvent);
-            });
-          }
-        });
-        keyShape.onTapLeave(() => {
-          keyShape.fillColor = this.keyColor;
-          letterCircle.hidden = true;
-        });
         const keyLabel = new Label({
           text: key.labelText,
           fontSize: this.fontSize,
-          fontNames: this.fontNames
+          fontNames: this.fontNames,
+          suppressEvents: true
         });
+        keyLabel.userData = { code: key.code };
         keyBox.addChild(keyLabel);
-        key.keyLabel = keyLabel;
-        if (key.isShift) {
-          this.shiftKeyShape = keyShape;
-        }
+        this.keyLabels.push(keyLabel);
         if (key.keyIcon) {
           keyBox.addChild(key.keyIcon);
         }
         keyboardRectangle.addChild(keyBox);
+        keyShape.onTapUp((tapEvent) => {
+          this.handleKeyShapeTapUp(key, keyShape, tapEvent);
+        });
+        keyShape.onTapDown((tapEvent) => {
+          this.handleKeyShapeTapDown(key, keyShape, tapEvent);
+        });
+        keyShape.onTapLeave((tapEvent) => {
+          this.handleKeyShapeTapLeave(key, keyShape, tapEvent);
+        });
       }
     }
-    const letterCircle = new Shape({
+    this.letterCircle = new Shape({
       circleOfRadius: 28,
       fillColor: WebColors.Silver,
-      hidden: true
+      hidden: true,
+      suppressEvents: true
     });
-    keyboardRectangle.addChild(letterCircle);
-    const letterCircleLabel = new Label({
+    keyboardRectangle.addChild(this.letterCircle);
+    this.letterCircleLabel = new Label({
       text: "",
       fontSize: this.fontSize,
-      fontNames: this.fontNames
+      fontNames: this.fontNames,
+      suppressEvents: true
     });
-    letterCircle.addChild(letterCircleLabel);
+    this.letterCircle.addChild(this.letterCircleLabel);
     this.needsInitialization = false;
   }
   /**
@@ -1643,8 +1684,9 @@ class VirtualKeyboard extends Composite {
    */
   onKeyDown(callback, options) {
     const eventListener = {
-      type: M2EventType.CompositeCustom,
-      compositeType: "VirtualKeyboardKeyDown",
+      type: M2EventType.Composite,
+      compositeEventType: "VirtualKeyboardKeyDown",
+      compositeType: this.compositeType,
       nodeUuid: this.uuid,
       callback
     };
@@ -1658,13 +1700,433 @@ class VirtualKeyboard extends Composite {
    */
   onKeyUp(callback, options) {
     const eventListener = {
-      type: M2EventType.CompositeCustom,
-      compositeType: "VirtualKeyboardKeyUp",
+      type: M2EventType.Composite,
+      compositeEventType: "VirtualKeyboardKeyUp",
+      compositeType: this.compositeType,
       nodeUuid: this.uuid,
       callback
     };
     this.addVirtualKeyboardEventListener(eventListener, options);
   }
+  /**
+   * Executes a callback when the user has pressed a key with the pointer, but
+   * moves the pointer outside the key bounds before releasing the pointer.
+   *
+   * @remarks Typically, this event will not be used, since it is a user's
+   * inaccurate interaction with the keyboard. However, it can be used to
+   * provide feedback to the user that they have moved the pointer outside the
+   * key bounds, and thus the key stroke will not be registered.
+   *
+   * @param callback - function to execute
+   * @param options
+   */
+  onKeyLeave(callback, options) {
+    const eventListener = {
+      type: M2EventType.Composite,
+      compositeEventType: "VirtualKeyboardKeyLeave",
+      compositeType: this.compositeType,
+      nodeUuid: this.uuid,
+      callback
+    };
+    this.addVirtualKeyboardEventListener(eventListener, options);
+  }
+  update() {
+    super.update();
+  }
+  draw(canvas) {
+    super.drawChildren(canvas);
+  }
+  warmup(canvas) {
+    this.initialize();
+    this.children.filter((child) => child.isDrawable).forEach((child) => {
+      child.warmup(canvas);
+    });
+  }
+  duplicate(newName) {
+    throw new Error(`Method not implemented. ${newName}`);
+  }
+  handleKeyShapeTapDown(key, keyShape, tapEvent) {
+    if (key.isShift) {
+      this.shiftActivated = !this.shiftActivated;
+    }
+    const keyAsString = this.getKeyAsString(key);
+    const virtualKeyboardEvent = {
+      type: M2EventType.Composite,
+      compositeType: "VirtualKeyboard",
+      compositeEventType: "VirtualKeyboardKeyDown",
+      target: this,
+      handled: false,
+      key: keyAsString,
+      code: key.code,
+      shiftKey: this.shiftActivated,
+      keyTapMetadata: {
+        size: keyShape.size,
+        point: tapEvent.point,
+        buttons: tapEvent.buttons
+      },
+      ...M2c2KitHelpers.createTimestamps()
+    };
+    this.handleCompositeEvent(virtualKeyboardEvent);
+    this.saveEvent(virtualKeyboardEvent);
+    if (this.eventListeners.length > 0) {
+      this.eventListeners.filter(
+        (listener) => listener.type === M2EventType.Composite && listener.compositeType === "VirtualKeyboard" && listener.compositeEventType === "VirtualKeyboardKeyDown"
+      ).forEach((listener) => {
+        listener.callback(virtualKeyboardEvent);
+      });
+    }
+  }
+  handleKeyShapeTapUp(key, keyShape, tapEvent) {
+    const keyAsString = this.getKeyAsString(key);
+    const virtualKeyboardEvent = {
+      type: M2EventType.Composite,
+      compositeType: "VirtualKeyboard",
+      compositeEventType: "VirtualKeyboardKeyUp",
+      target: this,
+      handled: false,
+      key: keyAsString,
+      code: key.code,
+      shiftKey: this.shiftActivated,
+      keyTapMetadata: {
+        size: keyShape.size,
+        point: tapEvent.point,
+        buttons: tapEvent.buttons
+      },
+      ...M2c2KitHelpers.createTimestamps()
+    };
+    this.handleCompositeEvent(virtualKeyboardEvent);
+    this.saveEvent(virtualKeyboardEvent);
+    if (this.eventListeners.length > 0) {
+      this.eventListeners.filter(
+        (listener) => listener.type === M2EventType.Composite && listener.compositeType === "VirtualKeyboard" && listener.compositeEventType === "VirtualKeyboardKeyUp"
+      ).forEach((listener) => {
+        listener.callback(virtualKeyboardEvent);
+      });
+    }
+  }
+  handleKeyShapeTapLeave(key, keyShape, tapEvent) {
+    const keyAsString = this.getKeyAsString(key);
+    const virtualKeyboardEvent = {
+      type: M2EventType.Composite,
+      compositeType: "VirtualKeyboard",
+      compositeEventType: "VirtualKeyboardKeyLeave",
+      target: this,
+      handled: false,
+      key: keyAsString,
+      code: key.code,
+      shiftKey: this.shiftActivated,
+      keyTapMetadata: {
+        size: keyShape.size,
+        point: tapEvent.point,
+        buttons: tapEvent.buttons
+      },
+      ...M2c2KitHelpers.createTimestamps()
+    };
+    this.handleCompositeEvent(virtualKeyboardEvent);
+    this.saveEvent(virtualKeyboardEvent);
+    if (this.eventListeners.length > 0) {
+      this.eventListeners.filter(
+        (listener) => listener.type === M2EventType.Composite && listener.compositeType === "VirtualKeyboard" && listener.compositeEventType === "VirtualKeyboardKeyLeave"
+      ).forEach((listener) => {
+        listener.callback(virtualKeyboardEvent);
+      });
+    }
+  }
+  getKeyAsString(key) {
+    if (key.isShift || key.code === " " || key.code === "Backspace") {
+      return key.code;
+    } else {
+      if (this.shiftActivated) {
+        return key.labelTextShifted ?? key.code;
+      } else {
+        return key.labelText ?? key.code;
+      }
+    }
+  }
+  /**
+   * Converts the keyboard rows to the internal keyboard configuration.
+   *
+   * @remarks This normalizes the keyboard rows so that each key is a
+   * full `KeyConfigurationWithShape` object, instead of a string or array of
+   * strings.
+   *
+   * @param keyboardRows
+   * @returns the keyboard for internal use
+   */
+  internalKeyboardRowsToInternalKeyboardConfiguration(keyboardRows) {
+    return keyboardRows.map((row) => {
+      return row.map((key) => {
+        let widthRatio = 1;
+        const heightRatio = 1;
+        let code;
+        let label;
+        let labelShifted;
+        let keyIcon;
+        let isShift = false;
+        if (typeof key === "string") {
+          code = key;
+          if (this.capitalLettersOnly) {
+            label = code.toUpperCase();
+          } else {
+            label = code;
+          }
+          labelShifted = code.toUpperCase();
+        } else if (Array.isArray(key)) {
+          code = key[0];
+          label = code;
+          labelShifted = key[1];
+        } else {
+          code = key.code;
+          label = key.labelText ?? "";
+          labelShifted = key.labelTextShifted ?? label;
+          widthRatio = key.widthRatio ?? 1;
+          keyIcon = key.keyIcon;
+          isShift = key.isShift ?? false;
+        }
+        return {
+          widthRatio,
+          heightRatio,
+          code,
+          labelText: label,
+          labelTextShifted: labelShifted,
+          keyIcon,
+          isShift
+        };
+      });
+    });
+  }
+  handleCompositeEvent(event) {
+    const keyboard = this.internalKeyboardRowsToInternalKeyboardConfiguration(
+      this.keyboardRows
+    );
+    const keyShape = this.keyShapes.find((k) => k.userData.code === event.code);
+    if (!keyShape) {
+      throw new Error("keyShape is not defined");
+    }
+    this.shiftActivated = event.shiftKey;
+    switch (event.compositeEventType) {
+      case "VirtualKeyboardKeyDown": {
+        this.handleKeyDownEvent(event, keyboard, keyShape);
+        break;
+      }
+      case "VirtualKeyboardKeyUp": {
+        this.handleKeyUpEvent(event, keyboard, keyShape);
+        break;
+      }
+      case "VirtualKeyboardKeyLeave": {
+        this.handleKeyLeaveEvent(event, keyboard, keyShape);
+        break;
+      }
+      default: {
+        throw new Error(
+          `Unknown VirtualKeyboardEvent: ${event.compositeEventType}`
+        );
+      }
+    }
+  }
+  handleKeyDownEvent(event, keyboard, keyShape) {
+    if (event.code.toLowerCase().includes("shift")) {
+      if (event.shiftKey) {
+        this.showKeyboardShifted(keyboard);
+      } else {
+        this.showKeyboardNotShifted(keyboard);
+      }
+    } else if (event.code === " " || event.code === "Backspace") {
+      keyShape.fillColor = this.specialKeyDownColor;
+    } else {
+      keyShape.fillColor = this.keyDownColor;
+      if (this.showKeyDownPreview) {
+        if (!this.letterCircle || !this.letterCircleLabel) {
+          throw new Error("letterCircle is not defined");
+        }
+        this.letterCircle.hidden = false;
+        const keyBox = keyShape.parent;
+        this.letterCircle.position.x = keyBox.position.x;
+        if (keyShape.rect?.size?.height === void 0) {
+          throw new Error("keyShape.rect.height is undefined");
+        }
+        this.letterCircle.position.y = keyBox.position.y - keyShape.rect.size.height * 1.2;
+        const keyboard2 = this.internalKeyboardRowsToInternalKeyboardConfiguration(
+          this.keyboardRows
+        );
+        const key = keyboard2.flat().find((k) => k.code === event.code);
+        if (!key) {
+          throw new Error("key is not defined");
+        }
+        if (this.shiftActivated) {
+          this.letterCircleLabel.text = key.labelTextShifted ?? key.code;
+        } else {
+          this.letterCircleLabel.text = key.labelText ?? key.code;
+        }
+      }
+    }
+  }
+  handleKeyUpEvent(event, keyboard, keyShape) {
+    if (event.code.toLowerCase().includes("shift") && event.shiftKey) {
+      return;
+    }
+    if (event.code.toLowerCase().includes("shift") && !event.shiftKey) {
+      this.shiftActivated = false;
+      this.showKeyboardNotShifted(keyboard);
+      return;
+    }
+    keyShape.fillColor = this.keyColor;
+    if (!this.letterCircle) {
+      throw new Error("letterCircle is not defined");
+    }
+    this.letterCircle.hidden = true;
+    if (!event.code.toLowerCase().includes("shift") && event.shiftKey) {
+      this.shiftActivated = false;
+      this.showKeyboardNotShifted(keyboard);
+    }
+  }
+  handleKeyLeaveEvent(event, keyboard, keyShape) {
+    if (event.code.toLowerCase().includes("shift")) {
+      if (event.shiftKey) {
+        this.showKeyboardNotShifted(keyboard);
+        this.shiftActivated = false;
+      } else {
+        this.showKeyboardShifted(keyboard);
+        this.shiftActivated = true;
+      }
+      return;
+    }
+    keyShape.fillColor = this.keyColor;
+    if (!this.letterCircle) {
+      throw new Error("letterCircle is not defined");
+    }
+    this.letterCircle.hidden = true;
+  }
+  showKeyboardShifted(keyboard) {
+    const shiftKeyShapes = this.keyShapes.filter(
+      (shape) => shape.userData.code.toLowerCase().includes("shift")
+    );
+    shiftKeyShapes.forEach((shape) => {
+      shape.fillColor = this.specialKeyDownColor;
+    });
+    const shiftKeys = keyboard.flat().filter((k) => k.isShift);
+    shiftKeys.forEach((k) => {
+      if (k.keyIcon) {
+        k.keyIcon.fillColor = WebColors.Black;
+      }
+    });
+    keyboard.flatMap((k) => k).forEach((k) => {
+      const keyLabel = this.keyLabels.find((l) => l.userData.code === k.code);
+      if (!keyLabel) {
+        throw new Error("keyLabel is not defined");
+      }
+      if (keyLabel.text !== void 0) {
+        keyLabel.text = k.labelTextShifted ?? "";
+      }
+    });
+  }
+  showKeyboardNotShifted(keyboard) {
+    const shiftKeyShapes = this.keyShapes.filter(
+      (shape) => shape.userData.code.toLowerCase().includes("shift")
+    );
+    shiftKeyShapes.forEach((shape) => {
+      shape.fillColor = this.keyColor;
+    });
+    const shiftKeys = keyboard.flat().filter((k) => k.isShift);
+    shiftKeys.forEach((k) => {
+      if (k.keyIcon) {
+        k.keyIcon.fillColor = WebColors.Transparent;
+      }
+    });
+    keyboard.flatMap((k) => k).forEach((k) => {
+      const keyLabel = this.keyLabels.find((l) => l.userData.code === k.code);
+      if (!keyLabel) {
+        throw new Error("keyLabel is not defined");
+      }
+      if (keyLabel.text !== void 0) {
+        keyLabel.text = k.labelText ?? "";
+      }
+    });
+  }
+  createDefaultKeyboardRows() {
+    const numKeys = [
+      ["1", "!"],
+      ["2", "@"],
+      ["3", "#"],
+      ["4", "$"],
+      ["5", "%"],
+      ["6", "^"],
+      ["7", "&"],
+      ["8", "*"],
+      ["9", "("],
+      ["0", ")"]
+    ];
+    const row1 = [
+      "q",
+      "w",
+      "e",
+      "r",
+      "t",
+      "y",
+      "u",
+      "i",
+      "o",
+      "p"
+    ];
+    const row2 = [
+      "a",
+      "s",
+      "d",
+      "f",
+      "g",
+      "h",
+      "j",
+      "k",
+      "l"
+    ];
+    const shiftArrowShapeOptions = {
+      path: {
+        // Public Domain from https://www.freesvg.org
+        pathString: "m288-6.6849e-14 -288 288h144v288h288v-288h144l-288-288z",
+        width: 24
+      },
+      lineWidth: 2,
+      strokeColor: WebColors.Black,
+      fillColor: WebColors.Transparent,
+      suppressEvents: true
+    };
+    const backspaceShapeOptions = {
+      path: {
+        // CC0 from https://www.svgrepo.com
+        pathString: "M10.625 5.09 0 22.09l10.625 17H44.18v-34H10.625zm31.555 32H11.734l-9.375-15 9.375-15H42.18v30zm-23.293-6.293 7.293-7.293 7.293 7.293 1.414-1.414-7.293-7.293 7.293-7.293-1.414-1.414-7.293 7.293-7.293-7.293-1.414 1.414 7.293 7.293-7.293 7.293",
+        width: 24
+      },
+      lineWidth: 1,
+      strokeColor: WebColors.Black,
+      fillColor: WebColors.Red,
+      suppressEvents: true
+    };
+    const row3 = [
+      {
+        code: "Shift",
+        isShift: true,
+        widthRatio: 1.5,
+        keyIcon: new Shape(shiftArrowShapeOptions)
+      },
+      "z",
+      "x",
+      "c",
+      "v",
+      "b",
+      "n",
+      "m",
+      {
+        code: "Backspace",
+        widthRatio: 1.5,
+        keyIcon: new Shape(backspaceShapeOptions)
+      }
+    ];
+    const row4 = [
+      { code: " ", labelText: "SPACE", widthRatio: 5 }
+    ];
+    const keyboardRows = [numKeys, row1, row2, row3, row4];
+    return keyboardRows;
+  }
   addVirtualKeyboardEventListener(eventListener, options) {
     if (options?.replaceExisting) {
       this.eventListeners = this.eventListeners.filter(
@@ -1684,26 +2146,14 @@ class VirtualKeyboard extends Composite {
    */
   set isUserInteractionEnabled(isUserInteractionEnabled) {
     this._isUserInteractionEnabled = isUserInteractionEnabled;
-    this.keyShapes.forEach((keyShape) => {
+    this.keyShapes?.forEach((keyShape) => {
       keyShape.isUserInteractionEnabled = isUserInteractionEnabled;
     });
   }
-  update() {
-    super.update();
-  }
-  draw(canvas) {
-    super.drawChildren(canvas);
-  }
-  warmup(canvas) {
-    this.initialize();
-    this.children.filter((child) => child.isDrawable).forEach((child) => {
-      child.warmup(canvas);
-    });
-  }
-  duplicate(newName) {
-    throw new Error(`Method not implemented. ${newName}`);
-  }
 }
+M2c2KitHelpers.registerM2NodeClass(
+  VirtualKeyboard
+);
 
 const SCENE_TRANSITION_EASING$1 = Easings.sinusoidalInOut;
 const SCENE_TRANSITION_DURATION = 500;
@@ -2079,7 +2529,6 @@ class LocalePicker extends Composite {
   constructor(options) {
     super(options);
     this.compositeType = "LocalePicker";
-    this.zPosition = Number.MAX_VALUE;
     this.DEFAULT_FONT_SIZE = 24;
     this.automaticallyChangeLocale = true;
     this._localeOptions = new Array();
@@ -2107,6 +2556,7 @@ class LocalePicker extends Composite {
      */
     this.LEFT_SELECTION_INDICATOR = "\xAB";
     this.RIGHT_SELECTION_INDICATOR = "\xBB";
+    this.zPosition = Number.MAX_VALUE;
     if (!options) {
       return;
     }
@@ -2146,7 +2596,7 @@ class LocalePicker extends Composite {
    */
   onResult(callback, options) {
     const eventListener = {
-      type: M2EventType.CompositeCustom,
+      type: M2EventType.Composite,
       compositeType: "LocalePickerResult",
       nodeUuid: this.uuid,
       callback
@@ -2200,10 +2650,10 @@ class LocalePicker extends Composite {
     }
     const overlay = new Shape({
       rect: {
-        width: Globals.canvasCssWidth,
-        height: Globals.canvasCssHeight,
-        x: Globals.canvasCssWidth / 2,
-        y: Globals.canvasCssHeight / 2
+        width: m2c2Globals.canvasCssWidth,
+        height: m2c2Globals.canvasCssHeight,
+        x: m2c2Globals.canvasCssWidth / 2,
+        y: m2c2Globals.canvasCssHeight / 2
       },
       fillColor: [0, 0, 0, this.overlayAlpha],
       zPosition: -1,
@@ -2215,12 +2665,16 @@ class LocalePicker extends Composite {
       if (this.eventListeners.length > 0) {
         this.eventListeners.filter((listener) => listener.type === "LocalePickerResult").forEach((listener) => {
           const languagePickerEvent = {
-            type: "LocalePickerResult",
+            type: M2EventType.Composite,
+            compositeType: this.compositeType,
+            compositeEventType: "LocalePickerResult",
             target: this,
             handled: false,
             result: {
               locale: void 0
-            }
+            },
+            timestamp: Timer.now(),
+            iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
           };
           listener.callback(languagePickerEvent);
         });
@@ -2230,10 +2684,10 @@ class LocalePicker extends Composite {
     this.addChild(overlay);
     const lineHeight = this.fontSize / this.DEFAULT_FONT_SIZE * 50;
     const dialogHeight = this.localeOptions.length * lineHeight;
-    const dialogWidth = Globals.canvasCssWidth / 2;
+    const dialogWidth = m2c2Globals.canvasCssWidth / 2;
     const sceneCenter = {
-      x: Globals.canvasCssWidth / 2,
-      y: Globals.canvasCssHeight / 2
+      x: m2c2Globals.canvasCssWidth / 2,
+      y: m2c2Globals.canvasCssHeight / 2
     };
     const localeDialog = new Shape({
       rect: {
@@ -2335,16 +2789,19 @@ class LocalePicker extends Composite {
     e.handled = true;
     if (this.eventListeners.length > 0) {
       this.eventListeners.filter(
-        (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "LocalePickerResult" && listener.nodeUuid == this.uuid
+        (listener) => listener.type === M2EventType.Composite && listener.compositeType === "LocalePickerResult" && listener.nodeUuid == this.uuid
       ).forEach((listener) => {
         const languagePickerEvent = {
-          type: M2EventType.CompositeCustom,
-          compositeType: "LocalePickerResult",
+          type: M2EventType.Composite,
+          compositeType: this.compositeType,
+          compositeEventType: "LocalePickerResult",
           target: this,
           handled: false,
           result: {
             locale: localeOption.locale
-          }
+          },
+          timestamp: Timer.now(),
+          iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
         listener.callback(languagePickerEvent);
       });
@@ -2508,7 +2965,7 @@ class LocalePicker extends Composite {
   }
 }
 
-console.log("\u26AA @m2c2kit/addons version 0.3.15 (b3a70752)");
+console.log("\u26AA @m2c2kit/addons version 0.3.16 (0679492d)");
 
 export { Button, CountdownScene, Dialog, DialogResult, DrawPad, DrawPadEventType, DrawPadItemEventType, Grid, Instructions, LocalePicker, VirtualKeyboard };
 //# sourceMappingURL=index.js.map