@m2c2kit/core 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -27,12 +27,11 @@ interface EntityEventListener {
27
27
  /**
28
28
  * Position in two-dimensional space.
29
29
  */
30
- declare class Point {
30
+ interface Point {
31
31
  /** Horizonal coordinate */
32
32
  x: number;
33
33
  /** Vertical coordinate */
34
34
  y: number;
35
- constructor(x?: number, y?: number);
36
35
  }
37
36
 
38
37
  interface TapEvent extends EntityEvent {
@@ -40,6 +39,11 @@ interface TapEvent extends EntityEvent {
40
39
  point: Point;
41
40
  }
42
41
 
42
+ interface DrawableOptions {
43
+ anchorPoint?: Point;
44
+ zPosition?: number;
45
+ }
46
+
43
47
  interface Constraints {
44
48
  /** Constrain the top (vertical axis) of this entity to the top of the specified entity. The tops of both will appear at the same vertical location */
45
49
  topToTopOf?: Entity | string;
@@ -79,13 +83,30 @@ interface Layout {
79
83
  constraints?: Constraints;
80
84
  }
81
85
 
86
+ /**
87
+ * Color in red (0-255), green (0-255), blue (0-255), alpha (0-1) format. Must be numeric array of length 4.
88
+ */
89
+ declare type RgbaColor = [number, number, number, number];
90
+
91
+ interface TextOptions {
92
+ /** Text to be displayed */
93
+ text?: string;
94
+ /** Name of font to use for text. Must have been previously loaded */
95
+ fontName?: string;
96
+ /** Color of text. Default is Constants.DEFAULT_FONT_COLOR (WebColors.Black) */
97
+ fontColor?: RgbaColor;
98
+ /** Size of text. Default is Constants.DEFAULT_FONT_SIZE (16) */
99
+ fontSize?: number;
100
+ }
101
+
82
102
  /**
83
103
  * Width and height on two-dimensional space
84
104
  */
85
- declare class Size {
105
+ interface Size {
106
+ /** Horizonal width, x-axis */
86
107
  width: number;
108
+ /** Vertical height, y-axis */
87
109
  height: number;
88
- constructor(width?: number, height?: number);
89
110
  }
90
111
 
91
112
  interface EntityOptions {
@@ -134,7 +155,7 @@ declare abstract class Entity implements EntityOptions {
134
155
  queuedAction?: Action;
135
156
  originalActions: Action[];
136
157
  eventListeners: EntityEventListener[];
137
- uuid: string;
158
+ readonly uuid: string;
138
159
  needsInitialization: boolean;
139
160
  userData: any;
140
161
  loopMessages: Set<string>;
@@ -209,9 +230,20 @@ declare abstract class Entity implements EntityOptions {
209
230
  * Remove all actions from this entity. If actions are running, they will be stopped.
210
231
  */
211
232
  removeAllActions(): void;
212
- private static getEntityOptions;
213
- private static getDrawableOptions;
214
- private static getTextOptions;
233
+ /**
234
+ * Duplicates an entity using deep copy.
235
+ *
236
+ * @remarks This is a deep recursive clone (entity and children).
237
+ * The uuid property of all duplicated entities will be newly created,
238
+ * because uuid must be unique.
239
+ *
240
+ * @param newName - optional name of the new, duplicated entity. If not
241
+ * provided, name will be the new uuid
242
+ */
243
+ abstract duplicate(newName?: string): Entity;
244
+ protected getEntityOptions(): EntityOptions;
245
+ protected getDrawableOptions(): DrawableOptions;
246
+ protected getTextOptions(): TextOptions;
215
247
  /**
216
248
  * Gets the scene that contains this entity by searching up the ancestor tree recursively. Throws exception if entity is not part of a scene.
217
249
  *
@@ -375,6 +407,11 @@ declare class ScaleAction extends Action {
375
407
  constructor(scale: number, duration: number, runDuringTransition?: boolean);
376
408
  }
377
409
 
410
+ declare enum ActivityType {
411
+ game = "Game",
412
+ survey = "Survey"
413
+ }
414
+
378
415
  declare class LoadedImage {
379
416
  name: string;
380
417
  image: Image;
@@ -384,18 +421,21 @@ declare class LoadedImage {
384
421
  }
385
422
 
386
423
  /**
387
- * Image that can be rendered by a browser and loaded from a URL or HTML svg tag in string form.
424
+ * Image that can be rendered by a browser from a URL or from a
425
+ * HTML svg tag in string form. Provide either url or svgString, not both.
388
426
  */
389
427
  interface BrowserImage {
390
- /** Name that will be used to refer to the SVG image. Must be unique among all images */
428
+ /** Name that will be used to refer to the image. Must be unique among all
429
+ * images within a game */
391
430
  name: string;
392
- /** Width to scale SVG image to */
431
+ /** Width to scale image to */
393
432
  width: number;
394
- /** Height to scale SVG image to */
433
+ /** Height to scale image to */
395
434
  height: number;
396
- /** The HTML SVG tag, in string form, that will be rendered and loaded. Must begin with &#60;svg> and end with &#60;/svg> */
435
+ /** The HTML SVG tag, in string form, that will be rendered and loaded.
436
+ * Must begin with &#60;svg> and end with &#60;/svg> */
397
437
  svgString?: string;
398
- /** URL of SVG asset to render and load */
438
+ /** URL of image asset (svg, png, jpg) to render and load */
399
439
  url?: string;
400
440
  }
401
441
 
@@ -411,24 +451,71 @@ declare class ImageManager {
411
451
  private _scratchCanvas?;
412
452
  private ctx?;
413
453
  private scale?;
454
+ /**
455
+ * Returns a CanvasKit Image that was previously rendered by the ImageManager.
456
+ *
457
+ * @remarks Typically, this won't be called directly because a programmer
458
+ * will use a higher-level abstraction (m2c2kit Sprite).
459
+ *
460
+ * @param gameUuid - The game that the image resource is part of
461
+ * @param imageName - The name given to the rendered image
462
+ * @returns A CanvasKit Image
463
+ */
414
464
  getLoadedImage(gameUuid: string, imageName: string): LoadedImage;
415
465
  /**
416
- * Adds a CanvasKit image to the images available to a given game.
417
- * Typically, this won't be called directly because images will be
466
+ * Adds a CanvasKit Image to the images available to a given game.
467
+ *
468
+ * @remarks Typically, a programmer won't call this because images will be
418
469
  * automatically rendered and loaded in the Activity async init.
419
- * The only time this function is called in-game is to add
420
- * screenshot images needed for transitions
470
+ * The only time this function is called in-game is when our internal
471
+ * methods add screenshot images needed for transitions.
421
472
  *
422
- * @param loadedImage
423
- * @param gameUuid
473
+ * @param loadedImage - An image that has been converted to a CanvasKit Image
474
+ * @param gameUuid - The game that the Image is part of
424
475
  */
425
476
  addLoadedImage(loadedImage: LoadedImage, gameUuid: string): void;
477
+ /**
478
+ * Renders game images from their original format (png, jpg, svg) to
479
+ * CanvasKit Image.
480
+ *
481
+ * @remarks Typically, a programmer won't call this because the Session
482
+ * object will manage this. Rendering is an async activity, and thus
483
+ * this method returns a promise. Rendering of all images is done in
484
+ * parallel.
485
+ *
486
+ * @param allGamesImages - An array of GameImages data structures that
487
+ * specify the image's desired size, it's name, and where the image to be
488
+ * rendered is located (e.g., embedded svgString or url)
489
+ * @returns A promise that completes when all game images have rendered
490
+ */
426
491
  renderImages(allGamesImages: Array<GameImages>): Promise<void[]>;
492
+ /**
493
+ * Adds all rendered CanvasKit Images to the images available to m2c2kit.
494
+ *
495
+ * @remarks Typically, a programmer won't call this because the Session
496
+ * object will manage this.
497
+ */
427
498
  loadAllGamesRenderedImages(): void;
499
+ /**
500
+ * Our private method rendering an image to a CanvasKit Image
501
+ *
502
+ * @remarks This is complex because there is a separate flow to render
503
+ * svg images versus other (e.g., jpg, png). Svg images may be provided
504
+ * in a url or inline. In addition, there is a Firefox svg rendering issue,
505
+ * see below, that must be handled.
506
+ * Additional complexity comes from the potentially multiple async steps and
507
+ * the multiple errors that can happen throughout.
508
+ *
509
+ * @param gameUuid
510
+ * @param browserImage
511
+ * @returns A promise of type void
512
+ */
428
513
  private renderBrowserImage;
429
514
  private convertRenderedDataUrlImageToCanvasKitImage;
430
515
  /**
431
- * scratchCanvas is an extra, non-visible canvas in the DOM we use so the native browser can render images
516
+ * Returns the scratchCanvas, which is an extra, non-visible canvas in the
517
+ * DOM we use so the native browser can render images like svg, png, jpg,
518
+ * that we later will convert to CanvasKit Image.
432
519
  */
433
520
  private get scratchCanvas();
434
521
  private dataURLtoArrayBuffer;
@@ -605,6 +692,10 @@ declare class Session {
605
692
  }
606
693
 
607
694
  interface Activity {
695
+ /** The type of activity: Game or Survey */
696
+ type: ActivityType;
697
+ /** Initializes the activity. */
698
+ init(): void;
608
699
  /** Starts the activity */
609
700
  start(): void;
610
701
  /** Stops the activity */
@@ -615,6 +706,8 @@ interface Activity {
615
706
  uuid: string;
616
707
  /** The activity's human friendly name */
617
708
  name: string;
709
+ /** Set activity parameters if defaults are not desired*/
710
+ setParameters(newParameters: any): void;
618
711
  }
619
712
 
620
713
  interface IDrawable {
@@ -623,11 +716,6 @@ interface IDrawable {
623
716
  zPosition: number;
624
717
  }
625
718
 
626
- interface DrawableOptions {
627
- anchorPoint?: Point;
628
- zPosition?: number;
629
- }
630
-
631
719
  interface CompositeOptions extends EntityOptions, DrawableOptions {
632
720
  }
633
721
 
@@ -648,11 +736,6 @@ declare abstract class Composite extends Entity implements IDrawable {
648
736
  draw(canvas: Canvas): void;
649
737
  }
650
738
 
651
- /**
652
- * Color in red (0-255), green (0-255), blue (0-255), alpha (0-1) format. Must be numeric array of length 4.
653
- */
654
- declare type RgbaColor = [number, number, number, number];
655
-
656
739
  /**
657
740
  * Reasonable defaults to use if values are not specified.
658
741
  */
@@ -700,12 +783,16 @@ interface SceneOptions extends EntityOptions, DrawableOptions {
700
783
  declare class Scene extends Entity implements IDrawable, SceneOptions {
701
784
  readonly type = EntityType.scene;
702
785
  isDrawable: boolean;
703
- anchorPoint: Point;
786
+ anchorPoint: {
787
+ x: number;
788
+ y: number;
789
+ };
704
790
  zPosition: number;
705
791
  private _backgroundColor;
706
792
  _active: boolean;
707
793
  _transitioning: boolean;
708
794
  _setupCallback?: (scene: Scene) => void;
795
+ _appearCallback?: (scene: Scene) => void;
709
796
  private _game?;
710
797
  private backgroundPaint?;
711
798
  /**
@@ -722,13 +809,31 @@ declare class Scene extends Entity implements IDrawable, SceneOptions {
722
809
  get backgroundColor(): RgbaColor;
723
810
  set backgroundColor(backgroundColor: RgbaColor);
724
811
  /**
725
- * Code that will be called every time the screen is first presented.
812
+ * Duplicates an entity using deep copy.
813
+ *
814
+ * @remarks This is a deep recursive clone (entity and children).
815
+ * The uuid property of all duplicated entities will be newly created,
816
+ * because uuid must be unique.
817
+ *
818
+ * @param newName - optional name of the new, duplicated entity. If not
819
+ * provided, name will be the new uuid
820
+ */
821
+ duplicate(newName?: string): Scene;
822
+ /**
823
+ * Code that will be called every time the screen is presented.
726
824
  *
727
825
  * @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.
728
826
  *
729
827
  * @param callback
730
828
  */
731
- setup(callback: (scene: Scene) => void): void;
829
+ onSetup(callback: (scene: Scene) => void): void;
830
+ /**
831
+ *
832
+ * Code that will be called after the scene has finished any transitions and has fully appeared on the screen.
833
+ *
834
+ * @param callback
835
+ */
836
+ onAppear(callback: (scene: Scene) => void): void;
732
837
  draw(canvas: Canvas): void;
733
838
  }
734
839
 
@@ -850,12 +955,14 @@ interface screenMetadata {
850
955
  readonly width: number;
851
956
  }
852
957
  declare class Game implements Activity {
958
+ readonly type = ActivityType.game;
853
959
  _canvasKit?: CanvasKit;
854
960
  _session?: Session;
855
961
  uuid: string;
856
962
  name: string;
857
963
  options: GameOptions;
858
964
  constructor(options: GameOptions);
965
+ init(): void;
859
966
  setParameters(newParameters: any): void;
860
967
  get canvasKit(): CanvasKit;
861
968
  set canvasKit(canvasKit: CanvasKit);
@@ -885,6 +992,7 @@ declare class Game implements Activity {
885
992
  private scenes;
886
993
  private incomingSceneTransitions;
887
994
  private currentSceneSnapshot?;
995
+ private pendingScreenshot?;
888
996
  /**
889
997
  * Adds a scene to the game.
890
998
  *
@@ -960,6 +1068,23 @@ declare class Game implements Activity {
960
1068
  private update;
961
1069
  private draw;
962
1070
  private takeCurrentSceneSnapshot;
1071
+ private handlePendingScreenshot;
1072
+ /**
1073
+ * Takes screenshot of canvas
1074
+ *
1075
+ * @remarks Coordinates should be provided unscaled; that is, the method
1076
+ * will handle any scaling that happened due to device pixel ratios
1077
+ * not equal to 1. This returns a promise because the screenshot request
1078
+ * must be queued and completed once a draw cycle has completed. See
1079
+ * the loop() method.
1080
+ *
1081
+ * @param sx - Upper left coordinate of screenshot
1082
+ * @param sy - Upper right coordinate of screenshot
1083
+ * @param sw - width of area to screenshot
1084
+ * @param sh - hegith of area to screenshot
1085
+ * @returns Promise of Uint8Array of image data
1086
+ */
1087
+ takeScreenshot(sx?: number, sy?: number, sw?: number, sh?: number): Promise<Uint8Array | null>;
963
1088
  private animateSceneTransition;
964
1089
  private drawFps;
965
1090
  /**
@@ -993,17 +1118,6 @@ interface IText {
993
1118
  fontSize?: number;
994
1119
  }
995
1120
 
996
- interface TextOptions {
997
- /** Text to be displayed */
998
- text?: string;
999
- /** Name of font to use for text. Must have been previously loaded */
1000
- fontName?: string;
1001
- /** Color of text. Default is Constants.DEFAULT_FONT_COLOR (WebColors.Black) */
1002
- fontColor?: RgbaColor;
1003
- /** Size of text. Default is Constants.DEFAULT_FONT_SIZE (16) */
1004
- fontSize?: number;
1005
- }
1006
-
1007
1121
  declare enum LabelHorizontalAlignmentMode {
1008
1122
  center = 0,
1009
1123
  left = 1,
@@ -1023,7 +1137,10 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
1023
1137
  readonly type = EntityType.label;
1024
1138
  isDrawable: boolean;
1025
1139
  isText: boolean;
1026
- anchorPoint: Point;
1140
+ anchorPoint: {
1141
+ x: number;
1142
+ y: number;
1143
+ };
1027
1144
  zPosition: number;
1028
1145
  private _text;
1029
1146
  private _fontName;
@@ -1057,6 +1174,17 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
1057
1174
  set preferredMaxLayoutWidth(preferredMaxLayoutWidth: number | undefined);
1058
1175
  get backgroundColor(): RgbaColor | undefined;
1059
1176
  set backgroundColor(backgroundColor: RgbaColor | undefined);
1177
+ /**
1178
+ * Duplicates an entity using deep copy.
1179
+ *
1180
+ * @remarks This is a deep recursive clone (entity and children).
1181
+ * The uuid property of all duplicated entities will be newly created,
1182
+ * because uuid must be unique.
1183
+ *
1184
+ * @param newName - optional name of the new, duplicated entity. If not
1185
+ * provided, name will be the new uuid
1186
+ */
1187
+ duplicate(newName?: string): Label;
1060
1188
  update(): void;
1061
1189
  draw(canvas: Canvas): void;
1062
1190
  }
@@ -1086,22 +1214,39 @@ declare class LayoutConstraint {
1086
1214
 
1087
1215
  declare class RandomDraws {
1088
1216
  /**
1089
- * Draw random integers, without replacement, from a uniform distribution.
1217
+ * Draws a single random integer from a uniform distribution of integers in
1218
+ * the specified range.
1219
+ *
1220
+ * @param minimumInclusive - Lower bound of range
1221
+ * @param maximumInclusive - Upper bound of range
1222
+ * @returns A sampled integer
1223
+ */
1224
+ static SingleFromRange(minimumInclusive: number, maximumInclusive: number): number;
1225
+ /**
1226
+ * Draws random integers, without replacement, from a uniform distribution
1227
+ * of integers in the specified range.
1090
1228
  *
1091
- * @param n
1092
- * @param minimumInclusive
1093
- * @param maximumInclusive
1094
- * @returns array of integers
1229
+ * @param n - Number of draws
1230
+ * @param minimumInclusive - Lower bound of range
1231
+ * @param maximumInclusive - Upper bound of range
1232
+ * @returns An array of integers
1095
1233
  */
1096
1234
  static FromRangeWithoutReplacement(n: number, minimumInclusive: number, maximumInclusive: number): Array<number>;
1097
1235
  /**
1098
- * Draw random grid cell locations, without replacement, from a uniform distribution of all grid cells. Grid cell locations are zero-based, i.e., upper-left is (0,0).
1236
+ * Draw random grid cell locations, without replacement, from a uniform
1237
+ * distribution of all grid cells. Grid cell locations are zero-based,
1238
+ * i.e., upper-left is (0,0).
1099
1239
  *
1100
1240
  * @param n - Number of draws
1101
1241
  * @param rows - Number of rows in grid; must be at least 1
1102
1242
  * @param columns - Number of columns in grid; must be at least 1
1103
- * @param predicate - Optional lambda function that takes a grid row number and grid column number pair and returns a boolean to indicate if the pair should be allowed. For example, if one wanted to constrain the random grid location to be along the diagonal, the predicate would be: (row, column) => row === column
1104
- * @returns array of grid cells. Each cell is object in form of { row: number, column: number }). Grid cell locations are zero-based
1243
+ * @param predicate - Optional lambda function that takes a grid row number
1244
+ * and grid column number pair and returns a boolean to indicate if the pair
1245
+ * should be allowed. For example, if one wanted to constrain the random
1246
+ * grid location to be along the diagonal, the predicate would be:
1247
+ * (row, column) => row === column
1248
+ * @returns Array of grid cells. Each cell is object in form of:
1249
+ * {row: number, column: number}. Grid cell locations are zero-based
1105
1250
  */
1106
1251
  static FromGridWithoutReplacement(n: number, rows: number, columns: number, predicate?: (row: number, column: number) => boolean): Array<{
1107
1252
  row: number;
@@ -1124,21 +1269,18 @@ interface RectOptions {
1124
1269
  height?: number;
1125
1270
  }
1126
1271
 
1127
- declare class Rect implements RectOptions {
1128
- origin?: Point;
1129
- size?: Size;
1130
- x?: number;
1131
- y?: number;
1132
- width?: number;
1133
- height?: number;
1134
- constructor(options: RectOptions);
1272
+ declare enum ShapeType {
1273
+ undefined = "Undefined",
1274
+ rectangle = "Rectangle",
1275
+ circle = "Circle"
1135
1276
  }
1136
1277
 
1137
1278
  interface ShapeOptions extends EntityOptions, DrawableOptions {
1279
+ shapeType?: ShapeType;
1138
1280
  /** If provided, shape will be a circle with given radius */
1139
1281
  circleOfRadius?: number;
1140
1282
  /** If provided, shape will be a rectangle as specified in {@link Rect} */
1141
- rect?: Rect;
1283
+ rect?: RectOptions;
1142
1284
  /** Radius of rectangle's corners */
1143
1285
  cornerRadius?: number;
1144
1286
  /** Color with which to fill shape. Default is Constants.DEFAULT_SHAPE_FILL_COLOR (WebColors.Red) */
@@ -1149,21 +1291,18 @@ interface ShapeOptions extends EntityOptions, DrawableOptions {
1149
1291
  lineWidth?: number;
1150
1292
  }
1151
1293
 
1152
- declare enum ShapeType {
1153
- undefined = "Undefined",
1154
- rectangle = "Rectangle",
1155
- circle = "Circle"
1156
- }
1157
-
1158
1294
  declare class Shape extends Entity implements IDrawable, ShapeOptions {
1159
1295
  readonly type = EntityType.shape;
1160
1296
  isDrawable: boolean;
1161
1297
  isShape: boolean;
1162
- anchorPoint: Point;
1298
+ anchorPoint: {
1299
+ x: number;
1300
+ y: number;
1301
+ };
1163
1302
  zPosition: number;
1164
1303
  shapeType: ShapeType;
1165
1304
  circleOfRadius?: number;
1166
- rect?: Rect;
1305
+ rect?: RectOptions;
1167
1306
  cornerRadius: number;
1168
1307
  private _fillColor;
1169
1308
  private _strokeColor?;
@@ -1181,6 +1320,17 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
1181
1320
  set fillColor(fillColor: RgbaColor);
1182
1321
  get strokeColor(): RgbaColor | undefined;
1183
1322
  set strokeColor(strokeColor: RgbaColor | undefined);
1323
+ /**
1324
+ * Duplicates an entity using deep copy.
1325
+ *
1326
+ * @remarks This is a deep recursive clone (entity and children).
1327
+ * The uuid property of all duplicated entities will be newly created,
1328
+ * because uuid must be unique.
1329
+ *
1330
+ * @param newName - optional name of the new, duplicated entity. If not
1331
+ * provided, name will be the new uuid
1332
+ */
1333
+ duplicate(newName?: string): Shape;
1184
1334
  update(): void;
1185
1335
  draw(canvas: Canvas): void;
1186
1336
  }
@@ -1193,7 +1343,10 @@ interface SpriteOptions extends EntityOptions, DrawableOptions {
1193
1343
  declare class Sprite extends Entity implements IDrawable, SpriteOptions {
1194
1344
  readonly type = EntityType.sprite;
1195
1345
  isDrawable: boolean;
1196
- anchorPoint: Point;
1346
+ anchorPoint: {
1347
+ x: number;
1348
+ y: number;
1349
+ };
1197
1350
  zPosition: number;
1198
1351
  private _imageName;
1199
1352
  private loadedImage?;
@@ -1208,6 +1361,17 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
1208
1361
  initialize(): void;
1209
1362
  set imageName(imageName: string);
1210
1363
  get imageName(): string;
1364
+ /**
1365
+ * Duplicates an entity using deep copy.
1366
+ *
1367
+ * @remarks This is a deep recursive clone (entity and children).
1368
+ * The uuid property of all duplicated entities will be newly created,
1369
+ * because uuid must be unique.
1370
+ *
1371
+ * @param newName - optional name of the new, duplicated entity. If not
1372
+ * provided, name will be the new uuid
1373
+ */
1374
+ duplicate(newName?: string): Sprite;
1211
1375
  update(): void;
1212
1376
  draw(canvas: Canvas): void;
1213
1377
  }
@@ -1229,7 +1393,10 @@ declare class TextLine extends Entity implements IDrawable, IText, TextLineOptio
1229
1393
  isDrawable: boolean;
1230
1394
  isText: boolean;
1231
1395
  zPosition: number;
1232
- anchorPoint: Point;
1396
+ anchorPoint: {
1397
+ x: number;
1398
+ y: number;
1399
+ };
1233
1400
  private _text;
1234
1401
  private _fontName;
1235
1402
  private _fontColor;
@@ -1254,25 +1421,116 @@ declare class TextLine extends Entity implements IDrawable, IText, TextLineOptio
1254
1421
  set fontSize(fontSize: number);
1255
1422
  update(): void;
1256
1423
  initialize(): void;
1424
+ /**
1425
+ * Duplicates an entity using deep copy.
1426
+ *
1427
+ * @remarks This is a deep recursive clone (entity and children).
1428
+ * The uuid property of all duplicated entities will be newly created,
1429
+ * because uuid must be unique.
1430
+ *
1431
+ * @param newName - optional name of the new, duplicated entity. If not
1432
+ * provided, name will be the new uuid
1433
+ */
1434
+ duplicate(newName?: string): TextLine;
1257
1435
  draw(canvas: Canvas): void;
1258
1436
  }
1259
1437
 
1260
1438
  declare class Timer {
1261
- private originTime;
1262
1439
  private startTime;
1263
1440
  private stopTime;
1264
1441
  private stopped;
1265
- private _elapsed;
1442
+ /**
1443
+ * cumulativeElapsed is a cumulative total of elapsed time while the timer
1444
+ * was in previous started (running) states, NOT INCLUDING the possibily
1445
+ * active run's duration
1446
+ */
1447
+ private cumulativeElapsed;
1266
1448
  private name;
1267
1449
  private static _timers;
1268
1450
  constructor(name: string);
1269
- static Start(name: string): void;
1270
- static Stop(name: string): void;
1271
- static Restart(name: string): void;
1272
- static Elapsed(name: string): number;
1273
- static Remove(name: string): void;
1274
- static Exists(name: string): boolean;
1275
- static RemoveAll(): void;
1451
+ /**
1452
+ * Aliases performance.now()
1453
+ *
1454
+ * @remarks The m2c2kit Timer class is designed to measure elapsed durations
1455
+ * after a designated start point for a uniquely named timer. However, if a
1456
+ * timestamp based on the
1457
+ * [time origin](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin)
1458
+ * is needed, this method can be used.
1459
+ *
1460
+ * @returns a [DOMHighResTimeStamp](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp)
1461
+ */
1462
+ static now(): number;
1463
+ /**
1464
+ * Starts a millisecond-resolution timer based on
1465
+ * [performance.now()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now).
1466
+ *
1467
+ * @remarks The method throws an error if a timer with the given
1468
+ * name is already in a started state.
1469
+ *
1470
+ * @param name - The name of the timer to be started
1471
+ */
1472
+ static start(name: string): void;
1473
+ /**
1474
+ * Stops a timer.
1475
+ *
1476
+ * @remarks The method throws an error if a timer with the given
1477
+ * name is already in a stopped state, or if a timer with the
1478
+ * given name has not been started.
1479
+ *
1480
+ * @param name - The name of the timer to be stopped
1481
+ */
1482
+ static stop(name: string): void;
1483
+ /**
1484
+ * Restarts a timer.
1485
+ *
1486
+ * @remarks The timer elapsed duration is set to 0 and it starts anew.
1487
+ * The method throws an error if a timer with the given
1488
+ * name does not exist (if there is not a started or stopped timer
1489
+ * with the given name).
1490
+ *
1491
+ * @param name - The name of the timer to be restarted
1492
+ */
1493
+ static restart(name: string): void;
1494
+ /**
1495
+ * Returns the total time elapsed, in milliseconds, of the timer.
1496
+ *
1497
+ * @remarks The total time elapsed will include all durations from multiple
1498
+ * starts and stops of the timer, if applicable. A timer's elapsed duration
1499
+ * can be read while it is in started or stopped state. The method throws
1500
+ * an error if a timer with the given name does not exist.
1501
+ *
1502
+ * @param name - The name of the timer whose elapsed duration is requested
1503
+ */
1504
+ static elapsed(name: string): number;
1505
+ /**
1506
+ * Removes a timer.
1507
+ *
1508
+ * @remarks After removal, no additional methods can be used with a timer
1509
+ * of the given name, other than to start a new timer with the given name,
1510
+ * whose duration will begin at 0 again. The method throws an error if
1511
+ * a timer with the given name does not exist.
1512
+ *
1513
+ * @param name - The name of the timer to be removed
1514
+ */
1515
+ static remove(name: string): void;
1516
+ /**
1517
+ * Remove all timers.
1518
+ *
1519
+ * @remarks This method will {@link remove} any timers in a started or
1520
+ * stopped state. This method is idempotent; method is safe to call even
1521
+ * if there are no timers to remove; no errors are thrown if there are
1522
+ * not any timers that can be removed.
1523
+ */
1524
+ static removeAll(): void;
1525
+ /**
1526
+ * Checks if a timer of the given name exists.
1527
+ *
1528
+ * @remarks The method checks if there is a timer with the given name.
1529
+ *
1530
+ * @param name - The name of the timer to check for existence
1531
+ * @returns boolean
1532
+ */
1533
+ static exists(name: string): boolean;
1276
1534
  }
1277
1535
 
1278
1536
  declare class Uuid {
@@ -1424,4 +1682,4 @@ declare class WebColors {
1424
1682
  static RebeccaPurple: RgbaColor;
1425
1683
  }
1426
1684
 
1427
- 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 };
1685
+ export { Action, Activity, ActivityDataEvent, ActivityLifecycleEvent, ActivityType, 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, 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 };