emeraldengine 3.0.0 → 3.1.0

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

@@ -0,0 +1,6 @@
+export type BodyType = BodyType;
+export namespace BodyType {
+    let STATIC: string;
+    let KINEMATIC: string;
+    let DYNAMIC: string;
+}

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

@@ -0,0 +1,210 @@
+/**
+ * @class BroadPhase
+ * @description Keeps the AABB tree and the list of proxies that moved since the
+ * last step, and turns those into the candidate pairs the narrowphase looks at.
+ */
+export class BroadPhase {
+    /** @private */
+    private tree;
+    /** @private */
+    private moveBuffer;
+    /** @private */
+    private proxyCount;
+    /**
+     * @method createProxy
+     * @description Adds a fixture proxy and queues it for pairing.
+     * @param {AABB} aabb
+     * @param {Object} userData
+     * @returns {number} - Proxy id
+     */
+    createProxy(aabb: AABB, userData: any): number;
+    /**
+     * @method destroyProxy
+     * @description Removes a fixture proxy.
+     * @param {number} id
+     */
+    destroyProxy(id: number): void;
+    /**
+     * @method moveProxy
+     * @description Updates a proxy's box, queueing it for re-pairing if the tree
+     * actually had to move it.
+     * @param {number} id
+     * @param {AABB} aabb
+     * @param {Object} displacement
+     */
+    moveProxy(id: number, aabb: AABB, displacement: any): void;
+    /**
+     * @method touchProxy
+     * @description Forces a proxy to be re-paired next update even though it
+     * didn't move (used when a fixture's filter changes).
+     * @param {number} id
+     */
+    touchProxy(id: number): void;
+    /** @private */
+    private bufferMove;
+    /** @private */
+    private unbufferMove;
+    /**
+     * @method getFatAABB
+     * @description Returns a proxy's fattened AABB.
+     * @param {number} id
+     * @returns {AABB}
+     */
+    getFatAABB(id: number): AABB;
+    /**
+     * @method getUserData
+     * @description Returns a proxy's payload.
+     * @param {number} id
+     * @returns {Object}
+     */
+    getUserData(id: number): any;
+    /**
+     * @method testOverlap
+     * @description True when two proxies' fat AABBs overlap.
+     * @param {number} idA
+     * @param {number} idB
+     * @returns {boolean}
+     */
+    testOverlap(idA: number, idB: number): boolean;
+    /**
+     * @method query
+     * @description Forwards an AABB query to the tree.
+     * @param {AABB} aabb
+     * @param {Function} callback
+     */
+    query(aabb: AABB, callback: Function): void;
+    /**
+     * @method rayCast
+     * @description Forwards a ray cast to the tree.
+     * @param {Object} input
+     * @param {Function} callback
+     */
+    rayCast(input: any, callback: Function): void;
+    /**
+     * @method updatePairs
+     * @description Emits `callback(userDataA, userDataB)` once for every new
+     * overlapping pair among the proxies that moved. Pairs are de-duplicated, so
+     * two proxies moving towards each other still report once.
+     * @param {Function} callback
+     */
+    updatePairs(callback: Function): void;
+}
+/**
+ * @class DynamicTree
+ * @description A balanced tree of axis-aligned boxes over every fixture in the
+ * world. Leaves are stored with a "fat" AABB so a body can jiggle a little
+ * without forcing a re-insert, and the tree is rebalanced with rotations on the
+ * way back up after each change. Every broadphase query, world raycast and
+ * continuous-collision sweep goes through it.
+ */
+export class DynamicTree {
+    /** @private */
+    private root;
+    /** @private */
+    private nodes;
+    /** @private */
+    private freeList;
+    /** @private */
+    private nodeCount;
+    /**
+     * @method allocateNode
+     * @description Takes a node from the free list, growing the pool if needed.
+     * @returns {number} - The node id
+     * @private
+     */
+    private allocateNode;
+    /**
+     * @method freeNode
+     * @description Returns a node to the free list.
+     * @param {number} id
+     * @private
+     */
+    private freeNode;
+    /**
+     * @method createProxy
+     * @description Adds a fixture proxy to the tree.
+     * @param {AABB} aabb - The tight world AABB
+     * @param {Object} userData - The FixtureProxy this leaf stands for
+     * @returns {number} - The proxy id
+     */
+    createProxy(aabb: AABB, userData: any): number;
+    /**
+     * @method destroyProxy
+     * @description Removes a proxy from the tree.
+     * @param {number} id
+     */
+    destroyProxy(id: number): void;
+    /**
+     * @method moveProxy
+     * @description Re-fits a proxy whose fixture moved. Returns false (and does
+     * nothing) while the new box still fits inside the fat one.
+     * @param {number} id
+     * @param {AABB} aabb - The new tight AABB
+     * @param {Object} displacement - How far the body moved this step
+     * @returns {boolean} - Whether the proxy was actually re-inserted
+     */
+    moveProxy(id: number, aabb: AABB, displacement: any): boolean;
+    /**
+     * @method getFatAABB
+     * @description Returns the stored (fattened) AABB of a proxy.
+     * @param {number} id
+     * @returns {AABB}
+     */
+    getFatAABB(id: number): AABB;
+    /**
+     * @method getUserData
+     * @description Returns the proxy payload of a leaf.
+     * @param {number} id
+     * @returns {Object}
+     */
+    getUserData(id: number): any;
+    /**
+     * @method insertLeaf
+     * @description Inserts a leaf, choosing the sibling that grows the tree's
+     * total surface area least, then rebalancing on the way back to the root.
+     * @param {number} leaf
+     * @private
+     */
+    private insertLeaf;
+    /**
+     * @method removeLeaf
+     * @description Unlinks a leaf and collapses its now-single-child parent.
+     * @param {number} leaf
+     * @private
+     */
+    private removeLeaf;
+    /**
+     * @method balance
+     * @description One AVL-style rotation at `iA` if its subtrees differ in
+     * height by more than one. Keeps queries logarithmic.
+     * @param {number} iA
+     * @returns {number} - The new root of that subtree
+     * @private
+     */
+    private balance;
+    /**
+     * @method query
+     * @description Calls `callback(proxyId)` for every leaf whose fat AABB
+     * overlaps `aabb`. Returning false from the callback stops the query.
+     * @param {AABB} aabb
+     * @param {Function} callback
+     */
+    query(aabb: AABB, callback: Function): void;
+    /**
+     * @method rayCast
+     * @description Walks the tree along a ray, calling
+     * `callback(subInput, proxyId)`. The callback returns the new max fraction
+     * (0 terminates the cast), which lets the traversal shrink as it finds hits.
+     * @param {Object} input - `{ p1, p2, maxFraction }`
+     * @param {Function} callback
+     */
+    rayCast(input: any, callback: Function): void;
+    /**
+     * @method getHeight
+     * @description Height of the tree (0 when empty), useful when profiling.
+     * @returns {number}
+     */
+    getHeight(): number;
+}
+export const NULL_NODE: -1;
+import AABB from "./AABB.js";

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";