emeraldengine 2.2.1 → 3.1.0

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

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

@@ -0,0 +1,22 @@
+/**
+ * @function timeOfImpact
+ * @description Finds the first fraction of a step at which two moving shapes
+ * touch, by conservative advancement: measure the gap, work out the fastest the
+ * shapes could possibly close it, and skip ahead by exactly that much time,
+ * never further. Repeating this converges on the impact without ever stepping
+ * past it, which is what stops a fast body from tunnelling through a wall.
+ *
+ * @param {Object} input - `{ proxyA, proxyB, sweepA, sweepB, tMax }`
+ * @returns {{state: string, t: number}} - The outcome and the impact fraction
+ */
+export function timeOfImpact(input: any): {
+    state: string;
+    t: number;
+};
+export type TOIState = TOIState;
+export namespace TOIState {
+    let SEPARATED: string;
+    let TOUCHING: string;
+    let OVERLAPPED: string;
+    let FAILED: string;
+}

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

@@ -0,0 +1,274 @@
+export default World;
+/**
+ * @class World
+ * @description The physics world: it owns the bodies, finds which ones touch,
+ * and advances them all by one time step. This is Emerald's own rigid-body
+ * engine: broadphase, narrowphase, an impulse solver and continuous collision
+ * detection, with no external physics dependency.
+ *
+ * Games normally reach it through {@link Physics}, which adds the pixel/meter
+ * conversion, a fixed-timestep accumulator and collision routing to
+ * {@link Behaviour} components.
+ *
+ * @param {Object} [def] - `{ gravity, allowSleep, warmStarting,
+ *   continuousPhysics, velocityThreshold, velocityIterations,
+ *   positionIterations }`
+ */
+declare class World {
+    constructor(def?: {});
+    gravity: Vec2;
+    broadPhase: BroadPhase;
+    contactManager: ContactManager;
+    /** Head of the body list; walk it with {@link Body#getNext}. @private */
+    private bodyList;
+    bodyCount: number;
+    /** Head of the joint list. @private */
+    private jointList;
+    jointCount: number;
+    allowSleep: boolean;
+    warmStarting: boolean;
+    continuousPhysics: boolean;
+    autoClearForces: boolean;
+    velocityThreshold: any;
+    velocityIterations: any;
+    positionIterations: any;
+    /** Optional `(fixtureA, fixtureB) => boolean` veto on new contacts. */
+    contactFilter: any;
+    /** @private */
+    private newContacts;
+    /** @private */
+    private locked;
+    /** @private */
+    private island;
+    /** @private */
+    private listeners;
+    /** @private */
+    private _toiProxyA;
+    /** @private */
+    private _toiProxyB;
+    /** What the last time-of-impact search hit. @private */
+    private _toiHitBody;
+    /**
+     * @method on
+     * @description Subscribes to a world event. Supported events:
+     * `begin-contact`, `end-contact`, `pre-solve`, `post-solve`, `remove-body`
+     * and `remove-fixture`.
+     * @param {string} name - Event name
+     * @param {Function} listener - Called with the contact (or body/fixture)
+     * @returns {World} - this
+     */
+    on(name: string, listener: Function): World;
+    /**
+     * @method off
+     * @description Unsubscribes a listener.
+     * @param {string} name
+     * @param {Function} listener
+     * @returns {World} - this
+     */
+    off(name: string, listener: Function): World;
+    /**
+     * @method dispatch
+     * @description Fires a world event. Listener errors are contained so one bad
+     * callback can't halt the simulation mid-step.
+     * @param {string} name
+     * @param {...*} args
+     */
+    dispatch(name: string, ...args: any[]): void;
+    /**
+     * @method createBody
+     * @description Creates a body in this world.
+     * @param {Object} [def] - See {@link Body}
+     * @returns {Body}
+     */
+    createBody(def?: any): Body;
+    /**
+     * @method destroyBody
+     * @description Removes a body, its fixtures and all its contacts.
+     * @param {Body} body
+     */
+    destroyBody(body: Body): void;
+    /**
+     * @method getBodyList
+     * @description Returns the first body; walk the rest with
+     * {@link Body#getNext}.
+     * @returns {Body|null}
+     */
+    getBodyList(): Body | null;
+    /**
+     * @method getBodyCount
+     * @description Number of bodies in the world.
+     * @returns {number}
+     */
+    getBodyCount(): number;
+    /**
+     * @method createJoint
+     * @description Creates a constraint between two bodies, a
+     * {@link DistanceJoint} or a {@link RevoluteJoint}, chosen by `def.type`
+     * (see {@link JointType}). Wakes both bodies, since a joint pulling on a
+     * sleeping body needs it simulating again immediately.
+     * @param {Object} def - `{ type, bodyA, bodyB, ... }`, forwarded to the
+     *   chosen joint's constructor
+     * @returns {Joint}
+     */
+    createJoint(def: any): Joint;
+    /**
+     * @method destroyJoint
+     * @description Removes a joint. Safe to call as part of destroying one of
+     * its bodies (see {@link World#destroyBody}).
+     * @param {Joint} joint
+     */
+    destroyJoint(joint: Joint): void;
+    /**
+     * @method getJointList
+     * @description Returns the first joint; walk the rest with `joint.next`.
+     * @returns {Joint|null}
+     */
+    getJointList(): Joint | null;
+    /**
+     * @method getJointCount
+     * @returns {number}
+     */
+    getJointCount(): number;
+    /**
+     * @method getContactList
+     * @description Returns every live contact (touching or merely close enough
+     * for their bounding boxes to overlap).
+     * @returns {Array<Contact>}
+     */
+    getContactList(): Array<Contact>;
+    /**
+     * @method getContactCount
+     * @description Number of live contacts.
+     * @returns {number}
+     */
+    getContactCount(): number;
+    /**
+     * @method setGravity
+     * @description Sets world gravity in physics units per second squared.
+     * @param {Object} gravity - `{ x, y }`
+     */
+    setGravity(gravity: any): void;
+    /**
+     * @method getGravity
+     * @description Returns world gravity.
+     * @returns {Vec2}
+     */
+    getGravity(): Vec2;
+    /**
+     * @method isLocked
+     * @description True while a step is in progress, when the body/fixture graph
+     * must not be modified.
+     * @returns {boolean}
+     */
+    isLocked(): boolean;
+    /**
+     * @method setAllowSleeping
+     * @description Enables or disables sleeping world-wide.
+     * @param {boolean} flag
+     */
+    setAllowSleeping(flag: boolean): void;
+    /**
+     * @method step
+     * @description Advances the simulation by `dt` seconds: refresh contacts,
+     * solve the islands, then sweep any continuous (bullet) bodies.
+     * @param {number} dt - Time step in seconds
+     * @param {number} [velocityIterations] - Solver velocity iterations
+     * @param {number} [positionIterations] - Solver position iterations
+     */
+    step(dt: number, velocityIterations?: number, positionIterations?: number): void;
+    /**
+     * @method solve
+     * @description Groups the awake bodies into islands of things that touch and
+     * solves each island on its own.
+     * @param {Object} step
+     * @private
+     */
+    private solve;
+    /**
+     * @method solveContinuous
+     * @description Sweeps every bullet body against the static and kinematic
+     * geometry it passed through this step, and rewinds it to the first impact.
+     * Without this, a body moving further than its own size in one step would
+     * simply appear on the far side of a thin wall.
+     * @private
+     */
+    private solveContinuous;
+    /**
+     * @method _absorbImpactVelocity
+     * @description Takes the excess approach speed out of a body that a rewind
+     * stopped short of a *moving* obstacle, leaving it travelling with whatever
+     * it landed on.
+     *
+     * The rewind puts the body where the two first touched, but the obstacle
+     * carries on to the end of the step, so the body is left hovering by up to
+     * one step of the obstacle's travel, too far apart for the discrete solver
+     * to see a contact next step. Keeping the body's original velocity as well
+     * means it arrives even faster the following step, is rewound again, and
+     * never lands: a rider on a descending platform would fall for ever without
+     * ever standing on it. Dropping the approach speed to the obstacle's own
+     * closes that gap within a step or two, which is where the discrete solver
+     * takes over and the two stay in contact.
+     *
+     * Static obstacles are left alone: they do not run away from the body, so
+     * the overlap the rewind aims for survives into the next step and the
+     * discrete solver already handles them.
+     *
+     * @param {Body} body - The body that was rewound
+     * @param {number} dx - How far it swept this step, before the rewind
+     * @param {number} dy
+     * @private
+     */
+    private _absorbImpactVelocity;
+    /**
+     * @method _findTimeOfImpact
+     * @description Earliest fraction of this step at which `body` first touches
+     * non-dynamic geometry, or null when it hits nothing. The body that was hit
+     * is left in `_toiHitBody`.
+     * @param {Body} body
+     * @returns {number|null}
+     * @private
+     */
+    private _findTimeOfImpact;
+    /**
+     * @method clearForces
+     * @description Zeroes the accumulated forces and torques on every body.
+     * Called automatically at the end of each step.
+     */
+    clearForces(): void;
+    /**
+     * @method rayCast
+     * @description Casts a ray from `p1` to `p2`, calling
+     * `callback(fixture, point, normal, fraction)` for every fixture hit.
+     *
+     * The callback controls what happens next, exactly like a filter: return the
+     * `fraction` to clip the ray there and keep looking for closer hits (the
+     * usual "closest hit" behaviour), `0` to stop immediately, `1` to keep the
+     * full ray and collect every hit, or `-1` to ignore this fixture entirely.
+     *
+     * @param {Object} p1 - Ray start `{ x, y }` in physics units
+     * @param {Object} p2 - Ray end `{ x, y }` in physics units
+     * @param {Function} callback
+     */
+    rayCast(p1: any, p2: any, callback: Function): void;
+    /**
+     * @method queryAABB
+     * @description Calls `callback(fixture)` for every fixture whose bounding box
+     * overlaps `aabb`. Returning false from the callback ends the query.
+     * @param {AABB} aabb
+     * @param {Function} callback
+     */
+    queryAABB(aabb: AABB, callback: Function): void;
+    /**
+     * @method queryPoint
+     * @description Calls `callback(fixture)` for every fixture containing a
+     * world-space point.
+     * @param {Object} point - `{ x, y }` in physics units
+     * @param {Function} callback
+     */
+    queryPoint(point: any, callback: Function): void;
+}
+import { Vec2 } from "./Math2D.js";
+import { BroadPhase } from "./BroadPhase.js";
+import { ContactManager } from "./Contact.js";
+import { Body } from "./Body.js";
+import AABB from "./AABB.js";

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

@@ -0,0 +1,34 @@
+import World from "./World.js";
+import { Body } from "./Body.js";
+import { BodyType } from "./Body.js";
+import { Fixture } from "./Fixture.js";
+import { Contact } from "./Contact.js";
+import { ContactManager } from "./Contact.js";
+import { shouldCollide } from "./Contact.js";
+import { Shape } from "./Shapes.js";
+import { ShapeType } from "./Shapes.js";
+import { CircleShape } from "./Shapes.js";
+import { PolygonShape } from "./Shapes.js";
+import { Box } from "./Shapes.js";
+import { Circle } from "./Shapes.js";
+import { Vec2 } from "./Math2D.js";
+import { Rot } from "./Math2D.js";
+import { Transform2 } from "./Math2D.js";
+import { Sweep } from "./Math2D.js";
+import AABB from "./AABB.js";
+import Settings from "./Settings.js";
+import { Manifold } from "./Collision.js";
+import { ManifoldType } from "./Collision.js";
+import { WorldManifold } from "./Collision.js";
+import { DistanceProxy } from "./Distance.js";
+import { distance } from "./Distance.js";
+import { testOverlap } from "./Distance.js";
+import { timeOfImpact } from "./TimeOfImpact.js";
+import { TOIState } from "./TimeOfImpact.js";
+import { BroadPhase } from "./BroadPhase.js";
+import { DynamicTree } from "./BroadPhase.js";
+import { Joint } from "./Joint.js";
+import { JointType } from "./Joint.js";
+import DistanceJoint from "./DistanceJoint.js";
+import RevoluteJoint from "./RevoluteJoint.js";
+export { World, Body, BodyType, Fixture, Contact, ContactManager, shouldCollide, Shape, ShapeType, CircleShape, PolygonShape, Box, Circle, Vec2, Rot, Transform2, Sweep, AABB, Settings, Manifold, ManifoldType, WorldManifold, DistanceProxy, distance, testOverlap, timeOfImpact, TOIState, BroadPhase, DynamicTree, Joint, JointType, DistanceJoint, RevoluteJoint };