@m2c2kit/core 0.1.6 → 0.1.9

package/dist/index.d.ts

@@ -27,12 +27,11 @@ interface EntityEventListener {
 /**
  * Position in two-dimensional space.
  */
-declare class Point {
+interface Point {
     /** Horizonal coordinate */
     x: number;
     /** Vertical coordinate */
     y: number;
-    constructor(x?: number, y?: number);
 }
 
 interface TapEvent extends EntityEvent {
@@ -40,6 +39,11 @@ interface TapEvent extends EntityEvent {
     point: Point;
 }
 
+interface DrawableOptions {
+    anchorPoint?: Point;
+    zPosition?: number;
+}
+
 interface Constraints {
     /** Constrain the top (vertical axis) of this entity to the top of the specified entity. The tops of both will appear at the same vertical location */
     topToTopOf?: Entity | string;
@@ -79,13 +83,30 @@ interface Layout {
     constraints?: Constraints;
 }
 
+/**
+ * Color in red (0-255), green (0-255), blue (0-255), alpha (0-1) format. Must be numeric array of length 4.
+ */
+declare type RgbaColor = [number, number, number, number];
+
+interface TextOptions {
+    /** Text to be displayed */
+    text?: string;
+    /** Name of font to use for text. Must have been previously loaded */
+    fontName?: string;
+    /** Color of text. Default is Constants.DEFAULT_FONT_COLOR (WebColors.Black) */
+    fontColor?: RgbaColor;
+    /** Size of text. Default is Constants.DEFAULT_FONT_SIZE (16) */
+    fontSize?: number;
+}
+
 /**
  * Width and height on two-dimensional space
  */
-declare class Size {
+interface Size {
+    /** Horizonal width, x-axis */
     width: number;
+    /** Vertical height, y-axis */
     height: number;
-    constructor(width?: number, height?: number);
 }
 
 interface EntityOptions {
@@ -134,7 +155,7 @@ declare abstract class Entity implements EntityOptions {
     queuedAction?: Action;
     originalActions: Action[];
     eventListeners: EntityEventListener[];
-    uuid: string;
+    readonly uuid: string;
     needsInitialization: boolean;
     userData: any;
     loopMessages: Set<string>;
@@ -209,9 +230,20 @@ declare abstract class Entity implements EntityOptions {
      * Remove all actions from this entity. If actions are running, they will be stopped.
      */
     removeAllActions(): void;
-    private static getEntityOptions;
-    private static getDrawableOptions;
-    private static getTextOptions;
+    /**
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    abstract duplicate(newName?: string): Entity;
+    protected getEntityOptions(): EntityOptions;
+    protected getDrawableOptions(): DrawableOptions;
+    protected getTextOptions(): TextOptions;
     /**
      * Gets the scene that contains this entity by searching up the ancestor tree recursively. Throws exception if entity is not part of a scene.
      *
@@ -375,6 +407,11 @@ declare class ScaleAction extends Action {
     constructor(scale: number, duration: number, runDuringTransition?: boolean);
 }
 
+declare enum ActivityType {
+    game = "Game",
+    survey = "Survey"
+}
+
 declare class LoadedImage {
     name: string;
     image: Image;
@@ -384,18 +421,21 @@ declare class LoadedImage {
 }
 
 /**
- * Image that can be rendered by a browser and loaded from a URL or HTML svg tag in string form.
+ * Image that can be rendered by a browser from a URL or from a
+ * HTML svg tag in string form. Provide either url or svgString, not both.
  */
 interface BrowserImage {
-    /** Name that will be used to refer to the SVG image. Must be unique among all images */
+    /** Name that will be used to refer to the image. Must be unique among all
+     * images within a game */
     name: string;
-    /** Width to scale SVG image to */
+    /** Width to scale image to */
     width: number;
-    /** Height to scale SVG image to */
+    /** Height to scale image to */
     height: number;
-    /** The HTML SVG tag, in string form, that will be rendered and loaded. Must begin with &#60;svg> and end with &#60;/svg> */
+    /** The HTML SVG tag, in string form, that will be rendered and loaded.
+     * Must begin with &#60;svg> and end with &#60;/svg> */
     svgString?: string;
-    /** URL of SVG asset to render and load */
+    /** URL of image asset (svg, png, jpg) to render and load */
     url?: string;
 }
 
@@ -411,24 +451,71 @@ declare class ImageManager {
     private _scratchCanvas?;
     private ctx?;
     private scale?;
+    /**
+     * Returns a CanvasKit Image that was previously rendered by the ImageManager.
+     *
+     * @remarks Typically, this won't be called directly because a programmer
+     * will use a higher-level abstraction (m2c2kit Sprite).
+     *
+     * @param gameUuid - The game that the image resource is part of
+     * @param imageName - The name given to the rendered image
+     * @returns A CanvasKit Image
+     */
     getLoadedImage(gameUuid: string, imageName: string): LoadedImage;
     /**
-     * Adds a CanvasKit image to the images available to a given game.
-     * Typically, this won't be called directly because images will be
+     * Adds a CanvasKit Image to the images available to a given game.
+     *
+     * @remarks Typically, a programmer won't call this because images will be
      * automatically rendered and loaded in the Activity async init.
-     * The only time this function is called in-game is to add
-     * screenshot images needed for transitions
+     * The only time this function is called in-game is when our internal
+     * methods add screenshot images needed for transitions.
      *
-     * @param loadedImage
-     * @param gameUuid
+     * @param loadedImage - An image that has been converted to a CanvasKit Image
+     * @param gameUuid - The game that the Image is part of
      */
     addLoadedImage(loadedImage: LoadedImage, gameUuid: string): void;
+    /**
+     * Renders game images from their original format (png, jpg, svg) to
+     * CanvasKit Image.
+     *
+     * @remarks Typically, a programmer won't call this because the Session
+     * object will manage this. Rendering is an async activity, and thus
+     * this method returns a promise. Rendering of all images is done in
+     * parallel.
+     *
+     * @param allGamesImages - An array of GameImages data structures that
+     * specify the image's desired size, it's name, and where the image to be
+     * rendered is located (e.g., embedded svgString or url)
+     * @returns A promise that completes when all game images have rendered
+     */
     renderImages(allGamesImages: Array<GameImages>): Promise<void[]>;
+    /**
+     * Adds all rendered CanvasKit Images to the images available to m2c2kit.
+     *
+     * @remarks Typically, a programmer won't call this because the Session
+     * object will manage this.
+     */
     loadAllGamesRenderedImages(): void;
+    /**
+     * Our private method rendering an image to a CanvasKit Image
+     *
+     * @remarks This is complex because there is a separate flow to render
+     * svg images versus other (e.g., jpg, png). Svg images may be provided
+     * in a url or inline. In addition, there is a Firefox svg rendering issue,
+     * see below, that must be handled.
+     * Additional complexity comes from the potentially multiple async steps and
+     * the multiple errors that can happen throughout.
+     *
+     * @param gameUuid
+     * @param browserImage
+     * @returns A promise of type void
+     */
     private renderBrowserImage;
     private convertRenderedDataUrlImageToCanvasKitImage;
     /**
-     * scratchCanvas is an extra, non-visible canvas in the DOM we use so the native browser can render images
+     * Returns the scratchCanvas, which is an extra, non-visible canvas in the
+     * DOM we use so the native browser can render images like svg, png, jpg,
+     * that we later will convert to CanvasKit Image.
      */
     private get scratchCanvas();
     private dataURLtoArrayBuffer;
@@ -484,22 +571,143 @@ declare class FontManager {
     private loadGameFonts;
 }
 
-interface GameEvent {
-    gameUuid: string;
-    gameName: string;
+interface EventBase {
+    eventType: EventType;
+}
+/** Note: I would have named it Event, but that would collide with
+ * the existing, and much more well-known, Web API Event */
+declare enum EventType {
+    activityData = "ActivityData",
+    activityLifecycle = "ActivityLifecycle",
+    sessionLifecycle = "SessionLifecycle"
 }
 
-interface GameLifecycleEvent extends GameEvent {
-    ended: boolean;
+interface ActivityEvent extends EventBase {
+    uuid: string;
+    name: string;
 }
 
-interface GameParameters {
-    [key: string]: DefaultParameter;
-}
-interface DefaultParameter {
-    value: any;
-    type?: "number" | "string" | "boolean" | "object";
-    description?: string;
+interface ActivityData {
+    [key: string]: string | number | boolean | object | undefined | null;
+}
+
+interface ActivityDataEvent extends ActivityEvent {
+    newData: ActivityData;
+    newDataSchema: any;
+    data: ActivityData;
+    dataSchema: any;
+    activityConfiguration: any;
+}
+
+interface ActivityLifecycleEvent extends ActivityEvent {
+    /** the activity started. */
+    started?: boolean;
+    /** the activity ended. the user fully completed the activity and  */
+    ended?: boolean;
+    /** the activity ended. the user canceled without fully completing the activity */
+    userCanceled?: boolean;
+}
+
+interface ActivityCallbacks {
+    /** Callback executed when the activity lifecycle changes, such as when it ends. */
+    onActivityLifecycleChange?: (event: ActivityLifecycleEvent) => void;
+    /** Callback executed when an activity creates some data. */
+    onActivityDataCreate?: (event: ActivityDataEvent) => void;
+}
+
+interface SessionEvent extends EventBase {
+}
+
+interface SessionLifecycleEvent extends SessionEvent {
+    initialized?: boolean;
+    ended?: boolean;
+    started?: boolean;
+}
+
+interface SessionCallbacks {
+    /** Callback executed when the session lifecycle changes, such as when it is initialized. */
+    onSessionLifecycleChange?: (event: SessionLifecycleEvent) => void;
+}
+
+interface SessionOptions {
+    /** The activities that compose this session */
+    activities: Array<Activity>;
+    /** Callbacks executed when activity events occurs, such as when activity creates data or ends */
+    activityCallbacks?: ActivityCallbacks;
+    /** Callbacks executed when session events occur */
+    sessionCallbacks?: SessionCallbacks;
+}
+
+declare class Session {
+    options: SessionOptions;
+    fontManager: FontManager;
+    imageManager: ImageManager;
+    currentActivity?: Activity;
+    uuid: string;
+    private canvasKit?;
+    /**
+     * A Session contains one or more activities; currently, the only
+     * class that implements Activity is Game, but Survey is planned.
+     * The session manages the start and stop of activities, and
+     * advancement to next activity
+     *
+     * @param options
+     */
+    constructor(options: SessionOptions);
+    /**
+     * Asynchronously initializes the m2c2kit engine and loads assets
+     */
+    init(): Promise<void>;
+    /**
+     * Starts the session and starts the first activity.
+     */
+    start(): void;
+    /**
+     * Declares the session ended and sends callback.
+     */
+    end(): void;
+    /**
+     * Stops the current activity and advances to next activity in the session.
+     * If there is no activity after the current activity, throws error
+     */
+    advanceToNextActivity(): void;
+    /**
+     * Gets the next activity after the current one, or undefined if
+     * this is the last activity.
+     */
+    get nextActivity(): Activity | undefined;
+    private logStartingActivity;
+    /**
+     * Gets asynchronous assets, including initialization of canvaskit wasm,
+     * fetching of fonts from specified urls, and rendering and fetching
+     * of images
+     * @returns
+     */
+    private getAsynchronousAssets;
+    private loadCanvasKit;
+    private loadAssets;
+    private assignCanvasKit;
+    private getFontsConfigurationFromGames;
+    private getImagesConfigurationFromGames;
+}
+
+interface Activity {
+    /** The type of activity: Game or Survey */
+    type: ActivityType;
+    /** Initializes the activity. */
+    init(): void;
+    /** Starts the activity */
+    start(): void;
+    /** Stops the activity */
+    stop(): void;
+    /** The activity's parent session */
+    session: Session;
+    /** The activity's unique identifier. NOTE: This is newly generated each session. The uuid for an activity will vary across sessions. */
+    uuid: string;
+    /** The activity's human friendly name */
+    name: string;
+    /** Set activity parameters if defaults are not desired*/
+    setParameters(newParameters: any): void;
 }
 
 interface IDrawable {
@@ -508,14 +716,63 @@ interface IDrawable {
     zPosition: number;
 }
 
+interface CompositeOptions extends EntityOptions, DrawableOptions {
+}
+
+declare abstract class Composite extends Entity implements IDrawable {
+    readonly type = EntityType.composite;
+    compositeType: string;
+    isDrawable: boolean;
+    anchorPoint: Point;
+    zPosition: number;
+    /**
+     * Base Drawable object for creating custom entities ("composites") composed of primitive entities.
+     *
+     * @param options
+     */
+    constructor(options?: CompositeOptions);
+    initialize(): void;
+    update(): void;
+    draw(canvas: Canvas): void;
+}
+
 /**
- * Color in red (0-255), green (0-255), blue (0-255), alpha (0-1) format. Must be numeric array of length 4.
+ * Reasonable defaults to use if values are not specified.
  */
-declare type RgbaColor = [number, number, number, number];
+declare class Constants {
+    static readonly FPS_DISPLAY_TEXT_FONT_SIZE = 12;
+    static readonly FPS_DISPLAY_TEXT_COLOR: RgbaColor;
+    static readonly FPS_DISPLAY_UPDATE_INTERVAL = 500;
+    static readonly DEFAULT_SCENE_BACKGROUND_COLOR: RgbaColor;
+    static readonly DEFAULT_SHAPE_FILL_COLOR: RgbaColor;
+    static readonly DEFAULT_FONT_COLOR: RgbaColor;
+    static readonly DEFAULT_FONT_SIZE = 16;
+    static readonly LIMITED_FPS_RATE = 5;
+}
 
-interface DrawableOptions {
-    anchorPoint?: Point;
-    zPosition?: number;
+/**
+ * This enum is used interally for processing the layout constraints. We use
+ * an enum to avoid magic strings.
+ */
+declare enum ConstraintType {
+    topToTopOf = "topToTopOf",
+    topToBottomOf = "topToBottomOf",
+    bottomToTopOf = "bottomToTopOf",
+    bottomToBottomOf = "bottomToBottomOf",
+    startToStartOf = "startToStartOf",
+    startToEndOf = "startToEndOf",
+    endToEndOf = "endToEndOf",
+    endToStartOf = "endToStartOf"
+}
+
+declare enum Dimensions {
+    MATCH_CONSTRAINT = 0
+}
+
+interface FontData {
+    gameUuid: string;
+    fontUrl: string;
+    fontArrayBuffer: ArrayBuffer;
 }
 
 interface SceneOptions extends EntityOptions, DrawableOptions {
@@ -526,12 +783,16 @@ interface SceneOptions extends EntityOptions, DrawableOptions {
 declare class Scene extends Entity implements IDrawable, SceneOptions {
     readonly type = EntityType.scene;
     isDrawable: boolean;
-    anchorPoint: Point;
+    anchorPoint: {
+        x: number;
+        y: number;
+    };
     zPosition: number;
     private _backgroundColor;
     _active: boolean;
     _transitioning: boolean;
     _setupCallback?: (scene: Scene) => void;
+    _appearCallback?: (scene: Scene) => void;
     private _game?;
     private backgroundPaint?;
     /**
@@ -548,13 +809,31 @@ declare class Scene extends Entity implements IDrawable, SceneOptions {
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
     /**
-     * Code that will be called every time the screen is first presented.
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): Scene;
+    /**
+     * Code that will be called every time the screen is presented.
      *
      * @remarks Use this callback to set entities to their initial state, if that state might be changed later. For example, if a scene allows players to place dots on a grid, the setup() method should ensure the grid is clear of any prior dots from previous times this scene may have been displayed. In addition, if entities should vary in each iteration, that should be done here.
      *
      * @param callback
      */
-    setup(callback: (scene: Scene) => void): void;
+    onSetup(callback: (scene: Scene) => void): void;
+    /**
+     *
+     * Code that will be called after the scene has finished any transitions and has fully appeared on the screen.
+     *
+     * @param callback
+     */
+    onAppear(callback: (scene: Scene) => void): void;
     draw(canvas: Canvas): void;
 }
 
@@ -594,7 +873,16 @@ interface TrialSchema {
     [key: string]: PropertySchema;
 }
 interface PropertySchema {
-    type: "number" | "string" | "boolean" | "object";
+    type: "number" | "string" | "boolean" | "object" | "array";
+    description?: string;
+}
+
+interface GameParameters {
+    [key: string]: DefaultParameter;
+}
+interface DefaultParameter {
+    value: any;
+    type?: "number" | "string" | "boolean" | "object";
     description?: string;
 }
 
@@ -636,18 +924,46 @@ interface GameOptions {
     _unitTesting?: boolean;
 }
 
+interface GameData extends ActivityData {
+    trials: Array<TrialData>;
+    metadata: Metadata;
+}
+
 interface TrialData {
     [key: string]: string | number | boolean | undefined | null;
 }
 interface Metadata {
     userAgent?: string;
+    devicePixelRatio?: number;
+    screen?: screenMetadata;
+}
+/**
+ * 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;
 }
 declare class Game implements Activity {
+    readonly type = ActivityType.game;
     _canvasKit?: CanvasKit;
     _session?: Session;
     uuid: string;
+    name: string;
     options: GameOptions;
-    constructor(options: GameOptions, specifiedParameters?: any);
+    constructor(options: GameOptions);
+    init(): void;
+    setParameters(newParameters: any): void;
     get canvasKit(): CanvasKit;
     set canvasKit(canvasKit: CanvasKit);
     get session(): Session;
@@ -676,6 +992,7 @@ declare class Game implements Activity {
     private scenes;
     private incomingSceneTransitions;
     private currentSceneSnapshot?;
+    private pendingScreenshot?;
     /**
      * Adds a scene to the game.
      *
@@ -712,6 +1029,7 @@ declare class Game implements Activity {
     start(entryScene?: Scene | string): void;
     stop(): void;
     initData(): void;
+    private getScreenMetadata;
     /**
      * Adds data to the game's TrialData object.
      *
@@ -724,7 +1042,7 @@ declare class Game implements Activity {
     /**
      * Should be called when the current trial has completed. It will
      * also increment the trial index.
-     * Calling this will trigger the onGameTrialComplete callback function,
+     * Calling this will trigger the onActivityDataCreate callback function,
      * if one was provided in SessionOptions. This is how the game communicates
      * trial data to the parent session, which can then save or process the data.
      * It is the responsibility of the the game programmer to call this at
@@ -733,7 +1051,7 @@ declare class Game implements Activity {
     trialComplete(): void;
     /**
      * Should be called when the current game has ended. This will trigger
-     * the onGameLifecycleChange callback function, if one was provided in
+     * the onActivityLifecycleChange callback function, if one was provided in
      * SessionOptions. This is how the game can communicate its ended or
      * "finished" state to the parent session.
      * It is the responsibility of the the game programmer to call this at
@@ -750,6 +1068,23 @@ declare class Game implements Activity {
     private update;
     private draw;
     private takeCurrentSceneSnapshot;
+    private handlePendingScreenshot;
+    /**
+     * 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 loop() method.
+     *
+     * @param sx - Upper left coordinate of screenshot
+     * @param sy - Upper right coordinate of screenshot
+     * @param sw - width of area to screenshot
+     * @param sh - hegith of area to screenshot
+     * @returns Promise of Uint8Array of image data
+     */
+    takeScreenshot(sx?: number, sy?: number, sw?: number, sh?: number): Promise<Uint8Array | null>;
     private animateSceneTransition;
     private drawFps;
     /**
@@ -776,151 +1111,6 @@ declare class Game implements Activity {
     private calculateEntityAbsoluteBoundingBox;
 }
 
-interface GameData {
-    trials: Array<TrialData>;
-    metadata: Metadata;
-}
-
-interface GameTrialEvent extends GameEvent {
-    trialIndex: number;
-    trialSchema: TrialSchema;
-    gameData: GameData;
-    gameParameters: GameParameters;
-}
-
-interface GameCallbacks {
-    /** Callback executed when the game lifecycle changes, such as when it ends. */
-    onGameLifecycleChange?: (event: GameLifecycleEvent) => void;
-    /** Callback executed when a game trial completes. */
-    onGameTrialComplete?: (event: GameTrialEvent) => void;
-}
-
-interface SessionOptions {
-    /** The activities that compose this session */
-    activities: Array<Activity>;
-    /** Callbacks executed when trials are completed and when game ends */
-    gameCallbacks?: GameCallbacks;
-}
-
-declare class Session {
-    options: SessionOptions;
-    fontManager: FontManager;
-    imageManager: ImageManager;
-    currentActivity?: Activity;
-    uuid: string;
-    private canvasKit?;
-    /**
-     * A Session contains one or more activities; currently, the only
-     * class that implements Activity is Game, but Survey is planned.
-     * The session manages the start and stop of activities, and
-     * advancement to next activity
-     *
-     * @param options
-     */
-    constructor(options: SessionOptions);
-    /**
-     * Asynchronously initializes the m2c2kit engine and loads assets
-     */
-    init(): Promise<void>;
-    /**
-     * Starts the session and starts the first activity.
-     */
-    start(): void;
-    /**
-     * Stops the current activity and advances to next activity in the session.
-     * If there is no activity after the current activity, throws error
-     */
-    advanceToNextActivity(): void;
-    /**
-     * Gets the next activity after the current one, or undefined if
-     * this is the last activity.
-     */
-    get nextActivity(): Activity | undefined;
-    private logStartingActivity;
-    /**
-     * Gets asynchronous assets, including initialization of canvaskit wasm,
-     * fetching of fonts from specified urls, and rendering and fetching
-     * of images
-     * @returns
-     */
-    private getAsynchronousAssets;
-    private loadCanvasKit;
-    private loadAssets;
-    private assignCanvasKit;
-    private getFontsConfigurationFromGames;
-    private getImagesConfigurationFromGames;
-}
-
-interface Activity {
-    /** Starts the activity */
-    start(): void;
-    /** Stops the activity */
-    stop(): void;
-    /** The activity's parent session */
-    session: Session;
-    /** The activity's unique identifier. NOTE: This is newly generated each session. The uuid for an activity will vary across sessions. */
-    uuid: string;
-}
-
-interface CompositeOptions extends EntityOptions, DrawableOptions {
-}
-
-declare abstract class Composite extends Entity implements IDrawable {
-    readonly type = EntityType.composite;
-    compositeType: string;
-    isDrawable: boolean;
-    anchorPoint: Point;
-    zPosition: number;
-    /**
-     * Base Drawable object for creating custom entities ("composites") composed of primitive entities.
-     *
-     * @param options
-     */
-    constructor(options?: CompositeOptions);
-    initialize(): void;
-    update(): void;
-    draw(canvas: Canvas): void;
-}
-
-/**
- * Reasonable defaults to use if values are not specified.
- */
-declare class Constants {
-    static readonly FPS_DISPLAY_TEXT_FONT_SIZE = 12;
-    static readonly FPS_DISPLAY_TEXT_COLOR: RgbaColor;
-    static readonly FPS_DISPLAY_UPDATE_INTERVAL = 500;
-    static readonly DEFAULT_SCENE_BACKGROUND_COLOR: RgbaColor;
-    static readonly DEFAULT_SHAPE_FILL_COLOR: RgbaColor;
-    static readonly DEFAULT_FONT_COLOR: RgbaColor;
-    static readonly DEFAULT_FONT_SIZE = 16;
-    static readonly LIMITED_FPS_RATE = 5;
-}
-
-/**
- * This enum is used interally for processing the layout constraints. We use
- * an enum to avoid magic strings.
- */
-declare enum ConstraintType {
-    topToTopOf = "topToTopOf",
-    topToBottomOf = "topToBottomOf",
-    bottomToTopOf = "bottomToTopOf",
-    bottomToBottomOf = "bottomToBottomOf",
-    startToStartOf = "startToStartOf",
-    startToEndOf = "startToEndOf",
-    endToEndOf = "endToEndOf",
-    endToStartOf = "endToStartOf"
-}
-
-declare enum Dimensions {
-    MATCH_CONSTRAINT = 0
-}
-
-interface FontData {
-    gameUuid: string;
-    fontUrl: string;
-    fontArrayBuffer: ArrayBuffer;
-}
-
 interface IText {
     text?: string;
     fontName?: string;
@@ -928,17 +1118,6 @@ interface IText {
     fontSize?: number;
 }
 
-interface TextOptions {
-    /** Text to be displayed */
-    text?: string;
-    /** Name of font to use for text. Must have been previously loaded */
-    fontName?: string;
-    /** Color of text. Default is Constants.DEFAULT_FONT_COLOR (WebColors.Black) */
-    fontColor?: RgbaColor;
-    /** Size of text. Default is Constants.DEFAULT_FONT_SIZE (16) */
-    fontSize?: number;
-}
-
 declare enum LabelHorizontalAlignmentMode {
     center = 0,
     left = 1,
@@ -958,7 +1137,10 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
     readonly type = EntityType.label;
     isDrawable: boolean;
     isText: boolean;
-    anchorPoint: Point;
+    anchorPoint: {
+        x: number;
+        y: number;
+    };
     zPosition: number;
     private _text;
     private _fontName;
@@ -992,6 +1174,17 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
     set preferredMaxLayoutWidth(preferredMaxLayoutWidth: number | undefined);
     get backgroundColor(): RgbaColor | undefined;
     set backgroundColor(backgroundColor: RgbaColor | undefined);
+    /**
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): Label;
     update(): void;
     draw(canvas: Canvas): void;
 }
@@ -1021,22 +1214,39 @@ declare class LayoutConstraint {
 
 declare class RandomDraws {
     /**
-     * Draw random integers, without replacement, from a uniform distribution.
+     * Draws a single random integer from a uniform distribution of integers in
+     * the specified range.
      *
-     * @param n
-     * @param minimumInclusive
-     * @param maximumInclusive
-     * @returns array of integers
+     * @param minimumInclusive - Lower bound of range
+     * @param maximumInclusive - Upper bound of range
+     * @returns A sampled integer
+     */
+    static SingleFromRange(minimumInclusive: number, maximumInclusive: number): number;
+    /**
+     * Draws random integers, without replacement, from a uniform distribution
+     * of integers in the specified range.
+     *
+     * @param n - Number of draws
+     * @param minimumInclusive - Lower bound of range
+     * @param maximumInclusive - Upper bound of range
+     * @returns An array of integers
      */
     static FromRangeWithoutReplacement(n: number, minimumInclusive: number, maximumInclusive: number): Array<number>;
     /**
-     * Draw random grid cell locations, without replacement, from a uniform distribution of all grid cells. Grid cell locations are zero-based, i.e., upper-left is (0,0).
+     * Draw random grid cell locations, without replacement, from a uniform
+     * distribution of all grid cells. Grid cell locations are zero-based,
+     * i.e., upper-left is (0,0).
      *
      * @param n - Number of draws
      * @param rows  - Number of rows in grid; must be at least 1
      * @param columns - Number of columns in grid; must be at least 1
-     * @param predicate - Optional lambda function that takes a grid row number and grid column number pair and returns a boolean to indicate if the pair should be allowed. For example, if one wanted to constrain the random grid location to be along the diagonal, the predicate would be: (row, column) => row === column
-     * @returns array of grid cells. Each cell is object in form of { row: number, column: number }). Grid cell locations are zero-based
+     * @param predicate - Optional lambda function that takes a grid row number
+     * and grid column number pair and returns a boolean to indicate if the pair
+     * should be allowed. For example, if one wanted to constrain the random
+     * grid location to be along the diagonal, the predicate would be:
+     * (row, column) => row === column
+     * @returns Array of grid cells. Each cell is object in form of:
+     * {row: number, column: number}. Grid cell locations are zero-based
      */
     static FromGridWithoutReplacement(n: number, rows: number, columns: number, predicate?: (row: number, column: number) => boolean): Array<{
         row: number;
@@ -1059,21 +1269,18 @@ interface RectOptions {
     height?: number;
 }
 
-declare class Rect implements RectOptions {
-    origin?: Point;
-    size?: Size;
-    x?: number;
-    y?: number;
-    width?: number;
-    height?: number;
-    constructor(options: RectOptions);
+declare enum ShapeType {
+    undefined = "Undefined",
+    rectangle = "Rectangle",
+    circle = "Circle"
 }
 
 interface ShapeOptions extends EntityOptions, DrawableOptions {
+    shapeType?: ShapeType;
     /** If provided, shape will be a circle with given radius */
     circleOfRadius?: number;
     /** If provided, shape will be a rectangle as specified in {@link Rect} */
-    rect?: Rect;
+    rect?: RectOptions;
     /** Radius of rectangle's corners */
     cornerRadius?: number;
     /** Color with which to fill shape. Default is Constants.DEFAULT_SHAPE_FILL_COLOR (WebColors.Red)  */
@@ -1084,21 +1291,18 @@ interface ShapeOptions extends EntityOptions, DrawableOptions {
     lineWidth?: number;
 }
 
-declare enum ShapeType {
-    undefined = "Undefined",
-    rectangle = "Rectangle",
-    circle = "Circle"
-}
-
 declare class Shape extends Entity implements IDrawable, ShapeOptions {
     readonly type = EntityType.shape;
     isDrawable: boolean;
     isShape: boolean;
-    anchorPoint: Point;
+    anchorPoint: {
+        x: number;
+        y: number;
+    };
     zPosition: number;
     shapeType: ShapeType;
     circleOfRadius?: number;
-    rect?: Rect;
+    rect?: RectOptions;
     cornerRadius: number;
     private _fillColor;
     private _strokeColor?;
@@ -1116,6 +1320,17 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     set fillColor(fillColor: RgbaColor);
     get strokeColor(): RgbaColor | undefined;
     set strokeColor(strokeColor: RgbaColor | undefined);
+    /**
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): Shape;
     update(): void;
     draw(canvas: Canvas): void;
 }
@@ -1128,7 +1343,10 @@ interface SpriteOptions extends EntityOptions, DrawableOptions {
 declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     readonly type = EntityType.sprite;
     isDrawable: boolean;
-    anchorPoint: Point;
+    anchorPoint: {
+        x: number;
+        y: number;
+    };
     zPosition: number;
     private _imageName;
     private loadedImage?;
@@ -1143,6 +1361,17 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     initialize(): void;
     set imageName(imageName: string);
     get imageName(): string;
+    /**
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): Sprite;
     update(): void;
     draw(canvas: Canvas): void;
 }
@@ -1164,7 +1393,10 @@ declare class TextLine extends Entity implements IDrawable, IText, TextLineOptio
     isDrawable: boolean;
     isText: boolean;
     zPosition: number;
-    anchorPoint: Point;
+    anchorPoint: {
+        x: number;
+        y: number;
+    };
     private _text;
     private _fontName;
     private _fontColor;
@@ -1189,25 +1421,116 @@ declare class TextLine extends Entity implements IDrawable, IText, TextLineOptio
     set fontSize(fontSize: number);
     update(): void;
     initialize(): void;
+    /**
+     * Duplicates an entity using deep copy.
+     *
+     * @remarks This is a deep recursive clone (entity and children).
+     * The uuid property of all duplicated entities will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated entity. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): TextLine;
     draw(canvas: Canvas): void;
 }
 
 declare class Timer {
-    private originTime;
     private startTime;
     private stopTime;
     private stopped;
-    private _elapsed;
+    /**
+     * cumulativeElapsed is a cumulative total of elapsed time while the timer
+     * was in previous started (running) states, NOT INCLUDING the possibily
+     * active run's duration
+     */
+    private cumulativeElapsed;
     private name;
     private static _timers;
     constructor(name: string);
-    static Start(name: string): void;
-    static Stop(name: string): void;
-    static Restart(name: string): void;
-    static Elapsed(name: string): number;
-    static Remove(name: string): void;
-    static Exists(name: string): boolean;
-    static RemoveAll(): void;
+    /**
+     * Aliases performance.now()
+     *
+     * @remarks The m2c2kit Timer class is designed to measure elapsed durations
+     * after a designated start point for a uniquely named timer. However, if a
+     * timestamp based on the
+     * [time origin](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
+     * is needed, this method can be used.
+     *
+     * @returns a [DOMHighResTimeStamp](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp)
+     */
+    static now(): number;
+    /**
+     * Starts a millisecond-resolution timer based on
+     * [performance.now()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now).
+     *
+     * @remarks The method throws an error if a timer with the given
+     * name is already in a started state.
+     *
+     * @param name - The name of the timer to be started
+     */
+    static start(name: string): void;
+    /**
+     * Stops a timer.
+     *
+     * @remarks The method throws an error if a timer with the given
+     * name is already in a stopped state, or if a timer with the
+     * given name has not been started.
+     *
+     * @param name - The name of the timer to be stopped
+     */
+    static stop(name: string): void;
+    /**
+     * Restarts a timer.
+     *
+     * @remarks The timer elapsed duration is set to 0 and it starts anew.
+     * The method throws an error if a timer with the given
+     * name does not exist (if there is not a started or stopped timer
+     * with the given name).
+     *
+     * @param name - The name of the timer to be restarted
+     */
+    static restart(name: string): void;
+    /**
+     * Returns the total time elapsed, in milliseconds, of the timer.
+     *
+     * @remarks The total time elapsed will include all durations from multiple
+     * starts and stops of the timer, if applicable. A timer's elapsed duration
+     * can be read while it is in started or stopped state. The method throws
+     * an error if a timer with the given name does not exist.
+     *
+     * @param name - The name of the timer whose elapsed duration is requested
+     */
+    static elapsed(name: string): number;
+    /**
+     * Removes a timer.
+     *
+     * @remarks After removal, no additional methods can be used with a timer
+     * of the given name, other than to start a new timer with the given name,
+     * whose duration will begin at 0 again. The method throws an error if
+     * a timer with the given name does not exist.
+     *
+     * @param name - The name of the timer to be removed
+     */
+    static remove(name: string): void;
+    /**
+     * Remove all timers.
+     *
+     * @remarks This method will {@link remove} any timers in a started or
+     * stopped state. This method is idempotent; method is safe to call even
+     * if there are no timers to remove; no errors are thrown if there are
+     * not any timers that can be removed.
+     */
+    static removeAll(): void;
+    /**
+     * Checks if a timer of the given name exists.
+     *
+     * @remarks The method checks if there is a timer with the given name.
+     *
+     * @param name - The name of the timer to check for existence
+     * @returns boolean
+     */
+    static exists(name: string): boolean;
 }
 
 declare class Uuid {
@@ -1359,4 +1682,4 @@ declare class WebColors {
     static RebeccaPurple: RgbaColor;
 }
 
-export { Action, Activity, BrowserImage, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, Entity, EntityEventListener, EntityOptions, EntityType, FontData, FontManager, Game, GameCallbacks, GameData, GameLifecycleEvent, GameOptions, GameParameters, GameTrialEvent, GlobalVariables, GroupAction, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, Metadata, MoveAction, MoveActionOptions, Point, PropertySchema, PushTransition, RandomDraws, Rect, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionOptions, Shape, ShapeOptions, ShapeType, Size, Sprite, SpriteOptions, Story, StoryOptions, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, handleInterfaceOptions };
+export { Action, Activity, ActivityDataEvent, ActivityLifecycleEvent, ActivityType, BrowserImage, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, Entity, EntityEventListener, EntityOptions, EntityType, EventBase, EventType, FontData, FontManager, Game, GameData, GameOptions, GameParameters, GlobalVariables, GroupAction, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, Metadata, MoveAction, MoveActionOptions, Point, PropertySchema, PushTransition, RandomDraws, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionLifecycleEvent, SessionOptions, Shape, ShapeOptions, ShapeType, Size, Sprite, SpriteOptions, Story, StoryOptions, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, handleInterfaceOptions };