@m2c2kit/addons 0.3.13 → 0.3.15

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Canvas } from 'canvaskit-wasm';
-import { CompositeOptions, Size, RgbaColor, Composite, Entity, GlobalVariables, TextOptions, IText, EntityEvent, Point, CallbackOptions, ShapeOptions, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene } from '@m2c2kit/core';
+import { CompositeOptions, Size, RgbaColor, Composite, M2Node, GlobalVariables, TextOptions, IText, StringInterpolationMap, M2NodeEvent, CallbackOptions, Point, ShapeOptions, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene, SceneOptions } from '@m2c2kit/core';
 
 interface GridOptions extends CompositeOptions {
     /** Number of rows in the grid. Must be 1 or greater */
@@ -16,7 +16,7 @@ interface GridOptions extends CompositeOptions {
     gridLineColor?: RgbaColor;
 }
 interface GridChild {
-    entity: Entity;
+    node: M2Node;
     row: number;
     column: number;
 }
@@ -32,11 +32,11 @@ declare class Grid extends Composite {
     gridChildren: GridChild[];
     private _gridBackground?;
     /**
-     * A rectangular grid that supports placement of entities within the grid's
+     * A rectangular grid that supports placement of nodes within the grid's
      * cells.
      *
-     * @remarks This composite entity is composed of rectangles and lines. It
-     * has convenience functions for placing and clearing entities on the grid
+     * @remarks This composite node is composed of rectangles and lines. It
+     * has convenience functions for placing and clearing nodes on the grid
      * by row and column position (zero-based indexing)
      *
      * @param options - {@link GridOptions}
@@ -47,13 +47,13 @@ declare class Grid extends Composite {
     private set gridBackground(value);
     dispose(): void;
     /**
-     * Duplicates an entity using deep copy.
+     * Duplicates a node using deep copy.
      *
-     * @remarks This is a deep recursive clone (entity and children).
-     * The uuid property of all duplicated entities will be newly created,
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
      * because uuid must be unique.
      *
-     * @param newName - optional name of the new, duplicated entity. If not
+     * @param newName - optional name of the new, duplicated node. If not
      * provided, name will be the new uuid
      */
     duplicate(newName?: string): Grid;
@@ -65,26 +65,26 @@ declare class Grid extends Composite {
      */
     removeAllChildren(): void;
     /**
-     * Adds an entity to the grid at the specified row and column position.
+     * Adds a node to the grid at the specified row and column position.
      *
-     * @param entity - entity to add to the grid
-     * @param row  - row position within grid to add entity; zero-based indexing
-     * @param column - column position within grid to add entity; zero-based indexing
+     * @param node - node to add to the grid
+     * @param row  - row position within grid to add node; zero-based indexing
+     * @param column - column position within grid to add node; zero-based indexing
      */
-    addAtCell(entity: Entity, row: number, column: number): void;
+    addAtCell(node: M2Node, row: number, column: number): void;
     /**
-     * Removes all child entities at the specified row and column position.
+     * Removes all child nodes at the specified row and column position.
      *
      * @param row - row position within grid at which to remove children; zero-based indexing
      * @param column - column position within grid at which to remove children; zero-based indexing
      */
     removeAllAtCell(row: number, column: number): void;
     /**
-     * Removes the child entity from the grid.
+     * Removes the child node from the grid.
      *
-     * @param entity - entity to remove
+     * @param node - node to remove
      */
-    removeChild(entity: Entity): void;
+    removeChild(node: M2Node): void;
 }
 
 declare global {
@@ -101,6 +101,8 @@ interface ButtonOptions extends CompositeOptions, TextOptions {
     backgroundColor?: RgbaColor;
     /** Color of button text. Default is WebColors.White */
     fontColor?: RgbaColor;
+    /** Names of multiple fonts to use for text. For example, if a text font and an emoji font are to be used together. Must have been previously loaded */
+    fontNames?: Array<string>;
 }
 declare class Button extends Composite implements IText {
     compositeType: string;
@@ -113,11 +115,15 @@ declare class Button extends Composite implements IText {
     fontSize: number;
     private _text;
     private _fontColor;
+    private _fontName;
+    private _fontNames;
+    private _interpolation;
+    private _localize;
     private backgroundPaint?;
     /**
      * A simple button of rectangle with text centered inside.
      *
-     * @remarks This composite entity is composed of a rectangle and text. To
+     * @remarks This composite node is composed of a rectangle and text. To
      * respond to user taps, the isUserInteractionEnabled property must be set
      * to true and an appropriate callback must be set to handle the tap event.
      *
@@ -132,14 +138,22 @@ declare class Button extends Composite implements IText {
     set backgroundColor(backgroundColor: RgbaColor);
     get fontColor(): RgbaColor;
     set fontColor(fontColor: RgbaColor);
+    get fontName(): string | undefined;
+    set fontName(fontName: string | undefined);
+    get fontNames(): Array<string> | undefined;
+    set fontNames(fontNames: Array<string> | undefined);
+    get interpolation(): StringInterpolationMap;
+    set interpolation(interpolation: StringInterpolationMap);
+    get localize(): boolean;
+    set localize(localize: boolean);
     /**
-     * Duplicates an entity using deep copy.
+     * Duplicates a node using deep copy.
      *
-     * @remarks This is a deep recursive clone (entity and children).
-     * The uuid property of all duplicated entities will be newly created,
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
      * because uuid must be unique.
      *
-     * @param newName - optional name of the new, duplicated entity. If not
+     * @param newName - optional name of the new, duplicated node. If not
      * provided, name will be the new uuid
      */
     duplicate(newName?: string): Button;
@@ -169,7 +183,7 @@ declare enum DialogResult {
     Positive = "Positive",
     Negative = "Negative"
 }
-interface DialogEvent extends EntityEvent {
+interface DialogEvent extends M2NodeEvent {
     dialogResult: DialogResult;
 }
 declare class Dialog extends Composite {
@@ -186,20 +200,20 @@ declare class Dialog extends Composite {
     private backgroundPaint?;
     constructor(options?: DialogOptions);
     show(): void;
-    onDialogResult(callback: (dialogResultEvent: DialogEvent) => void, replaceExistingCallback?: boolean): void;
+    onDialogResult(callback: (dialogResultEvent: DialogEvent) => void, options?: CallbackOptions): void;
     initialize(): void;
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
     get fontColor(): RgbaColor;
     set fontColor(fontColor: RgbaColor);
     /**
-     * Duplicates an entity using deep copy.
+     * Duplicates a node using deep copy.
      *
-     * @remarks This is a deep recursive clone (entity and children).
-     * The uuid property of all duplicated entities will be newly created,
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
      * because uuid must be unique.
      *
-     * @param newName - optional name of the new, duplicated entity. If not
+     * @param newName - optional name of the new, duplicated node. If not
      * provided, name will be the new uuid
      */
     duplicate(newName?: string): Dialog;
@@ -236,7 +250,7 @@ declare const DrawPadEventType: {
     readonly StrokeEnd: "StrokeEnd";
 };
 type DrawPadEventType = (typeof DrawPadEventType)[keyof typeof DrawPadEventType];
-interface DrawPadEvent extends EntityEvent {
+interface DrawPadEvent extends M2NodeEvent {
     type: DrawPadEventType;
     position: Point;
 }
@@ -245,7 +259,7 @@ declare const DrawPadItemEventType: {
     readonly StrokeLeave: "StrokeLeave";
 };
 type DrawPadItemEventType = (typeof DrawPadItemEventType)[keyof typeof DrawPadItemEventType];
-interface DrawPadItemEvent extends EntityEvent {
+interface DrawPadItemEvent extends M2NodeEvent {
     type: DrawPadItemEventType;
 }
 interface StrokeInteraction {
@@ -303,7 +317,7 @@ declare class DrawPad extends Composite {
     /**
      * A rectangular area on which the user can draw strokes (lines).
      *
-     * @remarks This composite entity is composed of a rectangle Shape and
+     * @remarks This composite node is composed of a rectangle Shape and
      * another Shape that is formed from a path of points.
      *
      * @param options - {@link DrawPadOptions}
@@ -349,20 +363,20 @@ declare class DrawPad extends Composite {
      */
     onStrokeEnd(callback: (ev: DrawPadEvent) => void, options?: CallbackOptions): void;
     /**
-     * Adds an entity to the DrawPad.
+     * Adds a node to the DrawPad.
      *
-     * @remarks After the entity is added to the DrawPad, its
+     * @remarks After the node is added to the DrawPad, its
      * position is adjusted to be relative to the DrawPad's coordinate
      * system, and it is made interactive. The method returns an object
-     * which is the entity as a DrawPadItem, which has additional methods,
-     * properties, and events specific to it now being on a DrawPad. The entity
+     * which is the node as a DrawPadItem, which has additional methods,
+     * properties, and events specific to it now being on a DrawPad. The node
      * now **must** be manipulated only using the DrawPadItem object. Using
-     * the original entity object will result in undefined behavior.
+     * the original node object will result in undefined behavior.
      *
-     * @param entity - the entity to add to the DrawPad
-     * @returns the entity as a DrawPadItem
+     * @param node - the node to add to the DrawPad
+     * @returns the node as a DrawPadItem
      */
-    addItem<T extends Entity>(entity: T): T & DrawPadItem;
+    addItem<T extends M2Node>(node: T): T & DrawPadItem;
     /**
      * Takes a screenshot of the DrawPad.
      *
@@ -454,7 +468,7 @@ interface VirtualKeyboardOptions extends CompositeOptions {
     /** If true, a preview of the key that will be pressed will be shown. */
     showKeyDownPreview?: boolean;
 }
-interface VirtualKeyboardEvent extends EntityEvent {
+interface VirtualKeyboardEvent extends M2NodeEvent {
     /** String that is generated when key is pressed, with any modifiers (e.g., Shift) applied. */
     key: string;
     /** Code for the key, not taking into account any modifiers. */
@@ -473,6 +487,7 @@ interface KeyTapMetadata {
     buttons: number;
 }
 declare class VirtualKeyboard extends Composite {
+    compositeType: string;
     private keyboardHorizontalPaddingPercent;
     private keyboardVerticalPaddingPercent;
     private keyHorizontalPaddingPercent;
@@ -490,6 +505,8 @@ declare class VirtualKeyboard extends Composite {
     private showKeyDownPreview;
     private shiftActivated;
     private shiftKeyShape;
+    private keyShapes;
+    _isUserInteractionEnabled: boolean;
     /**
      * An on-screen keyboard that can be used to enter text.
      *
@@ -501,29 +518,29 @@ declare class VirtualKeyboard extends Composite {
      * Executes a callback when the user presses down on a key.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be 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.
+     * @param options
      */
-    onKeyDown(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, replaceExistingCallback?: boolean): void;
+    onKeyDown(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a key.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be 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.
+     * @param options
      */
-    onKeyUp(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, replaceExistingCallback?: boolean): void;
+    onKeyUp(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
     private addVirtualKeyboardEventListener;
+    /**
+     * Does the `VirtualKeyboard` respond to user events? Default is true.
+     */
+    get isUserInteractionEnabled(): boolean;
+    /**
+     * Does the `VirtualKeyboard` respond to user events? Default is true.
+     */
+    set isUserInteractionEnabled(isUserInteractionEnabled: boolean);
     update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
-    duplicate(newName?: string | undefined): Entity;
+    duplicate(newName?: string | undefined): M2Node;
 }
 
 interface InstructionScene {
@@ -618,12 +635,231 @@ interface InstructionsOptions extends StoryOptions {
 }
 declare class Instructions extends Story {
     /**
-     * Create an array of scenes containing instructions on how to complete the task
+     * Creates an array of scenes containing instructions on how to complete the assessment
+     *
+     * @param options - {@link InstructionsOptions}
+     * @returns instruction scenes
+     */
+    static create(options: InstructionsOptions): Array<Scene>;
+    /**
+     * Creates an array of scenes containing instructions on how to complete the assessment
+     *
+     * @deprecated Use {@link Instructions.create} instead (lower case method name "create")
      *
      * @param options - {@link InstructionsOptions}
-     * @returns
+     * @returns instruction scenes
      */
     static Create(options: InstructionsOptions): Array<Scene>;
 }
 
-export { Button, type ButtonOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type StrokeInteraction, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };
+interface CountdownSceneOptions extends SceneOptions {
+    /** Duration of the countdown, in milliseconds. */
+    milliseconds: number;
+    /** Duration of the slide transition, in milliseconds, to the next scene after the countdown completes. Default is 500. */
+    transitionDurationMilliseconds?: number;
+    /** A custom transition to use to present next scene after the countdown completes. */
+    transition?: Transition;
+    /** Duration in milliseconds to stay on zero before transitioning to the next scene. Default is zero. This option should be used if `transition` is set to `Transition.none()`. Otherwise, the zero will flash for a single frame before presenting the next scene. */
+    zeroDwellMilliseconds?: number;
+    /** Text shown below the countdown shape. Default is "GET READY". */
+    text?: string;
+    /** Font name for text  */
+    textFontName?: string;
+    /** Font size for text. Default is 50. */
+    textFontSize?: number;
+    /** Font color for text. Default is black. */
+    textFontColor?: RgbaColor;
+    /** Distance between bottom of countdown shape and text. Default is 32. */
+    textMarginTop?: number;
+    /** Font name for timer numbers. */
+    timerNumbersFontName?: string;
+    /** Font size for timer numbers. Default is 50. */
+    timerNumbersFontSize?: number;
+    /** Font size for timer numbers. Default is white. */
+    timerNumbersFontColor?: RgbaColor;
+    /** String to show when the timer reaches zero. Default is "0". This could be changed to another value, such as "GO!" */
+    timerZeroString?: string;
+    /** Shape of the timer. Default is a Royal Blue circle with a radius of 100 centered vertically. */
+    timerShape?: TimerShape;
+}
+interface TimerShape {
+    circle?: {
+        /** Radius of the circle timer shape. */
+        radius: number;
+    };
+    rectangle?: {
+        /** Width of the rectangle timer shape. */
+        width: number;
+        /** Height of the rectangle timer shape. */
+        height: number;
+        /** Corner radius of the rectangle timer shape. Default is 0. */
+        cornerRadius?: number;
+    };
+    /** Color of the timer shape. Default is Royal Blue. */
+    fillColor?: RgbaColor;
+    /** Default is to center the timer shape vertically within the scene (verticalBias = .5). Setting verticalBias less than .5 will pull the shape towards the top. Setting verticalBias greater than .5 will pull the shape towards the bottom. */
+    verticalBias?: number;
+}
+declare class CountdownScene extends Scene {
+    /**
+     * A scene that counts down from a specified number to zero, then transitions to the next scene.
+     *
+     * @param options - {@link CountdownSceneOptions}
+     */
+    constructor(options: CountdownSceneOptions);
+}
+
+interface LocalePickerOptions extends CompositeOptions {
+    /** Background color of dialog box. Default is WebColors.White */
+    backgroundColor?: RgbaColor;
+    /** Locales to choose from in the dialog box. Default is the locales in the game's `Translation`. */
+    localeOptions?: Array<LocaleOption>;
+    /** What to show as the currently selected locale in the picker. Default is the game's current locale. */
+    currentLocale?: string;
+    /** Alpha level for the overlay that dims the scene underneath the dialog box. Default is .5 */
+    overlayAlpha?: number;
+    /** Size of dialog box. Default is automatically sized to fit the number of locale options. */
+    size?: Size;
+    /** Corner radius of dialog box; can be used to make rounded corners */
+    cornerRadius?: number;
+    /** Font size of locale options in dialog box. Default is 24. */
+    fontSize?: number;
+    /** Font color of locale options in dialog box. Default is WebColors.Black */
+    fontColor?: RgbaColor;
+    /** Image to use for LocalePicker. Default is a globe SVG, 32x32. */
+    icon?: LocalePickerIcon;
+    /** Position of the LocalePicker icon. Default is &#123; x: 32, y: 32 &#125; */
+    iconPosition: Point;
+    /** Should the selection in the LocalePicker automatically switch the game's locale? Default is true. */
+    automaticallyChangeLocale?: boolean;
+}
+interface LocalePickerIcon {
+    /** The HTML SVG tag, in string form, that will be rendered to display the locale.
+     * Must begin with &#60;svg> and end with &#60;/svg> */
+    svgString?: string;
+    /** Name of image to use for LocalePicker. Must have been previously loaded */
+    imageName?: string;
+    /** Height to scale image to */
+    height: number;
+    /** Width to scale image to */
+    width: number;
+}
+interface LocaleOption {
+    /** Human-readable text description of the locale. */
+    text: string;
+    /** SVG of the locale. */
+    svg?: LocaleSvg;
+    /** Locale in language-country format, xx-YY. */
+    locale: string;
+}
+interface LocalePickerResult {
+    /** Locale that was selected. Is undefined if dialog was dismissed. */
+    locale?: string;
+}
+interface LocalePickerEvent extends M2NodeEvent {
+    result: LocalePickerResult;
+}
+interface LocaleSvg {
+    /** The HTML SVG tag, in string form, that will be rendered to display the locale.
+     * Must begin with &#60;svg> and end with &#60;/svg> */
+    svgString: string;
+    /** Height to scale image to */
+    height: number;
+    /** Width to scale image to */
+    width: number;
+}
+declare class LocalePicker extends Composite {
+    compositeType: string;
+    zPosition: number;
+    private readonly DEFAULT_FONT_SIZE;
+    automaticallyChangeLocale: boolean;
+    private _localeOptions;
+    private _backgroundColor;
+    private _fontSize;
+    private _fontColor;
+    private _currentLocale?;
+    private _cornerRadius;
+    private _overlayAlpha;
+    private _icon;
+    private _iconPosition;
+    private iconSprite?;
+    /**
+     * Wrap displayed locale in double angle quotes if it is the current locale.
+     * Note: Although the code editor will allow us to enter almost any
+     * unicode character, it will not render correctly if the font does
+     * not support the character. Thus, be careful to use characters that
+     * are supported by the font. For example, check a page like
+     * https://www.fontspace.com/roboto-font-f13281 to see which characters
+     * are supported by Roboto Regular, which is often the default font in
+     * m2c2kit. Emoji or checkmarks like ✓ are not in Roboto Regular!
+     */
+    private readonly LEFT_SELECTION_INDICATOR;
+    private readonly RIGHT_SELECTION_INDICATOR;
+    /**
+     * An icon and dialog box for selecting a locale from a list of options.
+     *
+     * @remarks This composite node is composed of a dialog box that appears
+     * when the user taps a globe icon. Typically, the `LocalePicker` will be
+     * added as a free node to the game so that it exists independently of
+     * the game's scenes. The dialog box contains a list of locales that the
+     * user can choose from. By default, this list is populated with the locales
+     * in the game's `Translation` object. When the user selects a locale, the
+     * dialog box disappears and the locale is set as the game's current locale.
+     *  The dialog box is automatically sized to fit the number of locale
+     * options.
+     *
+     * @example
+     * let localePicker: LocalePicker;
+     * if (game.getParameter<boolean>("show_locale_picker")) {
+     *   localePicker = new LocalePicker();
+     *   game.addFreeNode(localePicker);
+     * }
+     *
+     * @param options - {@link LocalePickerOptions}
+     */
+    constructor(options?: LocalePickerOptions);
+    /**
+     * Executes a callback when the user selects a locale.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
+     */
+    onResult(callback: (localePickerEvent: LocalePickerEvent) => void, options?: CallbackOptions): void;
+    initialize(): void;
+    private handleLocaleSelection;
+    private setDialogVisibility;
+    get backgroundColor(): RgbaColor;
+    set backgroundColor(backgroundColor: RgbaColor);
+    get fontSize(): number;
+    set fontSize(fontSize: number);
+    get fontColor(): RgbaColor;
+    set fontColor(fontColor: RgbaColor);
+    get cornerRadius(): number;
+    set cornerRadius(cornerRadius: number);
+    get overlayAlpha(): number;
+    set overlayAlpha(alpha: number);
+    get icon(): LocalePickerIcon;
+    set icon(icon: LocalePickerIcon);
+    get iconPosition(): Point;
+    set iconPosition(position: Point);
+    get localeOptions(): Array<LocaleOption>;
+    set localeOptions(options: Array<LocaleOption>);
+    get currentLocale(): string | undefined;
+    set currentLocale(locale: string | undefined);
+    update(): void;
+    draw(canvas: Canvas): void;
+    warmup(canvas: Canvas): void;
+    /**
+     * Duplicates a node using deep copy.
+     *
+     * @remarks This is a deep recursive clone (node and children).
+     * The uuid property of all duplicated nodes will be newly created,
+     * because uuid must be unique.
+     *
+     * @param newName - optional name of the new, duplicated node. If not
+     * provided, name will be the new uuid
+     */
+    duplicate(newName?: string): LocalePicker;
+}
+
+export { Button, type ButtonOptions, CountdownScene, type CountdownSceneOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type LocaleOption, LocalePicker, type LocalePickerEvent, type LocalePickerIcon, type LocalePickerOptions, type LocalePickerResult, type StrokeInteraction, type TimerShape, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };