@m2c2kit/core 0.1.7 → 0.1.8

package/dist/index.d.ts

@@ -490,17 +490,51 @@ interface EventBase {
 /** 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 {
-    sessionLifecycle = "SessionLifecycle",
-    gameLifecycle = "GameLifecycle",
-    gameTrial = "GameTrial"
+    activityData = "ActivityData",
+    activityLifecycle = "ActivityLifecycle",
+    sessionLifecycle = "SessionLifecycle"
+}
+
+interface ActivityEvent extends EventBase {
+    uuid: string;
+    name: 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;
+    initialized?: boolean;
+    ended?: boolean;
+    started?: boolean;
 }
 
 interface SessionCallbacks {
@@ -508,22 +542,79 @@ interface SessionCallbacks {
     onSessionLifecycleChange?: (event: SessionLifecycleEvent) => void;
 }
 
-interface GameEvent extends EventBase {
-    gameUuid: string;
-    gameName: string;
+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;
 }
 
-interface GameLifecycleEvent extends GameEvent {
-    ended: boolean;
+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 GameParameters {
-    [key: string]: DefaultParameter;
-}
-interface DefaultParameter {
-    value: any;
-    type?: "number" | "string" | "boolean" | "object";
-    description?: string;
+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;
+    /** The activity's human friendly name */
+    name: string;
 }
 
 interface IDrawable {
@@ -532,14 +623,73 @@ interface IDrawable {
     zPosition: number;
 }
 
+interface DrawableOptions {
+    anchorPoint?: Point;
+    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.
  */
 declare type RgbaColor = [number, number, number, number];
 
-interface DrawableOptions {
-    anchorPoint?: Point;
-    zPosition?: number;
+/**
+ * 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 SceneOptions extends EntityOptions, DrawableOptions {
@@ -618,7 +768,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;
 }
 
@@ -660,16 +819,41 @@ 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 {
     _canvasKit?: CanvasKit;
     _session?: Session;
     uuid: string;
+    name: string;
     options: GameOptions;
     constructor(options: GameOptions);
     setParameters(newParameters: any): void;
@@ -737,6 +921,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.
      *
@@ -749,7 +934,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
@@ -758,7 +943,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
@@ -801,157 +986,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;
-    /** 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 {
-    /** 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;
@@ -1390,4 +1424,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, EventBase, EventType, 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, SessionLifecycleEvent, 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, 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, Rect, 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 };