@m2c2kit/core 0.3.7 → 0.3.9

package/dist/index.d.ts

@@ -14,16 +14,6 @@ declare global {
 }
 //# sourceMappingURL=Globals.d.ts.map
 
-/**
- * The type of activity.
- *
- * @remarks Currently, m2c2kit has only Game and Survey activities.
- */
-declare enum ActivityType {
-    Game = "Game",
-    Survey = "Survey"
-}
-
 /** Base interface for all Activity events. */
 interface ActivityEvent extends EventBase {
     target: Activity;
@@ -34,6 +24,16 @@ interface ActivityKeyValueData {
     [key: string]: string | number | boolean | object | undefined | null;
 }
 
+/**
+ * The type of activity.
+ *
+ * @remarks Currently, m2c2kit has only Game and Survey activities.
+ */
+declare enum ActivityType {
+    Game = "Game",
+    Survey = "Survey"
+}
+
 /** A snapshot of performance at a single point in time.
  *
  * @remarks This describes performance of the application internals, not the
@@ -96,6 +96,14 @@ interface ActivityResults {
     activityMetrics?: Array<ActivityMetric>;
 }
 
+/**
+ * Notifies when an activity starts, ends, cancels, or
+ * creates data.
+ */
+interface ActivityLifecycleEvent extends ActivityEvent {
+    results?: ActivityResults;
+}
+
 /**
  * Dispatched when new data is created by an activity.
  *
@@ -129,7 +137,7 @@ interface ActivityResultsEvent extends ActivityEvent, ActivityResults {
  * ...
  * const db: IDataStore = new LocalDatabase();
  * session.dataStore = db;
- * session.init();
+ * session.initialize();
  * ```
  */
 interface IDataStore {
@@ -705,6 +713,13 @@ declare class I18n {
     private mergeAdditionalTranslations;
 }
 
+interface CallbackOptions {
+    /** Should the provided callback replace any existing callbacks of the same event type for this target? Default is false */
+    replaceExisting?: boolean;
+    /** String identifier used to identify the callback. Only needed if the callback will be removed later */
+    key?: string;
+}
+
 interface TrialData {
     [key: string]: string | number | boolean | object | undefined | null;
 }
@@ -718,6 +733,7 @@ declare class Game implements Activity {
     options: GameOptions;
     beginTimestamp: number;
     beginIso8601Timestamp: string;
+    private eventListeners;
     private gameMetrics;
     private fpsMetricReportThreshold;
     private maximumRecordedActivityMetrics;
@@ -739,6 +755,7 @@ declare class Game implements Activity {
     constructor(options: GameOptions);
     private addLocalizationParametersToGameParameters;
     init(): Promise<void>;
+    initialize(): Promise<void>;
     /**
      * Saves an item to the activity's key-value store.
      *
@@ -747,7 +764,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      * @param key - item key
      * @param value - item value
@@ -765,7 +782,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
@@ -782,7 +799,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
@@ -798,7 +815,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      */
     storeClearItems(): Promise<void>;
@@ -810,7 +827,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      * @param globalStore - if true, treat the item as "global" and not
      * associated with a specific activity; global items can be accessed
@@ -825,7 +842,7 @@ declare class Game implements Activity {
      * ```
      * const db: IDataStore = new LocalDatabase();
      * session.dataStore = db;
-     * session.init();
+     * session.initialize();
      * ```
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
@@ -1098,21 +1115,23 @@ declare class Game implements Activity {
     /**
      * Should be called when current game has ended successfully.
      *
-     * @remarks This will trigger the onActivityLifecycleChange callback function,
-     * if one was provided in SessionOptions. This is how the game can communicate
-     * its 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.
+     * @remarks This will send an ActivityEnd event to any listeners, such as
+     * a function provided to Game.onEnd() or a callback defined in
+     * SessionOptions.activityCallbacks.onActivityLifecycle. This is how the
+     * game can communicate changes in activity 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;
     /**
      * Should be called when current game has been canceled by a user action.
      *
-     * @remarks This will trigger the onActivityLifecycleChange callback function,
-     * if one was provided in SessionOptions. This is how the game can communicate
-     * its 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.
+     * @remarks This will send an ActivityCancel event to any listeners, such as
+     * a function provided to Game.onCancel() or a callback defined in
+     * SessionOptions.activityCallbacks.onActivityLifecycle. This is how the
+     * game can communicate changes in activity 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.
      */
     cancel(): void;
     private setupHtmlCanvases;
@@ -1161,10 +1180,10 @@ declare class Game implements Activity {
      *
      * @param type - 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
+     * @param callback - the callback to be invoked when the event occurs
+     * @param callbackOptions
      */
-    createEventListener(type: EventType, entityName: string, callback: (event: EntityEvent) => void, replaceExistingCallback?: boolean): void;
+    createEventListener(type: EventType, entityName: string, callback: (event: EntityEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Returns array of all entities that have been added to the game object.
      */
@@ -1211,6 +1230,36 @@ declare class Game implements Activity {
     private raiseM2DragEvent;
     private raiseM2DragEndEvent;
     private calculatePointWithinEntityFromDomPointerEvent;
+    /**
+     * Executes a callback when the game starts.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onStart(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the game is canceled.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onCancel(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the game ends.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onEnd(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the game generates data.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): void;
+    private addEventListener;
+    private raiseActivityEventOnListeners;
     private raiseEventOnListeningEntities;
     private sceneCanReceiveUserInteraction;
     /**
@@ -1288,14 +1337,6 @@ declare class FontManager {
     loadAllGamesFontData(): void;
 }
 
-/**
- * Notifies when an activity starts, ends, cancels, or
- * creates data.
- */
-interface ActivityLifecycleEvent extends ActivityEvent {
-    results?: ActivityResults;
-}
-
 interface ActivityCallbacks {
     /** Callback executed when the activity lifecycle changes, such as when it ends. */
     onActivityLifecycle?: (event: ActivityLifecycleEvent) => void;
@@ -1332,6 +1373,12 @@ interface SessionOptions {
     sessionUuid?: string;
     /** URL of session assets folder (which contains wasm binary), if not the default location of "assets" */
     assetsUrl?: string;
+    /** After the session initializes, should the session automatically start? Default is true */
+    autoStartAfterInit?: boolean;
+    /** When an activity ends or is canceled, should the session automatically go to the next activity? Default is true */
+    autoGoToNextActivity?: boolean;
+    /** After the last activity ends or is canceled, should the session automatically end? Default is true */
+    autoEndAfterLastActivity?: boolean;
     /** NOT IMPLEMENTED YET: Orientation the screen should be locked to for this session. Value will be passed into the ScreenOrientation.lock() Web API. */
     orientation?: "natural" | "landscape" | "portrait" | "portrait-primary" | "portrait-secondary" | "landscape-primary" | "landscape-secondary";
 }
@@ -1343,8 +1390,10 @@ declare class Session {
     currentActivity?: Activity;
     uuid: string;
     dataStore?: IDataStore;
+    private eventListeners;
     private sessionDictionary;
     private canvasKit?;
+    private initialized;
     private version;
     /**
      * A Session contains one or more activities. The session manages the start
@@ -1353,10 +1402,71 @@ declare class Session {
      * @param options
      */
     constructor(options: SessionOptions);
+    /**
+     * Executes a callback when the session initializes.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onInitialize(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the session starts.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onStart(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the session ends.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onEnd(callback: (sessionLifecycleEvent: SessionLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when any activity in the session generates data.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onActivityData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): void;
+    private addEventListener;
+    private raiseEventOnListeners;
+    private sessionActivityStartHandler;
+    private sessionActivityCancelHandler;
+    private sessionActivityEndHandler;
+    private sessionActivityLifecycleHandler;
+    private activityResultsEventHandler;
     /**
      * Asynchronously initializes the m2c2kit engine and loads assets
+     *
+     * @deprecated Use Session.initialize() instead.
      */
     init(): Promise<void>;
+    /**
+     * Check if the Activity uses the deprecated init() method.
+     *
+     * @remarks Activity.init() is deprecated and should be replaced with
+     * Activity.initialize().
+     *
+     * @param activity
+     * @returns true if the activity defines its own init() method, false otherwise.
+     */
+    private activityUsesDeprecatedInit;
+    /**
+     * Asynchronously initializes the m2c2kit engine and loads assets
+     */
+    initialize(): Promise<void>;
+    /**
+     * Waits for the session to be initialized.
+     *
+     * @remarks Session.initialize() is asynchronous, and it should be awaited
+     * so that the session is fully initialized before calling Session.start().
+     * If it is not awaited (or it cannot be awaited because the target
+     * environment does not support top-level await), this function ensures that
+     * the session has been initialized.
+     */
+    private waitForSessionInitialization;
     /**
      * Starts the session and starts the first activity.
      */
@@ -1465,12 +1575,60 @@ type SessionDictionaryValues = string | number | boolean | object | null | undef
 interface Activity {
     /** The type of activity: Game or Survey */
     type: ActivityType;
-    /** Initializes the activity. All code to create the activity's appearance and behavior must be placed in this method. This method is asynchronous, and must be awaited. When writing a new game by extending the `Game` class, this method will be overridden, but the base method must still be called with `await super.init()`. */
+    /**
+     * Initializes the activity.
+     *
+     * @remarks All code to create the activity's appearance and behavior must
+     * be placed in this method. This method is asynchronous, and must be
+     * awaited. When writing a new game by extending the `Game` class, this
+     * method will be overridden, but the base method must still be called with
+     * `await super.initialize()`.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initializes the activity.
+     *
+     * @remarks All code to create the activity's appearance and behavior must
+     * be placed in this method. This method is asynchronous, and must be
+     * awaited. When writing a new game by extending the `Game` class, this
+     * method will be overridden, but the base method must still be called with
+     * `await super.init()`.
+     *
+     * @deprecated use Game.initialize() instead.
+     */
     init(): Promise<void>;
     /** Starts the activity */
     start(): Promise<void>;
     /** Stops the activity */
     stop(): void;
+    /**
+     * Executes a callback when the activity starts.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onStart(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the activity is canceled.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onCancel(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the activity ends.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onEnd(callback: (activityLifecycleEvent: ActivityLifecycleEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the activity generates data.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onData(callback: (activityResultsEvent: ActivityResultsEvent) => void, options?: CallbackOptions): 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. */
@@ -1731,7 +1889,7 @@ declare abstract class Entity implements EntityOptions {
      * 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;
+    onTapDown(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press, that has been fully
      * within the entity, from the entity.
@@ -1747,7 +1905,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onTapUp(callback: (tapEvent: TapEvent) => void, replaceExistingCallback?: boolean): void;
+    onTapUp(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press from the entity within
      * the bounds of the entity.
@@ -1764,7 +1922,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onTapUpAny(callback: (tapEvent: TapEvent) => void, replaceExistingCallback?: boolean): void;
+    onTapUpAny(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user moves the pointer (mouse, touches) beyond
      * the bounds of the entity while the pointer is down.
@@ -1780,7 +1938,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onTapLeave(callback: (tapEvent: TapEvent) => void, replaceExistingCallback?: boolean): void;
+    onTapLeave(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the pointer first is down on the entity.
      *
@@ -1794,7 +1952,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onPointerDown(callback: (m2PointerEvent: M2PointerEvent) => void, replaceExistingCallback?: boolean): void;
+    onPointerDown(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press from the entity within
      * the bounds of the entity.
@@ -1810,7 +1968,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onPointerUp(callback: (m2PointerEvent: M2PointerEvent) => void, replaceExistingCallback?: boolean): void;
+    onPointerUp(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user moves the pointer (mouse or touches)
      * within the bounds of the entity.
@@ -1822,7 +1980,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onPointerMove(callback: (m2PointerEvent: M2PointerEvent) => void, replaceExistingCallback?: boolean): void;
+    onPointerMove(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user begins dragging an entity.
      *
@@ -1833,7 +1991,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onDragStart(callback: (m2DragEvent: M2DragEvent) => void, replaceExistingCallback?: boolean): void;
+    onDragStart(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user continues dragging an entity.
      *
@@ -1844,7 +2002,7 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onDrag(callback: (m2DragEvent: M2DragEvent) => void, replaceExistingCallback?: boolean): void;
+    onDrag(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
     /**
      * Executes a callback when the user stop dragging an entity.
      *
@@ -1855,8 +2013,8 @@ declare abstract class Entity implements EntityOptions {
      * ones. It is strongly recommended not to change this, unless you have a
      * special use case. Default is true.
      */
-    onDragEnd(callback: (m2DragEvent: M2DragEvent) => void, replaceExistingCallback?: boolean): void;
-    private addEventListener;
+    onDragEnd(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
+    addEventListener(type: EventType, callback: (ev: EntityEvent) => void, callbackOptions?: CallbackOptions): void;
     private parseLayoutConstraints;
     private calculateYFromConstraint;
     private calculateXFromConstraint;
@@ -2184,6 +2342,7 @@ declare class Constants {
     static readonly OUTGOING_SCENE_NAME = "__outgoingScene";
     static readonly OUTGOING_SCENE_SPRITE_NAME = "__outgoingSceneSprite";
     static readonly OUTGOING_SCENE_IMAGE_NAME = "__outgoingSceneSnapshot";
+    static readonly SESSION_INITIALIZATION_POLLING_INTERVAL_MS = 50;
 }
 
 /**
@@ -2226,6 +2385,12 @@ declare class Equals {
     static rgbaColor(color1?: RgbaColor, color2?: RgbaColor): boolean;
 }
 
+interface EventListenerBase {
+    type: EventType;
+    callback: (event: EventBase) => void;
+    key?: string;
+}
+
 interface IText {
     text?: string;
     fontName?: string;
@@ -2581,7 +2746,7 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     /**
      * Visual image displayed on the screen.
      *
-     * @remarks Images that will be used to create the sprite must be loaded during the Game.init() method prior to their use.
+     * @remarks Images that will be used to create the sprite must be loaded during the Game.initialize() method prior to their use.
      *
      * @param options - {@link SpriteOptions}
      */
@@ -2935,4 +3100,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, Activity, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, ActivityType, BrowserImage, CanvasKitHelpers, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, EasingFunction, Easings, Entity, EntityEvent, EntityEventListener, EntityOptions, EntityType, Equals, EventBase, EventType, FontData, FontManager, Game, GameData, GameOptions, GameParameters, GlobalVariables, GoToActivityOptions, GroupAction, I18n, IDataStore, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, M2DragEvent, M2Path, MoveAction, MoveActionOptions, MutablePath, NoneTransition, Point, RandomDraws, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionDictionaryValues, SessionLifecycleEvent, SessionOptions, Shape, ShapeOptions, ShapeType, Size, SlideTransition, SlideTransitionOptions, Sprite, SpriteOptions, Story, StoryOptions, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, Translations, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, Activity, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, ActivityType, BrowserImage, CallbackOptions, CanvasKitHelpers, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, EasingFunction, Easings, Entity, EntityEvent, EntityEventListener, EntityOptions, EntityType, Equals, EventBase, EventListenerBase, EventType, FontData, FontManager, Game, GameData, GameOptions, GameParameters, GlobalVariables, GoToActivityOptions, GroupAction, I18n, IDataStore, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, M2DragEvent, M2Path, MoveAction, MoveActionOptions, MutablePath, NoneTransition, Point, RandomDraws, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionDictionaryValues, SessionLifecycleEvent, SessionOptions, Shape, ShapeOptions, ShapeType, Size, SlideTransition, SlideTransitionOptions, Sprite, SpriteOptions, Story, StoryOptions, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, Translations, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };