emeraldengine 2.2.1 → 3.1.0

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

@@ -0,0 +1,102 @@
+/**
+ * @class Manifold
+ * @description Up to two contact points plus the frame they are expressed in.
+ * Two points is all a 2D convex-convex overlap can produce, and it is exactly
+ * what a stable resting contact (a box on the ground) needs.
+ */
+export class Manifold {
+    type: number;
+    localNormal: Vec2;
+    localPoint: Vec2;
+    points: ManifoldPoint[];
+    pointCount: number;
+    /**
+     * @method reset
+     * @description Empties the manifold.
+     */
+    reset(): void;
+}
+/**
+ * @class ManifoldPoint
+ * @description A single contact point, stored in the reference body's local
+ * frame so it stays valid as the bodies move within a step.
+ */
+export class ManifoldPoint {
+    localPoint: Vec2;
+    normalImpulse: number;
+    tangentImpulse: number;
+    id: number;
+}
+export type ManifoldType = ManifoldType;
+export namespace ManifoldType {
+    let CIRCLES: number;
+    let FACE_A: number;
+    let FACE_B: number;
+}
+/**
+ * @class WorldManifold
+ * @description A manifold converted into world space: the collision normal
+ * (always pointing from body A to body B), the contact points, and how deeply
+ * each one is penetrating (negative means overlapping).
+ */
+export class WorldManifold {
+    normal: Vec2;
+    points: Vec2[];
+    separations: number[];
+    pointCount: number;
+    /**
+     * @method initialize
+     * @description Fills this world manifold from a local manifold.
+     * @param {Manifold} manifold
+     * @param {Transform2} xfA
+     * @param {number} radiusA
+     * @param {Transform2} xfB
+     * @param {number} radiusB
+     * @returns {WorldManifold} - this
+     */
+    initialize(manifold: Manifold, xfA: Transform2, radiusA: number, xfB: Transform2, radiusB: number): WorldManifold;
+}
+/**
+ * @function collideCircles
+ * @description Builds the manifold for two circles.
+ * @param {Manifold} manifold - Output manifold
+ * @param {CircleShape} circleA
+ * @param {Transform2} xfA
+ * @param {CircleShape} circleB
+ * @param {Transform2} xfB
+ */
+export function collideCircles(manifold: Manifold, circleA: CircleShape, xfA: Transform2, circleB: CircleShape, xfB: Transform2): void;
+/**
+ * @function collidePolygonAndCircle
+ * @description Builds the manifold for a polygon against a circle. The circle
+ * is pushed into the polygon's frame, then tested against the closest face,
+ * falling back to the nearest corner when it sits past the face's edge.
+ * @param {Manifold} manifold - Output manifold
+ * @param {PolygonShape} polygonA
+ * @param {Transform2} xfA
+ * @param {CircleShape} circleB
+ * @param {Transform2} xfB
+ */
+export function collidePolygonAndCircle(manifold: Manifold, polygonA: PolygonShape, xfA: Transform2, circleB: CircleShape, xfB: Transform2): void;
+/**
+ * @function collidePolygons
+ * @description Builds the manifold for two convex polygons using the
+ * separating-axis test to pick a reference face, then clipping the opposing
+ * (incident) edge against it. The result is the one- or two-point contact patch
+ * that makes boxes rest flat instead of rocking.
+ * @param {Manifold} manifold - Output manifold
+ * @param {PolygonShape} polyA
+ * @param {Transform2} xfA
+ * @param {PolygonShape} polyB
+ * @param {Transform2} xfB
+ */
+export function collidePolygons(manifold: Manifold, polyA: PolygonShape, xfA: Transform2, polyB: PolygonShape, xfB: Transform2): void;
+/**
+ * @function mulTXf
+ * @description Composes transforms: returns the transform of `B` expressed in
+ * `A`'s frame.
+ * @private
+ */
+export function mulTXf(A: any, B: any): Transform2;
+import { Vec2 } from "./Math2D.js";
+import { Transform2 } from "./Math2D.js";

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

@@ -0,0 +1,206 @@
+/**
+ * @class Contact
+ * @description A potential or actual touch between two fixtures. The broadphase
+ * creates one as soon as two AABBs overlap; `touching` only becomes true once
+ * the narrowphase finds real contact points. Contacts persist across steps,
+ * which is what lets the solver warm-start from last frame's impulses.
+ */
+export class Contact {
+    /**
+     * @method create
+     * @description Builds a contact for a fixture pair, normalizing the order so
+     * mixed polygon/circle pairs always arrive as (polygon, circle): the one
+     * ordering the narrowphase implements.
+     * @param {Fixture} fixtureA
+     * @param {Fixture} fixtureB
+     * @returns {Contact}
+     */
+    static create(fixtureA: Fixture, fixtureB: Fixture): Contact;
+    constructor(fixtureA: any, fixtureB: any);
+    fixtureA: any;
+    fixtureB: any;
+    manifold: Manifold;
+    friction: number;
+    restitution: any;
+    tangentSpeed: number;
+    /** @private */
+    private touching;
+    /** @private */
+    private enabled;
+    /** @private */
+    private filterFlag;
+    /** @private */
+    private islandFlag;
+    /** @private */
+    private toiFlag;
+    /** @private */
+    private toi;
+    /** @private */
+    private _index;
+    /**
+     * @method getManifold
+     * @description Returns the local-space manifold.
+     * @returns {Manifold}
+     */
+    getManifold(): Manifold;
+    /**
+     * @method getWorldManifold
+     * @description Returns the contact in world space: the normal (pointing from
+     * fixture A's body towards fixture B's), the contact points, and the
+     * separation at each point.
+     * @param {WorldManifold} [worldManifold] - Optional object to fill
+     * @returns {WorldManifold}
+     */
+    getWorldManifold(worldManifold?: WorldManifold): WorldManifold;
+    /**
+     * @method isTouching
+     * @description Whether the fixtures are actually in contact this step.
+     * @returns {boolean}
+     */
+    isTouching(): boolean;
+    /**
+     * @method setEnabled
+     * @description Enables or disables the collision response for this contact.
+     * Disabling only lasts for the current step (useful from a pre-solve
+     * callback to build one-way platforms).
+     * @param {boolean} value
+     */
+    setEnabled(value: boolean): void;
+    /**
+     * @method isEnabled
+     * @description Whether the collision response is enabled.
+     * @returns {boolean}
+     */
+    isEnabled(): boolean;
+    /**
+     * @method getFixtureA
+     * @description Returns the first fixture.
+     * @returns {Fixture}
+     */
+    getFixtureA(): Fixture;
+    /**
+     * @method getFixtureB
+     * @description Returns the second fixture.
+     * @returns {Fixture}
+     */
+    getFixtureB(): Fixture;
+    /**
+     * @method getFriction
+     * @description Returns the mixed friction used by the solver.
+     * @returns {number}
+     */
+    getFriction(): number;
+    /**
+     * @method setFriction
+     * @description Overrides the mixed friction for this contact.
+     * @param {number} friction
+     */
+    setFriction(friction: number): void;
+    /**
+     * @method resetFriction
+     * @description Restores the friction mixed from the two fixtures.
+     */
+    resetFriction(): void;
+    /**
+     * @method getRestitution
+     * @description Returns the mixed restitution used by the solver.
+     * @returns {number}
+     */
+    getRestitution(): number;
+    /**
+     * @method setRestitution
+     * @description Overrides the mixed restitution for this contact.
+     * @param {number} restitution
+     */
+    setRestitution(restitution: number): void;
+    /**
+     * @method resetRestitution
+     * @description Restores the restitution mixed from the two fixtures.
+     */
+    resetRestitution(): void;
+    /**
+     * @method flagForFiltering
+     * @description Marks the contact so the next step re-checks whether these two
+     * fixtures are still allowed to collide.
+     */
+    flagForFiltering(): void;
+    /**
+     * @method evaluate
+     * @description Runs the narrowphase for this fixture pair into `manifold`.
+     * @param {Manifold} manifold
+     * @param {Transform2} xfA
+     * @param {Transform2} xfB
+     * @private
+     */
+    private evaluate;
+    /**
+     * @method update
+     * @description Re-runs the narrowphase, carries last step's impulses over to
+     * matching contact points (warm starting), and fires begin/end contact
+     * events on the world when the touching state flips.
+     * @param {World} world - The owning world, used to dispatch events
+     */
+    update(world: World): void;
+}
+/**
+ * @class ContactManager
+ * @description Owns the world's contact list: creates contacts from broadphase
+ * pairs, drops them once the AABBs stop overlapping, and refreshes the ones
+ * that remain each step.
+ */
+export class ContactManager {
+    constructor(world: any);
+    world: any;
+    contacts: any[];
+    /**
+     * @method addPair
+     * @description Creates a contact for a new broadphase pair, unless the two
+     * fixtures share a body, already have a contact, or the filter rejects them.
+     * @param {FixtureProxy} proxyA
+     * @param {FixtureProxy} proxyB
+     */
+    addPair(proxyA: FixtureProxy, proxyB: FixtureProxy): void;
+    /**
+     * @method findNewContacts
+     * @description Turns this step's broadphase movement into new contacts.
+     */
+    findNewContacts(): void;
+    /**
+     * @method destroy
+     * @description Removes a contact, firing end-contact if it was touching.
+     * @param {Contact} contact
+     */
+    destroy(contact: Contact): void;
+    /**
+     * @method collide
+     * @description Refreshes every contact: drops the ones whose AABBs no longer
+     * overlap or whose filters changed, and re-runs the narrowphase on the rest.
+     */
+    collide(): void;
+}
+/**
+ * @function shouldCollide
+ * @description Applies the collision filter to a fixture pair. A positive
+ * shared group index always collides, a negative one never does; otherwise each
+ * fixture's category must appear in the other's mask.
+ * @param {Fixture} fixtureA
+ * @param {Fixture} fixtureB
+ * @returns {boolean}
+ */
+export function shouldCollide(fixtureA: Fixture, fixtureB: Fixture): boolean;
+/**
+ * @function mixFriction
+ * @description Combines two friction coefficients (geometric mean), so a slick
+ * body sliding on a rough one lands somewhere in between.
+ * @private
+ */
+export function mixFriction(a: any, b: any): number;
+/**
+ * @function mixRestitution
+ * @description Combines two restitutions: the bouncier surface wins, which is
+ * what players expect from a trampoline on concrete.
+ * @private
+ */
+export function mixRestitution(a: any, b: any): any;
+import { Manifold } from "./Collision.js";
+import { WorldManifold } from "./Collision.js";

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

@@ -0,0 +1,108 @@
+export default ContactSolver;
+/**
+ * @class ContactSolver
+ * @description Resolves every contact in an island with sequential impulses:
+ * for each contact point it works out the impulse that removes the approaching
+ * velocity (plus any bounce), applies it, and repeats over all points for a
+ * fixed number of iterations. Impulses are accumulated and clamped so they can
+ * only ever push, never pull, and they carry over between steps (warm starting)
+ * so stacks settle instead of sinking.
+ *
+ * Position error left over after the velocity pass is fixed separately, by
+ * nudging the bodies apart without injecting energy.
+ *
+ * @param {Object} def - `{ contacts, positions, velocities, dt, velocityThreshold }`
+ */
+declare class ContactSolver {
+    constructor(def: any);
+    positions: any;
+    velocities: any;
+    contacts: any;
+    dt: any;
+    velocityThreshold: any;
+    velocityConstraints: {
+        friction: any;
+        restitution: any;
+        tangentSpeed: any;
+        indexA: any;
+        indexB: any;
+        invMassA: any;
+        invMassB: any;
+        invIA: any;
+        invIB: any;
+        contactIndex: number;
+        pointCount: any;
+        normal: Vec2;
+        tangent: Vec2;
+        K: {
+            k11: number;
+            k12: number;
+            k22: number;
+        };
+        normalMass: {
+            k11: number;
+            k12: number;
+            k22: number;
+        };
+        points: any[];
+    }[];
+    positionConstraints: {
+        indexA: any;
+        indexB: any;
+        invMassA: any;
+        invMassB: any;
+        invIA: any;
+        invIB: any;
+        localCenterA: any;
+        localCenterB: any;
+        radiusA: any;
+        radiusB: any;
+        type: any;
+        localNormal: any;
+        localPoint: any;
+        localPoints: any[];
+        pointCount: any;
+    }[];
+    /**
+     * @method initializeVelocityConstraints
+     * @description Computes the effective mass at every contact point and the
+     * bounce target, from the state at the start of the step.
+     */
+    initializeVelocityConstraints(): void;
+    /**
+     * @method warmStart
+     * @description Re-applies last step's impulses before solving, which gets the
+     * solver most of the way to the answer immediately.
+     */
+    warmStart(): void;
+    /**
+     * @method solveVelocityConstraints
+     * @description One relaxation pass over every contact point: friction first,
+     * then the normal impulses that stop the bodies interpenetrating.
+     */
+    solveVelocityConstraints(): void;
+    /**
+     * @method _solveBlock
+     * @description Two-point block solve. Solving both points of a manifold
+     * together (rather than one after the other) is what keeps a box resting on
+     * the ground from rocking between its corners. Four candidate solutions are
+     * tried in turn: both points pushing, either one alone, or neither.
+     * @private
+     */
+    private _solveBlock;
+    /**
+     * @method storeImpulses
+     * @description Writes the accumulated impulses back onto the manifold so the
+     * next step can warm-start from them.
+     */
+    storeImpulses(): void;
+    /**
+     * @method solvePositionConstraints
+     * @description Pushes overlapping bodies apart geometrically. This runs on
+     * positions only, no velocity is added, so separating a deep overlap can't
+     * fling bodies across the level.
+     * @returns {boolean} - True once every overlap is within tolerance
+     */
+    solvePositionConstraints(): boolean;
+}
+import { Vec2 } from "./Math2D.js";

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

@@ -0,0 +1,54 @@
+/**
+ * @class DistanceProxy
+ * @description A convex shape reduced to what GJK needs: a point cloud plus a
+ * skin radius. Circles collapse to a single point with a large radius; polygons
+ * keep their corners and carry the small polygon skin.
+ */
+export class DistanceProxy {
+    vertices: any[];
+    radius: number;
+    /**
+     * @method set
+     * @description Fills this proxy from a shape.
+     * @param {Shape} shape - A CircleShape or PolygonShape
+     * @returns {DistanceProxy} - this
+     */
+    set(shape: Shape): DistanceProxy;
+    /**
+     * @method getSupport
+     * @description Index of the vertex furthest along a direction.
+     * @param {Object} d - Direction in the proxy's local frame
+     * @returns {number}
+     */
+    getSupport(d: any): number;
+    /**
+     * @method getMaxExtent
+     * @description Distance from the local origin to the furthest vertex, plus
+     * the skin. Continuous collision uses it to bound how fast a rotating body's
+     * surface can approach another.
+     * @returns {number}
+     */
+    getMaxExtent(): number;
+}
+/**
+ * @function distance
+ * @description GJK: computes the distance and the closest points between two
+ * convex proxies. This is the primitive continuous collision and overlap tests
+ * are built on.
+ * @param {Object} output - Written as `{ distance, pointA, pointB, iterations }`
+ * @param {Object} input - `{ proxyA, proxyB, transformA, transformB, useRadii }`
+ * @returns {Object} - The same output object
+ */
+export function distance(output: any, input: any): any;
+/**
+ * @function testOverlap
+ * @description True when two shapes overlap under their transforms. Sensors use
+ * this instead of building a manifold, since they never need contact points.
+ * @param {Shape} shapeA
+ * @param {Transform2} xfA
+ * @param {Shape} shapeB
+ * @param {Transform2} xfB
+ * @returns {boolean}
+ */
+export function testOverlap(shapeA: Shape, xfA: Transform2, shapeB: Shape, xfB: Transform2): boolean;
+import { Transform2 } from "./Math2D.js";

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

@@ -0,0 +1,90 @@
+export default DistanceJoint;
+/**
+ * @class DistanceJoint
+ * @extends Joint
+ * @description Holds two anchor points at a fixed distance apart, like a
+ * rigid rod. Passing `frequencyHz` turns it into a damped spring pulling the
+ * anchors toward that distance instead of holding it exactly, for tethers
+ * and camera rigs that should have some give.
+ * @param {Object} def - `{ bodyA, bodyB, localAnchorA, localAnchorB, length,
+ *   frequencyHz, dampingRatio, collideConnected, userData }`
+ */
+declare class DistanceJoint extends Joint {
+    localAnchorA: Vec2;
+    localAnchorB: Vec2;
+    length: any;
+    frequencyHz: any;
+    dampingRatio: any;
+    impulse: number;
+    gamma: number;
+    bias: number;
+    u: Vec2;
+    rA: Vec2;
+    rB: Vec2;
+    mass: number;
+    /** @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
+     * @returns {number}
+     */
+    getReactionTorque(): number;
+    /**
+     * @method setLength
+     * @param {number} length
+     */
+    setLength(length: number): void;
+    /**
+     * @method getLength
+     * @returns {number}
+     */
+    getLength(): number;
+    /**
+     * @method initVelocityConstraints
+     * @description Effective mass at the current anchor separation, plus (for
+     * a soft joint) the spring-damper bias for this step.
+     * @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 }` (unused here, kept for a uniform joint interface)
+     * @param {Array<Object>} velocities
+     */
+    solveVelocityConstraints(step: any, velocities: Array<any>): void;
+    /**
+     * @method solvePositionConstraints
+     * @description Skipped for a soft (spring) joint: the bias already pulled
+     * it toward rest length during the velocity pass, and correcting position
+     * on top of that would fight the spring.
+     * @param {Array<Object>} positions
+     * @returns {boolean}
+     */
+    solvePositionConstraints(positions: Array<any>): boolean;
+}
+import { Joint } from "./Joint.js";
+import { Vec2 } from "./Math2D.js";