excalibur 0.25.1 → 0.25.2

package/build/esm/Traits/Index.d.ts

@@ -1,5 +1,4 @@
 /**
  * @module
  */
-export * from './CapturePointer';
 export * from './OffscreenCulling';

package/build/esm/Trigger.d.ts

@@ -44,5 +44,9 @@ export declare class Trigger extends Actor {
     get target(): Entity;
     _initialize(engine: Engine): void;
     private _dispatchAction;
+    /**
+     * @deprecated signature will change in v0.26.0
+     * @param ctx
+     */
     debugDraw(ctx: CanvasRenderingContext2D): void;
 }

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

@@ -0,0 +1,118 @@
+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;
+    setFatalExceptionHandler(handler: (e: unknown) => any): void;
+    /**
+     * 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 milliseconds)
+     */
+    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 currently sampled fps over the last sample period, by default every 100ms
+     */
+    get fps(): number;
+    /**
+     * Return the instantaneous fps, this can be less useful because it will fluctuate given the current frames time
+     */
+    get instant(): number;
+}

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

@@ -17,7 +17,7 @@ export interface Observer<T> {
  */
 export declare type MaybeObserver<T> = Partial<Observer<T>>;
 /**
- * Simple Observable implemenation
+ * Simple Observable implementation
  * @template T is the typescript Type that defines the data being observed
  */
 export declare class Observable<T> {

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

@@ -1,12 +1,4 @@
-export interface Poolable {
-    /**
-     * Any type that is a member of a an object pool will have a reference to teh pool
-     * @internal
-     */
-    _pool?: Pool<this>;
-    dispose(): this;
-}
-export declare class Pool<Type extends Poolable> {
+export declare class Pool<Type> {
     builder: (...args: any[]) => Type;
     recycler: (instance: Type, ...args: any[]) => Type;
     maxObjects: number;
@@ -18,7 +10,7 @@ export declare class Pool<Type extends Poolable> {
     /**
      * Use many instances out of the in the context and return all to the pool.
      *
-     * By returning values out of the contex they will be un-hooked from the pool and are free to be passed to consumers
+     * By returning values out of the context they will be un-hooked from the pool and are free to be passed to consumers
      * @param context
      */
     using(context: (pool: Pool<Type>) => Type[] | void): Type[];

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

@@ -1,79 +1,39 @@
 import { Vector } from '../Math/vector';
-import { Random } from '../Math/Random';
 import { Side } from '../Collision/Side';
+import { Clock } from './Clock';
+import { clamp as lclamp, randomInRange as lrandomInRange, randomIntInRange as lrandomIntInRange, canonicalizeAngle as lcanonicalizeAngle, toDegrees as ltoDegrees, toRadians as ltoRadians } from '../Math/util';
 /**
- * Two PI constant
+ * @deprecated ex.Util.TwoPI import site will be removed in v0.26.0, use ex.TwoPI
  */
 export declare const TwoPI: number;
 /**
- * Merges one or more objects into a single target object
- *
- * @param deep Whether or not to do a deep clone
- * @param target The target object to attach properties on
- * @param objects The objects whose properties to merge
- * @returns Merged object with properties from other objects
- */
-export declare function extend(deep: boolean, target: any, ...objects: any[]): any;
-/**
- * Merges one or more objects into a single target object
- *
- * @param target The target object to attach properties on
- * @param object2 The second object whose properties to merge
- * @returns Merged object with properties from other objects
- */
-export declare function extend<T1, T2>(target: T1, object2: T2): T1 & T2;
-/**
- * Merges one or more objects into a single target object
- *
- * @param target The target object to attach properties on
- * @param object2 The second object whose properties to merge
- * @param object3 The third object whose properties to merge
- * @returns Merged object with properties from other objects
- */
-export declare function extend<T1, T2, T3>(target: T1, object2: T2, object3: T3): T1 & T2 & T3;
-/**
- * Merges one or more objects into a single target object
- *
- * @param target The target object to attach properties on
- * @param objects The objects whose properties to merge
- * @returns Merged object with properties from other objects
+ * @deprecated ex.Util.clamp import site will be removed in v0.26.0, use ex.clamp
  */
-export declare function extend(target: any, ...objects: any[]): any;
+export declare const clamp: typeof lclamp;
 /**
- * Encode a string in base64
- * @deprecated This will be removed in v0.26.0
+ * @deprecated ex.Util.randomInRange import site will be removed in v0.26.0, use ex.randomInRange
  */
-export declare function base64Encode(inputStr: string): string;
+export declare const randomInRange: typeof lrandomInRange;
 /**
- * Sugar that will use `nullishVal` if it's not null or undefined. Simulates the `??` operator
- * @param nullishVal
- * @param defaultVal
+ * @deprecated ex.Util.randomIntInRange import site will be removed in v0.26.0, use ex.randomIntInRange
  */
-export declare function nullish<T>(nullishVal: T | undefined | null, defaultVal: T): T;
+export declare const randomIntInRange: typeof lrandomIntInRange;
 /**
- * Clamps a value between a min and max inclusive
+ * @deprecated ex.Util.canonicalizeAngle import site will be removed in v0.26.0, use ex.canonicalizeAngle
  */
-export declare function clamp(val: number, min: number, max: number): number;
+export declare const canonicalizeAngle: typeof lcanonicalizeAngle;
 /**
- * Find a random floating point number in range
+ * @deprecated ex.Util.toDegrees import site will be removed in v0.26.0, use ex.toDegrees
  */
-export declare function randomInRange(min: number, max: number, random?: Random): number;
+export declare const toDegrees: typeof ltoDegrees;
 /**
- * Find a random integer in a range
+ * @deprecated ex.Util.toRadians import site will be removed in v0.26.0, use ex.toRadians
  */
-export declare function randomIntInRange(min: number, max: number, random?: Random): number;
+export declare const toRadians: typeof ltoRadians;
 /**
- * Convert an angle to be the equivalent in the range [0, 2PI]
+ * @deprecated ex.Util.range import site will be removed in v0.26.0, use ex.range
  */
-export declare function canonicalizeAngle(angle: number): number;
-/**
- * Convert radians to degrees
- */
-export declare function toDegrees(radians: number): number;
-/**
- * Convert degrees to radians
- */
-export declare function toRadians(degrees: number): number;
+export declare const range: (from: number, to: number) => number[];
 /**
  * Find the screen position of an HTML element
  */
@@ -93,7 +53,7 @@ export declare function removeItemFromArray<T>(item: T, array: T[]): boolean;
  */
 export declare function contains(array: Array<any>, obj: any): boolean;
 /**
- * Get the opposit side
+ * Get the opposite side
  * TODO: Move to Side type
  * @deprecated Will be removed in v0.26.0
  */
@@ -182,15 +142,12 @@ export declare class Collection<T> {
  * Used for exhaustive checks at compile time
  */
 export declare function fail(message: never): never;
-/**
- * Generate a range of numbers
- * For example: range(0, 5) -> [0, 1, 2, 3, 4, 5]
- * @param from inclusive
- * @param to inclusive
- */
-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>;