excalibur 0.33.0-alpha.99 → 1.1.0-alpha.310

package/build/{dist → esm/src/engine}/math/matrix.d.ts

@@ -1,4 +1,6 @@
 import { Vector } from './vector';
+import { Vector3 } from './vector3';
+import { Vector4 } from './vector4';
 export declare enum MatrixLocations {
     X = 12,
     Y = 13
@@ -59,6 +61,17 @@ export declare class Matrix {
      * @param y
      */
     static translation(x: number, y: number): Matrix;
+    /**
+     * Creates a brand new translation matrix at the specified 3d point
+     * @param vec
+     */
+    static translation3d(vec: Vector3): Matrix;
+    /**
+     * Creates a brand new translation matrix at the specified 4d point
+     * @param vec
+     *
+     */
+    static translation4d(vec: Vector4): Matrix;
     /**
      * Creates a brand new scaling matrix with the specified scaling factor
      * @param sx
@@ -82,6 +95,18 @@ export declare class Matrix {
      * @param dest
      */
     multiply(matrix: Matrix, dest?: Matrix): Matrix;
+    /**
+     * Multiply the current matrix by a 4D vector producing a new 4D vector
+     * @param vector
+     * @param dest
+     */
+    multiply(vector: Vector4, dest?: Vector4): Vector4;
+    /**
+     * Multiply the current matrix by a 3D vector producing a new 3D vector
+     * @param vector
+     * @param dest
+     */
+    multiply(vector: Vector3, dest?: Vector3): Vector3;
     /**
      * Applies translation to the current matrix mutating it
      * @param x

package/build/{dist → esm/src/engine}/math/ray.d.ts

@@ -17,7 +17,7 @@ export declare class Ray {
      * @param line  The line to test
      */
     intersect(line: LineSegment): number;
-    intersectPoint(line: LineSegment): Vector;
+    intersectPoint(line: LineSegment): Vector | null;
     /**
      * Returns the point of intersection given the intersection time
      */

package/build/{dist → esm/src/engine}/math/transform.d.ts

@@ -44,7 +44,16 @@ export declare class Transform {
      */
     get inverse(): AffineMatrix;
     private _scratch;
+    private _trigRotation;
+    private _cos;
+    private _sin;
     private _calculateMatrix;
+    private _version;
+    /**
+     * Increments every time this transform (or one of its parents) changes, cheap change detection for caches built
+     * from this transform
+     */
+    get version(): number;
     flagDirty(): void;
     apply(point: Vector): Vector;
     applyInverse(point: Vector): Vector;

package/build/{dist → esm/src/engine}/math/vector.d.ts

@@ -100,17 +100,6 @@ export declare class Vector implements Clonable<Vector> {
      * @param magnitude
      */
     clampMagnitude(magnitude: number): Vector;
-    /**
-     * The size (magnitude) of the Vector
-     * @deprecated Will be removed in v1, use Vector.magnitude
-     */
-    get size(): number;
-    /**
-     * Setting the size mutates the current vector
-     * @warning Can be used to set the size of the vector, **be very careful using this, mutating vectors can cause hard to find bugs**
-     * @deprecated Will be removed in v1, use Vector.magnitude
-     */
-    set size(newLength: number);
     /**
      * The magnitude (length) of the Vector
      */
@@ -130,10 +119,15 @@ export declare class Vector implements Clonable<Vector> {
     average(vec: Vector): Vector;
     /**
      * Scales a vector's by a factor of size
-     * @param size  The factor to scale the magnitude by
-     * @param dest  Optionally provide a destination vector for the result
+     * @param scale The factor to scale the magnitude by
+     * @param dest {Optional} Optionally provide a destination vector for the result
      */
     scale(scale: Vector, dest?: Vector): Vector;
+    /**
+     * Scales a vector's by a factor of size
+     * @param size  The factor to scale the magnitude by
+     * @param dest {Optional} Optionally provide a destination vector for the result
+     */
     scale(size: number, dest?: Vector): Vector;
     /**
      * Adds one vector to another
@@ -226,6 +220,15 @@ export declare class Vector implements Clonable<Vector> {
      * @returns A new vector that is the result of the linear interpolation.
      */
     lerp(target: Vector, t: number): Vector;
+    /**
+     * Copies components out into an array or Float32Array
+     */
+    toArray(dest?: number[], offset?: number): number[];
+    toArray(dest: Float32Array, offset?: number): Float32Array;
+    /**
+     * Converts to a Float32Array suitable for WebGL uniforms
+     */
+    toFloat32Array(): Float32Array;
 }
 /**
  * Shorthand for creating new Vectors - returns a new Vector instance with the

package/build/esm/src/engine/math/vector3.d.ts

@@ -0,0 +1,163 @@
+import type { Clonable } from '../interfaces/clonable';
+/**
+ * A 3D vector.
+ */
+export declare class Vector3 implements Clonable<Vector3> {
+    /**
+     * Get or set the vector equals epsilon, by default 0.001 meaning vectors within that tolerance on x, y, or z will be considered equal.
+     */
+    static EQUALS_EPSILON: number;
+    /**
+     * A (0, 0, 0) vector
+     */
+    static get Zero(): Vector3;
+    /**
+     * A (1, 1, 1) vector
+     */
+    static get One(): Vector3;
+    /**
+     * A unit vector pointing right (1, 0, 0)
+     */
+    static get Right(): Vector3;
+    /**
+     * A unit vector pointing left (-1, 0, 0)
+     */
+    static get Left(): Vector3;
+    /**
+     * A unit vector pointing up (0, -1, 0)
+     */
+    static get Up(): Vector3;
+    /**
+     * A unit vector pointing down (0, 1, 0)
+     */
+    static get Down(): Vector3;
+    /**
+     * A unit vector pointing forward/out (0, 0, 1)
+     */
+    static get Forward(): Vector3;
+    /**
+     * A unit vector pointing backward/in (0, 0, -1)
+     */
+    static get Back(): Vector3;
+    /**
+     * Checks if vector is not null, undefined, or if any of its components are NaN or Infinity.
+     */
+    static isValid(vec: Vector3): boolean;
+    /**
+     * Calculates distance between two Vectors
+     */
+    static distance(vec1: Vector3, vec2: Vector3): number;
+    static min(vec1: Vector3, vec2: Vector3): Vector3;
+    static max(vec1: Vector3, vec2: Vector3): Vector3;
+    /**
+     * Creates a Vector3 from an array [x, y, z]
+     */
+    static fromArray(array: number[] | Float32Array, offset?: number): Vector3;
+    /**
+     * @param x X component of the Vector
+     * @param y Y component of the Vector
+     * @param z Z component of the Vector
+     */
+    constructor(x: number, y: number, z: number);
+    protected _x: number;
+    get x(): number;
+    set x(val: number);
+    protected _y: number;
+    get y(): number;
+    set y(val: number);
+    protected _z: number;
+    get z(): number;
+    set z(val: number);
+    /**
+     * Sets the x, y, and z components at once, THIS MUTATES the current vector.
+     */
+    setTo(x: number, y: number, z: number): void;
+    /**
+     * Compares this vector against another and tests for equality
+     */
+    equals(vector: Vector3, tolerance?: number): boolean;
+    /**
+     * The distance to another vector. If no other Vector is specified, this will return magnitude.
+     */
+    distance(v?: Vector3): number;
+    squareDistance(v?: Vector3): number;
+    /**
+     * Clamps the current vector's magnitude mutating it
+     */
+    clampMagnitude(magnitude: number): Vector3;
+    /**
+     * The magnitude (length) of the Vector
+     */
+    get magnitude(): number;
+    set magnitude(newMagnitude: number);
+    /**
+     * Normalizes a non-zero vector to have a magnitude of 1. Zero vectors return a new zero vector.
+     */
+    normalize(): Vector3;
+    /**
+     * Returns the average (midpoint) between the current point and the specified point
+     */
+    average(vec: Vector3): Vector3;
+    /**
+     * Scales a vector by a factor or component-wise vector
+     */
+    scale(scale: Vector3, dest?: Vector3): Vector3;
+    scale(size: number, dest?: Vector3): Vector3;
+    /**
+     * Adds one vector to another
+     */
+    add(v: Vector3, dest?: Vector3): Vector3;
+    /**
+     * Subtracts a vector from another
+     */
+    sub(v: Vector3, dest?: Vector3): Vector3;
+    /**
+     * Adds one vector to this one modifying the original
+     */
+    addEqual(v: Vector3): Vector3;
+    /**
+     * Subtracts a vector from this one modifying the original
+     */
+    subEqual(v: Vector3): Vector3;
+    /**
+     * Scales this vector by a factor and modifies the original
+     */
+    scaleEqual(size: number): Vector3;
+    /**
+     * Performs a dot product with another vector
+     */
+    dot(v: Vector3): number;
+    /**
+     * Performs a 3D cross product with another vector
+     */
+    cross(v: Vector3, dest?: Vector3): Vector3;
+    /**
+     * Negate the current vector
+     */
+    negate(): Vector3;
+    /**
+     * Creates new vector that has the same values as the previous.
+     */
+    clone(dest?: Vector3): Vector3;
+    /**
+     * Returns a string representation of the vector.
+     */
+    toString(fixed?: number): string;
+    /**
+     * Linearly interpolates between current vector and target vector.
+     */
+    lerp(target: Vector3, t: number): Vector3;
+    /**
+     * Copies components out into an array or Float32Array
+     */
+    toArray(dest?: number[], offset?: number): number[];
+    toArray(dest: Float32Array, offset?: number): Float32Array;
+    /**
+     * Converts to a Float32Array suitable for WebGL uniforms
+     */
+    toFloat32Array(): Float32Array;
+}
+/**
+ * Shorthand for creating new 3D Vectors
+ */
+export declare function vec3(x: number, y: number, z: number): Vector3;

package/build/esm/src/engine/math/vector4.d.ts

@@ -0,0 +1,157 @@
+import type { Clonable } from '../interfaces/clonable';
+import type { Matrix } from './matrix';
+import { Vector3 } from './vector3';
+/**
+ * A 4D vector, often used for homogeneous coordinates in WebGL shaders and transforms.
+ */
+export declare class Vector4 implements Clonable<Vector4> {
+    /**
+     * Get or set the vector equals epsilon, by default 0.001 meaning vectors within that tolerance will be considered equal.
+     */
+    static EQUALS_EPSILON: number;
+    /**
+     * A (0, 0, 0, 0) vector
+     */
+    static get Zero(): Vector4;
+    /**
+     * A (1, 1, 1, 1) vector
+     */
+    static get One(): Vector4;
+    /**
+     * Creates a homogeneous point vector (w = 1) from a Vector3
+     */
+    static fromPoint(v: Vector3): Vector4;
+    /**
+     * Creates a homogeneous direction vector (w = 0) from a Vector3
+     */
+    static fromDirection(v: Vector3): Vector4;
+    /**
+     * Checks if vector is not null, undefined, or if any of its components are NaN or Infinity.
+     */
+    static isValid(vec: Vector4): boolean;
+    /**
+     * Calculates distance between two Vectors
+     */
+    static distance(vec1: Vector4, vec2: Vector4): number;
+    static min(vec1: Vector4, vec2: Vector4): Vector4;
+    static max(vec1: Vector4, vec2: Vector4): Vector4;
+    /**
+     * Creates a Vector4 from an array [x, y, z, w]
+     */
+    static fromArray(array: number[] | Float32Array, offset?: number): Vector4;
+    /**
+     * @param x X component
+     * @param y Y component
+     * @param z Z component
+     * @param w W component
+     */
+    constructor(x: number, y: number, z: number, w: number);
+    protected _x: number;
+    get x(): number;
+    set x(val: number);
+    protected _y: number;
+    get y(): number;
+    set y(val: number);
+    protected _z: number;
+    get z(): number;
+    set z(val: number);
+    protected _w: number;
+    get w(): number;
+    set w(val: number);
+    /**
+     * Sets all 4 components at once, THIS MUTATES the current vector.
+     */
+    setTo(x: number, y: number, z: number, w: number): void;
+    /**
+     * Compares this vector against another and tests for equality
+     */
+    equals(vector: Vector4, tolerance?: number): boolean;
+    /**
+     * Distance to another vector or magnitude if omitted
+     */
+    distance(v?: Vector4): number;
+    squareDistance(v?: Vector4): number;
+    /**
+     * Clamps the current vector's magnitude mutating it
+     */
+    clampMagnitude(magnitude: number): Vector4;
+    /**
+     * Magnitude (length) of the Vector
+     */
+    get magnitude(): number;
+    set magnitude(newMagnitude: number);
+    /**
+     * Normalizes a non-zero vector. Zero vectors return a new zero vector.
+     */
+    normalize(): Vector4;
+    /**
+     * Returns midpoint between this and target point
+     */
+    average(vec: Vector4): Vector4;
+    /**
+     * Scales vector component-wise or by scalar
+     */
+    scale(scale: Vector4, dest?: Vector4): Vector4;
+    scale(size: number, dest?: Vector4): Vector4;
+    /**
+     * Adds one vector to another
+     */
+    add(v: Vector4, dest?: Vector4): Vector4;
+    /**
+     * Subtracts a vector from another
+     */
+    sub(v: Vector4, dest?: Vector4): Vector4;
+    /**
+     * Adds one vector to this one modifying the original
+     */
+    addEqual(v: Vector4): Vector4;
+    /**
+     * Subtracts a vector from this one modifying the original
+     */
+    subEqual(v: Vector4): Vector4;
+    /**
+     * Scales this vector by a factor and modifies the original
+     */
+    scaleEqual(size: number): Vector4;
+    /**
+     * Performs a dot product with another vector
+     */
+    dot(v: Vector4): number;
+    /**
+     * Negates current vector
+     */
+    negate(): Vector4;
+    /**
+     * Transforms this vector using a 4x4 Matrix
+     */
+    transform(matrix: Matrix, dest?: Vector4): Vector4;
+    /**
+     * Projects back down to 3D via perspective divide (x/w, y/w, z/w)
+     */
+    toVector3(): Vector3;
+    /**
+     * Creates new vector that has the same values as the previous.
+     */
+    clone(dest?: Vector4): Vector4;
+    /**
+     * Returns a string representation of the vector.
+     */
+    toString(fixed?: number): string;
+    /**
+     * Linearly interpolates between current vector and target vector.
+     */
+    lerp(target: Vector4, t: number): Vector4;
+    /**
+     * Copies components out into an array or Float32Array
+     */
+    toArray(dest?: number[], offset?: number): number[];
+    toArray(dest: Float32Array, offset?: number): Float32Array;
+    /**
+     * Converts to a Float32Array suitable for WebGL uniforms
+     */
+    toFloat32Array(): Float32Array;
+}
+/**
+ * Shorthand for creating new 4D Vectors
+ */
+export declare function vec4(x: number, y: number, z: number, w: number): Vector4;

package/build/{dist → esm/src/engine}/particles/gpu-particle-emitter.d.ts

@@ -1,7 +1,7 @@
 import type { Engine } from '../engine';
 import { Actor } from '../actor';
 import { EmitterType } from './emitter-type';
-import type { ParticleEmitterArgs } from './particles';
+import type { ParticleEmitterOptions } from './particles';
 import type { GpuParticleConfig } from './gpu-particle-renderer';
 import { GpuParticleRenderer } from './gpu-particle-renderer';
 import { GraphicsComponent } from '../graphics/graphics-component';
@@ -22,7 +22,7 @@ export declare class GpuParticleEmitter extends Actor {
     set pos(pos: Vector);
     get z(): number;
     set z(z: number);
-    constructor(config: ParticleEmitterArgs & {
+    constructor(config: ParticleEmitterOptions & {
         maxParticles?: number;
         particle?: GpuParticleConfig;
     });

package/build/{dist → esm/src/engine}/particles/particle-emitter.d.ts

@@ -2,7 +2,7 @@ import type { Engine } from '../engine';
 import { Actor } from '../actor';
 import { Random } from '../math/random';
 import { EmitterType } from './emitter-type';
-import type { ParticleEmitterArgs, ParticleConfig } from './particles';
+import type { ParticleConfig, ParticleEmitterOptions } from './particles';
 import { Particle } from './particles';
 /**
  * Using a particle emitter is a great way to create interesting effects
@@ -43,7 +43,7 @@ export declare class ParticleEmitter extends Actor {
     /**
      * @param config particle emitter options bag
      */
-    constructor(config: ParticleEmitterArgs);
+    constructor(config: ParticleEmitterOptions);
     removeParticle(particle: Particle): void;
     private _activeParticles;
     /**

package/build/{dist → esm/src/engine}/particles/particles.d.ts

@@ -41,6 +41,7 @@ export declare class Particle extends Entity {
     name: string;
     constructor(options: ParticleConfig);
     private _emitter?;
+    private _isDead;
     registerEmitter(emitter: ParticleEmitter): void;
     configure(options: ParticleConfig): void;
     kill(): void;
@@ -166,7 +167,7 @@ export declare enum ParticleTransform {
      */
     Local = "local"
 }
-export interface ParticleEmitterArgs {
+export interface ParticleEmitterOptions {
     particle?: ParticleConfig;
     x?: number;
     y?: number;
@@ -194,3 +195,7 @@ export interface ParticleEmitterArgs {
     radius?: number;
     random?: Random;
 }
+/**
+ * @deprecated use ParticleEmitterOptions
+ */
+export type ParticleEmitterArgs = ParticleEmitterOptions;