@m2c2kit/core 0.3.9 → 0.3.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Scott T. Yabiku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,22 @@
 # @m2c2kit/core
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI/CD](https://github.com/m2c2-project/m2c2kit/actions/workflows/ci.yml/badge.svg)](https://github.com/m2c2-project/m2c2kit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@m2c2kit/core.svg)](https://www.npmjs.com/package/@m2c2kit/core)
+
 This package implements the m2c2kit core functionality.
 
-License: MIT
+**m2c2kit** is a library for cross-platform cognitive assessments. Features:
+
+- **Mobile first**. Optimized for touch and mobile devices while also usable on desktops.
+- **Portable**. Use on browsers, compile within native apps using web views, or embed in products like Qualtrics. A shared assessment codebase reduces development time and promotes experiment standardization across devices and services.
+- **Rapid iteration**. Quickly develop and test new assessments with the JavaScript-based library and deploy them in studies.
+
+## Resources
+
+---
+
+- [Website](https://m2c2-project.github.io/m2c2kit/)
+- [Live Examples](https://m2c2-project.github.io/m2c2kit/docs/category/examples)
+- [Getting Started](https://m2c2-project.github.io/m2c2kit/docs/getting-started)
+- [Interactive Tutorials](https://m2c2-project.github.io/m2c2kit/docs/category/tutorials)

package/dist/index.d.ts

@@ -720,6 +720,15 @@ interface CallbackOptions {
     key?: string;
 }
 
+/**
+ * Notifies when events in the Frame cycle occur on a Game.
+ */
+interface FrameCycleEvent extends EventBase {
+    target: Game;
+    /** difference in milliseconds since the last Frame lifecycle began */
+    deltaTime: number;
+}
+
 interface TrialData {
     [key: string]: string | number | boolean | object | undefined | null;
 }
@@ -742,7 +751,7 @@ declare class Game implements Activity {
     i18n?: I18n;
     private warmupFunctionQueue;
     private loaderElementsRemoved;
-    private _dataStore?;
+    private _dataStores?;
     additionalParameters?: unknown;
     staticTrialSchema: {
         [key: string]: JsonSchemaDataTypeScriptTypes;
@@ -760,12 +769,13 @@ declare class Game implements Activity {
      * Saves an item to the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      * @param key - item key
      * @param value - item value
      * @param globalStore - if true, treat the item as "global" and not
@@ -778,12 +788,13 @@ declare class Game implements Activity {
      * Gets an item value from the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
      * associated with a specific activity; global items can be accessed
@@ -795,12 +806,13 @@ declare class Game implements Activity {
      * Deletes an item value from the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
      * associated with a specific activity; global items can be accessed
@@ -811,24 +823,26 @@ declare class Game implements Activity {
      * Deletes all items from the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      */
     storeClearItems(): Promise<void>;
     /**
      * Returns keys of all items in the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      * @param globalStore - if true, treat the item as "global" and not
      * associated with a specific activity; global items can be accessed
      * by any activity. Default is false.
@@ -838,12 +852,13 @@ declare class Game implements Activity {
      * Determines if a key exists in the activity's key-value store.
      *
      * @remarks The underlying persistence provider of the key-value store must
-     * be previously set in the activity's `Session` before use:
-     * ```
-     * const db: IDataStore = new LocalDatabase();
-     * session.dataStore = db;
-     * session.initialize();
-     * ```
+     * have been previously provided in `SessionOptions`.
+     * @example
+     * import { LocalDatabase } from "@m2c2kit/db";
+     * const session = new Session({
+     *   dataStores: [new LocalDatabase()]
+     *   ...
+     * });
      * @param key - item key
      * @param globalStore - if true, treat the item as "global" and not
      * associated with a specific activity; global items can be accessed
@@ -851,8 +866,8 @@ declare class Game implements Activity {
      * @returns true if the key exists, false otherwise
      */
     storeItemExists(key: string, globalStore?: boolean): Promise<boolean>;
-    get dataStore(): IDataStore;
-    set dataStore(dataStore: IDataStore);
+    get dataStores(): IDataStore[];
+    set dataStores(dataStores: IDataStore[]);
     private getLocalizationOptionsFromGameParameters;
     private isLocalizationRequested;
     setParameters(additionalParameters: unknown): void;
@@ -1150,6 +1165,13 @@ declare class Game implements Activity {
      * @returns - the scene with the screen shot
      */
     private createOutgoingScene;
+    /**
+     * Executes a callback when the frame has finished simulating physics.
+     *
+     * @param callback - function to execute.
+     * @param options - options for the callback.
+     */
+    onFrameDidSimulatePhysics(callback: (frameCycleEvent: FrameCycleEvent) => void, options?: CallbackOptions): void;
     private update;
     private draw;
     private calculateFps;
@@ -1373,6 +1395,8 @@ interface SessionOptions {
     sessionUuid?: string;
     /** URL of session assets folder (which contains wasm binary), if not the default location of "assets" */
     assetsUrl?: string;
+    /** Array of one or more optional databases that implement the IDataStore interface for persisting data. For store item operations, the first data store will be used. */
+    dataStores?: IDataStore[];
     /** 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 */
@@ -1389,7 +1413,7 @@ declare class Session {
     imageManager: ImageManager;
     currentActivity?: Activity;
     uuid: string;
-    dataStore?: IDataStore;
+    dataStores?: IDataStore[];
     private eventListeners;
     private sessionDictionary;
     private canvasKit?;
@@ -1645,8 +1669,8 @@ interface Activity {
     setParameters(additionalParameters: unknown): void;
     /** Additional activity parameters that were set. */
     readonly additionalParameters?: unknown;
-    /** Optional store to use for saving data. The implementation of the store is not provided by the \@m2c2kit/core library. */
-    dataStore?: IDataStore;
+    /** Optional stores to use for saving data. The implementation of the store is not provided by the \@m2c2kit/core library. */
+    dataStores?: IDataStore[];
 }
 
 /**
@@ -1684,7 +1708,8 @@ declare enum EventType {
     Drag = "Drag",
     DragStart = "DragStart",
     DragEnd = "DragEnd",
-    CompositeCustom = "CompositeCustom"
+    CompositeCustom = "CompositeCustom",
+    FrameDidSimulatePhysics = "FrameDidSimulatePhysics"
 }
 
 interface EntityEventListener {
@@ -1807,6 +1832,12 @@ declare abstract class Entity implements EntityOptions {
      * @remarks Throws error if entity is not part of the game object.
      */
     get game(): Game;
+    /**
+     * Determines if the entity has been added to the game object.
+     *
+     * @returns true if entity has been added
+     */
+    private isPartOfGame;
     /**
      * Overrides toString() and returns a human-friendly description of the entity.
      *
@@ -1815,7 +1846,8 @@ declare abstract class Entity implements EntityOptions {
     toString: () => string;
     /**
      * Adds a child to this parent entity. Throws exception if the child's name
-     * is not unique with respect to other children of this parent.
+     * is not unique with respect to other children of this parent, or if the
+     * child has already been added to another parent.
      *
      * @param child - The child entity to add
      */
@@ -2608,7 +2640,7 @@ declare enum ShapeType {
  */
 interface SvgStringPath {
     /** SVG string from which to create te path */
-    svgString?: string;
+    svgPathString?: string;
     /** If provided, scale the SVG path to this height, and scale the width to keep the original SVG proportions */
     height?: number;
     /** If provided, scale the SVG path to this width, and scale the height to keep the original SVG proportions */
@@ -3100,4 +3132,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-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 };
+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, TapEvent, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, Translations, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };