diff --git a/types/matter.d.ts b/types/matter.d.ts index 464dc855c..2e4cadf58 100644 --- a/types/matter.d.ts +++ b/types/matter.d.ts @@ -2076,6 +2076,7 @@ declare namespace MatterJS { /** * Creates a new rigid body model with a trapezoid hull. + * The `slope` is parameterised as a fraction of `width` and must be < 1 to form a valid trapezoid. * The options parameter is an object that specifies any properties you wish to override the defaults. * See the properties section of the `Matter.Body` module for detailed information on what you can pass via the `options` object. * @method trapezoid @@ -2110,6 +2111,17 @@ declare namespace MatterJS { * @return {body} */ static fromVertices (x: number, y: number, vertexSets: Array>, options?: IBodyDefinition, flagInternal?: boolean, removeCollinear?: number, minimumArea?: number): BodyType; + + /** + * Takes an array of Body objects and flags all internal edges (coincident parts) based on the maxDistance + * value. The array is changed in-place and returned, so you can pass this function a `Body.parts` property. + * + * @method flagCoincidentParts + * @param {body[]} parts - The Body parts, or array of bodies, to flag. + * @param {number} [maxDistance=5] + * @return {body[]} The modified `parts` parameter. + */ + static flagCoincidentParts (parts: Array, maxDistance?: number): Array; } class BodiesFactory { @@ -2158,6 +2170,7 @@ declare namespace MatterJS { /** * Creates a new rigid body model with a trapezoid hull. + * The `slope` is parameterised as a fraction of `width` and must be < 1 to form a valid trapezoid. * The options parameter is an object that specifies any properties you wish to override the defaults. * See the properties section of the `Matter.Body` module for detailed information on what you can pass via the `options` object. * @method trapezoid @@ -2192,6 +2205,18 @@ declare namespace MatterJS { * @return {body} */ fromVertices (x: number, y: number, vertexSets: Array>, options?: IBodyDefinition, flagInternal?: boolean, removeCollinear?: number, minimumArea?: number): BodyType; + + /** + * Takes an array of Body objects and flags all internal edges (coincident parts) based on the maxDistance + * value. The array is changed in-place and returned, so you can pass this function a `Body.parts` property. + * + * @method flagCoincidentParts + * @param {body[]} parts - The Body parts, or array of bodies, to flag. + * @param {number} [maxDistance=5] + * @return {body[]} The modified `parts` parameter. + */ + flagCoincidentParts (parts: Array, maxDistance?: number): Array; + } /** @@ -2214,6 +2239,13 @@ declare namespace MatterJS { */ static applyForce (body: BodyType, position: Vector, force: Vector): void; + /** + * Updates properties `body.velocity`, `body.speed`, `body.angularVelocity` and `body.angularSpeed` which are normalised in relation to `Body._baseDelta`. + * @method updateVelocities + * @param {body} body + */ + static updateVelocities (body: BodyType): void; + /** * Creates a new rigid body model. The options parameter is an object that specifies any properties you wish to override the defaults. * All properties have default values, and many are pre-calculated automatically based on other properties. @@ -2229,8 +2261,9 @@ declare namespace MatterJS { * @method rotate * @param {body} body * @param {number} rotation + * @param {boolean} [updateVelocity] */ - static rotate (body: BodyType, rotation: number): void; + static rotate (body: BodyType, rotation: number, updateVelocity?: boolean): void; /** * Returns the next unique group index for which bodies will collide. @@ -2329,16 +2362,18 @@ declare namespace MatterJS { * @method setPosition * @param {body} body * @param {vector} position + * @param {boolean} updateVelocity */ - static setPosition (body: BodyType, position: Vector): void; + static setPosition (body: BodyType, position: Vector, updateVelocity: boolean): void; /** * Sets the angle of the body instantly. Angular velocity, position, force etc. are unchanged. * @method setAngle * @param {body} body * @param {number} angle + * @param {boolean} updateVelocity */ - static setAngle (body: BodyType, angle: number): void; + static setAngle (body: BodyType, angle: number, updateVelocity: boolean): void; /** * Sets the linear velocity of the body instantly. Position, angle, force etc. are unchanged. See also `Body.applyForce`. @@ -2379,19 +2414,59 @@ declare namespace MatterJS { * @method translate * @param {body} body * @param {vector} translation + * @param {boolean} [updateVelocity] */ - static translate (body: BodyType, translation: Vector): void; + static translate (body: BodyType, translation: Vector, updateVelocity?: boolean): void; /** * Performs a simulation step for the given `body`, including updating position and angle using Verlet integration. * @method update * @param {body} body * @param {number} deltaTime - * @param {number} timeScale - * @param {number} correction */ - static update (body: BodyType, deltaTime: number, timeScale: number, correction: number): void; + static update (body: BodyType, deltaTime: number): void; + /** + * Gets the current linear speed of the body. + * Equivalent to the magnitude of its velocity. + * @method getSpeed + * @param {body} body + * @return {number} speed + */ + static getSpeed (body: BodyType): number; + + /** + * Sets the current linear speed of the body. + * Direction is maintained. Affects body velocity. + * @method setSpeed + * @param {body} body + * @param {number} speed + */ + static setSpeed (body: BodyType, speed: number): void; + + /** + * Gets the current rotational velocity of the body. + * @method getAngularVelocity + * @param {body} body + * @return {number} angular velocity + */ + static getAngularVelocity (body: BodyType): number; + + /** + * Gets the current rotational velocity of the body. + * @method getAngularSpeed + * @param {body} body + * @return {number} angular velocity + */ + static getAngularSpeed (body: BodyType): number; + + /** + * Sets the angular velocity of the body instantly. Position, angle, force etc. are unchanged. See also `Body.applyForce`. + * @method setAngularSpeed + * @param {body} body + * @param {number} velocity + */ + static setAngularSpeed (body: BodyType, velocity: number): void; } class BodyFactory { @@ -2405,6 +2480,13 @@ declare namespace MatterJS { */ applyForce (body: BodyType, position: Vector, force: Vector): void; + /** + * Updates properties `body.velocity`, `body.speed`, `body.angularVelocity` and `body.angularSpeed` which are normalised in relation to `Body._baseDelta`. + * @method updateVelocities + * @param {body} body + */ + updateVelocities (body: BodyType): void; + /** * Creates a new rigid body model. The options parameter is an object that specifies any properties you wish to override the defaults. * All properties have default values, and many are pre-calculated automatically based on other properties. @@ -2420,8 +2502,9 @@ declare namespace MatterJS { * @method rotate * @param {body} body * @param {number} rotation + * @param {boolean} [updateVelocity] */ - rotate (body: BodyType, rotation: number): void; + rotate (body: BodyType, rotation: number, updateVelocity?: boolean): void; /** * Returns the next unique group index for which bodies will collide. @@ -2520,16 +2603,18 @@ declare namespace MatterJS { * @method setPosition * @param {body} body * @param {vector} position + * @param {boolean} updateVelocity */ - setPosition (body: BodyType, position: Vector): void; + setPosition (body: BodyType, position: Vector, updateVelocity: boolean): void; /** * Sets the angle of the body instantly. Angular velocity, position, force etc. are unchanged. * @method setAngle * @param {body} body * @param {number} angle + * @param {boolean} updateVelocity */ - setAngle (body: BodyType, angle: number): void; + setAngle (body: BodyType, angle: number, updateVelocity: boolean): void; /** * Sets the linear velocity of the body instantly. Position, angle, force etc. are unchanged. See also `Body.applyForce`. @@ -2539,6 +2624,14 @@ declare namespace MatterJS { */ setVelocity (body: BodyType, velocity: Vector): void; + /** + * Gets the current linear velocity of the body. + * @method setVelocity + * @param {body} body + * @return {vector} velocity + */ + getVelocity (body: BodyType): Vector; + /** * Sets the angular velocity of the body instantly. Position, angle, force etc. are unchanged. See also `Body.applyForce`. * @method setAngularVelocity @@ -2570,19 +2663,59 @@ declare namespace MatterJS { * @method translate * @param {body} body * @param {vector} translation + * @param {boolean} [updateVelocity] */ - translate (body: BodyType, translation: Vector): void; + translate (body: BodyType, translation: Vector, updateVelocity?: boolean): void; /** * Performs a simulation step for the given `body`, including updating position and angle using Verlet integration. * @method update * @param {body} body * @param {number} deltaTime - * @param {number} timeScale - * @param {number} correction */ - update (body: BodyType, deltaTime: number, timeScale: number, correction: number): void; + update (body: BodyType, deltaTime: number): void; + /** + * Gets the current linear speed of the body. + * Equivalent to the magnitude of its velocity. + * @method getSpeed + * @param {body} body + * @return {number} speed + */ + getSpeed (body: BodyType): number; + + /** + * Sets the current linear speed of the body. + * Direction is maintained. Affects body velocity. + * @method setSpeed + * @param {body} body + * @param {number} speed + */ + setSpeed (body: BodyType, speed: number): void; + + /** + * Gets the current rotational velocity of the body. + * @method getAngularVelocity + * @param {body} body + * @return {number} angular velocity + */ + getAngularVelocity (body: BodyType): number; + + /** + * Gets the current rotational velocity of the body. + * @method getAngularSpeed + * @param {body} body + * @return {number} angular velocity + */ + getAngularSpeed (body: BodyType): number; + + /** + * Sets the angular velocity of the body instantly. Position, angle, force etc. are unchanged. See also `Body.applyForce`. + * @method setAngularSpeed + * @param {body} body + * @param {number} velocity + */ + setAngularSpeed (body: BodyType, velocity: number): void; } /** @@ -3003,14 +3136,14 @@ declare namespace MatterJS { /** * Creates a composite with simple car setup of bodies and constraints. * @method car - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} width * @param {number} height * @param {number} wheelSize * @return {composite} A new composite car body */ - static car (xx: number, yy: number, width: number, height: number, wheelSize: number): CompositeType; + static car (x: number, y: number, width: number, height: number, wheelSize: number): CompositeType; /** * Chains all bodies in the given composite together using constraints. @@ -3040,21 +3173,21 @@ declare namespace MatterJS { /** * Creates a composite with a Newton's Cradle setup of bodies and constraints. * @method newtonsCradle - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} number * @param {number} size * @param {number} length * @return {composite} A new composite newtonsCradle body */ - static newtonsCradle (xx: number, yy: number, number: number, size: number, length: number): CompositeType; + static newtonsCradle (x: number, y: number, number: number, size: number, length: number): CompositeType; /** * Create a new composite containing bodies created in the callback in a pyramid arrangement. * This function uses the body's bounds to prevent overlaps. * @method pyramid - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3062,13 +3195,13 @@ declare namespace MatterJS { * @param {function} callback * @return {composite} A new composite containing objects created in the callback */ - static pyramid (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; + static pyramid (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; /** * Creates a simple soft body like object. * @method softBody - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3079,14 +3212,14 @@ declare namespace MatterJS { * @param {} constraintOptions * @return {composite} A new composite softBody */ - static softBody (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, crossBrace: boolean, particleRadius: number, particleOptions: any, constraintOptions: any): CompositeType; + static softBody (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, crossBrace: boolean, particleRadius: number, particleOptions: any, constraintOptions: any): CompositeType; /** * Create a new composite containing bodies created in the callback in a grid arrangement. * This function uses the body's bounds to prevent overlaps. * @method stack - * @param {number} xx - * @param {number} yy + * @param {number} x Starting position in X. + * @param {number} y Starting position in Y. * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3094,7 +3227,7 @@ declare namespace MatterJS { * @param {function} callback * @return {composite} A new composite containing objects created in the callback */ - static stack (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; + static stack (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; } @@ -3103,14 +3236,14 @@ declare namespace MatterJS { /** * Creates a composite with simple car setup of bodies and constraints. * @method car - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} width * @param {number} height * @param {number} wheelSize * @return {composite} A new composite car body */ - car (xx: number, yy: number, width: number, height: number, wheelSize: number): CompositeType; + car (x: number, y: number, width: number, height: number, wheelSize: number): CompositeType; /** * Chains all bodies in the given composite together using constraints. @@ -3140,21 +3273,21 @@ declare namespace MatterJS { /** * Creates a composite with a Newton's Cradle setup of bodies and constraints. * @method newtonsCradle - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} number * @param {number} size * @param {number} length * @return {composite} A new composite newtonsCradle body */ - newtonsCradle (xx: number, yy: number, number: number, size: number, length: number): CompositeType; + newtonsCradle (x: number, y: number, number: number, size: number, length: number): CompositeType; /** * Create a new composite containing bodies created in the callback in a pyramid arrangement. * This function uses the body's bounds to prevent overlaps. * @method pyramid - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3162,13 +3295,13 @@ declare namespace MatterJS { * @param {function} callback * @return {composite} A new composite containing objects created in the callback */ - pyramid (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; + pyramid (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; /** * Creates a simple soft body like object. * @method softBody - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3179,14 +3312,14 @@ declare namespace MatterJS { * @param {} constraintOptions * @return {composite} A new composite softBody */ - softBody (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, crossBrace: boolean, particleRadius: number, particleOptions: any, constraintOptions: any): CompositeType; + softBody (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, crossBrace: boolean, particleRadius: number, particleOptions: any, constraintOptions: any): CompositeType; /** * Create a new composite containing bodies created in the callback in a grid arrangement. * This function uses the body's bounds to prevent overlaps. * @method stack - * @param {number} xx - * @param {number} yy + * @param {number} x + * @param {number} y * @param {number} columns * @param {number} rows * @param {number} columnGap @@ -3194,7 +3327,7 @@ declare namespace MatterJS { * @param {function} callback * @return {composite} A new composite containing objects created in the callback */ - stack (xx: number, yy: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; + stack (x: number, y: number, columns: number, rows: number, columnGap: number, rowGap: number, callback: Function): CompositeType; } @@ -3219,6 +3352,15 @@ declare namespace MatterJS { */ static create (options: IConstraintDefinition): ConstraintType; + /** + * Returns the current length of the constraint. + * This is the distance between both of the constraint's end points. + * See `constraint.length` for the target rest length. + * @method currentLength + * @param {constraint} ConstraintType + * @return {number} the current length + */ + static currentLength (constraint: ConstraintType): number; } class ConstraintFactory { @@ -3233,6 +3375,15 @@ declare namespace MatterJS { */ create (options: IConstraintDefinition): ConstraintType; + /** + * Returns the current length of the constraint. + * This is the distance between both of the constraint's end points. + * See `constraint.length` for the target rest length. + * @method currentLength + * @param {constraint} ConstraintType + * @return {number} the current length + */ + currentLength (constraint: ConstraintType): number; } /** @@ -3286,20 +3437,13 @@ declare namespace MatterJS { /** * Moves the simulation forward in time by `delta` ms. - * The `correction` argument is an optional `Number` that specifies the time correction factor to apply to the update. - * This can help improve the accuracy of the simulation in cases where `delta` is changing between updates. - * The value of `correction` is defined as `delta / lastDelta`, i.e. the percentage change of `delta` over the last step. - * Therefore the value is always `1` (no correction) when `delta` constant (or when no correction is desired, which is the default). - * See the paper on Time Corrected Verlet for more information. - * * Triggers `beforeUpdate` and `afterUpdate` events. * Triggers `collisionStart`, `collisionActive` and `collisionEnd` events. * @method update * @param {engine} engine * @param {number} [delta=16.666] - * @param {number} [correction=1] */ - static update (engine: Engine, delta?: number, correction?: number): Engine; + static update (engine: Engine, delta?: number): Engine; /** * An alias for `Runner.run`, see `Matter.Runner` for more information. @@ -3690,10 +3834,10 @@ declare namespace MatterJS { * Find a solution for pair positions. * @method solvePosition * @param {pair[]} pairs - * @param {body[]} bodies - * @param {number} timeScale + * @param {number} delta + * @param {number} [damping=1] */ - static solvePosition (pairs: IPair[], bodies: BodyType[], timeScale: number): void; + static solvePosition (pairs: IPair[], delta: number, damping?: number): void; /** * Apply position resolution. @@ -3713,9 +3857,9 @@ declare namespace MatterJS { * Find a solution for pair velocities. * @method solveVelocity * @param {pair[]} pairs - * @param {number} timeScale + * @param {number} delta */ - static solveVelocity (pairs: IPair[], timeScale: number): void; + static solveVelocity (pairs: IPair[], delta: number): void; } @@ -3732,10 +3876,10 @@ declare namespace MatterJS { * Find a solution for pair positions. * @method solvePosition * @param {pair[]} pairs - * @param {body[]} bodies - * @param {number} timeScale + * @param {number} delta + * @param {number} [damping=1] */ - solvePosition (pairs: IPair[], bodies: BodyType[], timeScale: number): void; + solvePosition (pairs: IPair[], delta: number, damping?: number): void; /** * Apply position resolution. @@ -3755,9 +3899,9 @@ declare namespace MatterJS { * Find a solution for pair velocities. * @method solveVelocity * @param {pair[]} pairs - * @param {number} timeScale + * @param {number} delta */ - solveVelocity (pairs: IPair[], timeScale: number): void; + solveVelocity (pairs: IPair[], delta: number): void; } @@ -3972,14 +4116,56 @@ declare namespace MatterJS { */ class Sleeping { + /** + * Set a body as sleeping or awake. + * @method set + * @param {body} body + * @param {boolean} isSleeping + */ static set (body: BodyType, isSleeping: boolean): void; + /** + * Puts bodies to sleep or wakes them up depending on their motion. + * @method update + * @param {body[]} bodies + * @param {number} delta + */ + static update (bodies: Array, delta: number): void; + + /** + * Given a set of colliding pairs, wakes the sleeping bodies involved. + * @method afterCollisions + * @param {pair[]} pairs + */ + static afterCollisions (pairs: Array): void; + } class SleepingFactory { + /** + * Set a body as sleeping or awake. + * @method set + * @param {body} body + * @param {boolean} isSleeping + */ set (body: BodyType, isSleeping: boolean): void; + /** + * Puts bodies to sleep or wakes them up depending on their motion. + * @method update + * @param {body[]} bodies + * @param {number} delta + */ + update (bodies: Array, delta: number): void; + + /** + * Given a set of colliding pairs, wakes the sleeping bodies involved. + * @method afterCollisions + * @param {pair[]} pairs + */ + afterCollisions (pairs: Array): void; + } /**