emeraldengine 3.0.0 → 3.1.0

package/dist/types/src/physics/Math2D.d.ts

@@ -0,0 +1,371 @@
+/**
+ * @file Math primitives for the Emerald physics engine.
+ * @description Everything here works in *physics units* (meters, radians), not
+ * world/pixel units. The conversion happens in {@link Physics} and
+ * {@link RigidBody}, so nothing below ever needs to know about the pixel scale.
+ */
+/**
+ * @class Vec2
+ * @description A 2D vector in physics space. Instance methods mutate in place
+ * (used in the hot solver paths); the statics allocate a new vector. Accepts
+ * either two numbers or any `{ x, y }` object.
+ * @param {number|Object} [x=0] - The x coordinate, or an `{ x, y }` object
+ * @param {number} [y=0] - The y coordinate
+ */
+export class Vec2 {
+    /**
+     * @method zero
+     * @description Returns a fresh zero vector.
+     * @returns {Vec2}
+     */
+    static zero(): Vec2;
+    /**
+     * @method add
+     * @description a + b as a new vector.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {Vec2}
+     */
+    static add(a: any, b: any): Vec2;
+    /**
+     * @method sub
+     * @description a - b as a new vector.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {Vec2}
+     */
+    static sub(a: any, b: any): Vec2;
+    /**
+     * @method mul
+     * @description s * v as a new vector (either argument order works).
+     * @param {number|Object} a
+     * @param {number|Object} b
+     * @returns {Vec2}
+     */
+    static mul(a: number | any, b: number | any): Vec2;
+    /**
+     * @method combine
+     * @description sa * a + sb * b as a new vector.
+     * @param {number} sa
+     * @param {Object} a
+     * @param {number} sb
+     * @param {Object} b
+     * @returns {Vec2}
+     */
+    static combine(sa: number, a: any, sb: number, b: any): Vec2;
+    /**
+     * @method neg
+     * @description -v as a new vector.
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static neg(v: any): Vec2;
+    /**
+     * @method dot
+     * @description Dot product.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {number}
+     */
+    static dot(a: any, b: any): number;
+    /**
+     * @method cross
+     * @description 2D cross product (the z of the 3D cross): a.x*b.y - a.y*b.x.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {number}
+     */
+    static cross(a: any, b: any): number;
+    /**
+     * @method crossVS
+     * @description Cross of a vector with a scalar: (v.y * s, -v.x * s).
+     * @param {Object} v
+     * @param {number} s
+     * @returns {Vec2}
+     */
+    static crossVS(v: any, s: number): Vec2;
+    /**
+     * @method crossSV
+     * @description Cross of a scalar with a vector: (-s * v.y, s * v.x). This is
+     * how angular velocity turns into linear velocity at an offset.
+     * @param {number} s
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static crossSV(s: number, v: any): Vec2;
+    /**
+     * @method distance
+     * @description Distance between two points.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {number}
+     */
+    static distance(a: any, b: any): number;
+    /**
+     * @method distanceSquared
+     * @description Squared distance between two points.
+     * @param {Object} a
+     * @param {Object} b
+     * @returns {number}
+     */
+    static distanceSquared(a: any, b: any): number;
+    /**
+     * @method lerp
+     * @description Linear interpolation between two points.
+     * @param {Object} a
+     * @param {Object} b
+     * @param {number} t
+     * @returns {Vec2}
+     */
+    static lerp(a: any, b: any, t: number): Vec2;
+    constructor(x?: number, y?: number);
+    x: any;
+    y: any;
+    /**
+     * @method set
+     * @description Sets both components in place.
+     * @param {number} x
+     * @param {number} y
+     * @returns {Vec2} - this
+     */
+    set(x: number, y: number): Vec2;
+    /**
+     * @method copy
+     * @description Copies another vector's components into this one.
+     * @param {Object} v - Any `{ x, y }`
+     * @returns {Vec2} - this
+     */
+    copy(v: any): Vec2;
+    /**
+     * @method clone
+     * @description Returns an independent copy.
+     * @returns {Vec2}
+     */
+    clone(): Vec2;
+    /**
+     * @method setZero
+     * @description Zeroes both components in place.
+     * @returns {Vec2} - this
+     */
+    setZero(): Vec2;
+    /**
+     * @method add
+     * @description Adds another vector in place.
+     * @param {Object} v
+     * @returns {Vec2} - this
+     */
+    add(v: any): Vec2;
+    /**
+     * @method addMul
+     * @description Adds `s * v` in place. The workhorse of the solver.
+     * @param {number} s
+     * @param {Object} v
+     * @returns {Vec2} - this
+     */
+    addMul(s: number, v: any): Vec2;
+    /**
+     * @method sub
+     * @description Subtracts another vector in place.
+     * @param {Object} v
+     * @returns {Vec2} - this
+     */
+    sub(v: any): Vec2;
+    /**
+     * @method subMul
+     * @description Subtracts `s * v` in place.
+     * @param {number} s
+     * @param {Object} v
+     * @returns {Vec2} - this
+     */
+    subMul(s: number, v: any): Vec2;
+    /**
+     * @method mul
+     * @description Scales in place.
+     * @param {number} s
+     * @returns {Vec2} - this
+     */
+    mul(s: number): Vec2;
+    /**
+     * @method neg
+     * @description Negates in place.
+     * @returns {Vec2} - this
+     */
+    neg(): Vec2;
+    /**
+     * @method length
+     * @description Euclidean length.
+     * @returns {number}
+     */
+    length(): number;
+    /**
+     * @method lengthSquared
+     * @description Squared length (no sqrt).
+     * @returns {number}
+     */
+    lengthSquared(): number;
+    /**
+     * @method normalize
+     * @description Normalizes in place and returns the previous length. A
+     * zero-length vector is left untouched (and reports 0).
+     * @returns {number} - The length before normalizing
+     */
+    normalize(): number;
+    /**
+     * @method isValid
+     * @description True when both components are finite.
+     * @returns {boolean}
+     */
+    isValid(): boolean;
+}
+/**
+ * @class Rot
+ * @description A 2D rotation stored as sine/cosine, so rotating a vector never
+ * needs a trig call in the inner loop.
+ * @param {number} [angle=0] - Angle in radians
+ */
+export class Rot {
+    /**
+     * @method mulVec
+     * @description Rotates a vector by `q` into a new vector.
+     * @param {Rot} q
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static mulVec(q: Rot, v: any): Vec2;
+    /**
+     * @method mulTVec
+     * @description Inverse-rotates a vector by `q` (world direction -> local).
+     * @param {Rot} q
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static mulTVec(q: Rot, v: any): Vec2;
+    constructor(angle?: number);
+    s: number;
+    c: number;
+    /**
+     * @method set
+     * @description Sets the rotation from an angle in radians.
+     * @param {number} angle
+     * @returns {Rot} - this
+     */
+    set(angle: number): Rot;
+    /**
+     * @method copy
+     * @description Copies another rotation.
+     * @param {Rot} r
+     * @returns {Rot} - this
+     */
+    copy(r: Rot): Rot;
+    /**
+     * @method setIdentity
+     * @description Resets to zero rotation.
+     * @returns {Rot} - this
+     */
+    setIdentity(): Rot;
+    /**
+     * @method getAngle
+     * @description Returns the angle in radians.
+     * @returns {number}
+     */
+    getAngle(): number;
+}
+/**
+ * @class Transform2
+ * @description A rigid transform: a translation `p` plus a rotation `q`. Named
+ * Transform2 so it never collides with the engine's renderable `Transform`.
+ */
+export class Transform2 {
+    /**
+     * @method mulVec
+     * @description Transforms a local point into world space.
+     * @param {Transform2} xf
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static mulVec(xf: Transform2, v: any): Vec2;
+    /**
+     * @method mulTVec
+     * @description Transforms a world point into local space.
+     * @param {Transform2} xf
+     * @param {Object} v
+     * @returns {Vec2}
+     */
+    static mulTVec(xf: Transform2, v: any): Vec2;
+    p: Vec2;
+    q: Rot;
+    /**
+     * @method setIdentity
+     * @description Resets to the identity transform.
+     * @returns {Transform2} - this
+     */
+    setIdentity(): Transform2;
+    /**
+     * @method set
+     * @description Sets position and angle.
+     * @param {Object} position
+     * @param {number} angle
+     * @returns {Transform2} - this
+     */
+    set(position: any, angle: number): Transform2;
+    /**
+     * @method copy
+     * @description Copies another transform.
+     * @param {Transform2} xf
+     * @returns {Transform2} - this
+     */
+    copy(xf: Transform2): Transform2;
+}
+/**
+ * @class Sweep
+ * @description The motion of a body's center of mass across one step, used by
+ * continuous collision detection to reconstruct where the body was at any
+ * fraction of the step.
+ */
+export class Sweep {
+    /** Local center of mass */
+    localCenter: Vec2;
+    /** World center at the start of the step */
+    c0: Vec2;
+    /** World center now */
+    c: Vec2;
+    /** Angle at the start of the step */
+    a0: number;
+    /** Angle now */
+    a: number;
+    /** Fraction of the step `c0`/`a0` correspond to (0..1) */
+    alpha0: number;
+    /**
+     * @method getTransform
+     * @description Writes the body transform at fraction `beta` of the sweep into
+     * `xf`. beta 0 is the start of the (remaining) sweep, 1 is the end.
+     * @param {Transform2} xf - Output transform
+     * @param {number} beta - Interpolation fraction
+     * @returns {Transform2} - xf
+     */
+    getTransform(xf: Transform2, beta: number): Transform2;
+    /**
+     * @method advance
+     * @description Moves the start of the sweep forward to fraction `alpha` of
+     * the original span, so later TOI queries only consider the remaining motion.
+     * @param {number} alpha - Absolute fraction of the original sweep
+     */
+    advance(alpha: number): void;
+    /**
+     * @method normalize
+     * @description Keeps the sweep angles near zero so long-lived spinning bodies
+     * don't lose float precision.
+     */
+    normalize(): void;
+}
+/**
+ * @function clamp
+ * @description Clamps a number to [min, max].
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ * @private
+ */
+export function clamp(value: number, min: number, max: number): number;
+export const EPSILON: 1.1920929e-7;

package/dist/types/src/physics/RevoluteJoint.d.ts

@@ -0,0 +1,119 @@
+export default RevoluteJoint;
+/**
+ * @class RevoluteJoint
+ * @extends Joint
+ * @description Pins two bodies together at a shared point while leaving
+ * rotation free, like a door hinge or a pendulum arm. Optionally driven by a
+ * motor that spins the joint toward a target angular speed, up to a torque
+ * limit; set `enableMotor` for a turntable, a windmill blade, or a wheel.
+ * @param {Object} def - `{ bodyA, bodyB, localAnchorA, localAnchorB,
+ *   enableMotor, motorSpeed, maxMotorTorque, collideConnected, userData }`
+ */
+declare class RevoluteJoint extends Joint {
+    localAnchorA: Vec2;
+    localAnchorB: Vec2;
+    referenceAngle: any;
+    enableMotor: boolean;
+    motorSpeed: any;
+    maxMotorTorque: any;
+    impulse: Vec2;
+    motorImpulse: number;
+    axialMass: number;
+    motorMass: number;
+    K: {
+        k11: number;
+        k12: number;
+        k22: number;
+    };
+    rA: Vec2;
+    rB: Vec2;
+    /** @private */
+    private indexA;
+    /** @private */
+    private indexB;
+    /**
+     * @method getAnchorA
+     * @returns {Vec2}
+     */
+    getAnchorA(): Vec2;
+    /**
+     * @method getAnchorB
+     * @returns {Vec2}
+     */
+    getAnchorB(): Vec2;
+    /**
+     * @method getReactionForce
+     * @param {number} invDt
+     * @returns {Vec2}
+     */
+    getReactionForce(invDt: number): Vec2;
+    /**
+     * @method getReactionTorque
+     * @param {number} invDt
+     * @returns {number}
+     */
+    getReactionTorque(invDt: number): number;
+    /**
+     * @method getJointAngle
+     * @description Current angle of body B relative to body A, minus the angle
+     * they started at.
+     * @returns {number}
+     */
+    getJointAngle(): number;
+    /**
+     * @method setMotorSpeed
+     * @param {number} speed
+     */
+    setMotorSpeed(speed: number): void;
+    /**
+     * @method getMotorSpeed
+     * @returns {number}
+     */
+    getMotorSpeed(): number;
+    /**
+     * @method setMaxMotorTorque
+     * @param {number} torque
+     */
+    setMaxMotorTorque(torque: number): void;
+    /**
+     * @method setEnableMotor
+     * @param {boolean} flag
+     */
+    setEnableMotor(flag: boolean): void;
+    /**
+     * @method isMotorEnabled
+     * @returns {boolean}
+     */
+    isMotorEnabled(): boolean;
+    /**
+     * @method getMotorTorque
+     * @param {number} invDt
+     * @returns {number}
+     */
+    getMotorTorque(invDt: number): number;
+    /**
+     * @method initVelocityConstraints
+     * @param {Object} step - `{ dt, warmStarting }`
+     * @param {Array<Object>} positions
+     * @param {Array<Object>} velocities
+     */
+    initVelocityConstraints(step: any, positions: Array<any>, velocities: Array<any>): void;
+    invMassA: any;
+    invMassB: any;
+    invIA: any;
+    invIB: any;
+    /**
+     * @method solveVelocityConstraints
+     * @param {Object} step - `{ dt }`
+     * @param {Array<Object>} velocities
+     */
+    solveVelocityConstraints(step: any, velocities: Array<any>): void;
+    /**
+     * @method solvePositionConstraints
+     * @param {Array<Object>} positions
+     * @returns {boolean}
+     */
+    solvePositionConstraints(positions: Array<any>): boolean;
+}
+import { Joint } from "./Joint.js";
+import { Vec2 } from "./Math2D.js";

package/dist/types/src/physics/Settings.d.ts

@@ -0,0 +1,22 @@
+export default Settings;
+declare namespace Settings {
+    let linearSlop: number;
+    let angularSlop: number;
+    let polygonRadius: number;
+    let maxLinearCorrection: number;
+    let maxAngularCorrection: number;
+    let maxTranslation: number;
+    let maxRotation: number;
+    let baumgarte: number;
+    let toiBaumgarte: number;
+    let velocityThreshold: number;
+    let timeToSleep: number;
+    let linearSleepTolerance: number;
+    let angularSleepTolerance: number;
+    let aabbExtension: number;
+    let aabbMultiplier: number;
+    let velocityIterations: number;
+    let positionIterations: number;
+    let maxTOIIterations: number;
+    let maxTOIPasses: number;
+}

package/dist/types/src/physics/Shapes.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @class Shape
+ * @description Base class for collision shapes. A shape is pure geometry in a
+ * body's local frame: it carries no position of its own and can be shared
+ * between fixtures.
+ */
+export class Shape {
+    constructor(type: any, radius: any);
+    type: any;
+    radius: any;
+    /**
+     * @method getType
+     * @description Returns the shape type ("circle" or "polygon").
+     * @returns {string}
+     */
+    getType(): string;
+    /**
+     * @method getRadius
+     * @description Returns the shape's skin radius.
+     * @returns {number}
+     */
+    getRadius(): number;
+}
+export type ShapeType = ShapeType;
+export namespace ShapeType {
+    let CIRCLE: string;
+    let POLYGON: string;
+}
+/**
+ * @class CircleShape
+ * @extends Shape
+ * @description A circle, optionally offset from the body origin.
+ * @param {number} [radius=0] - Radius in physics units
+ * @param {Object} [center] - Local center `{ x, y }`, defaults to the origin
+ */
+export class CircleShape extends Shape {
+    constructor(radius?: number, center?: any);
+    p: Vec2;
+    /**
+     * @method getVertexCount
+     * @description A circle is a single-point proxy plus a radius.
+     * @returns {number}
+     */
+    getVertexCount(): number;
+    /**
+     * @method getVertex
+     * @description Returns the circle's local center (its only support point).
+     * @returns {Vec2}
+     */
+    getVertex(): Vec2;
+    /**
+     * @method getSupport
+     * @description Index of the vertex furthest along a direction (always 0).
+     * @returns {number}
+     */
+    getSupport(): number;
+    /**
+     * @method computeAABB
+     * @description Writes this shape's world AABB under a transform.
+     * @param {AABB} aabb - Output box
+     * @param {Transform2} xf - The owning body's transform
+     */
+    computeAABB(aabb: AABB, xf: Transform2): void;
+    /**
+     * @method computeMass
+     * @description Writes mass, center and rotational inertia for a density.
+     * @param {Object} massData - Output `{ mass, center, I }`
+     * @param {number} density
+     */
+    computeMass(massData: any, density: number): void;
+    /**
+     * @method testPoint
+     * @description True when a world point is inside the circle.
+     * @param {Transform2} xf
+     * @param {Object} p - World point
+     * @returns {boolean}
+     */
+    testPoint(xf: Transform2, p: any): boolean;
+    /**
+     * @method rayCast
+     * @description Casts a ray against the circle.
+     * @param {Object} output - Written as `{ fraction, normal }` on a hit
+     * @param {Object} input - `{ p1, p2, maxFraction }` in world space
+     * @param {Transform2} xf
+     * @returns {boolean} - Whether the ray hit
+     */
+    rayCast(output: any, input: any, xf: Transform2): boolean;
+}
+/**
+ * @class PolygonShape
+ * @extends Shape
+ * @description A convex polygon with up to `MAX_VERTICES` corners, wound
+ * counter-clockwise. Boxes, by far the common case, come from
+ * {@link PolygonShape.box}.
+ * @param {Array<Object>} [points] - Optional points to build a convex hull from
+ */
+export class PolygonShape extends Shape {
+    /**
+     * @method box
+     * @description Builds an axis-aligned box from half-extents, optionally
+     * offset and rotated in the body's local frame.
+     * @param {number} hx - Half width
+     * @param {number} hy - Half height
+     * @param {Object} [center] - Local center `{ x, y }`
+     * @param {number} [angle=0] - Local rotation in radians
+     * @returns {PolygonShape}
+     */
+    static box(hx: number, hy: number, center?: any, angle?: number): PolygonShape;
+    constructor(points?: any);
+    vertices: any[];
+    normals: any[];
+    centroid: Vec2;
+    /**
+     * @method setAsBox
+     * @description Turns this polygon into a box in place.
+     * @param {number} hx - Half width
+     * @param {number} hy - Half height
+     * @param {Object} [center] - Local center `{ x, y }`
+     * @param {number} [angle=0] - Local rotation in radians
+     * @returns {PolygonShape} - this
+     */
+    setAsBox(hx: number, hy: number, center?: any, angle?: number): PolygonShape;
+    /**
+     * @method set
+     * @description Builds the convex hull of a point cloud. Points inside the
+     * hull are dropped, so callers can pass a rough outline.
+     * @param {Array<Object>} points - `{ x, y }` points
+     * @returns {PolygonShape} - this
+     */
+    set(points: Array<any>): PolygonShape;
+    /**
+     * @method getVertexCount
+     * @description Number of corners.
+     * @returns {number}
+     */
+    getVertexCount(): number;
+    /**
+     * @method getVertex
+     * @description Returns a corner by index.
+     * @param {number} index
+     * @returns {Vec2}
+     */
+    getVertex(index: number): Vec2;
+    /**
+     * @method getSupport
+     * @description Index of the vertex furthest along a local direction: the
+     * support function GJK is built on.
+     * @param {Object} d - Local direction
+     * @returns {number}
+     */
+    getSupport(d: any): number;
+    /**
+     * @method computeAABB
+     * @description Writes this shape's world AABB under a transform.
+     * @param {AABB} aabb - Output box
+     * @param {Transform2} xf
+     */
+    computeAABB(aabb: AABB, xf: Transform2): void;
+    /**
+     * @method computeMass
+     * @description Writes mass, center and rotational inertia for a density by
+     * summing the triangle fan of the polygon.
+     * @param {Object} massData - Output `{ mass, center, I }`
+     * @param {number} density
+     */
+    computeMass(massData: any, density: number): void;
+    /**
+     * @method testPoint
+     * @description True when a world point is inside the polygon.
+     * @param {Transform2} xf
+     * @param {Object} p - World point
+     * @returns {boolean}
+     */
+    testPoint(xf: Transform2, p: any): boolean;
+    /**
+     * @method rayCast
+     * @description Casts a ray against the polygon by clipping it against every
+     * edge plane and keeping the surviving interval.
+     * @param {Object} output - Written as `{ fraction, normal }` on a hit
+     * @param {Object} input - `{ p1, p2, maxFraction }` in world space
+     * @param {Transform2} xf
+     * @returns {boolean}
+     */
+    rayCast(output: any, input: any, xf: Transform2): boolean;
+}
+/**
+ * @function Box
+ * @description Convenience factory for a box polygon.
+ * @param {number} hx - Half width in physics units
+ * @param {number} hy - Half height in physics units
+ * @param {Object} [center] - Local center `{ x, y }`
+ * @param {number} [angle=0] - Local rotation in radians
+ * @returns {PolygonShape}
+ */
+export function Box(hx: number, hy: number, center?: any, angle?: number): PolygonShape;
+/**
+ * @function Circle
+ * @description Convenience factory for a circle shape.
+ * @param {number} radius - Radius in physics units
+ * @param {Object} [center] - Local center `{ x, y }`
+ * @returns {CircleShape}
+ */
+export function Circle(radius: number, center?: any): CircleShape;
+import AABB from "./AABB.js";
+import { Vec2 } from "./Math2D.js";
+import { Transform2 } from "./Math2D.js";
+export { AABB };