@m2c2kit/core 0.3.30 → 0.3.32

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as canvaskit_wasm from 'canvaskit-wasm';
 import { Canvas, Typeface, TypefaceFontProvider, Image, Paint, CanvasKit, Surface, Font, ParagraphBuilder, Paragraph, FontMgr, Path, PaintStyle } from 'canvaskit-wasm';
 
 /**
@@ -1006,6 +1007,10 @@ interface GameOptions extends LocalizationOptions {
     moduleMetadata?: ModuleMetadata;
 }
 
+interface TrialData {
+    [key: string]: string | number | boolean | object | undefined | null;
+}
+
 interface GameData extends ActivityKeyValueData {
     trials: Array<TrialData>;
     scoring: ActivityKeyValueData;
@@ -1556,9 +1561,316 @@ declare class EventMaterializer {
     private materializeScenePresentEvent;
 }
 
-interface TrialData {
-    [key: string]: string | number | boolean | object | undefined | null;
+declare class InputManager {
+    private game;
+    private htmlCanvas;
+    constructor(game: Game, htmlCanvas: HTMLCanvasElement);
+    dispose(): void;
+    private addEventListeners;
+    private removeEventListeners;
+    private touchStartHandler;
+    /**
+     * Receives callback from DOM PointerDown event
+     *
+     * @param domPointerEvent - PointerEvent from the DOM
+     * @returns
+     */
+    private htmlCanvasPointerDownHandler;
+    private htmlCanvasPointerUpHandler;
+    private htmlCanvasPointerMoveHandler;
+    private htmlCanvasPointerLeaveHandler;
+    private documentKeyDownHandler;
+    private documentKeyUpHandler;
+    /**
+     * Determines if/how m2c2kit nodes respond to the DOM PointerDown event
+     *
+     * @param node - node that might be affected by the DOM PointerDown event
+     * @param nodeEvent
+     * @param domPointerEvent
+     */
+    private processDomPointerDown;
+    private processDomPointerUp;
+    private processDomPointerMove;
+    private processDomPointerLeave;
+    private raiseEventOnListeningNodes;
+    private raiseM2PointerDownEvent;
+    private raiseTapDownEvent;
+    private raiseTapLeaveEvent;
+    private raiseM2PointerUpEvent;
+    private raiseTapUpEvent;
+    private raiseTapUpAny;
+    private raiseM2PointerMoveEvent;
+    private raiseM2PointerLeaveEvent;
+    private raiseM2DragStartEvent;
+    private raiseM2DragEvent;
+    private raiseM2DragEndEvent;
+    private sceneCanReceiveUserInteraction;
+    /**
+     *
+     * Checks if the given canvas point is within the node's bounds.
+     *
+     * @param node - node to check bounds for
+     * @param x - x coordinate of the canvas point
+     * @param y - y coordinate of the canvas point
+     * @returns true if x, y point is within the node's bounds
+     */
+    private IsCanvasPointWithinNodeBounds;
+    private calculatePointWithinNodeFromDomPointerEvent;
+}
+
+declare class SceneManager {
+    private game;
+    scenes: Scene[];
+    freeNodesScene: Scene;
+    currentScene?: Scene;
+    incomingSceneTransitions: SceneTransition[];
+    snapshots: Image[];
+    private currentSceneSnapshot?;
+    private pendingScreenshot?;
+    constructor(game: Game);
+    /**
+     * Clears the current game scene by setting it to undefined.
+     */
+    clearCurrentScene(): void;
+    /**
+     * Updates all active scenes and their children.
+     */
+    updateScenes(): void;
+    /**
+     * Draws all active scenes and their children on the provided canvas.
+     *
+     * @param canvas - the canvas to draw the scenes on
+     */
+    drawScenes(canvas: Canvas): void;
+    /**
+     * Adds events from a node and its children to the game's event store.
+     *
+     * @remarks This method is first called when a scene is added to the game.
+     * If the scene or any of its descendants was constructed or had its
+     * properties changed before it was added to the game, these events were
+     * stored within the node (because the game event store was not yet
+     * available). This method retrieves these events from the node and adds
+     * them to the game's event store.
+     *
+     * @param node - node that contains events to add
+     */
+    private addNodeEvents;
+    /**
+     * Adds a scene to the game.
+     *
+     * @remarks A scene, and its children nodes, cannot be presented unless it
+     * has been added to the game object. A scene can be added to the game
+     * only once.
+     *
+     * @param scene
+     */
+    add(scene: Scene): void;
+    /**
+     * Removes a scene from the game.
+     *
+     * @param scene - the scene to remove or its name as a string
+     */
+    remove(scene: Scene | string): void;
+    /**
+     * Specifies the scene that will be presented upon the next frame draw.
+     *
+     * @param scene - the scene, its string name, or UUID
+     * @param transition
+     */
+    present(scene: string | Scene, transition?: Transition): void;
+    handleIncomingSceneTransitions(): void;
+    /**
+     * Creates a scene that has a screen shot of the current scene.
+     *
+     * @param outgoingSceneImage - an image of the current scene
+     * @returns - the scene with the screen shot
+     */
+    private createOutgoingScene;
+    private animateSceneTransition;
+    /**
+     * Takes screenshot of canvas
+     *
+     * @remarks Coordinates should be provided unscaled; that is, the method
+     * will handle any scaling that happened due to device pixel ratios
+     * not equal to 1. This returns a promise because the screenshot request
+     * must be queued and completed once a draw cycle has completed. See
+     * the handleScreenshots() method.
+     *
+     * @param sx - Upper left coordinate of screenshot
+     * @param sy - Upper right coordinate of screenshot
+     * @param sw - width of area to screenshot
+     * @param sh - height of area to screenshot
+     * @returns Promise of Uint8Array of image data
+     */
+    takeScreenshot(sx?: number, sy?: number, sw?: number, sh?: number): Promise<Uint8Array | null>;
+    /**
+     * Handles game screenshots.
+     *
+     * @remarks This is called on every iteration of the game loop.
+     * In prior versions, I took a snapshot only when needed, e.g.,
+     * after a new scene transition was requested. From performance testing,
+     * however, I found that taking a snapshot has negligible impact on
+     * performance. It is only encoding the image to bytes, i.e.,
+     * image.encodeToBytes(), that is expensive. Thus, we can take a snapshot
+     * after every draw, in case we'll need the snapshot. IMPORTANT: snapshots
+     * must be deleted when not needed, otherwise we will create a massive memory
+     * leak because we are creating them 60 times per second.
+     */
+    handleScreenshots(): void;
+    takeCurrentSceneSnapshot(): Image;
+    private handlePendingScreenshot;
+    private raiseSceneEvent;
+    private createFreeNodesScene;
+    get freeNodes(): Array<M2Node>;
+    addFreeNode(node: M2Node): void;
+    removeFreeNode(node: M2Node | string): void;
+    removeAllFreeNodes(): void;
+}
+
+interface DeviceMetadata {
+    userAgent?: string;
+    devicePixelRatio?: number;
+    screen?: screenMetadata;
+    webGlRenderer?: string;
+}
+/**
+ * screenMetadata is similar to window.Screen, except we don't want the
+ * methods on the window.Screen.ScreenOrientation
+ */
+interface screenMetadata {
+    readonly availHeight: number;
+    readonly availWidth: number;
+    readonly colorDepth: number;
+    readonly height: number;
+    /** ScreenOrientation has some methods on it; we only want these two properties
+     * However, when unit testing, orientation is not available to us. Thus, make this
+     * property optional
+     */
+    readonly orientation?: Pick<ScreenOrientation, "type" | "angle">;
+    readonly pixelDepth: number;
+    readonly width: number;
 }
+
+/**
+ * Manages the participant data for a game.
+ *
+ * @internal For m2c2kit library use only
+ *
+ * @param game - The game instance that this DataManager is associated with.
+ */
+declare class DataManager {
+    private game;
+    private webGlRendererInfo;
+    data: GameData;
+    trialIndex: number;
+    staticTrialSchema: {
+        [key: string]: JsonSchemaDataTypeScriptTypes;
+    };
+    constructor(game: Game);
+    /**
+     * Initializes the participant data structure for a new game.
+     *
+     * @remarks This method should be called once at the start of a new game.
+     */
+    initializeData(): void;
+    /**
+     * The m2c2kit engine will automatically include these schema and their
+     * values in the trial data.
+     *
+     * @remarks These are in the `Game` class, rather than in the `DataManager`
+     * class, because the schema-util parses the code to find these
+     * properties, and it expects them in the `Game` class.
+     */
+    private readonly automaticTrialSchema;
+    /**
+     * The m2c2kit engine will automatically include these schema and their
+     * values in the scoring data.
+     *
+     * @remarks These are in the `Game` class, rather than in the `DataManager`
+     * class, because the schema-util parses the code to find these
+     * properties, and it expects them in the `Game` class.
+     */
+    private readonly automaticScoringSchema;
+    /**
+     * Queries the WebGL renderer for graphics drivers information and stores
+     * it so it can be included in the device metadata.
+     *
+     * @remarks This method should be called once during the game start to avoid
+     * performance issues (it could be slow on some devices/browsers).
+     */
+    queryWebGlRendererInfo(): void;
+    private propertySchemaDataTypeIsValid;
+    /**
+     * Increments the trial index by 1.
+     */
+    incrementTrialIndex(): void;
+    /**
+     * Adds data to the game's TrialData object.
+     *
+     * @remarks `variableName` must be previously defined in the
+     * {@link TrialSchema} object in {@link GameOptions}. The type of the value
+     * must match what was defined in the trial schema, otherwise an error is
+     * thrown.
+     *
+     * @param variableName - variable to be set
+     * @param value - value of the variable to set
+     */
+    addTrialData(variableName: string, value: JsonSchemaDataTypeScriptTypes): void;
+    /**
+     * Sets the value of a variable that will be the same for all trials.
+     *
+     * @remarks This sets the value of a variable that is the same across
+     * all trials ("static"). This is useful for variables that are not
+     * part of the trial schema, but that you want to save for each trial in
+     * your use case. For example, you might want to save the subject's
+     * participant ID for each trial, but this is not part of the trial schema.
+     * Rather than modify the source code for the game, you can do the following
+     * to ensure that the participant ID is saved for each trial:
+     *
+     *   game.addTrialSchema(&#123
+     *     participant_id: &#123
+     *       type: "string",
+     *       description: "ID of the participant",
+     *     &#125;
+     *   &#125;);
+     *   game.addStaticTrialData("participant_id", "12345");
+     *
+     *  When Game.trialComplete() is called, the participant_id variable will
+     *  be saved for the trial with the value "12345".
+     *
+     * @param variableName - variable to be set
+     * @param value - value of the variable to set
+     */
+    addStaticTrialData(variableName: string, value: JsonSchemaDataTypeScriptTypes): void;
+    /**
+     * Adds data to the game's scoring data.
+     *
+     * @remarks The variable name (or object property names) must be previously
+     * defined in the {@link ScoringSchema} object in {@link GameOptions}.
+     * The type of the value must match what was defined in the scoring schema,
+     * otherwise an error is thrown.
+     *
+     * @param variableNameOrObject - Either a variable name (string) or an object
+     * containing multiple key-value pairs to add all at once.
+     * @param value - Value of the variable to set (only used when
+     * variableNameOrObject is a variable name string).
+     */
+    addScoringData(variableNameOrObject: string | Record<string, JsonSchemaDataTypeScriptTypes> | Array<Record<string, JsonSchemaDataTypeScriptTypes>>, value?: JsonSchemaDataTypeScriptTypes): void;
+    /**
+     * Helper method to validate and set a single scoring variable
+     *
+     * @param variableName - Name of the variable to set
+     * @param value - Value to set
+     * @private
+     */
+    private validateAndSetScoringVariable;
+    getDeviceMetadata(): DeviceMetadata;
+    makeNewGameDataSchema(): JsonSchema;
+    makeGameDataSchema(): JsonSchema;
+    makeScoringDataSchema(): JsonSchema;
+    private validateSchema;
+}
+
 declare class Game implements Activity {
     readonly type = ActivityType.Game;
     _canvasKit?: CanvasKit;
@@ -1586,12 +1898,12 @@ declare class Game implements Activity {
     private _dataStores?;
     private plugins;
     additionalParameters?: unknown;
-    staticTrialSchema: {
-        [key: string]: JsonSchemaDataTypeScriptTypes;
-    };
     private _fontManager?;
     private _imageManager?;
     private _soundManager?;
+    private _inputManager?;
+    sceneManager: SceneManager;
+    dataManager: DataManager;
     manifest?: Manifest;
     eventStore: EventStore;
     private nodeFactory;
@@ -1604,7 +1916,22 @@ declare class Game implements Activity {
      * @param options - {@link GameOptions}
      */
     constructor(options: GameOptions);
-    private createFreeNodesScene;
+    /**
+     * Returns the base URL of an imported module.
+     *
+     * @remarks Previously, a regex was used:
+     * `const regex = new RegExp(`^.*${packageName}[^\\/]*`);`
+     * but this triggered irrelevant warnings for ReDoS in some overly
+     * sensitive package scanners, so now we use URL and pathname parsing.
+     * Also: trailing slashes are removed from the returned base URL.
+     *
+     * @param packageName - the name of the imported package module, like
+     * `@m2c2kit/assessment-symbol-search`
+     * @param moduleUrl - the full URL of the module's entrypoint, possibly
+     * including a version suffix, like `https://cdn.com/@m2c2kit/assessment-symbol-search@0.8.13/dist/index.js`
+     * @returns - the base URL of the imported module, without the entrypoint,
+     * like `https://cdn.com/@m2c2kit/assessment-symbol-search@0.8.13`
+     */
     private getImportedModuleBaseUrl;
     private addLocalizationParametersToGameParameters;
     init(): Promise<void>;
@@ -1654,6 +1981,29 @@ declare class Game implements Activity {
     set soundManager(soundManager: SoundManager);
     get eventMaterializer(): EventMaterializer;
     set eventMaterializer(eventMaterializer: EventMaterializer);
+    get inputManager(): InputManager;
+    set inputManager(inputManager: InputManager);
+    /**
+     * Returns the scenes that have been added to the game.
+     */
+    get scenes(): Scene[];
+    /**
+     * Returns the current game scene.
+     *
+     * @remarks The current scene is the scene that is currently being
+     * rendered. If no scene has been set as the current scene, this will
+     * return undefined.
+     */
+    get currentScene(): Scene | undefined;
+    /**
+     * Returns the game snapshots.
+     *
+     * @remarks Snapshots are the most recent images of the current scene. These
+     * are in raw CanvasKit `Image` format and must be converted to another
+     * format, such as PNG via `CanvasKit.MakeImage()`, before they can be
+     * meaningfully exported.
+     */
+    get snapshots(): canvaskit_wasm.Image[];
     /**
      * Adds prefixes to a key to ensure that keys are unique across activities
      * and studies.
@@ -1779,14 +2129,14 @@ declare class Game implements Activity {
     set canvasKit(canvasKit: CanvasKit);
     /** The scene, or its name as a string, to be presented when the game is started. If this is undefined, the game will start with the first scene that has been added */
     entryScene?: Scene | string;
-    data: GameData;
+    /** The participant data generated by the game. */
+    get data(): GameData;
     /** The 0-based index of the current trial */
-    trialIndex: number;
+    get trialIndex(): number;
     private htmlCanvas?;
     surface?: Surface;
     private showFps?;
-    private bodyBackgroundColor?;
-    currentScene?: Scene;
+    bodyBackgroundColor?: RgbaColor;
     private priorUpdateTime?;
     private fpsTextFont?;
     private fpsTextPaint?;
@@ -1797,14 +2147,8 @@ declare class Game implements Activity {
     private animationFramesRequested;
     private limitFps;
     private gameStopRequested;
-    private webGlRendererInfo;
     canvasCssWidth: number;
     canvasCssHeight: number;
-    scenes: Scene[];
-    freeNodesScene: Scene;
-    private incomingSceneTransitions;
-    private currentSceneSnapshot?;
-    private pendingScreenshot?;
     /**
      * Adds a node as a free node (a node that is not part of a scene)
      * to the game.
@@ -1865,19 +2209,6 @@ declare class Game implements Activity {
      * @param scene
      */
     addScene(scene: Scene): void;
-    /**
-     * Adds events from a node and its children to the game's event store.
-     *
-     * @remarks This method is first called when a scene is added to the game.
-     * If the scene or any of its descendants was constructed or had its
-     * properties changed before it was added to the game, these events were
-     * stored within the node (because the game event store was not yet
-     * available). This method retrieves these events from the node and adds
-     * them to the game's event store.
-     *
-     * @param node - node that contains events to add
-     */
-    private addNodeEvents;
     /**
      * Adds multiple scenes to the game.
      *
@@ -1985,10 +2316,6 @@ declare class Game implements Activity {
      * end-user must not call this. FOR INTERNAL USE ONLY.
      */
     dispose(): void;
-    private initData;
-    private validateSchema;
-    private propertySchemaDataTypeIsValid;
-    private getDeviceMetadata;
     /**
      * Adds data to the game's TrialData object.
      *
@@ -2015,14 +2342,6 @@ declare class Game implements Activity {
      * variableNameOrObject is a variable name string).
      */
     addScoringData(variableNameOrObject: string | Record<string, JsonSchemaDataTypeScriptTypes> | Array<Record<string, JsonSchemaDataTypeScriptTypes>>, value?: JsonSchemaDataTypeScriptTypes): void;
-    /**
-     * Helper method to validate and set a single scoring variable
-     *
-     * @param variableName - Name of the variable to set
-     * @param value - Value to set
-     * @private
-     */
-    private validateAndSetScoringVariable;
     /**
      * Adds custom trial schema to the game's trialSchema object.
      *
@@ -2082,18 +2401,6 @@ declare class Game implements Activity {
      * to call this at the appropriate time. It is not triggered automatically.
      */
     scoringComplete(): void;
-    /**
-     * The m2c2kit engine will automatically include these schema and their
-     * values in the scoring data.
-     */
-    private readonly automaticScoringSchema;
-    /**
-     * The m2c2kit engine will automatically include these schema and their
-     * values in the trial data.
-     */
-    private readonly automaticTrialSchema;
-    private makeNewGameDataSchema;
-    private makeGameDataSchema;
     /**
      * GameParameters combines default parameters values and
      * JSON Schema to describe what the parameters are.
@@ -2103,7 +2410,6 @@ declare class Game implements Activity {
      */
     private makeGameActivityConfiguration;
     private makeGameActivityConfigurationSchema;
-    private makeScoringDataSchema;
     /**
      * Should be called when current game has ended successfully.
      *
@@ -2128,20 +2434,10 @@ declare class Game implements Activity {
     cancel(): void;
     private setupHtmlCanvases;
     private setupCanvasKitSurface;
-    private interceptWebGlCalls;
     private setupFpsFont;
-    private setupCanvasDomEventHandlers;
+    private setupInputManager;
     private loop;
-    snapshots: Image[];
     private updateGameTime;
-    private handleIncomingSceneTransitions;
-    /**
-     * Creates a scene that has a screen shot of the current scene.
-     *
-     * @param outgoingSceneImage - an image of the current scene
-     * @returns - the scene with the screen shot
-     */
-    private createOutgoingScene;
     /**
      * Registers a plugin with the game.
      *
@@ -2156,10 +2452,6 @@ declare class Game implements Activity {
      *
      */
     private update;
-    /**
-     * Updates all active scenes and their children.
-     */
-    private updateScenes;
     /**
      * Executes all active plugins before scenes are updated.
      */
@@ -2170,8 +2462,6 @@ declare class Game implements Activity {
     private executeAfterUpdatePlugins;
     private draw;
     private calculateFps;
-    private takeCurrentSceneSnapshot;
-    private handlePendingScreenshot;
     /**
      * Takes screenshot of canvas
      *
@@ -2188,7 +2478,6 @@ declare class Game implements Activity {
      * @returns Promise of Uint8Array of image data
      */
     takeScreenshot(sx?: number, sy?: number, sw?: number, sh?: number): Promise<Uint8Array | null>;
-    private animateSceneTransition;
     private drawFps;
     /**
      * Creates an event listener for a node based on the node name
@@ -2209,42 +2498,6 @@ declare class Game implements Activity {
      * @deprecated use Game.nodes instead
      */
     get entities(): Array<M2Node>;
-    /**
-     * Receives callback from DOM PointerDown event
-     *
-     * @param domPointerEvent - PointerEvent from the DOM
-     * @returns
-     */
-    private htmlCanvasPointerDownHandler;
-    private htmlCanvasPointerUpHandler;
-    private htmlCanvasPointerMoveHandler;
-    private htmlCanvasPointerLeaveHandler;
-    private documentKeyDownHandler;
-    private documentKeyUpHandler;
-    /**
-     * Determines if/how m2c2kit nodes respond to the DOM PointerDown event
-     *
-     * @param node - node that might be affected by the DOM PointerDown event
-     * @param nodeEvent
-     * @param domPointerEvent
-     */
-    private processDomPointerDown;
-    private processDomPointerUp;
-    private processDomPointerMove;
-    private processDomPointerLeave;
-    private raiseM2PointerDownEvent;
-    private raiseTapDownEvent;
-    private raiseTapLeaveEvent;
-    private raiseM2PointerUpEvent;
-    private raiseTapUpEvent;
-    private raiseTapUpAny;
-    private raiseM2PointerMoveEvent;
-    private raiseM2PointerLeaveEvent;
-    private raiseM2DragStartEvent;
-    private raiseM2DragEvent;
-    private raiseM2DragEndEvent;
-    private raiseSceneEvent;
-    private calculatePointWithinNodeFromDomPointerEvent;
     /**
      * Executes a callback when the game starts.
      *
@@ -2293,18 +2546,6 @@ declare class Game implements Activity {
     onWarmupEnd(callback: (activityEvent: ActivityEvent) => void, options?: CallbackOptions): void;
     private addEventListener;
     private raiseActivityEventOnListeners;
-    private raiseEventOnListeningNodes;
-    private sceneCanReceiveUserInteraction;
-    /**
-     *
-     * Checks if the given canvas point is within the node's bounds.
-     *
-     * @param node - node to check bounds for
-     * @param x - x coordinate of the canvas point
-     * @param y - y coordinate of the canvas point
-     * @returns true if x, y point is within the node's bounds
-     */
-    private IsCanvasPointWithinNodeBounds;
 }
 
 /**
@@ -4027,6 +4268,13 @@ declare class M2c2KitHelpers {
      * "https://", "file://", etc.)
      */
     static urlHasScheme(url: string): boolean;
+    /**
+     * Sanitizes parameters object to prevent prototype pollution.
+     *
+     * @param parameters  - parameters object to be sanitized
+     * @returns sanitized parameters or undefined if parameters is undefined
+     */
+    static sanitizeParameters(parameters: unknown | undefined): any;
     /**
      * Converts a value to a JSON schema type or one of types.
      *
@@ -5505,6 +5753,7 @@ declare class WebGlInfo {
      * Removes the temporary canvas that was created to get WebGL information.
      */
     static dispose(): void;
+    static interceptWebGlCalls(htmlCanvas: HTMLCanvasElement): void;
 }
 
 export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2Error, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, 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 };