foster/liabru-matter-js
0
0
Fork 0
mirror of https://github.com/liabru/matter-js.git synced 2024-11-23 09:26:51 -05:00
Code Issues Wiki Activity

improve Matter.Body docs for functions and properties including readonly

Browse source
This commit is contained in:
liabru 2022-07-27 20:51:03 +01:00
parent 3ff6ff4372
commit 85a9eb2df5
1 changed files with 141 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

240
src/body/Body.js
View file

@ -1,7 +1,6 @@
/** /**
* The `Matter.Body` module contains methods for creating and manipulating body models. * The `Matter.Body` module contains methods for creating and manipulating rigid bodies.
* A `Matter.Body` is a rigid body that can be simulated by a `Matter.Engine`. * For creating bodies with common configurations such as rectangles, circles and other polygons see the module `Matter.Bodies`.
* Factories for commonly used body configurations (such as rectangles, circles and other polygons) can be found in the module `Matter.Bodies`.
* *
* See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples). * See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples).
@ -346,7 +345,7 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Sets the moment of inertia (i.e. second moment of area) of the body. * Sets the moment of inertia of the body. This is the second moment of area in two dimensions.
* Inverse inertia is automatically updated to reflect the change. Mass is not changed. * Inverse inertia is automatically updated to reflect the change. Mass is not changed.
* @method setInertia * @method setInertia
* @param {body} body * @param {body} body
@ -363,8 +362,8 @@ var Axes = require('../geometry/Axes');
* They are then automatically translated to world space based on `body.position`. * They are then automatically translated to world space based on `body.position`.
* *
* The `vertices` argument should be passed as an array of `Matter.Vector` points (or a `Matter.Vertices` array). * The `vertices` argument should be passed as an array of `Matter.Vector` points (or a `Matter.Vertices` array).
* Vertices must form a convex hull, concave hulls are not supported. * Vertices must form a convex hull. Concave vertices must be decomposed into convex parts.
* *
* @method setVertices * @method setVertices
* @param {body} body * @param {body} body
* @param {vector[]} vertices * @param {vector[]} vertices
@ -545,8 +544,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Sets the current linear velocity of the body. Updates `body.speed`. See `body.velocity` for details. * Sets the current linear velocity of the body.
* Use this instead of setting `body.velocity`. See also `Body.applyForce`. * Affects body speed.
* @method setVelocity * @method setVelocity
* @param {body} body * @param {body} body
* @param {vector} velocity * @param {vector} velocity
@ -561,7 +560,7 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Gets the current linear velocity of the body. See `body.velocity` for details. * Gets the current linear velocity of the body.
* @method getVelocity * @method getVelocity
* @param {body} body * @param {body} body
* @return {vector} velocity * @return {vector} velocity
@ -576,7 +575,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Gets the current linear speed of the body. See `body.speed` for details. * Gets the current linear speed of the body.
* Equivalent to the magnitude of its velocity.
* @method getSpeed * @method getSpeed
* @param {body} body * @param {body} body
* @return {number} speed * @return {number} speed
@ -586,7 +586,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Sets the current linear speed of the body. See `body.speed` for details. Use this instead of setting `body.speed`. * Sets the current linear speed of the body.
* Direction is maintained. Affects body velocity.
* @method setSpeed * @method setSpeed
* @param {body} body * @param {body} body
* @param {number} speed * @param {number} speed
@ -596,8 +597,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Sets the current rotational velocity of the body. Updates `body.angularSpeed`. See `body.angularVelocity` for details. * Sets the current rotational velocity of the body.
* Use this instead of setting `body.angularVelocity`. See also `Body.applyForce`. * Affects body angular speed.
* @method setAngularVelocity * @method setAngularVelocity
* @param {body} body * @param {body} body
* @param {number} velocity * @param {number} velocity
@ -610,7 +611,7 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Gets the current rotational velocity of the body. See `body.angularVelocity` for details. * Gets the current rotational velocity of the body.
* @method getAngularVelocity * @method getAngularVelocity
* @param {body} body * @param {body} body
* @return {number} angular velocity * @return {number} angular velocity
@ -620,7 +621,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Gets the current rotational speed of the body. See `body.angularSpeed` for details. * Gets the current rotational speed of the body.
* Equivalent to the magnitude of its angular velocity.
* @method getAngularSpeed * @method getAngularSpeed
* @param {body} body * @param {body} body
* @return {number} angular speed * @return {number} angular speed
@ -630,7 +632,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Sets the current rotational speed of the body. See `body.angularSpeed` for details. Use this instead of setting `body.angularSpeed`. * Sets the current rotational speed of the body.
* Direction is maintained. Affects body angular velocity.
* @method setAngularSpeed * @method setAngularSpeed
* @param {body} body * @param {body} body
* @param {number} speed * @param {number} speed
@ -743,7 +746,8 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Performs a simulation step for the given `body`, including updating position and angle using Verlet integration. * Performs an update by integrating the equations of motion on the `body`.
* This is applied every update by `Matter.Engine` automatically.
* @method update * @method update
* @param {body} body * @param {body} body
* @param {number} [deltaTime=16.666] * @param {number} [deltaTime=16.666]
@ -815,7 +819,12 @@ var Axes = require('../geometry/Axes');
}; };
/** /**
* Applies a force to a body from a given world-space position, including resulting torque. * Applies a force to a body from a given world-space position for a _single update_, including resulting torque.
* The position must be specified. Using `body.position` results in zero torque.
*
* Forces create an acceleration that acts over time, so may need to be applied over multiple updates for the body to gain a visible momentum.
*
* See also `Body.setVelocity` and related methods which do not require any time for acceleration to reach the given velocity.
* @method applyForce * @method applyForce
* @param {body} body * @param {body} body
* @param {vector} position * @param {vector} position
@ -904,12 +913,14 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Set by `Body.create`.
*
* A `String` denoting the type of object. * A `String` denoting the type of object.
* *
* @readOnly
* @property type * @property type
* @type string * @type string
* @default "body" * @default "body"
* @readOnly
*/ */
/** /**
@ -921,6 +932,8 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Use `Body.setParts` to set.
*
* An array of bodies that make up this body. * An array of bodies that make up this body.
* The first body in the array must always be a self reference to the current body instance. * The first body in the array must always be a self reference to the current body instance.
* All bodies in the `parts` array together form a single rigid compound body. * All bodies in the `parts` array together form a single rigid compound body.
@ -928,6 +941,7 @@ var Axes = require('../geometry/Axes');
* Parts themselves should never be added to a `World`, only the parent body should be. * Parts themselves should never be added to a `World`, only the parent body should be.
* Use `Body.setParts` when setting parts to ensure correct updates of all properties. * Use `Body.setParts` when setting parts to ensure correct updates of all properties.
* *
* @readOnly
* @property parts * @property parts
* @type body[] * @type body[]
*/ */
@ -940,16 +954,18 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* A self reference if the body is _not_ a part of another body. * _Read only_. Updated by `Body.setParts`.
* Otherwise this is a reference to the body that this is a part of. *
* See `body.parts`. * A reference to the body that this is a part of. See `body.parts`.
* This is a self reference if the body is not a part of another body.
* *
* @readOnly
* @property parent * @property parent
* @type body * @type body
*/ */
/** /**
* A `Number` specifying the angle of the body, in radians. * A `Number` specifying the angle of the body.
* *
* @property angle * @property angle
* @type number * @type number
@ -957,40 +973,53 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Use `Body.setVertices` or `Body.setParts` to set. See also `Bodies.fromVertices`.
*
* An array of `Vector` objects that specify the convex hull of the rigid body. * An array of `Vector` objects that specify the convex hull of the rigid body.
* These should be provided about the origin `(0, 0)`. E.g. * These should be provided about the origin `(0, 0)`. E.g.
* *
* [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }] * `[{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]`
*
* Vertices must always be convex, in clockwise order and must not contain any duplicate points.
*
* Concave vertices should be decomposed into convex `parts`, see `Bodies.fromVertices` and `Body.setParts`.
* *
* When passed via `Body.create`, the vertices are translated relative to `body.position` (i.e. world-space, and constantly updated by `Body.update` during simulation). * When set the vertices are translated such that `body.position` is at the centre of mass.
* The `Vector` objects are also augmented with additional properties required for efficient collision detection. * Many other body properties are automatically calculated from these vertices when set including `density`, `area` and `inertia`.
* *
* Other properties such as `inertia` and `bounds` are automatically calculated from the passed vertices (unless provided via `options`). * The module `Matter.Vertices` contains useful methods for working with vertices.
* Concave hulls are not currently supported. The module `Matter.Vertices` contains useful methods for working with vertices.
* *
* @readOnly
* @property vertices * @property vertices
* @type vector[] * @type vector[]
*/ */
/** /**
* _Read only_. Use `Body.setPosition` to set.
*
* A `Vector` that specifies the current world-space position of the body. * A `Vector` that specifies the current world-space position of the body.
* *
* @readOnly
* @property position * @property position
* @type vector * @type vector
* @default { x: 0, y: 0 } * @default { x: 0, y: 0 }
*/ */
/** /**
* A `Vector` that specifies the force to apply in the current step. It is zeroed after every `Body.update`. See also `Body.applyForce`. * A `Vector` that accumulates the total force applied to the body for a single update.
* * Force is zeroed after every `Body.update`, so constant forces should be applied for every update they are needed. See also `Body.applyForce`.
*
* @property force * @property force
* @type vector * @type vector
* @default { x: 0, y: 0 } * @default { x: 0, y: 0 }
*/ */
/** /**
* A `Number` that specifies the torque (turning force) to apply in the current step. It is zeroed after every `Body.update`. * A `Number` that accumulates the total torque (turning force) applied to the body for a single update. See also `Body.applyForce`.
* Torque is zeroed after every `Body.update`, so constant torques should be applied for every update they are needed.
* *
* Torques are converted to acceleration on every update, which depends on body inertia and the engine update delta.
*
* @property torque * @property torque
* @type number * @type number
* @default 0 * @default 0
@ -999,12 +1028,7 @@ var Axes = require('../geometry/Axes');
/** /**
* _Read only_. Use `Body.setSpeed` to set. * _Read only_. Use `Body.setSpeed` to set.
* *
* The body's current linear speed in _unit distance_ per _unit time_. * See `Body.getSpeed` for details.
*
* By default when rendering _1:1_ this is equivalent to
* _pixels_ per `Body.timeUnit` _milliseconds_.
*
* See `Body.timeUnit` for more details.
* *
* Equivalent to the magnitude of `body.velocity` (always positive). * Equivalent to the magnitude of `body.velocity` (always positive).
* *
@ -1014,33 +1038,12 @@ var Axes = require('../geometry/Axes');
* @default 0 * @default 0
*/ */
/**
* _Read only_. Use `Body.setAngularSpeed` to set.
*
* The body's current rotational speed in _radians_ per _unit time_.
*
* By default when rendering _1:1_ this is equivalent to
* _radians_ per `Body.timeUnit` _milliseconds_.
*
* See `Body.timeUnit` for more details.
*
* Equivalent to the magnitude of `body.angularVelocity` (always positive).
*
* @readOnly
* @property angularSpeed
* @type number
* @default 0
*/
/** /**
* _Read only_. Use `Body.setVelocity` to set. * _Read only_. Use `Body.setVelocity` to set.
* *
* The body's current linear velocity in _unit distance_ per _unit time_. * See `Body.getVelocity` for details.
* *
* By default when rendering _1:1_ this is equivalent to * Equivalent to the magnitude of `body.angularVelocity` (always positive).
* _pixels_ per `Body.timeUnit` _milliseconds_.
*
* See `Body.timeUnit` for more details.
* *
* @readOnly * @readOnly
* @property velocity * @property velocity
@ -1048,15 +1051,23 @@ var Axes = require('../geometry/Axes');
* @default { x: 0, y: 0 } * @default { x: 0, y: 0 }
*/ */
/**
* _Read only_. Use `Body.setAngularSpeed` to set.
*
* See `Body.getAngularSpeed` for details.
*
*
* @readOnly
* @property angularSpeed
* @type number
* @default 0
*/
/** /**
* _Read only_. Use `Body.setAngularVelocity` to set. * _Read only_. Use `Body.setAngularVelocity` to set.
* *
* The body's current rotational velocity in _radians_ per _unit time_. * See `Body.getAngularVelocity` for details.
* *
* By default when rendering _1:1_ this is equivalent to
* _radians_ per `Body.timeUnit` _milliseconds_.
*
* See `Body.timeUnit` for more details.
* *
* @readOnly * @readOnly
* @property angularVelocity * @property angularVelocity
@ -1065,9 +1076,11 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Use `Body.setStatic` to set.
*
* A flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed. * A flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed.
* If you need to set a body as static after its creation, you should use `Body.setStatic` as this requires more than just setting this flag.
* *
* @readOnly
* @property isStatic * @property isStatic
* @type boolean * @type boolean
* @default false * @default false
@ -1082,18 +1095,23 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Use `Sleeping.set` to set.
*
* A flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken. * A flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken.
* If you need to set a body as sleeping, you should use `Sleeping.set` as this requires more than just setting this flag.
* *
* @readOnly
* @property isSleeping * @property isSleeping
* @type boolean * @type boolean
* @default false * @default false
*/ */
/** /**
* A `Number` that _measures_ the amount of movement a body currently has (a combination of `speed` and `angularSpeed`). It is read-only and always positive. * _Read only_. Calculated during engine update only when sleeping is enabled.
* It is used and updated by the `Matter.Sleeping` module during simulation to decide if a body has come to rest. *
* A `Number` that loosely measures the amount of movement a body currently has.
* *
* Derived from `body.speed^2 + body.angularSpeed^2`. See `Sleeping.update`.
*
* @readOnly * @readOnly
* @property motion * @property motion
* @type number * @type number
@ -1101,52 +1119,66 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* A `Number` that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping by the `Matter.Sleeping` module (if sleeping is enabled by the engine). * A `Number` that defines the length of time during which this body must have near-zero velocity before it is set as sleeping by the `Matter.Sleeping` module (if sleeping is enabled by the engine).
* *
* @property sleepThreshold * @property sleepThreshold
* @type number * @type number
* @default 60 * @default 60
*/ */
/** /**
* A `Number` that defines the density of the body, that is its mass per unit area. * _Read only_. Use `Body.setDensity` to set.
* If you pass the density via `Body.create` the `mass` property is automatically calculated for you based on the size (area) of the object. *
* This is generally preferable to simply setting mass and allows for more intuitive definition of materials (e.g. rock has a higher density than wood). * A `Number` that defines the density of the body (mass per unit area).
*
* Mass will also be updated when set.
* *
* @readOnly
* @property density * @property density
* @type number * @type number
* @default 0.001 * @default 0.001
*/ */
/** /**
* A `Number` that defines the mass of the body, although it may be more appropriate to specify the `density` property instead. * _Read only_. Use `Body.setMass` to set.
* If you modify this value, you must also modify the `body.inverseMass` property (`1 / mass`). *
* * A `Number` that defines the mass of the body.
*
* Density will also be updated when set.
*
* @readOnly
* @property mass * @property mass
* @type number * @type number
*/ */
/** /**
* _Read only_. Use `Body.setMass` to set.
*
* A `Number` that defines the inverse mass of the body (`1 / mass`). * A `Number` that defines the inverse mass of the body (`1 / mass`).
* If you modify this value, you must also modify the `body.mass` property.
* *
* @readOnly
* @property inverseMass * @property inverseMass
* @type number * @type number
*/ */
/** /**
* A `Number` that defines the moment of inertia (i.e. second moment of area) of the body. * _Read only_. Automatically calculated when vertices, mass or density are set.
* It is automatically calculated from the given convex hull (`vertices` array) and density in `Body.create`. *
* If you modify this value, you must also modify the `body.inverseInertia` property (`1 / inertia`). * A `Number` that defines the moment of inertia of the body. This is the second moment of area in two dimensions.
* *
* Can be manually set to `Infinity` to prevent rotation of the body. See `Body.setInertia`.
*
* @readOnly
* @property inertia * @property inertia
* @type number * @type number
*/ */
/** /**
* _Read only_. Automatically calculated when vertices, mass or density are set.
*
* A `Number` that defines the inverse moment of inertia of the body (`1 / inertia`). * A `Number` that defines the inverse moment of inertia of the body (`1 / inertia`).
* If you modify this value, you must also modify the `body.inertia` property. *
* * @readOnly
* @property inverseInertia * @property inverseInertia
* @type number * @type number
*/ */
@ -1157,7 +1189,7 @@ var Axes = require('../geometry/Axes');
* A value of `0.8` means the body may bounce back with approximately 80% of its kinetic energy. * A value of `0.8` means the body may bounce back with approximately 80% of its kinetic energy.
* Note that collision response is based on _pairs_ of bodies, and that `restitution` values are _combined_ with the following formula: * Note that collision response is based on _pairs_ of bodies, and that `restitution` values are _combined_ with the following formula:
* *
* Math.max(bodyA.restitution, bodyB.restitution) * `Math.max(bodyA.restitution, bodyB.restitution)`
* *
* @property restitution * @property restitution
* @type number * @type number
@ -1174,7 +1206,7 @@ var Axes = require('../geometry/Axes');
* The engine uses a Coulomb friction model including static and kinetic friction. * The engine uses a Coulomb friction model including static and kinetic friction.
* Note that collision response is based on _pairs_ of bodies, and that `friction` values are _combined_ with the following formula: * Note that collision response is based on _pairs_ of bodies, and that `friction` values are _combined_ with the following formula:
* *
* Math.min(bodyA.friction, bodyB.friction) * `Math.min(bodyA.friction, bodyB.friction)`
* *
* @property friction * @property friction
* @type number * @type number
@ -1259,9 +1291,11 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* A `Number` that specifies a tolerance on how far a body is allowed to 'sink' or rotate into other bodies. * A `Number` that specifies a thin boundary around the body where it is allowed to slightly sink into other bodies.
* Avoid changing this value unless you understand the purpose of `slop` in physics engines. *
* The default should generally suffice, although very large bodies may require larger values for stable stacking. * This is required for proper collision response, including friction and restitution effects.
*
* The default should generally suffice in most cases. You may need to decrease this value for very small bodies that are nearing the default value in scale.
* *
* @property slop * @property slop
* @type number * @type number
@ -1269,7 +1303,7 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* A `Number` that allows per-body time scaling, e.g. a force-field where bodies inside are in slow-motion, while others are at full speed. * A `Number` that specifies per-body time scaling.
* *
* @property timeScale * @property timeScale
* @type number * @type number
@ -1277,13 +1311,15 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Updated during engine update.
*
* A `Number` that records the last delta time value used to update this body. * A `Number` that records the last delta time value used to update this body.
* This is automatically updated by the engine inside of `Body.update`. * Used to calculate speed and velocity.
* *
* @readOnly * @readOnly
* @property deltaTime * @property deltaTime
* @type number * @type number
* @default null * @default 1000 / 60
*/ */
/** /**
@ -1383,17 +1419,23 @@ var Axes = require('../geometry/Axes');
*/ */
/** /**
* _Read only_. Calculated automatically when vertices are set.
*
* An array of unique axis vectors (edge normals) used for collision detection. * An array of unique axis vectors (edge normals) used for collision detection.
* These are automatically calculated from the given convex hull (`vertices` array) in `Body.create`. * These are automatically calculated when vertices are set.
* They are constantly updated by `Body.update` during the simulation. * They are constantly updated by `Body.update` during the simulation.
* *
* @readOnly
* @property axes * @property axes
* @type vector[] * @type vector[]
*/ */
/** /**
* A `Number` that _measures_ the area of the body's convex hull, calculated at creation by `Body.create`. * _Read only_. Calculated automatically when vertices are set.
* *
* A `Number` that measures the area of the body's convex hull.
*
* @readOnly
* @property area * @property area
* @type string * @type string
* @default * @default
@ -1401,8 +1443,8 @@ var Axes = require('../geometry/Axes');
/** /**
* A `Bounds` object that defines the AABB region for the body. * A `Bounds` object that defines the AABB region for the body.
* It is automatically calculated from the given convex hull (`vertices` array) in `Body.create` and constantly updated by `Body.update` during simulation. * It is automatically calculated when vertices are set and constantly updated by `Body.update` during simulation.
* *
* @property bounds * @property bounds
* @type bounds * @type bounds
*/ */