foster/liabru-matter-js
0
0
Fork 0
mirror of https://github.com/liabru/matter-js.git synced 2025-01-21 17:14:38 -05:00
Code Issues Wiki Activity

improve constraint docs

Browse source
This commit is contained in:
liabru 2020-12-31 14:30:18 +00:00
parent 0ea0be87d1
commit 0b63f1207f
1 changed files with 63 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
src/constraint/Constraint.js
View file

@ -1,7 +1,11 @@
/** /**
* The `Matter.Constraint` module contains methods for creating and manipulating constraints. * The `Matter.Constraint` module contains methods for creating and manipulating constraints.
* Constraints are used for specifying that a fixed distance must be maintained between two bodies (or a body and a fixed world-space position). *
* The stiffness of constraints can be modified to create springs or elastic. * Constraints are used for specifying that a fixed distance or angle must be maintained between bodies or fixed points.
*
* The stiffness and damping can be modified for a spring-like effect.
*
* The angle range and angle stiffness can also be limited if needed.
* *
* 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).
* *
@ -28,11 +32,18 @@ var Common = require('../core/Common');
/** /**
* Creates a new constraint. * Creates a new constraint.
* All properties have default values, and many are pre-calculated automatically based on other properties. *
* To simulate a revolute constraint (or pin joint) set `length: 0` and a high `stiffness` value (e.g. `0.7` or above). * All properties have default values and some may be calculated automatically based on other properties.
* If the constraint is unstable, try lowering the `stiffness` value and / or increasing `engine.constraintIterations`. *
* For compound bodies, constraints must be applied to the parent body (not one of its parts). * To simulate a pin constraint (or revolute joint) set `length: 0` and a high `stiffness` value (e.g. `0.7` or above).
* See the properties section below for detailed information on what you can pass via the `options` object. *
* To limit the range of angles of the constraint see the set of angle properties.
*
* If the constraint is unstable, try lowering the `stiffness` value or increasing `engine.constraintIterations`.
*
* For compound bodies, constraints must be applied to the parent body and not its parts.
*
* See the properties section which may be set through the `options` object.
* @method create * @method create
* @param {} options * @param {} options
* @return {constraint} constraint * @return {constraint} constraint
@ -515,7 +526,7 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Boolean` that defines if the constraint's anglular limits should be rendered. * A `Boolean` that defines if the constraint's anglular limits should be rendered.
* *
* @property render.angles * @property render.angles
* @type boolean * @type boolean
@ -556,7 +567,9 @@ var Common = require('../core/Common');
/** /**
* A `Number` that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`. * A `Number` that specifies the stiffness of the constraint, i.e. the rate at which it returns to its resting `constraint.length`.
*
* A value of `1` means the constraint should be very stiff. * A value of `1` means the constraint should be very stiff.
*
* A value of `0.2` means the constraint acts like a soft spring. * A value of `0.2` means the constraint acts like a soft spring.
* *
* @property stiffness * @property stiffness
@ -567,8 +580,11 @@ var Common = require('../core/Common');
/** /**
* A `Number` that specifies the damping of the constraint, * A `Number` that specifies the damping of the constraint,
* i.e. the amount of resistance applied to each body based on their velocities to limit the amount of oscillation. * i.e. the amount of resistance applied to each body based on their velocities to limit the amount of oscillation.
*
* Damping will only be apparent when the constraint also has a very low `stiffness`. * Damping will only be apparent when the constraint also has a very low `stiffness`.
*
* A value of `0.1` means the constraint will apply heavy damping, resulting in little to no oscillation. * A value of `0.1` means the constraint will apply heavy damping, resulting in little to no oscillation.
*
* A value of `0` means the constraint will apply no damping. * A value of `0` means the constraint will apply no damping.
* *
* @property damping * @property damping
@ -578,6 +594,7 @@ var Common = require('../core/Common');
/** /**
* A `Number` that specifies the target resting length of the constraint. * A `Number` that specifies the target resting length of the constraint.
*
* It is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`. * It is calculated automatically in `Constraint.create` from initial positions of the `constraint.bodyA` and `constraint.bodyB`.
* *
* @property length * @property length
@ -585,11 +602,15 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the limiting angle of the constraint about `constraint.pointA`. * A `Number` in radians that specifies the limiting angle of the constraint about `constraint.pointA`.
* It is relative to `constraint.bodyA.angle` if `constraint.bodyA` is set, otherwise is absolute. *
* Defaults to the initial angle of the constraint or `0`.
* Only applies if `constraint.angleAStiffness > 0`. * Only applies if `constraint.angleAStiffness > 0`.
* The constraint angle is measured between the vector `pointA - pointB` and the x-axis. *
* Defaults to the initial angle of the constraint or `0`.
*
* The angle is relative to `constraint.bodyA.angle` if `constraint.bodyA` is set, otherwise is absolute.
*
* When absolute the angle is measured between the vector `constraint.pointA - constraint.pointB` and the x-axis.
* *
* @property angleA * @property angleA
* @type number * @type number
@ -597,9 +618,12 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` that specifies the stiffness of angular limits about `constraint.pointA`. * A `Number` that specifies the stiffness of angular limits about `constraint.pointA`.
*
* A value of `0` (default) means the constraint will not limit the angle. * A value of `0` (default) means the constraint will not limit the angle.
*
* A value of `0.01` means the constraint will softly limit the angle. * A value of `0.01` means the constraint will softly limit the angle.
*
* A value of `1` means the constraint will rigidly limit the angle. * A value of `1` means the constraint will rigidly limit the angle.
* *
* @property angleAStiffness * @property angleAStiffness
@ -608,8 +632,9 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the lower angular limit * A `Number` in radians that specifies the lower angular limit
* about `constraint.pointA` relative to `constraint.angleA`. * about `constraint.pointA` relative to `constraint.angleA`.
*
* A value of `-0.5` means the constraint is limited to `0.5` radians * A value of `-0.5` means the constraint is limited to `0.5` radians
* anti-clockwise of `constraint.angleA`, or clockwise if the value is positive. * anti-clockwise of `constraint.angleA`, or clockwise if the value is positive.
* *
@ -619,8 +644,11 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the upper angular limit * A `Number` in radians that specifies the upper angular limit
* about `constraint.pointA` relative to `constraint.angleA`. See `constraint.angleAMin` for more. * about `constraint.pointA` relative to `constraint.angleA`.
*
* A value of `-0.5` means the constraint is limited to `0.5` radians
* anti-clockwise of `constraint.angleA`, or clockwise if the value is positive.
* *
* @property angleAMax * @property angleAMax
* @type number * @type number
@ -628,11 +656,15 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the limiting angle of the constraint about `constraint.pointB`. * A `Number` in radians that specifies the limiting angle of the constraint about `constraint.pointB`.
* It is relative to `constraint.bodyB.angle` if `constraint.bodyB` is set, otherwise is absolute. *
* Defaults to the initial angle of the constraint or `0`.
* Only applies if `constraint.angleBStiffness > 0`. * Only applies if `constraint.angleBStiffness > 0`.
* The constraint angle is measured between the vector `pointA - pointB` and the x-axis. *
* Defaults to the initial angle of the constraint or `0`.
*
* The angle is relative to `constraint.bodyB.angle` if `constraint.bodyB` is set, otherwise is absolute.
*
* When absolute the angle is measured between the vector `constraint.pointA - constraint.pointB` and the x-axis.
* *
* @property angleB * @property angleB
* @type number * @type number
@ -640,9 +672,12 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` that specifies the stiffness of angular limits about `constraint.pointB`. * A `Number` that specifies the stiffness of angular limits about `constraint.pointB`.
*
* A value of `0` (default) means the constraint will not limit the angle. * A value of `0` (default) means the constraint will not limit the angle.
*
* A value of `0.01` means the constraint will softly limit the angle. * A value of `0.01` means the constraint will softly limit the angle.
*
* A value of `1` means the constraint will rigidly limit the angle. * A value of `1` means the constraint will rigidly limit the angle.
* *
* @property angleBStiffness * @property angleBStiffness
@ -651,8 +686,9 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the lower angular limit * A `Number` in radians that specifies the lower angular limit
* about `constraint.pointB` relative to `constraint.angleB`. * about `constraint.pointB` relative to `constraint.angleB`.
*
* A value of `-0.5` means the constraint is limited to `0.5` radians * A value of `-0.5` means the constraint is limited to `0.5` radians
* anti-clockwise of `constraint.angleB`, or clockwise if the value is positive. * anti-clockwise of `constraint.angleB`, or clockwise if the value is positive.
* *
@ -662,8 +698,11 @@ var Common = require('../core/Common');
*/ */
/** /**
* **ALPHA**: A `Number` in radians that specifies the upper angular limit * A `Number` in radians that specifies the upper angular limit
* about `constraint.pointB` relative to `constraint.angleB`. See `constraint.angleBMin` for more. * about `constraint.pointB` relative to `constraint.angleB`.
*
* A value of `-0.5` means the constraint is limited to `0.5` radians
* anti-clockwise of `constraint.angleB`, or clockwise if the value is positive.
* *
* @property angleBMax * @property angleBMax
* @type number * @type number