excalibur 0.26.0-alpha.310 → 0.26.0-alpha.314

package/build/dist/index.d.ts

@@ -55,4 +55,7 @@ export * from './Util/Observable';
 export * from './Util/Log';
 export * from './Util/SortedList';
 export * from './Util/Pool';
+export * from './Util/Fps';
+export * from './Util/Clock';
+export * from './Util/WebAudio';
 export * from './Promises';

package/build/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * The current Excalibur version string
- * @description `'0.26.0-alpha.310+5f94c2f'` gets replaced by Webpack on build
+ * @description `'0.26.0-alpha.314+ff3f7ae'` gets replaced by Webpack on build
  */
-export const EX_VERSION = '0.26.0-alpha.310+5f94c2f';
+export const EX_VERSION = '0.26.0-alpha.314+ff3f7ae';
 import { polyfill } from './Polyfill';
 polyfill();
 // This file is used as the bundle entry point and exports everything
@@ -64,6 +64,9 @@ export * from './Util/Observable';
 export * from './Util/Log';
 export * from './Util/SortedList';
 export * from './Util/Pool';
+export * from './Util/Fps';
+export * from './Util/Clock';
+export * from './Util/WebAudio';
 // ex.Deprecated
 export * from './Promises';
 // import * as deprecated from './Deprecated';

package/build/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,QAAQ,EAAE,CAAC;AAEX,qEAAqE;AACrE,oDAAoD;AACpD,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC;AACrB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,EAAa,MAAM,SAAS,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClF,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAqC,WAAW,EAAE,MAAM,aAAa,CAAC;AACxG,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAyB,MAAM,WAAW,CAAC;AACjE,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,6BAA6B;AAC7B,OAAO,KAAK,aAAa,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,IAAI,aAAa,EAAE,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAElC,cAAc,+BAA+B,CAAC;AAE9C,cAAc,SAAS,CAAC;AAExB,cAAc,kBAAkB,CAAC;AAEjC,sBAAsB;AACtB,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC;AAE5B,qBAAqB;AACrB,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,sBAAsB;AACtB,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC;AAE5B,qBAAqB;AACrB,OAAO,KAAK,IAAI,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;AACxB,OAAO,EACL,KAAK,EACL,KAAK,EACL,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAE5B,gBAAgB;AAChB,cAAc,YAAY,CAAC;AAC3B,8CAA8C;AAC9C,uCAAuC;AACvC,gCAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,QAAQ,EAAE,CAAC;AAEX,qEAAqE;AACrE,oDAAoD;AACpD,cAAc,SAAS,CAAC;AACxB,cAAc,MAAM,CAAC;AACrB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,EAAa,MAAM,SAAS,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClF,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAqC,WAAW,EAAE,MAAM,aAAa,CAAC;AACxG,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAyB,MAAM,WAAW,CAAC;AACjE,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAEhC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,6BAA6B;AAC7B,OAAO,KAAK,aAAa,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,IAAI,aAAa,EAAE,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAElC,cAAc,+BAA+B,CAAC;AAE9C,cAAc,SAAS,CAAC;AAExB,cAAc,kBAAkB,CAAC;AAEjC,sBAAsB;AACtB,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC;AAE5B,qBAAqB;AACrB,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,sBAAsB;AACtB,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,CAAC;AAE5B,qBAAqB;AACrB,OAAO,KAAK,IAAI,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;AACxB,OAAO,EACL,KAAK,EACL,KAAK,EACL,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAEhC,gBAAgB;AAChB,cAAc,YAAY,CAAC;AAC3B,8CAA8C;AAC9C,uCAAuC;AACvC,gCAAgC"}

package/build/esm/Collision/Detection/DynamicTreeCollisionProcessor.d.ts

@@ -10,7 +10,7 @@ import { ExcaliburGraphicsContext } from '../..';
  */
 export declare class DynamicTreeCollisionProcessor implements CollisionProcessor {
     private _dynamicCollisionTree;
-    private _collisions;
+    private _pairs;
     private _collisionPairCache;
     private _colliders;
     getColliders(): readonly Collider[];
@@ -22,7 +22,7 @@ export declare class DynamicTreeCollisionProcessor implements CollisionProcessor
      * Untracks a physics body
      */
     untrack(target: Collider): void;
-    private _shouldGenerateCollisionPair;
+    private _pairExists;
     /**
      * Detects potential collision pairs in a broadphase approach with the dynamic aabb tree strategy
      */

package/build/esm/Collision/Detection/Pair.d.ts

@@ -9,6 +9,11 @@ export declare class Pair {
     colliderB: Collider;
     id: string;
     constructor(colliderA: Collider, colliderB: Collider);
+    /**
+     * Returns whether a it is allowed for 2 colliders in a Pair to collide
+     * @param colliderA
+     * @param colliderB
+     */
     static canCollide(colliderA: Collider, colliderB: Collider): boolean;
     /**
      * Returns whether or not it is possible for the pairs to collide

package/build/esm/Debug/Debug.d.ts

@@ -2,6 +2,7 @@ import { DebugFlags, ColorBlindFlags } from './DebugFlags';
 import { Engine } from '../Engine';
 import { Color } from '../Color';
 import { CollisionContact } from '../Collision/Detection/CollisionContact';
+import { StandardClock, TestClock } from '..';
 /**
  * Debug stats containing current and previous frame statistics
  */
@@ -129,6 +130,21 @@ export interface GraphicsStatistics {
 export declare class Debug implements DebugFlags {
     private _engine;
     constructor(engine: Engine);
+    /**
+     * Switch the current excalibur clock with the [[TestClock]] and return
+     * it in the same running state.
+     *
+     * This is useful when you need to debug frame by frame.
+     */
+    useTestClock(): TestClock;
+    /**
+     * Switch the current excalibur clock with the [[StandardClock]] and
+     * return it in the same runnign state.
+     *
+     * This is useful when you need to switch back to normal mode after
+     * debugging.
+     */
+    useStandardClock(): StandardClock;
     /**
      * Performance statistics
      */

package/build/esm/Engine.d.ts

@@ -18,6 +18,7 @@ import * as Input from './Input/Index';
 import * as Events from './Events';
 import { BrowserEvents } from './Util/Browser';
 import { ExcaliburGraphicsContext } from './Graphics';
+import { Clock } from './Util/Clock';
 /**
  * Enum representing the different mousewheel event bubble prevention
  */
@@ -124,6 +125,13 @@ export interface EngineOptions {
      * Optionally set the background color
      */
     backgroundColor?: Color;
+    /**
+     * Optionally set the maximum fps if not set Excalibur will go as fast as the device allows.
+     *
+     * You may want to constrain max fps if your game cannot maintain fps consistenly, it can look and feel better to have a 30fps game than
+     * one that bounces between 30fps and 60fps
+     */
+    maxFps?: number;
 }
 /**
  * The Excalibur Engine
@@ -154,6 +162,17 @@ export declare class Engine extends Class implements CanInitialize, CanUpdate, C
      * Direct access to the canvas element ID, if an ID exists
      */
     canvasElementId: string;
+    /**
+     * Optionally set the maximum fps if not set Excalibur will go as fast as the device allows.
+     *
+     * You may want to constrain max fps if your game cannot maintain fps consistenly, it can look and feel better to have a 30fps game than
+     * one that bounces between 30fps and 60fps
+     */
+    maxFps: number;
+    /**
+     * Direct access to the excalibur clock
+     */
+    clock: Clock;
     /**
      * The width of the game canvas in pixels (physical width component of the
      * resolution of the canvas element)
@@ -276,7 +295,6 @@ export declare class Engine extends Class implements CanInitialize, CanUpdate, C
     private _compatible;
     private _timescale;
     private _loader;
-    private _isLoading;
     private _isInitialized;
     private _deferredGoTo;
     on(eventName: Events.initialize, handler: (event: Events.InitializeEvent<Engine>) => void): void;
@@ -555,13 +573,28 @@ export declare class Engine extends Class implements CanInitialize, CanUpdate, C
      * Returns true when loading is totally complete and the player has clicked start
      */
     get loadingComplete(): boolean;
+    private _isReady;
+    get ready(): boolean;
+    private _isReadyResolve;
+    private _isReadyPromise;
+    isReady(): Promise<void>;
     /**
      * Starts the internal game loop for Excalibur after loading
      * any provided assets.
      * @param loader  Optional [[Loader]] to use to load resources. The default loader is [[Loader]], override to provide your own
      * custom loader.
+     *
+     * Note: start() only resolves AFTER the user has clicked the play button
      */
     start(loader?: Loader): Promise<void>;
+    private _mainloop;
+    /**
+     *
+     * @param game
+     * @param raf
+     * @param nowFn
+     * @deprecated Use [[Clock]] to run the mainloop, will be removed in v0.26.0
+     */
     static createMainLoop(game: Engine, raf: (func: Function) => number, nowFn: () => number): () => void;
     /**
      * Stops Excalibur's main loop, useful for pausing the game.

package/build/esm/EntityComponentSystem/SystemManager.d.ts

@@ -34,6 +34,12 @@ export declare class SystemManager<ContextType> {
      * @param system
      */
     removeSystem(system: System<any, ContextType>): void;
+    /**
+     * Initialize all systems in the manager
+     *
+     * Systems added after initialize() will be initialized on add
+     */
+    initialize(): void;
     /**
      * Updates all systems
      * @param type whether this is an update or draw system

package/build/esm/Loader.d.ts

@@ -154,9 +154,12 @@ export declare class Loader extends Class implements Loadable<Loadable<any>[]> {
     dispose(): void;
     update(_engine: Engine, _delta: number): void;
     data: Loadable<any>[];
+    private _isLoadedResolve;
+    private _isLoadedPromise;
+    areResourcesLoaded(): Promise<void>;
     /**
      * Begin loading all of the supplied resources, returning a promise
-     * that resolves when loading of all is complete
+     * that resolves when loading of all is complete AND the user has clicked the "Play button"
      */
     load(): Promise<Loadable<any>[]>;
     markResourceComplete(): void;

package/build/esm/Util/Clock.d.ts

@@ -0,0 +1,117 @@
+import { FpsSampler } from './Fps';
+export interface ClockOptions {
+    /**
+     * Define the function you'd like the clock to tick when it is started
+     */
+    tick: (elapsedMs: number) => any;
+    /**
+     * Optionally define the fatal exception handler, used if an error is thrown in tick
+     */
+    onFatalException?: (e: unknown) => any;
+    /**
+     * Optionally limit the maximum FPS of the clock
+     */
+    maxFps?: number;
+}
+/**
+ * Abstract Clock is the base type of all Clocks
+ *
+ * It has a few opinions
+ * 1. It manages the calculation of what "elapsed" time means and thus maximum fps
+ * 2. The default timing api is implemented in now()
+ *
+ * To implement your own clock, extend Clock and override start/stop to start and stop the clock, then call update() with whatever
+ * method is unique to your clock implementation.
+ */
+export declare abstract class Clock {
+    protected tick: (elapsedMs: number) => any;
+    private _onFatalException;
+    private _maxFps;
+    private _lastTime;
+    fpsSampler: FpsSampler;
+    private _options;
+    private _elapsed;
+    private _scheduledCbs;
+    private _totalElapsed;
+    constructor(options: ClockOptions);
+    /**
+     * Get the elapsed time for the last completed frame
+     */
+    elapsed(): number;
+    /**
+     * Get the current time in milliseconds
+     */
+    now(): number;
+    toTestClock(): TestClock;
+    toStandardClock(): StandardClock;
+    /**
+     * Schedule a callback to fire given a timeout in milliseconds using the excalibur [[Clock]]
+     *
+     * This is useful to use over the built in browser `setTimeout` because callbacks will be tied to the
+     * excalibur update clock, instead of browser time, this means that callbacks wont fire if the game is
+     * stopped or paused.
+     *
+     * @param cb callback to fire
+     * @param timeoutMs Optionally specify a timeout in milliseconds from now, default is 0ms which means the next possible tick
+     */
+    schedule(cb: () => any, timeoutMs?: number): void;
+    private _runScheduledCbs;
+    protected update(overrideUpdateMs?: number): void;
+    /**
+     * Returns if the clock is currently running
+     */
+    abstract isRunning(): boolean;
+    /**
+     * Start the clock, it will then periodically call the tick(elapsedMilliseconds) since the last tick
+     */
+    abstract start(): void;
+    /**
+     * Stop the clock, tick() is no longer called
+     */
+    abstract stop(): void;
+}
+/**
+ * The [[StandardClock]] implements the requestAnimationFrame browser api to run the tick()
+ */
+export declare class StandardClock extends Clock {
+    private _running;
+    private _requestId;
+    constructor(options: ClockOptions);
+    isRunning(): boolean;
+    start(): void;
+    stop(): void;
+}
+export interface TestClockOptions {
+    /**
+     * Specify the update milliseconds to use for each manual step()
+     */
+    defaultUpdateMs: number;
+}
+/**
+ * The TestClock is meant for debugging interactions in excalibur that require precise timing to replicate or test
+ */
+export declare class TestClock extends Clock {
+    private _logger;
+    private _updateMs;
+    private _running;
+    private _currentTime;
+    constructor(options: ClockOptions & TestClockOptions);
+    /**
+     * Get the current time in milliseconds
+     */
+    now(): number;
+    isRunning(): boolean;
+    start(): void;
+    stop(): void;
+    /**
+     * Manually step the clock forward 1 tick, optionally specify an elapsed time in milliseconds
+     * @param overrideUpdateMs
+     */
+    step(overrideUpdateMs?: number): void;
+    /**
+     * Run a number of steps that tick the clock, optionally specify an elapsed time in milliseconds
+     * @param numberOfSteps
+     * @param overrideUpdateMs
+     */
+    run(numberOfSteps: number, overrideUpdateMs?: number): void;
+}

package/build/esm/Util/Fps.d.ts

@@ -0,0 +1,40 @@
+export interface FpsSamplerOptions {
+    /**
+     * Specify the sampling period in milliseconds (default 100)
+     */
+    samplePeriod?: number;
+    /**
+     * Specify the initial FPS
+     */
+    initialFps: number;
+    /**
+     * Specify the function used to return the current time (in millseconds)
+     */
+    nowFn: () => number;
+}
+export declare class FpsSampler {
+    private _fps;
+    private _samplePeriod;
+    private _currentFrameTime;
+    private _frames;
+    private _previousSampleTime;
+    private _beginFrameTime;
+    private _nowFn;
+    constructor(options: FpsSamplerOptions);
+    /**
+     * Start of code block to sample FPS for
+     */
+    start(): void;
+    /**
+     * End of code block to sample FPS for
+     */
+    end(): void;
+    /**
+     * Return the currenty sampled fps over the last sample period, by default every 100ms
+     */
+    get fps(): number;
+    /**
+     * Return the instantanteous fps, this can be less useful because it will fluctuate given the current frames time
+     */
+    get instant(): number;
+}

package/build/esm/Util/Util.d.ts

@@ -1,6 +1,7 @@
 import { Vector } from '../Math/vector';
 import { Random } from '../Math/Random';
 import { Side } from '../Collision/Side';
+import { Clock } from '..';
 /**
  * Two PI constant
  */
@@ -157,6 +158,10 @@ export declare function fail(message: never): never;
 export declare const range: (from: number, to: number) => number[];
 /**
  * Create a promise that resolves after a certain number of milliseconds
+ *
+ * It is strongly recommended you pass the excalibur clock so delays are bound to the
+ * excalibur clock which would be unaffected by stop/pause.
  * @param milliseconds
+ * @param clock
  */
-export declare function delay(milliseconds: number): Promise<void>;
+export declare function delay(milliseconds: number, clock?: Clock): Promise<void>;