@m2c2kit/core 0.1.4 → 0.1.8

package/dist/index.d.ts

@@ -484,22 +484,137 @@ 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 {
+    /** 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 {
@@ -508,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 {
@@ -548,9 +722,9 @@ 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 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 callback
      */
@@ -594,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;
 }
 
@@ -636,18 +819,44 @@ 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, specifiedParameters?: any);
+    constructor(options: GameOptions);
+    setParameters(newParameters: any): void;
     get canvasKit(): CanvasKit;
     set canvasKit(canvasKit: CanvasKit);
     get session(): Session;
@@ -712,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.
      *
@@ -724,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 onTrialComplete 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,9 +943,9 @@ declare class Game implements Activity {
     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.
+     * 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
      * the appropriate time. It is not triggered automatically.
      */
@@ -776,151 +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 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;
@@ -1359,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, 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, 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 };