@m2c2kit/core 0.1.1 → 0.1.5

package/dist/index.d.ts

@@ -1,67 +1,6 @@
-import { FontMgr, Typeface, Image, CanvasKit, Canvas } from 'canvaskit-wasm';
-
-interface FontData {
-    fontUrl: string;
-    fontArrayBuffer: ArrayBuffer;
-}
-
-declare class FontManager {
-    _fontMgr?: FontMgr;
-    private _typefaces;
-    _getTypeface(name: string): Typeface;
-    FetchFontsAsArrayBuffers(fontUrls: Array<string>): Promise<FontData>[];
-    LoadFonts(fonts: Array<ArrayBuffer>): void;
-}
-
-declare class LoadedImage {
-    name: string;
-    image: Image;
-    width: number;
-    height: number;
-    constructor(name: string, image: Image, width: number, height: number);
-}
-
-declare class RenderedDataUrlImage {
-    name: string;
-    dataUrlImage: string;
-    width: number;
-    height: number;
-    constructor(name: string, dataUrlImage: string, width: number, height: number);
-}
-
-/**
- * SVG image to be rendered and loaded from a URL or HTML svg tag in string form.
- */
-interface SvgImage {
-    /** Name that will be used to refer to the SVG image. Must be unique among all images */
-    name: string;
-    /** Width to scale SVG image to */
-    width: number;
-    /** Height to scale SVG 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> */
-    svgString?: string;
-    /** URL of SVG asset to render and load */
-    url?: string;
-}
-
-declare class ImageManager {
-    private scratchCanvas?;
-    private ctx?;
-    private scale?;
-    _renderedDataUrlImages: Record<string, RenderedDataUrlImage>;
-    _loadedImages: Record<string, LoadedImage>;
-    initialize(scratchCanvas: HTMLCanvasElement): void;
-    renderSvgImage(svgImage: SvgImage): Promise<RenderedDataUrlImage>;
-    LoadRenderedSvgImages(urls: RenderedDataUrlImage[]): void;
-    private convertRenderedDataUrlImage;
-    private dataURLtoArrayBuffer;
-}
+import { Canvas, CanvasKit, Image, FontMgr, Typeface } from 'canvaskit-wasm';
 
 declare class GlobalVariables {
-    canvasKit: CanvasKit;
-    fontManager: FontManager;
-    imageManager: ImageManager;
     now: number;
     deltaTime: number;
     canvasScale: number;
@@ -72,41 +11,55 @@ declare class GlobalVariables {
 
 declare global {
     var Globals: GlobalVariables;
+}
+//# sourceMappingURL=Globals.d.ts.map
+
+interface EntityEvent {
+    target: Entity;
+}
+
+interface EntityEventListener {
+    eventType: string;
+    entityName: string;
+    callback: (event: EntityEvent) => void;
 }
 
 /**
  * Position in two-dimensional space.
  */
 declare class Point {
+    /** Horizonal coordinate */
     x: number;
+    /** Vertical coordinate */
     y: number;
     constructor(x?: number, y?: number);
 }
 
-declare class TapListener {
-    entityName?: string;
-    codeCallback?: (tapevent: TapEvent) => void;
-}
-/**
- * Object passed to the tap event handler when the entity is tapped.
- */
-interface TapEvent {
-    /** The entity that was tapped */
-    tappedEntity: Entity;
+interface TapEvent extends EntityEvent {
     /** Point that was tapped on entity, relative to the entity coordinate system */
     point: Point;
 }
 
 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;
+    /** Constrain the top (vertical axis) of this entity to the bottom of the specified entity. This entity will appear immediately below the specified entity */
     topToBottomOf?: Entity | string;
+    /** Constrain the bottom (vertical axis) of this entity to the top of the specified entity. This entity will appear immediately above of the specified entity */
     bottomToTopOf?: Entity | string;
+    /** Constrain the bottom (vertical axis) of this entity to the bottom of the specified entity. The bottoms of both will appear at the same vertical location */
     bottomToBottomOf?: Entity | string;
+    /** Constrain the start (horizontal axis) of this entity to the start of the specified entity. The start of both will appear at the same horizontal location */
     startToStartOf?: Entity | string;
+    /** Constrain the start (horizontal axis) of this entity to the end of the specified entity. This entity will appear immediately to the right of the specified entity */
     startToEndOf?: Entity | string;
+    /** Constrain the end (horizontal axis) of this entity to the end of the specified entity. The end of both will appear at the same horizontal location */
     endToEndOf?: Entity | string;
+    /** Constrain the end (horizontal axis) of this entity to the start of the specified entity. This entity will appear immediately to the left of the specified entity */
     endToStartOf?: Entity | string;
+    /** When opposing horizontal constraints are applied, the default is to center the entity within the constraints (horizontalBias = .5). Setting horizontalBias less than .5 will pull the entity towards the start (to the left). Setting horizontalBias greater than .5 will pull the entity towards the end (to the right)  */
     horizontalBias?: number;
+    /** When opposing vertical constraints are applied, the default is to center the entity within the constraints (verticalBias = .5). Setting verticalBias less than .5 will pull the entity towards the top. Setting verticalBias greater than .5 will pull the entity towards the bottom */
     verticalBias?: number;
     [key: string]: Entity | string | number | undefined;
 }
@@ -136,11 +89,17 @@ declare class Size {
 }
 
 interface EntityOptions {
+    /** Name of the entity. Only needed if the entity will be referred to by name in a later function */
     name?: string;
+    /** Position of the entity within its parent coordinate system. Default is (0, 0) */
     position?: Point;
+    /** Scale of the entity. Default is 1.0 */
     scale?: number;
+    /** Does the entity respond to user events, such as taps? Default is false */
     isUserInteractionEnabled?: boolean;
+    /** Is the entity, and its children, hidden? (not displayed). Default is false */
     hidden?: boolean;
+    /** FOR INTERNAL USE ONLY */
     layout?: Layout;
 }
 
@@ -155,7 +114,7 @@ declare enum EntityType {
 }
 
 declare function handleInterfaceOptions(entity: Entity, options: EntityOptions): void;
-declare abstract class Entity {
+declare abstract class Entity implements EntityOptions {
     type: EntityType;
     isDrawable: boolean;
     isShape: boolean;
@@ -174,7 +133,7 @@ declare abstract class Entity {
     actions: Action[];
     queuedAction?: Action;
     originalActions: Action[];
-    tapListeners: TapListener[];
+    eventListeners: EntityEventListener[];
     uuid: string;
     needsInitialization: boolean;
     userData: any;
@@ -214,7 +173,13 @@ declare abstract class Entity {
      * Returns all descendant entities. Descendants are children and children of children, recursively.
      */
     get descendants(): Array<Entity>;
-    onTap(codeCallback: (tapEvent: TapEvent) => void, replaceExistingCodeCallback?: boolean): void;
+    /**
+     * Takes the callback function to be executed when the user taps down on the entity. A TapDown is either a mouse click within the bounds of an entity OR the beginning of touches within the bounds of an entity.
+     *
+     * @param callback - function to execute
+     * @param replaceExistingCallback  - should the provided callback replace any existing callbacks? Usually we want to have only one callback defined, instead of chaining multiple ones. It is strongly recommended not to change this, unless you have a special use case. Default is true.
+     */
+    onTapDown(callback: (tapEvent: TapEvent) => void, replaceExistingCallback?: boolean): void;
     private parseLayoutConstraints;
     private calculateYFromConstraint;
     private calculateXFromConstraint;
@@ -252,8 +217,8 @@ declare abstract class Entity {
      *
      * @returns Scene that contains this entity
      */
+    get canvasKit(): CanvasKit;
     get parentSceneAsEntity(): Entity;
-    private generateUUID;
     /**
      * 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
@@ -389,8 +354,8 @@ declare class GroupAction extends Action implements IActionContainer {
 }
 declare class CustomAction extends Action {
     type: ActionType;
-    codeCallback: () => void;
-    constructor(codeCallback: () => void, runDuringTransition?: boolean);
+    callback: () => void;
+    constructor(callback: () => void, runDuringTransition?: boolean);
 }
 declare class WaitAction extends Action {
     type: ActionType;
@@ -410,80 +375,155 @@ declare class ScaleAction extends Action {
     constructor(scale: number, duration: number, runDuringTransition?: boolean);
 }
 
-interface IDrawable {
-    draw(canvas: Canvas): void;
-    anchorPoint: Point;
-    zPosition: number;
+declare class LoadedImage {
+    name: string;
+    image: Image;
+    width: number;
+    height: number;
+    constructor(name: string, image: Image, width: number, height: number);
 }
 
-interface DrawableOptions {
-    anchorPoint?: Point;
-    zPosition?: number;
+/**
+ * Image that can be rendered by a browser and loaded from a URL or HTML svg tag in string form.
+ */
+interface BrowserImage {
+    /** Name that will be used to refer to the SVG image. Must be unique among all images */
+    name: string;
+    /** Width to scale SVG image to */
+    width: number;
+    /** Height to scale SVG 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> */
+    svgString?: string;
+    /** URL of SVG asset to render and load */
+    url?: string;
 }
 
-interface CompositeOptions extends EntityOptions, DrawableOptions {
+interface GameImages {
+    uuid: string;
+    images: Array<BrowserImage>;
 }
 
-declare abstract class Composite extends Entity implements IDrawable {
-    readonly type = EntityType.composite;
-    compositeType: string;
-    isDrawable: boolean;
-    anchorPoint: Point;
-    zPosition: number;
+declare class ImageManager {
+    canvasKit?: CanvasKit;
+    private renderedImages;
+    private loadedImages;
+    private _scratchCanvas?;
+    private ctx?;
+    private scale?;
+    getLoadedImage(gameUuid: string, imageName: string): LoadedImage;
     /**
-     * Base Drawable object for creating custom entities ("composites") composed of primitive entities.
+     * Adds a CanvasKit image to the images available to a given game.
+     * Typically, this won't be called directly 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
      *
-     * @param options
+     * @param loadedImage
+     * @param gameUuid
      */
-    constructor(options?: CompositeOptions);
-    initialize(): void;
-    update(): void;
-    draw(canvas: Canvas): void;
+    addLoadedImage(loadedImage: LoadedImage, gameUuid: string): void;
+    renderImages(allGamesImages: Array<GameImages>): Promise<void[]>;
+    loadAllGamesRenderedImages(): void;
+    private renderBrowserImage;
+    private convertRenderedDataUrlImageToCanvasKitImage;
+    /**
+     * scratchCanvas is an extra, non-visible canvas in the DOM we use so the native browser can render images
+     */
+    private get scratchCanvas();
+    private dataURLtoArrayBuffer;
 }
 
-/**
- * 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 GameFontUrls {
+    uuid: string;
+    fontUrls: Array<string>;
+}
 
-/**
- * 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;
+declare class FontManager {
+    canvasKit?: CanvasKit;
+    fontMgr?: FontMgr;
+    private gameTypefaces;
+    private allGamesFontData?;
+    /**
+     * Gets a typeface that was previously loaded for the specified game.
+     *
+     * @param gameUuid
+     * @param fontFamily
+     * @returns the requested Typeface
+     */
+    getTypeface(gameUuid: string, fontFamily: string): Typeface;
+    /**
+     * Fetches all fonts for all games.
+     *
+     * @param allGamesFontUrls
+     * @returns
+     */
+    fetchFonts(allGamesFontUrls: Array<GameFontUrls>): Promise<void>;
+    /**
+     * Takes the fonts, which have been previously fetched and converted into
+     * Array Buffers using FontManager.fetchFonts(), and makes them available
+     * to our engine
+     */
+    loadAllGamesFontData(): void;
+    /**
+     * For the specified game, fetches all fonts in the array of urls and
+     * stores fonts as array buffers.
+     *
+     * @param gameUuid
+     * @param fontUrls - array of font urls
+     * @returns
+     */
+    private fetchGameFontsAsArrayBuffers;
+    /**
+     * For the specified game, loads all fonts from array buffers and makes
+     * fonts available within canvaskit as a Typeface
+     *
+     * @param gameUuid
+     * @param fonts - array of fonts in array buffer form
+     */
+    private loadGameFonts;
+}
+
+interface GameEvent {
+    gameUuid: string;
+    gameName: string;
+}
+
+interface GameLifecycleEvent extends GameEvent {
+    ended: boolean;
+}
+
+interface GameParameters {
+    [key: string]: DefaultParameter;
+}
+interface DefaultParameter {
+    value: any;
+    type?: "number" | "string" | "boolean" | "object";
+    description?: string;
+}
+
+interface IDrawable {
+    draw(canvas: Canvas): void;
+    anchorPoint: Point;
+    zPosition: number;
 }
 
 /**
- * This enum is used interally for processing the layout constraints. We use
- * an enum to avoid magic strings.
+ * Color in red (0-255), green (0-255), blue (0-255), alpha (0-1) format. Must be numeric array of length 4.
  */
-declare enum ConstraintType {
-    topToTopOf = "topToTopOf",
-    topToBottomOf = "topToBottomOf",
-    bottomToTopOf = "bottomToTopOf",
-    bottomToBottomOf = "bottomToBottomOf",
-    startToStartOf = "startToStartOf",
-    startToEndOf = "startToEndOf",
-    endToEndOf = "endToEndOf",
-    endToStartOf = "endToStartOf"
-}
+declare type RgbaColor = [number, number, number, number];
 
-declare enum Dimensions {
-    MATCH_CONSTRAINT = 0
+interface DrawableOptions {
+    anchorPoint?: Point;
+    zPosition?: number;
 }
 
 interface SceneOptions extends EntityOptions, DrawableOptions {
+    /** Background color of the scene. Default is Constants.DEFAULT_SCENE_BACKGROUND_COLOR (WebColors.WhiteSmoke) */
     backgroundColor?: RgbaColor;
 }
 
-declare class Scene extends Entity implements IDrawable {
+declare class Scene extends Entity implements IDrawable, SceneOptions {
     readonly type = EntityType.scene;
     isDrawable: boolean;
     anchorPoint: Point;
@@ -499,8 +539,7 @@ declare class Scene extends Entity implements IDrawable {
      *
      * @remarks The scene is the game screen or stage, and fills the entire available screen. There are usually multiple screens to contain multiple stages of the game, such as various instruction pages or phases of a game.
      *
-     * @param options
-     * @see {@link SceneOptions}
+     * @param options - {@link SceneOptions}
      */
     constructor(options?: SceneOptions);
     initialize(): void;
@@ -509,19 +548,26 @@ declare class Scene extends Entity implements IDrawable {
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
     /**
-     * Code that will be called every time the screen is shown.
+     * Code that will be called every time the screen is first presented.
      *
-     * @remarks Use this callback to "reset" entities to their initial state. For example, if a screen 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 screen may have been displayed. In addition, if entities should vary in each iteration, that should be done here.
+     * @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 codeCallback
+     * @param callback
      */
-    setup(codeCallback: (scene: Scene) => void): void;
+    setup(callback: (scene: Scene) => void): void;
     draw(canvas: Canvas): void;
 }
 
 declare abstract class Transition {
     abstract type: TransitionType;
     duration: number;
+    /**
+     * Creates a scene transition in which the outgoing scene slides out and the incoming scene slides in, as if the incoming scene pushes it.
+     *
+     * @param direction - TransitionDirection in which the push action goes
+     * @param duration - Duration, in millis, of the transition
+     * @returns
+     */
     static push(direction: TransitionDirection, duration: number): PushTransition;
 }
 declare class PushTransition extends Transition {
@@ -544,10 +590,28 @@ declare class SceneTransition {
     constructor(scene: Scene, transition?: Transition | undefined);
 }
 
+interface TrialSchema {
+    [key: string]: PropertySchema;
+}
+interface PropertySchema {
+    type: "number" | "string" | "boolean" | "object";
+    description?: string;
+}
+
 /**
  * Options to specify HTML canvas, set game canvas size, and load game assets.
  */
-interface GameInitOptions {
+interface GameOptions {
+    /** Human-friendly name of this game */
+    name: string;
+    /** Version of this game */
+    version?: string;
+    /** Uri (repository, webpage, or other location where full information about the game can be found) */
+    uri?: string;
+    /** Brief description of game */
+    shortDescription?: string;
+    /** Full description of game */
+    longDescription?: string;
     /** Id of the HTML canvas that game will be drawn on. If not provided, the first canvas found will be used */
     canvasId?: string;
     /** Width of game canvas */
@@ -557,13 +621,13 @@ interface GameInitOptions {
     /** Stretch to fill screen? Default is false */
     stretch?: boolean;
     /** Schema of trial data; JSON object where key is variable name, value is data type */
-    trialSchema?: object;
+    trialSchema?: TrialSchema;
     /** Default game parameters; JSON object where key is the game parameter, value is default value */
-    defaultParameters?: object;
+    parameters?: GameParameters;
     /** String array of urls from which to load fonts. The first element will be the default font */
     fontUrls?: Array<string>;
-    /** Array of SvgImage objects to render and load */
-    svgImages?: SvgImage[];
+    /** Array of BrowserImage objects to render and load */
+    images?: Array<BrowserImage>;
     /** Show FPS in upper left corner? Default is false */
     showFps?: boolean;
     /** Color of the html body, if the game does not fill the screen. Useful for showing scene boundaries. Default is the scene background color */
@@ -578,25 +642,20 @@ interface TrialData {
 interface Metadata {
     userAgent?: string;
 }
-interface GameData {
-    trials: Array<TrialData>;
-    metadata: Metadata;
-}
-interface LifecycleCallbacks {
-    trialComplete: (trialNumber: number, data: GameData, trialSchema: object) => void;
-    allTrialsComplete: (data: GameData, trialSchema: object) => void;
-}
-declare class Game {
+declare class Game implements Activity {
+    _canvasKit?: CanvasKit;
+    _session?: Session;
+    uuid: string;
+    options: GameOptions;
+    constructor(options: GameOptions, specifiedParameters?: any);
+    get canvasKit(): CanvasKit;
+    set canvasKit(canvasKit: CanvasKit);
+    get session(): Session;
+    set session(session: Session);
     entryScene?: Scene | string;
-    parameters: any;
-    private defaultParameters;
     data: GameData;
-    trialNumber: number;
-    trialSchema: {};
-    lifecycle: LifecycleCallbacks;
-    private trialSchemaMap;
+    trialIndex: number;
     private htmlCanvas?;
-    private scratchHtmlCanvas?;
     private surface?;
     private showFps?;
     private bodyBackgroundColor?;
@@ -611,40 +670,25 @@ declare class Game {
     private animationFramesRequested;
     private limitFps;
     private unitTesting;
+    private gameStopRequested;
     canvasCssWidth: number;
     canvasCssHeight: number;
     private scenes;
     private incomingSceneTransitions;
     private currentSceneSnapshot?;
-    /**
-     * Asynchronously initializes the game engine and load assets
-     *
-     * @param gameInitOptions
-     * @returns Promise<void>
-     */
-    init(gameInitOptions: GameInitOptions): Promise<void>;
-    /**
-     * Provide a callback function to be invoked when a trial has completed.
-     * It is the responsibility of the the game programmer to call this
-     * at the appropriate time. It is not triggered automatically.
-     * @param codeCallback
-     */
-    onTrialComplete(codeCallback: (trialNumber: number, data: GameData, trialSchema: object) => void): void;
-    /**
-     * Provide a callback function to be invoked when all trials are complete.
-     * It is the responsibility of the the game programmer to call this
-     * at the appropriate time. It is not triggered automatically.
-     * @param codeCallback
-     */
-    onAllTrialsComplete(codeCallback: (data: GameData) => void): void;
     /**
      * Adds a scene to the game.
      *
-     * @remarks A scene, and its children entities, cannot be preseneted unless it has been added to the game object.
+     * @remarks A scene, and its children entities, cannot be presented unless it has been added to the game object.
      *
      * @param scene
      */
     addScene(scene: Scene): void;
+    /**
+     * Adds multiple scenes to the game.
+     *
+     * @param scenes
+     */
     addScenes(scenes: Array<Scene>): void;
     /**
      * Specifies the scene that will be presented upon the next frame draw.
@@ -654,10 +698,8 @@ declare class Game {
      */
     presentScene(scene: string | Scene, transition?: Transition): void;
     /**
-     * Gets the value of the specified game parameter. If the value was not
-     * provided in the parameters property above, then return the value in
-     * defaultParameters. If the parameterName is still not found, then
-     * throw exception.
+     * Gets the value of the game parameter. If parameterName
+     * is not found, then throw exception.
      * @param parameterName - the name of the game parameter whose value is requested
      * @returns
      */
@@ -668,13 +710,37 @@ declare class Game {
      * @param entryScene - The scene (Scene object or its string name) to display when the game starts
      */
     start(entryScene?: Scene | string): void;
-    initData(trialSchema: object): void;
+    stop(): void;
+    initData(): void;
+    /**
+     * Adds data to the game's TrialData object.
+     *
+     * @remarks The variableName must be previously defined in the trialSchema object passed in during game initialization. see {@link GameInitOptions.trialSchema}. The type of the value must match what was defined in the trialSchema, otherwise an error is thrown.
+     *
+     * @param variableName - variable to be set
+     * @param value - value of the variable to set
+     */
     addTrialData(variableName: string, value: any): void;
-    private loadCanvasKit;
+    /**
+     * Should be called when the current trial has completed. It will
+     * also increment the trial index.
+     * Calling this will trigger the onTrialComplete 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
+     * the appropriate time. It is not triggered automatically.
+     */
+    trialComplete(): void;
+    /**
+     * Should be called when the current game has ended. This will trigger
+     * the onGameEnd callback function, if one was provided in SessionOptions.
+     * This is how the game communicates its ended or "finished" state to the
+     * parent session.
+     * It is the responsibility of the the game programmer to call this at
+     * the appropriate time. It is not triggered automatically.
+     */
+    end(): void;
     private setupHtmlCanvases;
-    private fetchFonts;
-    private renderSvgImages;
-    private loadFonts;
     private setupCanvasKitSurface;
     private setupFpsFont;
     private setupEventHandlers;
@@ -687,27 +753,174 @@ declare class Game {
     private animateSceneTransition;
     private drawFps;
     /**
-     * Creates a tap listener for an entity based on the entity name
+     * Creates an event listener for an entity based on the entity name
      *
-     * @remarks Typically, tap listeners will be created using the onTap() method of each entity. This alternative allows creation with entity name.
+     * @remarks Typically, event listeners will be created using a method specific to the event, such as onTapDown(). This alternative allows creation with entity name.
      *
-     * @param entityName
-     * @param codeCallback
-     * @param replaceExistingCodeCallback
+     * @param eventType - the type of event to listen for, e.g., "tapdown"
+     * @param entityName - the entity name for which an event will be listened
+     * @param callback
+     * @param replaceExistingCallback
      */
-    createTapListener(entityName: string, codeCallback: (tapEvent: TapEvent) => void, replaceExistingCodeCallback?: boolean): void;
+    createEventListener(eventType: string, entityName: string, callback: (event: EntityEvent) => void, replaceExistingCallback?: boolean): void;
     /**
      * Returns array of all entities that have been added to the game object.
      */
     get entities(): Array<Entity>;
     private htmlCanvasMouseDownHandler;
     private htmlCanvasTouchStartHandler;
+    private sceneCanReceiveUserInteraction;
     private processTaps;
     private handleEntityTapped;
     private tapIsWithinEntityBounds;
     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 current game has ended. */
+    onGameEnd?: (event: GameLifecycleEvent) => void;
+    /** Callback executed when a game trial has completed. */
+    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;
@@ -716,9 +929,13 @@ interface IText {
 }
 
 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;
 }
 
@@ -729,12 +946,15 @@ declare enum LabelHorizontalAlignmentMode {
 }
 
 interface LabelOptions extends EntityOptions, DrawableOptions, TextOptions {
+    /** Horizontal alignment of label text. see {@link LabelHorizontalAlignmentMode}. Default is LabelHorizontalAlignmentMode.center  */
     horizontalAlignmentMode?: LabelHorizontalAlignmentMode;
+    /** Maximum width of label text before wrapping occurs. Default is the canvas width */
     preferredMaxLayoutWidth?: number;
+    /** Background color  of label text. Default is no background color */
     backgroundColor?: RgbaColor;
 }
 
-declare class Label extends Entity implements IDrawable, IText {
+declare class Label extends Entity implements IDrawable, IText, LabelOptions {
     readonly type = EntityType.label;
     isDrawable: boolean;
     isText: boolean;
@@ -752,9 +972,9 @@ declare class Label extends Entity implements IDrawable, IText {
     /**
      * Single or multi-line text formatted and rendered on the screen.
      *
-     * @remarks  Label (in contrast to TextLine) has enhanced text support for line wrapping, centering/alignment, and background colors.
+     * @remarks Label (in contrast to TextLine) has enhanced text support for line wrapping, centering/alignment, and background colors.
      *
-     * @param options
+     * @param options - {@link LabelOptions}
      */
     constructor(options?: LabelOptions);
     initialize(): void;
@@ -825,11 +1045,17 @@ declare class RandomDraws {
 }
 
 interface RectOptions {
+    /** Position of rectangle */
     origin?: Point;
+    /** Size of rectangle */
     size?: Size;
+    /** X coordinate of rectangle position; this can be used instead of setting the origin property */
     x?: number;
+    /** Y coordinate of rectangle position; this can be used instead of setting the origin property */
     y?: number;
+    /** Width of rectangle; this can be used instead of setting the size property */
     width?: number;
+    /** Height of rectangle; this can be used instead of setting the size property */
     height?: number;
 }
 
@@ -844,11 +1070,17 @@ declare class Rect implements RectOptions {
 }
 
 interface ShapeOptions extends EntityOptions, DrawableOptions {
+    /** 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;
+    /** Radius of rectangle's corners */
     cornerRadius?: number;
+    /** Color with which to fill shape. Default is Constants.DEFAULT_SHAPE_FILL_COLOR (WebColors.Red)  */
     fillColor?: RgbaColor;
+    /** Color with which to outline shape. Default is no color */
     strokeColor?: RgbaColor;
+    /** Width of outline. Default is undefined */
     lineWidth?: number;
 }
 
@@ -858,7 +1090,7 @@ declare enum ShapeType {
     circle = "Circle"
 }
 
-declare class Shape extends Entity implements IDrawable {
+declare class Shape extends Entity implements IDrawable, ShapeOptions {
     readonly type = EntityType.shape;
     isDrawable: boolean;
     isShape: boolean;
@@ -874,9 +1106,9 @@ declare class Shape extends Entity implements IDrawable {
     private fillColorPaint?;
     private strokeColorPaint?;
     /**
-     * Rectangular shape
+     * Rectangular or circular shape
      *
-     * @param options
+     * @param options - {@link ShapeOptions}
      */
     constructor(options?: ShapeOptions);
     initialize(): void;
@@ -889,10 +1121,11 @@ declare class Shape extends Entity implements IDrawable {
 }
 
 interface SpriteOptions extends EntityOptions, DrawableOptions {
+    /** Name of image to use for sprite. Must have been previously loaded */
     imageName?: string;
 }
 
-declare class Sprite extends Entity implements IDrawable {
+declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     readonly type = EntityType.sprite;
     isDrawable: boolean;
     anchorPoint: Point;
@@ -904,7 +1137,7 @@ declare class Sprite extends Entity implements IDrawable {
      *
      * @remarks Sprites must be loaded during the Game.init() method prior to their use.
      *
-     * @param options
+     * @param options - {@link SpriteOptions}
      */
     constructor(options?: SpriteOptions);
     initialize(): void;
@@ -926,7 +1159,7 @@ interface TextLineOptions extends EntityOptions, DrawableOptions, TextOptions {
     width?: number;
 }
 
-declare class TextLine extends Entity implements IDrawable, IText {
+declare class TextLine extends Entity implements IDrawable, IText, TextLineOptions {
     readonly type = EntityType.textline;
     isDrawable: boolean;
     isText: boolean;
@@ -943,7 +1176,7 @@ declare class TextLine extends Entity implements IDrawable, IText {
      *
      * @remarks TextLine has no paragraph formatting options; Label will be preferred in most use cases.
      *
-     * @param options
+     * @param options - {@link TextLineOptions}
      */
     constructor(options?: TextLineOptions);
     get text(): string;
@@ -977,6 +1210,10 @@ declare class Timer {
     static RemoveAll(): void;
 }
 
+declare class Uuid {
+    static generate(): string;
+}
+
 declare class WebColors {
     static Transparent: RgbaColor;
     static MediumVioletRed: RgbaColor;
@@ -1122,4 +1359,4 @@ declare class WebColors {
     static RebeccaPurple: RgbaColor;
 }
 
-export { Action, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, Dimensions, DrawableOptions, Entity, EntityOptions, EntityType, FontData, FontManager, Game, GameInitOptions, GlobalVariables, GroupAction, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, MoveAction, MoveActionOptions, Point, PushTransition, RandomDraws, Rect, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Shape, ShapeOptions, ShapeType, Size, Sprite, SpriteOptions, Story, StoryOptions, SvgImage, TapEvent, TapListener, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, WaitAction, WaitActionOptions, WebColors, handleInterfaceOptions };
+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 };