emeraldengine 2.2.1 → 3.1.0

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

@@ -0,0 +1,221 @@
+/**
+ * @class Fixture
+ * @description A shape bound to a body, together with the material properties
+ * that decide how contacts behave: density (which feeds the body's mass),
+ * friction, restitution (bounciness), the sensor flag, and the collision
+ * filter. A body can carry any number of fixtures.
+ *
+ * Fixtures are created through {@link Body#createFixture}, never directly.
+ */
+export class Fixture {
+    constructor(body: any, shape: any, def?: {});
+    body: any;
+    shape: any;
+    density: any;
+    friction: any;
+    restitution: any;
+    sensor: boolean;
+    userData: any;
+    filter: {
+        categoryBits: any;
+        maskBits: any;
+        groupIndex: any;
+    };
+    /** @private */
+    private proxies;
+    /** @private */
+    private next;
+    /**
+     * @method getType
+     * @description Returns the underlying shape type ("circle" or "polygon").
+     * @returns {string}
+     */
+    getType(): string;
+    /**
+     * @method getShape
+     * @description Returns the fixture's shape.
+     * @returns {Shape}
+     */
+    getShape(): Shape;
+    /**
+     * @method getBody
+     * @description Returns the body this fixture is attached to.
+     * @returns {Body}
+     */
+    getBody(): Body;
+    /**
+     * @method getNext
+     * @description Returns the next fixture on the same body, or null.
+     * @returns {Fixture|null}
+     */
+    getNext(): Fixture | null;
+    /**
+     * @method setUserData
+     * @description Attaches arbitrary data to the fixture.
+     * @param {*} data
+     */
+    setUserData(data: any): void;
+    /**
+     * @method getUserData
+     * @description Returns the attached data.
+     * @returns {*}
+     */
+    getUserData(): any;
+    /**
+     * @method setSensor
+     * @description A sensor still reports contacts but never generates a
+     * collision response: the classic trigger volume.
+     * @param {boolean} value
+     */
+    setSensor(value: boolean): void;
+    /**
+     * @method isSensor
+     * @description Whether this fixture is a sensor.
+     * @returns {boolean}
+     */
+    isSensor(): boolean;
+    /**
+     * @method setFilterData
+     * @description Replaces the collision filter. Two fixtures collide only when
+     * each one's category bit appears in the other's mask (or they share a
+     * positive group index).
+     * @param {Object} filter - `{ categoryBits, maskBits, groupIndex }`
+     */
+    setFilterData(filter?: any): void;
+    /**
+     * @method getFilterData
+     * @description Returns the current collision filter.
+     * @returns {Object}
+     */
+    getFilterData(): any;
+    /**
+     * @method getFilterCategoryBits
+     * @description Returns the category bits.
+     * @returns {number}
+     */
+    getFilterCategoryBits(): number;
+    /**
+     * @method getFilterMaskBits
+     * @description Returns the mask bits.
+     * @returns {number}
+     */
+    getFilterMaskBits(): number;
+    /**
+     * @method getFilterGroupIndex
+     * @description Returns the group index.
+     * @returns {number}
+     */
+    getFilterGroupIndex(): number;
+    /**
+     * @method refilter
+     * @description Re-evaluates existing contacts after a filter change, so a
+     * fixture that just stopped colliding with a layer separates immediately
+     * instead of on its next move.
+     */
+    refilter(): void;
+    /**
+     * @method setDensity
+     * @description Sets the density. Call {@link Body#resetMassData} afterwards
+     * for it to take effect on the body's mass.
+     * @param {number} density
+     */
+    setDensity(density: number): void;
+    /**
+     * @method getDensity
+     * @description Returns the density.
+     * @returns {number}
+     */
+    getDensity(): number;
+    /**
+     * @method setFriction
+     * @description Sets the friction coefficient (0 = ice).
+     * @param {number} friction
+     */
+    setFriction(friction: number): void;
+    /**
+     * @method getFriction
+     * @description Returns the friction coefficient.
+     * @returns {number}
+     */
+    getFriction(): number;
+    /**
+     * @method setRestitution
+     * @description Sets the bounciness (0 = no bounce, 1 = perfectly elastic).
+     * @param {number} restitution
+     */
+    setRestitution(restitution: number): void;
+    /**
+     * @method getRestitution
+     * @description Returns the bounciness.
+     * @returns {number}
+     */
+    getRestitution(): number;
+    /**
+     * @method testPoint
+     * @description True when a world-space point is inside this fixture.
+     * @param {Object} p - `{ x, y }` in physics units
+     * @returns {boolean}
+     */
+    testPoint(p: any): boolean;
+    /**
+     * @method rayCast
+     * @description Casts a ray against this fixture's shape.
+     * @param {Object} output - Written as `{ fraction, normal }` on a hit
+     * @param {Object} input - `{ p1, p2, maxFraction }`
+     * @returns {boolean}
+     */
+    rayCast(output: any, input: any): boolean;
+    /**
+     * @method getMassData
+     * @description Computes this fixture's contribution to the body's mass.
+     * @param {Object} [massData]
+     * @returns {Object} - `{ mass, center, I }`
+     */
+    getMassData(massData?: any): any;
+    /**
+     * @method getAABB
+     * @description Returns the fixture's current world AABB.
+     * @param {number} [childIndex=0]
+     * @returns {AABB}
+     */
+    getAABB(childIndex?: number): AABB;
+    /**
+     * @method createProxies
+     * @description Registers this fixture with the broadphase.
+     * @param {BroadPhase} broadPhase
+     * @param {Transform2} xf
+     * @private
+     */
+    private createProxies;
+    /**
+     * @method destroyProxies
+     * @description Removes this fixture from the broadphase.
+     * @param {BroadPhase} broadPhase
+     * @private
+     */
+    private destroyProxies;
+    /**
+     * @method synchronize
+     * @description Re-fits the broadphase proxies after the body moved. The AABB
+     * spans both the old and the new transform so a fast body's proxy still
+     * covers the ground it swept over.
+     * @param {BroadPhase} broadPhase
+     * @param {Transform2} xf1
+     * @param {Transform2} xf2
+     * @private
+     */
+    private synchronize;
+}
+/**
+ * @class FixtureProxy
+ * @description The link between a fixture and its entry in the broadphase tree.
+ * @private
+ */
+export class FixtureProxy {
+    constructor(fixture: any, childIndex: any);
+    aabb: AABB;
+    fixture: any;
+    childIndex: any;
+    proxyId: number;
+}
+import AABB from "./AABB.js";

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

@@ -0,0 +1,52 @@
+export default Island;
+/**
+ * @class Island
+ * @description A connected group of bodies, everything reachable through
+ * touching contacts, solved together. Islands are what make sleeping work:
+ * a pile of crates only goes to sleep once *every* body in it has settled, so
+ * one crate still rolling keeps the whole pile simulated.
+ */
+declare class Island {
+    bodies: any[];
+    contacts: any[];
+    joints: any[];
+    /** @private */
+    private positions;
+    /** @private */
+    private velocities;
+    /**
+     * @method clear
+     * @description Empties the island for reuse on the next seed body.
+     */
+    clear(): void;
+    /**
+     * @method addBody
+     * @description Adds a body and records its index for the solver.
+     * @param {Body} body
+     */
+    addBody(body: Body): void;
+    /**
+     * @method addContact
+     * @description Adds a touching contact to be solved with this island.
+     * @param {Contact} contact
+     */
+    addContact(contact: Contact): void;
+    /**
+     * @method addJoint
+     * @description Adds a joint to be solved with this island.
+     * @param {Joint} joint
+     */
+    addJoint(joint: Joint): void;
+    /**
+     * @method solve
+     * @description Advances the island by one step: integrate velocities, solve
+     * contacts, integrate positions, fix leftover overlap, then decide whether
+     * the island can go to sleep.
+     * @param {Object} step - `{ dt, velocityIterations, positionIterations,
+     *   warmStarting, velocityThreshold }`
+     * @param {Vec2} gravity - World gravity in physics units
+     * @param {boolean} allowSleep - Whether sleeping is enabled world-wide
+     */
+    solve(step: any, gravity: Vec2, allowSleep: boolean): void;
+}
+import { Vec2 } from "./Math2D.js";

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

@@ -0,0 +1,59 @@
+/**
+ * @class Joint
+ * @description Base class for a constraint between two bodies. A joint is
+ * solved by the same island that solves contacts (see {@link Island}), right
+ * alongside them, so a body linked only by a joint (no touching fixtures)
+ * still wakes, sleeps and moves together with whatever it is jointed to.
+ *
+ * Concrete joints ({@link DistanceJoint}, {@link RevoluteJoint}) implement
+ * `initVelocityConstraints`, `solveVelocityConstraints` and
+ * `solvePositionConstraints`, matching {@link ContactSolver}'s per-step
+ * lifecycle.
+ * @param {Object} def - `{ type, bodyA, bodyB, collideConnected, userData }`
+ */
+export class Joint {
+    constructor(def: any);
+    type: any;
+    bodyA: any;
+    bodyB: any;
+    collideConnected: any;
+    userData: any;
+    /** @private */
+    private islandFlag;
+    /** @private */
+    private prev;
+    /** @private */
+    private next;
+    /**
+     * @method getType
+     * @returns {string}
+     */
+    getType(): string;
+    /**
+     * @method getBodyA
+     * @returns {Body}
+     */
+    getBodyA(): Body;
+    /**
+     * @method getBodyB
+     * @returns {Body}
+     */
+    getBodyB(): Body;
+    /**
+     * @method getUserData
+     * @returns {*}
+     */
+    getUserData(): any;
+    /**
+     * @method setUserData
+     * @param {*} data
+     */
+    setUserData(data: any): void;
+}
+/**
+ * @description Identifies a concrete {@link Joint} subclass.
+ */
+export const JointType: Readonly<{
+    DISTANCE: "distance";
+    REVOLUTE: "revolute";
+}>;

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;