emeraldengine 2.2.1 → 3.1.0

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

@@ -0,0 +1,435 @@
+/**
+ * @class Body
+ * @description A rigid body: a position, an orientation, and the velocity and
+ * mass that go with them. Collision geometry lives on its fixtures, added with
+ * {@link Body#createFixture}. Bodies are created through
+ * {@link World#createBody}, never with `new`.
+ *
+ * Everything here is in physics units (meters, radians, seconds). The engine's
+ * {@link RigidBody} component is the pixel-space wrapper around this class.
+ *
+ * @param {World} world - The owning world
+ * @param {Object} [def] - `{ type, position, angle, linearVelocity,
+ *   angularVelocity, linearDamping, angularDamping, fixedRotation, bullet,
+ *   allowSleep, awake, active, gravityScale, userData }`
+ */
+export class Body {
+    constructor(world: any, def?: {});
+    world: any;
+    type: any;
+    xf: Transform2;
+    sweep: Sweep;
+    linearVelocity: Vec2;
+    angularVelocity: any;
+    force: Vec2;
+    torque: number;
+    linearDamping: any;
+    angularDamping: any;
+    gravityScale: any;
+    mass: number;
+    invMass: number;
+    I: number;
+    invI: number;
+    fixedRotation: boolean;
+    bullet: boolean;
+    allowSleep: boolean;
+    awake: boolean;
+    active: boolean;
+    sleepTime: number;
+    userData: any;
+    /** Head of this body's fixture list. @private */
+    private fixtureList;
+    /** @private */
+    private fixtureCount;
+    /** Contacts this body currently takes part in. @private */
+    private contacts;
+    /** Joints this body currently takes part in. @private */
+    private joints;
+    /** @private */
+    private prev;
+    /** @private */
+    private next;
+    /** Scratch flag used while building solver islands. @private */
+    private islandFlag;
+    /** Index into the current island's body array. @private */
+    private islandIndex;
+    /**
+     * @method createFixture
+     * @description Attaches a shape to this body. The second argument may be a
+     * plain density number or a definition object.
+     * @param {Shape} shape - A CircleShape or PolygonShape
+     * @param {Object|number} [def] - `{ density, friction, restitution, isSensor,
+     *   filterCategoryBits, filterMaskBits, filterGroupIndex, userData }`
+     * @returns {Fixture} - The new fixture
+     */
+    createFixture(shape: Shape, def?: any | number): Fixture;
+    /**
+     * @method destroyFixture
+     * @description Removes a fixture and every contact it was part of.
+     * @param {Fixture} fixture
+     */
+    destroyFixture(fixture: Fixture): void;
+    /**
+     * @method getFixtureList
+     * @description Returns the first fixture; walk the rest with
+     * {@link Fixture#getNext}.
+     * @returns {Fixture|null}
+     */
+    getFixtureList(): Fixture | null;
+    /**
+     * @method getNext
+     * @description Returns the next body in the world's list.
+     * @returns {Body|null}
+     */
+    getNext(): Body | null;
+    /**
+     * @method setUserData
+     * @description Attaches arbitrary data to the body. The engine stores the
+     * owning {@link RigidBody} here so contacts can be traced back to game
+     * objects.
+     * @param {*} data
+     */
+    setUserData(data: any): void;
+    /**
+     * @method getUserData
+     * @description Returns the attached data.
+     * @returns {*}
+     */
+    getUserData(): any;
+    /**
+     * @method getWorld
+     * @description Returns the owning world.
+     * @returns {World}
+     */
+    getWorld(): World;
+    /**
+     * @method getType
+     * @description Returns "static", "kinematic" or "dynamic".
+     * @returns {string}
+     */
+    getType(): string;
+    /**
+     * @method setType
+     * @description Changes the body type at runtime, resetting velocities and
+     * re-deriving mass. Existing contacts are dropped so they rebuild against the
+     * new type.
+     * @param {string} type - "static", "kinematic" or "dynamic"
+     */
+    setType(type: string): void;
+    /**
+     * @method setTransform
+     * @description Teleports the body: sets position and angle directly, without
+     * any velocity implied by the move.
+     *
+     * A teleport wakes the body. Contacts are only re-evaluated for bodies that
+     * are awake, so a sleeping body dropped into a new spot would otherwise sit
+     * there without noticing what it now overlaps: respawning a player onto a
+     * pickup, for instance, would silently miss it.
+     *
+     * @param {Object} position - `{ x, y }` in physics units
+     * @param {number} angle - Radians
+     */
+    setTransform(position: any, angle: number): void;
+    /**
+     * @method setPosition
+     * @description Moves the body, keeping its angle.
+     * @param {Object} position - `{ x, y }` in physics units
+     */
+    setPosition(position: any): void;
+    /**
+     * @method setAngle
+     * @description Rotates the body, keeping its position.
+     * @param {number} angle - Radians
+     */
+    setAngle(angle: number): void;
+    /**
+     * @method getTransform
+     * @description Returns the body's transform (live reference).
+     * @returns {Transform2}
+     */
+    getTransform(): Transform2;
+    /**
+     * @method getPosition
+     * @description Returns the body origin in world space (live reference).
+     * @returns {Vec2}
+     */
+    getPosition(): Vec2;
+    /**
+     * @method getAngle
+     * @description Returns the body's angle in radians.
+     * @returns {number}
+     */
+    getAngle(): number;
+    /**
+     * @method getWorldCenter
+     * @description Returns the center of mass in world space.
+     * @returns {Vec2}
+     */
+    getWorldCenter(): Vec2;
+    /**
+     * @method getLocalCenter
+     * @description Returns the center of mass in the body's frame.
+     * @returns {Vec2}
+     */
+    getLocalCenter(): Vec2;
+    /**
+     * @method getWorldPoint
+     * @description Converts a local point to world space.
+     * @param {Object} localPoint
+     * @returns {Vec2}
+     */
+    getWorldPoint(localPoint: any): Vec2;
+    /**
+     * @method getLocalPoint
+     * @description Converts a world point to the body's frame.
+     * @param {Object} worldPoint
+     * @returns {Vec2}
+     */
+    getLocalPoint(worldPoint: any): Vec2;
+    /**
+     * @method getWorldVector
+     * @description Rotates a local direction into world space.
+     * @param {Object} localVector
+     * @returns {Vec2}
+     */
+    getWorldVector(localVector: any): Vec2;
+    /**
+     * @method getLocalVector
+     * @description Rotates a world direction into the body's frame.
+     * @param {Object} worldVector
+     * @returns {Vec2}
+     */
+    getLocalVector(worldVector: any): Vec2;
+    /**
+     * @method setLinearVelocity
+     * @description Sets the velocity of the center of mass.
+     * @param {Object} velocity - `{ x, y }` in physics units per second
+     */
+    setLinearVelocity(velocity: any): void;
+    /**
+     * @method getLinearVelocity
+     * @description Returns the velocity of the center of mass (live reference).
+     * @returns {Vec2}
+     */
+    getLinearVelocity(): Vec2;
+    /**
+     * @method getLinearVelocityFromWorldPoint
+     * @description Velocity of the material point of this body that currently
+     * coincides with a world point (linear plus the spin contribution).
+     * @param {Object} worldPoint
+     * @returns {Vec2}
+     */
+    getLinearVelocityFromWorldPoint(worldPoint: any): Vec2;
+    /**
+     * @method setAngularVelocity
+     * @description Sets the spin in radians per second.
+     * @param {number} omega
+     */
+    setAngularVelocity(omega: number): void;
+    /**
+     * @method getAngularVelocity
+     * @description Returns the spin in radians per second.
+     * @returns {number}
+     */
+    getAngularVelocity(): number;
+    /**
+     * @method applyForce
+     * @description Applies a force at a world point. Forces are cleared at the
+     * end of every step, so this belongs in your update loop.
+     * @param {Object} force
+     * @param {Object} [point] - Defaults to the center of mass
+     * @param {boolean} [wake=true]
+     */
+    applyForce(force: any, point?: any, wake?: boolean): void;
+    /**
+     * @method applyForceToCenter
+     * @description Applies a force at the center of mass (no torque).
+     * @param {Object} force
+     * @param {boolean} [wake=true]
+     */
+    applyForceToCenter(force: any, wake?: boolean): void;
+    /**
+     * @method applyTorque
+     * @description Applies a torque about the center of mass.
+     * @param {number} torque
+     * @param {boolean} [wake=true]
+     */
+    applyTorque(torque: number, wake?: boolean): void;
+    /**
+     * @method applyLinearImpulse
+     * @description Applies an instantaneous change in momentum at a world point.
+     * Unlike a force, an impulse takes effect immediately: this is what a jump
+     * or a knockback should use.
+     * @param {Object} impulse
+     * @param {Object} [point] - Defaults to the center of mass
+     * @param {boolean} [wake=true]
+     */
+    applyLinearImpulse(impulse: any, point?: any, wake?: boolean): void;
+    /**
+     * @method applyAngularImpulse
+     * @description Applies an instantaneous change in angular momentum.
+     * @param {number} impulse
+     * @param {boolean} [wake=true]
+     */
+    applyAngularImpulse(impulse: number, wake?: boolean): void;
+    /**
+     * @method getMass
+     * @description Returns the body's mass.
+     * @returns {number}
+     */
+    getMass(): number;
+    /**
+     * @method getInertia
+     * @description Returns the rotational inertia about the center of mass.
+     * @returns {number}
+     */
+    getInertia(): number;
+    /**
+     * @method resetMassData
+     * @description Recomputes mass, center of mass and inertia from the
+     * fixtures' densities. Called automatically when fixtures change.
+     */
+    resetMassData(): void;
+    /**
+     * @method setMassData
+     * @description Overrides the computed mass properties.
+     * @param {Object} massData - `{ mass, center, I }`
+     */
+    setMassData(massData: any): void;
+    /**
+     * @method setAwake
+     * @description Wakes the body or puts it to sleep. A sleeping body is skipped
+     * by the solver until something touches it, which is what keeps a settled
+     * pile of crates free.
+     * @param {boolean} flag
+     */
+    setAwake(flag: boolean): void;
+    /**
+     * @method isAwake
+     * @description Whether the body is currently simulated.
+     * @returns {boolean}
+     */
+    isAwake(): boolean;
+    /**
+     * @method setSleepingAllowed
+     * @description Allows or forbids this body from ever sleeping.
+     * @param {boolean} flag
+     */
+    setSleepingAllowed(flag: boolean): void;
+    /**
+     * @method isSleepingAllowed
+     * @description Whether this body may sleep.
+     * @returns {boolean}
+     */
+    isSleepingAllowed(): boolean;
+    /**
+     * @method setActive
+     * @description Adds or removes the body from collision detection without
+     * destroying it.
+     * @param {boolean} flag
+     */
+    setActive(flag: boolean): void;
+    /**
+     * @method isActive
+     * @description Whether the body takes part in collision detection.
+     * @returns {boolean}
+     */
+    isActive(): boolean;
+    /**
+     * @method setFixedRotation
+     * @description Locks or unlocks the body's rotation. Locking is the usual
+     * choice for player characters, which should never topple over.
+     * @param {boolean} flag
+     */
+    setFixedRotation(flag: boolean): void;
+    /**
+     * @method isFixedRotation
+     * @description Whether rotation is locked.
+     * @returns {boolean}
+     */
+    isFixedRotation(): boolean;
+    /**
+     * @method setBullet
+     * @description Turns continuous collision detection on for this body, so it
+     * is swept against static geometry instead of teleporting between steps.
+     * @param {boolean} flag
+     */
+    setBullet(flag: boolean): void;
+    /**
+     * @method isBullet
+     * @description Whether continuous collision detection is enabled.
+     * @returns {boolean}
+     */
+    isBullet(): boolean;
+    /**
+     * @method setLinearDamping
+     * @description Sets the drag applied to linear motion each step.
+     * @param {number} damping
+     */
+    setLinearDamping(damping: number): void;
+    /**
+     * @method getLinearDamping
+     * @description Returns the linear damping.
+     * @returns {number}
+     */
+    getLinearDamping(): number;
+    /**
+     * @method setAngularDamping
+     * @description Sets the drag applied to rotation each step.
+     * @param {number} damping
+     */
+    setAngularDamping(damping: number): void;
+    /**
+     * @method getAngularDamping
+     * @description Returns the angular damping.
+     * @returns {number}
+     */
+    getAngularDamping(): number;
+    /**
+     * @method setGravityScale
+     * @description Scales how strongly gravity pulls on this body (0 disables it,
+     * 2 makes it twice as heavy-feeling).
+     * @param {number} scale
+     */
+    setGravityScale(scale: number): void;
+    /**
+     * @method getGravityScale
+     * @description Returns the gravity multiplier.
+     * @returns {number}
+     */
+    getGravityScale(): number;
+    /**
+     * @method getContactList
+     * @description Returns the contacts this body is part of.
+     * @returns {Array<Contact>}
+     */
+    getContactList(): Array<Contact>;
+    /**
+     * @method synchronizeTransform
+     * @description Rebuilds the body transform from the sweep's current state.
+     * @private
+     */
+    private synchronizeTransform;
+    /**
+     * @method synchronizeFixtures
+     * @description Updates the broadphase proxies to span where the body was at
+     * the start of the step and where it is now.
+     * @param {Transform2} [xf1] - Optional explicit "before" transform
+     * @private
+     */
+    private synchronizeFixtures;
+    /**
+     * @method advance
+     * @description Moves the body to a fraction of its sweep, used by continuous
+     * collision detection when an impact is found mid-step.
+     * @param {number} alpha
+     * @private
+     */
+    private advance;
+}
+import { BodyType } from "./BodyType.js";
+import { Transform2 } from "./Math2D.js";
+import { Sweep } from "./Math2D.js";
+import { Vec2 } from "./Math2D.js";
+import { Fixture } from "./Fixture.js";
+export { BodyType };

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