@m2c2kit/core 0.3.15 → 0.3.16

package/dist/index.d.ts

@@ -726,12 +726,21 @@ interface CallbackOptions {
 }
 
 /**
- * Notifies when events in the Frame cycle occur on a Game.
+ * A Plugin is code that can be registered to run at certain points in the game loop.
  */
-interface FrameCycleEvent extends EventBase {
-    target: Game;
-    /** difference in milliseconds since the last Frame lifecycle began */
-    deltaTime: number;
+interface Plugin {
+    /** Short identifier of the plugin. */
+    id: string;
+    /** What kind of m2c2kit object does the plugin work with? */
+    type: "Game" | "Session" | "Survey";
+    /** Initialization code run when the plugin is registered with the game. */
+    initialize?: (game: Game) => Promise<void>;
+    /** Is the plugin disabled and not to be run? Default is false. @remarks Disabled plugins will still be initialized. */
+    disabled?: boolean;
+    /** Plugin code run before the frame update, but before the frame draw. */
+    beforeUpdate?: (game: Game, deltaTime: number) => void;
+    /** Plugin code run after the frame update, but before the frame draw. */
+    afterUpdate?: (game: Game, deltaTime: number) => void;
 }
 
 interface TrialData {
@@ -757,6 +766,7 @@ declare class Game implements Activity {
     private warmupFunctionQueue;
     private loaderElementsRemoved;
     private _dataStores?;
+    private plugins;
     additionalParameters?: unknown;
     staticTrialSchema: {
         [key: string]: JsonSchemaDataTypeScriptTypes;
@@ -983,7 +993,7 @@ declare class Game implements Activity {
      * is not found, then return fallback value
      *
      * @param parameterName - the name of the game parameter whose value is requested
-     * @param fallback - the value to return if parameterName is not found
+     * @param fallbackValue - the value to return if parameterName is not found
      * @returns
      */
     getParameterOrFallback<T, U>(parameterName: string, fallbackValue: U): T | U;
@@ -1171,12 +1181,14 @@ declare class Game implements Activity {
      */
     private createOutgoingScene;
     /**
-     * Executes a callback when the frame has finished simulating physics.
+     * Registers a plugin with the game.
      *
-     * @param callback - function to execute.
-     * @param options - options for the callback.
+     * @remarks Upon registration, the plugin's optional asynchronous
+     * `initialize()` method will be called.
+     *
+     * @param plugin - Plugin to register
      */
-    onFrameDidSimulatePhysics(callback: (frameCycleEvent: FrameCycleEvent) => void, options?: CallbackOptions): void;
+    registerPlugin(plugin: Plugin): Promise<void>;
     private update;
     private draw;
     private calculateFps;
@@ -1224,17 +1236,6 @@ declare class Game implements Activity {
     private htmlCanvasPointerDownHandler;
     private htmlCanvasPointerUpHandler;
     private htmlCanvasPointerMoveHandler;
-    /**
-     * Adjusts dragging behavior when the pointer leaves the canvas
-     *
-     * @remarks This is necessary because the pointerup event is not fired when
-     * the pointer leaves the canvas. On desktop, this means that the user might
-     * lift the pointer outside the canvas, but the entity will still be dragged
-     * when the pointer is moved back into the canvas.
-     *
-     * @param domPointerEvent
-     * @returns
-     */
     private htmlCanvasPointerLeaveHandler;
     /**
      * Determines if/how m2c2kit entities respond to the DOM PointerDown event
@@ -1246,6 +1247,7 @@ declare class Game implements Activity {
     private processDomPointerDown;
     private processDomPointerUp;
     private processDomPointerMove;
+    private processDomPointerLeave;
     private raiseM2PointerDownEvent;
     private raiseTapDownEvent;
     private raiseTapLeaveEvent;
@@ -1688,7 +1690,7 @@ interface EventBase {
     /** Type of event. */
     type: EventType | string;
     /** The object on which the event occurred. */
-    target: Entity | Session | Activity;
+    target: Entity | Session | Activity | Plugin;
     /** Has the event been taken care of by the listener and not be dispatched to other targets? */
     handled?: boolean;
 }
@@ -1794,10 +1796,10 @@ declare abstract class Entity implements EntityOptions {
     isShape: boolean;
     isText: boolean;
     name: string;
-    position: Point;
-    scale: number;
+    _position: Point;
+    _scale: number;
     alpha: number;
-    zRotation: number;
+    _zRotation: number;
     isUserInteractionEnabled: boolean;
     draggable: boolean;
     hidden: boolean;
@@ -2095,6 +2097,12 @@ declare abstract class Entity implements EntityOptions {
      */
     get canvasKit(): CanvasKit;
     get parentSceneAsEntity(): Entity;
+    get position(): Point;
+    set position(position: Point);
+    get zRotation(): number;
+    set zRotation(zRotation: number);
+    get scale(): number;
+    set scale(scale: number);
     /**
      * For a given directed acyclic graph, topological ordering of the vertices will be identified using BFS
      * @param adjList Adjacency List that represent a graph with vertices and edges
@@ -3263,4 +3271,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, type Activity, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DrawableOptions, type EasingFunction, Easings, Entity, type EntityEvent, type EntityEventListener, type EntityOptions, EntityType, Equals, type EventBase, type EventListenerBase, EventType, FadeAlphaAction, type FadeAlphaActionOptions, type FontData, FontManager, Game, type GameData, type GameOptions, type GameParameters, GlobalVariables, type GoToActivityOptions, GroupAction, I18n, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LoadedImage, type M2ColorfulPath, type M2DragEvent, type M2Path, type M2PointerEvent, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, type Point, RandomDraws, type RectOptions, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, SceneTransition, SequenceAction, Session, type SessionDictionaryValues, type SessionLifecycleEvent, type SessionOptions, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, Sprite, type SpriteOptions, Story, type StoryOptions, type TapEvent, TextLine, type TextLineOptions, type TextOptions, Timer, Transition, TransitionDirection, TransitionType, type Translations, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, type Activity, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DrawableOptions, type EasingFunction, Easings, Entity, type EntityEvent, type EntityEventListener, type EntityOptions, EntityType, Equals, type EventBase, type EventListenerBase, EventType, FadeAlphaAction, type FadeAlphaActionOptions, type FontData, FontManager, Game, type GameData, type GameOptions, type GameParameters, GlobalVariables, type GoToActivityOptions, GroupAction, I18n, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LoadedImage, type M2ColorfulPath, type M2DragEvent, type M2Path, type M2PointerEvent, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, type Plugin, type Point, RandomDraws, type RectOptions, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, SceneTransition, SequenceAction, Session, type SessionDictionaryValues, type SessionLifecycleEvent, type SessionOptions, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, Sprite, type SpriteOptions, Story, type StoryOptions, type TapEvent, TextLine, type TextLineOptions, type TextOptions, Timer, Transition, TransitionDirection, TransitionType, type Translations, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };

package/dist/index.js

@@ -1515,11 +1515,11 @@ class Entity {
     this.isDrawable = false;
     this.isShape = false;
     this.isText = false;
-    this.position = { x: 0, y: 0 };
+    this._position = { x: 0, y: 0 };
     // position of the entity in the parent coordinate system
-    this.scale = 1;
+    this._scale = 1;
     this.alpha = 1;
-    this.zRotation = 0;
+    this._zRotation = 0;
     this.isUserInteractionEnabled = false;
     this.draggable = false;
     this.hidden = false;
@@ -2352,6 +2352,38 @@ class Entity {
     }
     throw new Error(`Entity ${this} has not been added to a scene`);
   }
+  get position() {
+    const entity = this;
+    return {
+      get x() {
+        return entity._position.x;
+      },
+      set x(x) {
+        entity._position.x = x;
+      },
+      get y() {
+        return entity._position.y;
+      },
+      set y(y) {
+        entity._position.y = y;
+      }
+    };
+  }
+  set position(position) {
+    this._position = position;
+  }
+  get zRotation() {
+    return this._zRotation;
+  }
+  set zRotation(zRotation) {
+    this._zRotation = zRotation;
+  }
+  get scale() {
+    return this._scale;
+  }
+  set scale(scale) {
+    this._scale = scale;
+  }
   // 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
@@ -3670,6 +3702,7 @@ class Game {
     this.steppingNow = 0;
     this.warmupFunctionQueue = new Array();
     this.loaderElementsRemoved = false;
+    this.plugins = [];
     this.staticTrialSchema = {};
     this.data = {
       trials: new Array()
@@ -4117,7 +4150,7 @@ class Game {
    * is not found, then return fallback value
    *
    * @param parameterName - the name of the game parameter whose value is requested
-   * @param fallback - the value to return if parameterName is not found
+   * @param fallbackValue - the value to return if parameterName is not found
    * @returns
    */
   getParameterOrFallback(parameterName, fallbackValue) {
@@ -5112,27 +5145,34 @@ class Game {
     return outgoingScene;
   }
   /**
-   * Executes a callback when the frame has finished simulating physics.
+   * Registers a plugin with the game.
    *
-   * @param callback - function to execute.
-   * @param options - options for the callback.
+   * @remarks Upon registration, the plugin's optional asynchronous
+   * `initialize()` method will be called.
+   *
+   * @param plugin - Plugin to register
    */
-  onFrameDidSimulatePhysics(callback, options) {
-    this.addEventListener(
-      EventType.FrameDidSimulatePhysics,
-      callback,
-      options
-    );
+  async registerPlugin(plugin) {
+    if (plugin.type !== ActivityType.Game) {
+      throw new Error(
+        `registerPlugin(): plugin ${plugin.id} is not a game plugin. It is a ${plugin.type} plugin.`
+      );
+    }
+    if (this.plugins.includes(plugin) || this.plugins.map((p) => p.id).includes(plugin.id)) {
+      throw new Error(
+        `registerPlugin(): plugin ${plugin.id} already registered.`
+      );
+    }
+    this.plugins.push(plugin);
+    if (plugin.initialize) {
+      await plugin.initialize(this);
+    }
   }
   update() {
+    this.plugins.filter((p) => p.beforeUpdate !== void 0 && p.disabled !== true).forEach((p) => p.beforeUpdate(this, Globals.deltaTime));
     this.scenes.filter((scene) => scene._active).forEach((scene) => scene.update());
     this.freeEntitiesScene.update();
-    const frameDidSimulatePhysicsEvent = {
-      target: this,
-      type: EventType.FrameDidSimulatePhysics,
-      deltaTime: Globals.deltaTime
-    };
-    this.raiseActivityEventOnListeners(frameDidSimulatePhysicsEvent);
+    this.plugins.filter((p) => p.afterUpdate !== void 0 && p.disabled !== true).forEach((p) => p.afterUpdate(this, Globals.deltaTime));
   }
   draw(canvas) {
     this.scenes.filter((scene) => scene._active).forEach((scene) => scene.draw(canvas));
@@ -5546,35 +5586,26 @@ class Game {
       domPointerEvent
     );
   }
-  /**
-   * Adjusts dragging behavior when the pointer leaves the canvas
-   *
-   * @remarks This is necessary because the pointerup event is not fired when
-   * the pointer leaves the canvas. On desktop, this means that the user might
-   * lift the pointer outside the canvas, but the entity will still be dragged
-   * when the pointer is moved back into the canvas.
-   *
-   * @param domPointerEvent
-   * @returns
-   */
   htmlCanvasPointerLeaveHandler(domPointerEvent) {
     if (!this.currentScene) {
       return;
     }
-    this.currentScene.children.forEach((entity) => {
-      if (entity.dragging) {
-        const m2Event = {
-          target: entity,
-          type: EventType.DragEnd,
-          handled: false
-        };
-        entity.dragging = false;
-        entity.pressed = false;
-        entity.pressedAndWithinHitArea = false;
-        this.raiseM2DragEndEvent(entity, m2Event, domPointerEvent);
-        return;
-      }
-    });
+    domPointerEvent.preventDefault();
+    const scene = this.currentScene;
+    if (!scene || !this.sceneCanReceiveUserInteraction(scene)) {
+      return;
+    }
+    const m2Event = {
+      target: scene,
+      type: EventType.PointerLeave,
+      handled: false
+    };
+    this.processDomPointerLeave(scene, m2Event, domPointerEvent);
+    this.processDomPointerLeave(
+      this.freeEntitiesScene,
+      m2Event,
+      domPointerEvent
+    );
   }
   /**
    * Determines if/how m2c2kit entities respond to the DOM PointerDown event
@@ -5687,7 +5718,7 @@ class Game {
       entity.pressedAndWithinHitArea = false;
       this.raiseTapLeaveEvent(entity, m2Event, domPointerEvent);
     }
-    if (this.IsCanvasPointWithinEntityBounds(
+    if (entity.isUserInteractionEnabled && this.IsCanvasPointWithinEntityBounds(
       entity,
       domPointerEvent.offsetX,
       domPointerEvent.offsetY
@@ -5695,15 +5726,13 @@ class Game {
       this.raiseM2PointerMoveEvent(entity, m2Event, domPointerEvent);
       entity.withinHitArea = true;
     }
-    if (!this.IsCanvasPointWithinEntityBounds(
+    if (entity.isUserInteractionEnabled && entity.withinHitArea && !this.IsCanvasPointWithinEntityBounds(
       entity,
       domPointerEvent.offsetX,
       domPointerEvent.offsetY
     )) {
-      if (entity.withinHitArea) {
-        this.raiseM2PointerLeaveEvent(entity, m2Event, domPointerEvent);
-        entity.withinHitArea = false;
-      }
+      entity.withinHitArea = false;
+      this.raiseM2PointerLeaveEvent(entity, m2Event, domPointerEvent);
     }
     if (entity.children) {
       entity.children.filter((entity2) => !entity2.hidden).filter((entity2) => entity2.isDrawable).sort(
@@ -5713,6 +5742,46 @@ class Game {
       );
     }
   }
+  processDomPointerLeave(entity, m2Event, domPointerEvent) {
+    if (m2Event.handled) {
+      return;
+    }
+    if (entity.dragging) {
+      const m2Event2 = {
+        target: entity,
+        type: EventType.DragEnd,
+        handled: false
+      };
+      entity.dragging = false;
+      entity.pressed = false;
+      entity.pressedAndWithinHitArea = false;
+      this.raiseM2DragEndEvent(entity, m2Event2, domPointerEvent);
+      return;
+    }
+    if (entity.isUserInteractionEnabled && entity.pressed && entity.pressedAndWithinHitArea && !this.IsCanvasPointWithinEntityBounds(
+      entity,
+      domPointerEvent.offsetX,
+      domPointerEvent.offsetY
+    )) {
+      entity.pressedAndWithinHitArea = false;
+      this.raiseTapLeaveEvent(entity, m2Event, domPointerEvent);
+    }
+    if (entity.isUserInteractionEnabled && entity.withinHitArea && !this.IsCanvasPointWithinEntityBounds(
+      entity,
+      domPointerEvent.offsetX,
+      domPointerEvent.offsetY
+    )) {
+      entity.withinHitArea = false;
+      this.raiseM2PointerLeaveEvent(entity, m2Event, domPointerEvent);
+    }
+    if (entity.children) {
+      entity.children.filter((entity2) => !entity2.hidden).filter((entity2) => entity2.isDrawable).sort(
+        (a, b) => b.zPosition - a.zPosition
+      ).forEach(
+        (entity2) => this.processDomPointerLeave(entity2, m2Event, domPointerEvent)
+      );
+    }
+  }
   raiseM2PointerDownEvent(entity, m2Event, domPointerEvent) {
     m2Event.target = entity;
     m2Event.type = EventType.PointerDown;
@@ -7422,7 +7491,7 @@ class Session {
     this.eventListeners = new Array();
     this.sessionDictionary = /* @__PURE__ */ new Map();
     this.initialized = false;
-    this.version = "0.3.15 (38470c49)";
+    this.version = "0.3.16 (d8a00e86)";
     this.options = options;
     for (const activity of this.options.activities) {
       if (this.options.activities.filter((a) => a === activity).length > 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2c2kit/core",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "The m2c2kit core functionality",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -48,7 +48,7 @@
     "jest-environment-jsdom": "29.7.0",
     "jsdom": "23.0.1",
     "rimraf": "5.0.5",
-    "rollup": "4.8.0",
+    "rollup": "4.9.2",
     "rollup-plugin-copy": "3.5.0",
     "rollup-plugin-dts": "6.1.0",
     "rollup-plugin-esbuild": "6.1.0",