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

improved docs

Browse source
This commit is contained in:
liabru 2014-05-20 14:15:39 +01:00
parent 261c7949c4
commit 2317f02fb4
12 changed files with 976 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

397
src/body/Body.js
View file

@ -1,7 +1,11 @@
/**
* The `Matter.Body` module contains methods for creating and manipulating body models.
* A `Matter.Body` is a rigid body that can be simulated by a `Matter.Engine`.
* Factories for commonly used body configurations (such as rectangles, circles and other polygons) can be found in the module `Matter.Bodies`.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
* @class Body
*/
@ -12,7 +16,9 @@ var Body = {};
var _nextGroupId = 1;
/**
* Description to be written.
* 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.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {} options
* @return {body} body
@ -62,7 +68,7 @@ var Body = {};
};
/**
* Description
* Returns the next unique groupID number.
* @method nextGroupId
* @return {Number} Unique groupID
*/
@ -71,7 +77,7 @@ var Body = {};
};
/**
* Initialises body properties
* Initialises body properties.
* @method _initProperties
* @private
* @param {body} body
@ -104,7 +110,7 @@ var Body = {};
};
/**
* Sets the body as static, including isStatic flag and setting mass and inertia to Infinity
* Sets the body as static, including isStatic flag and setting mass and inertia to Infinity.
* @method setStatic
* @param {bool} isStatic
*/
@ -129,7 +135,7 @@ var Body = {};
};
/**
* Description
* Zeroes the `body.force` and `body.torque` force buffers.
* @method resetForcesAll
* @param {body[]} bodies
*/
@ -145,7 +151,7 @@ var Body = {};
};
/**
* Description
* Applys a mass dependant force to all given bodies.
* @method applyGravityAll
* @param {body[]} bodies
* @param {vector} gravity
@ -164,12 +170,14 @@ var Body = {};
};
/**
* Description
* Applys `Body.update` to all given `bodies`.
* @method updateAll
* @param {body[]} bodies
* @param {number} deltaTime
* The amount of time elapsed between updates
* @param {number} timeScale
* @param {number} correction
* The Verlet correction factor (deltaTime / lastDeltaTime)
* @param {bounds} worldBounds
*/
Body.updateAll = function(bodies, deltaTime, timeScale, correction, worldBounds) {
@ -190,7 +198,7 @@ var Body = {};
};
/**
* Description
* Performs a simulation step for the given `body`, including updating position and angle using Verlet integration.
* @method update
* @param {body} body
* @param {number} deltaTime
@ -233,7 +241,7 @@ var Body = {};
};
/**
* Description
* Applies a force to a body from a given world-space position, including resulting torque.
* @method applyForce
* @param {body} body
* @param {vector} position
@ -247,7 +255,7 @@ var Body = {};
};
/**
* Description
* Moves a body by a given vector relative to its current position, without imparting any velocity.
* @method translate
* @param {body} body
* @param {vector} translation
@ -262,7 +270,7 @@ var Body = {};
};
/**
* Description
* Rotates a body by a given angle relative to its current angle, without imparting any angular velocity.
* @method rotate
* @param {body} body
* @param {number} angle
@ -276,12 +284,12 @@ var Body = {};
};
/**
* Scales the body, including updating physical properties (mass, area, axes, inertia), from a point (default is centre)
* Scales the body, including updating physical properties (mass, area, axes, inertia), from a world-space point (default is body centre).
* @method translate
* @param {body} body
* @param {number} scaleX
* @param {number} scaleY
* @param {vector} point
* @param {vector} [point]
*/
Body.scale = function(body, scaleX, scaleY, point) {
// scale vertices
@ -303,4 +311,365 @@ var Body = {};
Bounds.update(body.bounds, body.vertices, body.velocity);
};
/*
*
* Properties Documentation
*
*/
/**
* An integer `Number` uniquely identifying number generated in `Body.create` by `Common.nextId`.
*
* @property id
* @type number
*/
/**
* A `String` denoting the type of object.
*
* @property type
* @type string
* @default "body"
*/
/**
* An arbitrary `String` name to help the user identify and manage bodies.
*
* @property label
* @type string
* @default "Body"
*/
/**
* A `Number` specifying the angle of the body, in radians.
*
* @property angle
* @type number
* @default 0
*/
/**
* 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.
*
* [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
*
* When passed via `Body.create`, the verticies are translated relative to `body.position` (i.e. world-space, and constantly updated by `Body.update` during simulation).
* The `Vector` objects are also augmented with additional properties required for efficient collision detection.
*
* Other properties such as `inertia` and `bounds` are automatically calculated from the passed vertices (unless provided via `options`).
* Concave hulls are not currently supported. The module `Matter.Vertices` contains useful methods for working with vertices.
*
* @property vertices
* @type vector[]
*/
/**
* A `Vector` that specifies the current world-space position of the body.
*
* @property position
* @type vector
* @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`.
*
* @property force
* @type vector
* @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`.
*
* @property torque
* @type number
* @default 0
*/
/**
* A `Number` that _measures_ the current speed of the body after the last `Body.update`. It is read-only and always positive (it's the magnitude of `body.velocity`).
*
* @readOnly
* @property speed
* @type number
* @default 0
*/
/**
* A `Number` that _measures_ the current angular speed of the body after the last `Body.update`. It is read-only and always positive (it's the magnitude of `body.angularVelocity`).
*
* @readOnly
* @property angularSpeed
* @type number
* @default 0
*/
/**
* A `Vector` that _measures_ the current velocity of the body after the last `Body.update`. It is read-only.
* If you need to modify a body's velocity directly, you should either apply a force or simply change the body's `position` (as the engine uses position-Verlet integration).
*
* @readOnly
* @property velocity
* @type vector
* @default { x: 0, y: 0 }
*/
/**
* A `Number` that _measures_ the current angular velocity of the body after the last `Body.update`. It is read-only.
* If you need to modify a body's angular velocity directly, you should apply a torque or simply change the body's `angle` (as the engine uses position-Verlet integration).
*
* @readOnly
* @property angularVelocity
* @type number
* @default 0
*/
/**
* 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.
*
* @property isStatic
* @type boolean
* @default false
*/
/**
* 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.
*
* @property isSleeping
* @type boolean
* @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.
* It is used and updated by the `Matter.Sleeping` module during simulation to decide if a body has come to rest.
*
* @readOnly
* @property motion
* @type number
* @default 0
*/
/**
* 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).
*
* @property sleepThreshold
* @type number
* @default 60
*/
/**
* A `Number` that defines the density of the body, that is its mass per unit area.
* 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).
*
* @property density
* @type number
* @default 0.001
*/
/**
* A `Number` that defines the mass of the body, although it may be more appropriate to specify the `density` property instead.
* If you modify this value, you must also modify the `body.inverseMass` property (`1 / mass`).
*
* @property mass
* @type number
*/
/**
* 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.
*
* @property inverseMass
* @type number
*/
/**
* A `Number` that defines the moment of inertia (i.e. second moment of area) of the body.
* 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`).
*
* @property inertia
* @type number
*/
/**
* 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.
*
* @property inverseInertia
* @type number
*/
/**
* A `Number` that defines the restitution (elasticity) of the body. The value is always positive and is in the range `(0, 1)`.
* A value of `0` means collisions may be perfectly inelastic and no bouncing may occur.
* 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:
*
* Math.max(bodyA.restitution, bodyB.restitution)
*
* @property restitution
* @type number
* @default 0
*/
/**
* A `Number` that defines the friction of the body. The value is always positive and is in the range `(0, 1)`.
* A value of `0` means that the body may slide indefinitely.
* A value of `1` means the body may come to a stop almost instantly after a force is applied.
*
* The effects of the value may be non-linear.
* High values may be unstable depending on the body.
* 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:
*
* Math.min(bodyA.friction, bodyB.friction)
*
* @property friction
* @type number
* @default 0.1
*/
/**
* A `Number` that defines the air friction of the body (air resistance).
* A value of `0` means the body will never slow as it moves through space.
* The higher the value, the faster a body slows when moving through space.
* The effects of the value are non-linear.
*
* @property frictionAir
* @type number
* @default 0.01
*/
/**
* An integer `Number` that specifies the collision group the body belongs to.
* Bodies with the same `groupId` are considered _as-one_ body and therefore do not interact.
* This allows for creation of segmented bodies that can self-intersect, such as a rope.
* The default value 0 means the body does not belong to a group, and can interact with all other bodies.
*
* @property groupId
* @type number
* @default 0
*/
/**
* A `Number` that specifies a tollerance on how far a body is allowed to 'sink' or rotate 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.
*
* @property slop
* @type number
* @default 0.05
*/
/**
* 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.
*
* @property timeScale
* @type number
* @default 1
*/
/**
* An `Object` that defines the rendering properties to be consumed by the module `Matter.Render`.
*
* @property render
* @type object
*/
/**
* A flag that indicates if the body should be rendered.
*
* @property render.visible
* @type boolean
* @default true
*/
/**
* An `Object` that defines the sprite properties to use when rendering, if any.
*
* @property render.sprite
* @type object
*/
/**
* An `String` that defines the path to the image to use as the sprite texture, if any.
*
* @property render.sprite.texture
* @type string
*/
/**
* A `Number` that defines the scaling in the x-axis for the sprite, if any.
*
* @property render.sprite.xScale
* @type number
* @default 1
*/
/**
* A `Number` that defines the scaling in the y-axis for the sprite, if any.
*
* @property render.sprite.yScale
* @type number
* @default 1
*/
/**
* A `Number` that defines the line width to use when rendering the body outline (if a sprite is not defined).
* A value of `0` means no outline will be rendered.
*
* @property render.lineWidth
* @type number
* @default 1.5
*/
/**
* A `String` that defines the fill style to use when rendering the body (if a sprite is not defined).
* It is the same as when using a canvas, so it accepts CSS style property values.
*
* @property render.fillStyle
* @type string
* @default a random colour
*/
/**
* A `String` that defines the stroke style to use when rendering the body outline (if a sprite is not defined).
* It is the same as when using a canvas, so it accepts CSS style property values.
*
* @property render.strokeStyle
* @type string
* @default a random colour
*/
/**
* 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`.
* They are constantly updated by `Body.update` during the simulation.
*
* @property axes
* @type vector[]
*/
/**
* A `Number` that _measures_ the area of the body's convex hull, calculated at creation by `Body.create`.
*
* @property area
* @type string
* @default
*/
/**
* 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.
*
* @property bounds
* @type bounds
*/
})();

107
src/body/Composite.js
View file

@ -1,4 +1,9 @@
/**
* The `Matter.Composite` module contains methods for creating and manipulating composite bodies.
* A composite body is a collection of `Matter.Body`, `Matter.Constraint` and other `Matter.Composite`, therefore composites form a tree structure.
* It is important to use the functions in this module to modify composites, rather than directly modifying their properties.
* Note that the `Matter.World` object is also a type of `Matter.Composite` and as such all composite methods here can also operate on a `Matter.World`.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -12,9 +17,10 @@ var Composite = {};
(function() {
/**
* Description
* Creates a new composite. The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {} options
* @param {} [options]
* @return {composite} A new composite
*/
Composite.create = function(options) {
@ -37,8 +43,8 @@ var Composite = {};
* @method setModified
* @param {composite} composite
* @param {boolean} isModified
* @param {boolean} updateParents
* @param {boolean} updateChildren
* @param {boolean} [updateParents=false]
* @param {boolean} [updateChildren=false]
*/
Composite.setModified = function(composite, isModified, updateParents, updateChildren) {
composite.isModified = isModified;
@ -95,7 +101,7 @@ var Composite = {};
* @method remove
* @param {composite} composite
* @param {} object
* @param {boolean} deep
* @param {boolean} [deep=false]
* @return {composite} The original composite with the objects removed
*/
Composite.remove = function(composite, object, deep) {
@ -126,7 +132,7 @@ var Composite = {};
};
/**
* Description
* Adds a composite to the given composite
* @method addComposite
* @param {composite} compositeA
* @param {composite} compositeB
@ -144,7 +150,7 @@ var Composite = {};
* @method removeComposite
* @param {composite} compositeA
* @param {composite} compositeB
* @param {boolean} deep
* @param {boolean} [deep=false]
* @return {composite} The original compositeA with the composite removed
*/
Composite.removeComposite = function(compositeA, compositeB, deep) {
@ -177,7 +183,7 @@ var Composite = {};
};
/**
* Description
* Adds a body to the given composite
* @method addBody
* @param {composite} composite
* @param {body} body
@ -194,7 +200,7 @@ var Composite = {};
* @method removeBody
* @param {composite} composite
* @param {body} body
* @param {boolean} deep
* @param {boolean} [deep=false]
* @return {composite} The original composite with the body removed
*/
Composite.removeBody = function(composite, body, deep) {
@ -227,7 +233,7 @@ var Composite = {};
};
/**
* Description
* Adds a constraint to the given composite
* @method addConstraint
* @param {composite} composite
* @param {constraint} constraint
@ -244,7 +250,7 @@ var Composite = {};
* @method removeConstraint
* @param {composite} composite
* @param {constraint} constraint
* @param {boolean} deep
* @param {boolean} [deep=false]
* @return {composite} The original composite with the constraint removed
*/
Composite.removeConstraint = function(composite, constraint, deep) {
@ -281,7 +287,7 @@ var Composite = {};
* @method clear
* @param {world} world
* @param {boolean} keepStatic
* @param {boolean} deep
* @param {boolean} [deep=false]
*/
Composite.clear = function(composite, keepStatic, deep) {
if (deep) {
@ -416,4 +422,81 @@ var Composite = {};
return composite;
};
/*
*
* Properties Documentation
*
*/
/**
* An integer `Number` uniquely identifying number generated in `Composite.create` by `Common.nextId`.
*
* @property id
* @type number
*/
/**
* A `String` denoting the type of object.
*
* @property type
* @type string
* @default "composite"
*/
/**
* An arbitrary `String` name to help the user identify and manage composites.
*
* @property label
* @type string
* @default "Composite"
*/
/**
* A flag that specifies whether the composite has been modified during the current step.
* Most `Matter.Composite` methods will automatically set this flag to `true` to inform the engine of changes to be handled.
* If you need to change it manually, you should use the `Composite.setModified` method.
*
* @property isModified
* @type boolean
* @default false
*/
/**
* The `Composite` that is the parent of this composite. It is automatically managed by the `Matter.Composite` methods.
*
* @property parent
* @type composite
* @default null
*/
/**
* An array of `Body` that are _direct_ children of this composite.
* To add or remove bodies you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
* If you wish to recursively find all descendants, you should use the `Composite.allBodies` method.
*
* @property bodies
* @type body[]
* @default []
*/
/**
* An array of `Constraint` that are _direct_ children of this composite.
* To add or remove constraints you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
* If you wish to recursively find all descendants, you should use the `Composite.allConstraints` method.
*
* @property constraints
* @type constraint[]
* @default []
*/
/**
* An array of `Composite` that are _direct_ children of this composite.
* To add or remove composites you should use `Composite.add` and `Composite.remove` methods rather than directly modifying this property.
* If you wish to recursively find all descendants, you should use the `Composite.allComposites` method.
*
* @property composites
* @type composite[]
* @default []
*/
})();

17
src/body/World.js
View file

@ -1,4 +1,10 @@
/**
* The `Matter.World` module contains methods for creating and manipulating the world composite.
* A `Matter.World` is a `Matter.Composite` body, which is a collection of `Matter.Body`, `Matter.Constraint` and other `Matter.Composite`.
* A `Matter.World` has a few additional properties including `gravity` and `bounds`.
* It is important to use the functions in the `Matter.Composite` module to modify the world composite, rather than directly modifying its properties.
* There are also a few methods here that alias those in `Matter.Composite` for easier readability.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -10,7 +16,8 @@ var World = {};
(function() {
/**
* Description
* Creates a new world composite. The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @constructor
* @param {} options
@ -35,14 +42,14 @@ var World = {};
// see src/module/Outro.js for these aliases:
/**
* An alias for Composite.clear since World is also a Composite (see Outro.js)
* An alias for Composite.clear since World is also a Composite
* @method clear
* @param {world} world
* @param {boolean} keepStatic
*/
/**
* An alias for Composite.add since World is also a Composite (see Outro.js)
* An alias for Composite.add since World is also a Composite
* @method addComposite
* @param {world} world
* @param {composite} composite
@ -50,7 +57,7 @@ var World = {};
*/
/**
* An alias for Composite.addBody since World is also a Composite (see Outro.js)
* An alias for Composite.addBody since World is also a Composite
* @method addBody
* @param {world} world
* @param {body} body
@ -58,7 +65,7 @@ var World = {};
*/
/**
* An alias for Composite.addConstraint since World is also a Composite (see Outro.js)
* An alias for Composite.addConstraint since World is also a Composite
* @method addConstraint
* @param {world} world
* @param {constraint} constraint

7
src/collision/Query.js
View file

@ -1,5 +1,5 @@
/**
* Functions for performing collision queries
* The `Matter.Query` module contains methods for performing collision queries.
*
* @class Query
*/
@ -14,6 +14,7 @@ var Query = {};
* @param {body[]} bodies
* @param {vector} startPoint
* @param {vector} endPoint
* @param {number} [rayWidth]
* @return {object[]} Collisions
*/
Query.ray = function(bodies, startPoint, endPoint, rayWidth) {
@ -42,11 +43,11 @@ var Query = {};
};
/**
* Returns all bodies whose bounds are inside (or outside if set) the given set of bounds, from the given set of bodies
* Returns all bodies whose bounds are inside (or outside if set) the given set of bounds, from the given set of bodies.
* @method region
* @param {body[]} bodies
* @param {bounds} bounds
* @param {bool} outside
* @param {bool} [outside=false]
* @return {body[]} The bodies matching the query
*/
Query.region = function(bodies, bounds, outside) {

123
src/constraint/Constraint.js
View file

@ -1,4 +1,8 @@
/**
* 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.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -21,7 +25,9 @@ var Constraint = {};
_minDifference = 0.001;
/**
* Description
* Creates a new constraint.
* All properties have default values, and many are pre-calculated automatically based on other properties.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {} options
* @return {constraint} constraint
@ -65,6 +71,7 @@ var Constraint = {};
/**
* Description
* @private
* @method solveAll
* @param {constraint[]} constraints
* @param {number} timeScale
@ -77,6 +84,7 @@ var Constraint = {};
/**
* Description
* @private
* @method solve
* @param {constraint} constraint
* @param {number} timeScale
@ -231,6 +239,7 @@ var Constraint = {};
/**
* Performs body updates required after solving constraints
* @private
* @method postSolveAll
* @param {body[]} bodies
*/
@ -255,4 +264,116 @@ var Constraint = {};
}
};
/*
*
* Properties Documentation
*
*/
/**
* An integer `Number` uniquely identifying number generated in `Composite.create` by `Common.nextId`.
*
* @property id
* @type number
*/
/**
* A `String` denoting the type of object.
*
* @property type
* @type string
* @default "constraint"
*/
/**
* An arbitrary `String` name to help the user identify and manage bodies.
*
* @property label
* @type string
* @default "Constraint"
*/
/**
* An `Object` that defines the rendering properties to be consumed by the module `Matter.Render`.
*
* @property render
* @type object
*/
/**
* A flag that indicates if the constraint should be rendered.
*
* @property render.visible
* @type boolean
* @default true
*/
/**
* A `Number` that defines the line width to use when rendering the constraint outline.
* A value of `0` means no outline will be rendered.
*
* @property render.lineWidth
* @type number
* @default 2
*/
/**
* A `String` that defines the stroke style to use when rendering the constraint outline.
* It is the same as when using a canvas, so it accepts CSS style property values.
*
* @property render.strokeStyle
* @type string
* @default a random colour
*/
/**
* The first possible `Body` that this constraint is attached to.
*
* @property bodyA
* @type body
* @default null
*/
/**
* The second possible `Body` that this constraint is attached to.
*
* @property bodyB
* @type body
* @default null
*/
/**
* A `Vector` that specifies the offset of the constraint from center of the `constraint.bodyA` if defined, otherwise a world-space position.
*
* @property pointA
* @type vector
* @default { x: 0, y: 0 }
*/
/**
* A `Vector` that specifies the offset of the constraint from center of the `constraint.bodyA` if defined, otherwise a world-space position.
*
* @property pointB
* @type vector
* @default { x: 0, y: 0 }
*/
/**
* 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 `0.2` means the constraint acts like a soft spring.
*
* @property stiffness
* @type number
* @default 1
*/
/**
* A `Number` that specifies the target resting length of the constraint.
* It is calculated automatically in `Constraint.create` from intial positions of the `constraint.bodyA` and `constraint.bodyB`.
*
* @property length
* @type number
*/
})();

55
src/constraint/MouseConstraint.js
View file

@ -1,4 +1,7 @@
/**
* The `Matter.MouseConstraint` module contains methods for creating mouse constraints.
* Mouse constraints are used for allowing user interaction, providing the ability to move bodies via the mouse or touch.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -10,7 +13,9 @@ var MouseConstraint = {};
(function() {
/**
* Description
* Creates a new mouse constraint.
* All properties have default values, and many are pre-calculated automatically based on other properties.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {engine} engine
* @param {} options
@ -51,7 +56,8 @@ var MouseConstraint = {};
};
/**
* Description
* Updates the given mouse constraint.
* @private
* @method update
* @param {MouseConstraint} mouseConstraint
* @param {body[]} bodies
@ -85,4 +91,49 @@ var MouseConstraint = {};
}
};
/*
*
* Properties Documentation
*
*/
/**
* A `String` denoting the type of object.
*
* @property type
* @type string
* @default "constraint"
*/
/**
* The `Mouse` instance in use.
*
* @property mouse
* @type mouse
* @default engine.input.mouse
*/
/**
* The `Body` that is currently being moved by the user, or `null` if no body.
*
* @property dragBody
* @type body
* @default null
*/
/**
* The `Vector` offset at which the drag started relative to the `dragBody`, if any.
*
* @property dragPoint
* @type body
* @default null
*/
/**
* The `Constraint` object that is used to move the body during interaction.
*
* @property constraint
* @type constraint
*/
})();

139
src/core/Engine.js
View file

@ -1,12 +1,13 @@
/**
* The `Matter.Engine` module contains methods for creating and manipulating engines.
* An engine is a controller that manages updating and rendering the simulation of the world.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
* @class Engine
*/
// TODO: viewports
var Engine = {};
(function() {
@ -20,10 +21,12 @@ var Engine = {};
|| function(callback){ window.setTimeout(function() { callback(Common.now()); }, _delta); };
/**
* Description
* Creates a new engine. 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.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {HTMLElement} element
* @param {object} options
* @param {object} [options]
* @return {engine} engine
*/
Engine.create = function(element, options) {
@ -178,8 +181,7 @@ var Engine = {};
* @method update
* @param {engine} engine
* @param {number} delta
* @param {number} correction
* @return engine
* @param {number} [correction]
*/
Engine.update = function(engine, delta, correction) {
correction = (typeof correction !== 'undefined') ? correction : 1;
@ -298,7 +300,7 @@ var Engine = {};
};
/**
* Description
* Merges two engines by keeping the configuration of `engineA` but replacing the world with the one from `engineB`.
* @method merge
* @param {engine} engineA
* @param {engine} engineB
@ -322,7 +324,7 @@ var Engine = {};
};
/**
* Description
* Clears the engine including the world, pairs and broadphase.
* @method clear
* @param {engine} engine
*/
@ -538,4 +540,125 @@ var Engine = {};
* @param {} event.name The name of the event
*/
/*
*
* Properties Documentation
*
*/
/**
* A flag that specifies whether the engine is running or not.
*
* @property enabled
* @type boolean
* @default true
*/
/**
* An integer `Number` that specifies the number of position iterations to perform each update.
* The higher the value, the higher quality the simulation will be at the expense of performance.
*
* @property positionIterations
* @type number
* @default 6
*/
/**
* An integer `Number` that specifies the number of velocity iterations to perform each update.
* The higher the value, the higher quality the simulation will be at the expense of performance.
*
* @property velocityIterations
* @type number
* @default 4
*/
/**
* An integer `Number` that specifies the number of constraint iterations to perform each update.
* The higher the value, the higher quality the simulation will be at the expense of performance.
* The default value of `2` is usually very adequate.
*
* @property constraintIterations
* @type number
* @default 2
*/
/**
* A flag that specifies whether the engine should allow sleeping via the `Matter.Sleeping` module.
* Sleeping can improve stability and performance, but often at the expense of accuracy.
*
* @property enableSleeping
* @type boolean
* @default false
*/
/**
* An `Object` containing properties regarding the timing systems of the engine.
*
* @property timing
* @type object
*/
/**
* A `Number` that specifies the global scaling factor of time for all bodies.
* A value of `0` freezes the simulation.
* A value of `0.1` gives a slow-motion effect.
* A value of `1.2` gives a speed-up effect.
*
* @property timing.timeScale
* @type number
* @default 1
*/
/**
* A `Number` that specifies the current simulation-time in milliseconds starting from `0`.
* It is incremented on every `Engine.update` by the `timing.delta`.
*
* @property timing.timestamp
* @type number
* @default 0
*/
/**
* A `Number` that specifies the time step between updates in milliseconds.
* If `engine.timing.isFixed` is set to `true`, then `delta` is fixed.
* If it is `false`, then `delta` can dynamically change to maintain the correct apparant simulation speed.
*
* @property timing.delta
* @type number
* @default 1000 / 60
*/
/**
* A `Number` that specifies the time correction factor to apply to the current timestep.
* It is automatically handled when using `Engine.run`, but is also only optional even if you use your own game loop.
* The value is defined as `delta / lastDelta`, i.e. the percentage change of `delta` between steps.
* This value is always `1` (no correction) when frame rate is constant or `engine.timing.isFixed` is `true`.
* If the framerate and hence `delta` are changing, then correction should be applied to the current update to account for the change.
* See the paper on <a href="http://lonesock.net/article/verlet.html">Time Corrected Verlet</a> for more information.
*
* @property timing.correction
* @type number
* @default 1
*/
/**
* An instance of a `Render` controller. The default value is a `Matter.Render` instance created by `Engine.create`.
* One may also develop a custom renderer module based on `Matter.Render` and pass an instance of it to `Engine.create` via `options.render`.
*
* A minimal custom renderer object must define at least three functions: `create`, `clear` and `world` (see `Matter.Render`).
* It is also possible to instead pass the _module_ reference via `options.render.controller` and `Engine.create` will instantiate one for you.
*
* @property render
* @type render
* @default a Matter.Render instance
*/
/**
* A `World` composite object that will contain all simulated bodies and constraints.
*
* @property world
* @type world
* @default a Matter.World instance
*/
})();

6
src/core/Events.js
View file

@ -10,7 +10,7 @@ var Events = {};
(function() {
/**
* Subscribes a callback function to the given object's eventName
* Subscribes a callback function to the given object's `eventName`.
* @method on
* @param {} object
* @param {string} eventNames
@ -31,7 +31,7 @@ var Events = {};
};
/**
* Removes the given event callback. If no callback, clears all callbacks in eventNames. If no eventNames, clears all events.
* Removes the given event callback. If no callback, clears all callbacks in `eventNames`. If no `eventNames`, clears all events.
* @method off
* @param {} object
* @param {string} eventNames
@ -67,7 +67,7 @@ var Events = {};
};
/**
* Fires all the callbacks subscribed to the given object's eventName, in the order they subscribed, if any
* Fires all the callbacks subscribed to the given object's `eventName`, in the order they subscribed, if any.
* @method trigger
* @param {} object
* @param {string} eventNames

27
src/factory/Bodies.js
View file

@ -1,4 +1,7 @@
/**
* The `Matter.Bodies` module contains factory methods for creating rigid body models
* with commonly used body configurations (such as rectangles, circles and other polygons).
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -12,13 +15,15 @@ var Bodies = {};
(function() {
/**
* Description
* Creates a new rigid body model with a rectangle hull.
* The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
* @method rectangle
* @param {number} x
* @param {number} y
* @param {number} width
* @param {number} height
* @param {object} options
* @param {object} [options]
* @return {body} A new rectangle body
*/
Bodies.rectangle = function(x, y, width, height, options) {
@ -41,14 +46,16 @@ var Bodies = {};
};
/**
* Description
* Creates a new rigid body model with a trapezoid hull.
* The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
* @method trapezoid
* @param {number} x
* @param {number} y
* @param {number} width
* @param {number} height
* @param {number} slope
* @param {object} options
* @param {object} [options]
* @return {body} A new trapezoid body
*/
Bodies.trapezoid = function(x, y, width, height, slope, options) {
@ -78,12 +85,14 @@ var Bodies = {};
};
/**
* Description
* Creates a new rigid body model with a circle hull.
* The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
* @method circle
* @param {number} x
* @param {number} y
* @param {number} radius
* @param {object} options
* @param {object} [options]
* @param {number} maxSides
* @return {body} A new circle body
*/
@ -107,13 +116,15 @@ var Bodies = {};
};
/**
* Description
* Creates a new rigid body model with a regular polygon hull with the given number of sides.
* The options parameter is an object that specifies any properties you wish to override the defaults.
* See the properites section of the `Matter.Body` module for detailed information on what you can pass via the `options` object.
* @method polygon
* @param {number} x
* @param {number} y
* @param {number} sides
* @param {number} radius
* @param {object} options
* @param {object} [options]
* @return {body} A new regular polygon body
*/
Bodies.polygon = function(x, y, sides, radius, options) {

40
src/geometry/Vector.js
View file

@ -1,4 +1,8 @@
/**
* The `Matter.Vector` module contains methods for creating and manipulating vectors.
* Vectors are the basis of all the geometry related operations in the engine.
* A `Matter.Vector` object is of the form `{ x: 0, y: 0 }`.
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -12,7 +16,7 @@ var Vector = {};
(function() {
/**
* Description
* Returns the magnitude (length) of a vector.
* @method magnitude
* @param {vector} vector
* @return {number} The magnitude of the vector
@ -22,7 +26,7 @@ var Vector = {};
};
/**
* Description
* Returns the magnitude (length) of a vector (therefore saving a `sqrt` operation).
* @method magnitudeSquared
* @param {vector} vector
* @return {number} The squared magnitude of the vector
@ -32,11 +36,11 @@ var Vector = {};
};
/**
* Description
* Rotates the vector about (0, 0) by specified angle.
* @method rotate
* @param {vector} vector
* @param {number} angle
* @return {vector} A new vector rotated
* @return {vector} A new vector rotated about (0, 0)
*/
Vector.rotate = function(vector, angle) {
var cos = Math.cos(angle), sin = Math.sin(angle);
@ -47,7 +51,7 @@ var Vector = {};
};
/**
* Description
* Rotates the vector about a specified point by specified angle.
* @method rotateAbout
* @param {vector} vector
* @param {number} angle
@ -63,7 +67,7 @@ var Vector = {};
};
/**
* Description
* Normalises a vector (such that its magnitude is `1`).
* @method normalise
* @param {vector} vector
* @return {vector} A new vector normalised
@ -76,7 +80,7 @@ var Vector = {};
};
/**
* Description
* Returns the dot-product of two vectors.
* @method dot
* @param {vector} vectorA
* @param {vector} vectorB
@ -87,7 +91,7 @@ var Vector = {};
};
/**
* Description
* Returns the cross-product of two vectors.
* @method cross
* @param {vector} vectorA
* @param {vector} vectorB
@ -98,29 +102,29 @@ var Vector = {};
};
/**
* Description
* Adds the two vectors.
* @method add
* @param {vector} vectorA
* @param {vector} vectorB
* @return {vector} A new vector added
* @return {vector} A new vector of vectorA and vectorB added
*/
Vector.add = function(vectorA, vectorB) {
return { x: vectorA.x + vectorB.x, y: vectorA.y + vectorB.y };
};
/**
* Description
* Subtracts the two vectors.
* @method sub
* @param {vector} vectorA
* @param {vector} vectorB
* @return {vector} A new vector subtracted
* @return {vector} A new vector of vectorA and vectorB subtracted
*/
Vector.sub = function(vectorA, vectorB) {
return { x: vectorA.x - vectorB.x, y: vectorA.y - vectorB.y };
};
/**
* Description
* Multiplies a vector and a scalar.
* @method mult
* @param {vector} vector
* @param {number} scalar
@ -131,7 +135,7 @@ var Vector = {};
};
/**
* Description
* Divides a vector and a scalar.
* @method div
* @param {vector} vector
* @param {number} scalar
@ -142,10 +146,10 @@ var Vector = {};
};
/**
* Description
* Returns the perpendicular vector. Set `negate` to true for the perpendicular in the opposite direction.
* @method perp
* @param {vector} vector
* @param {bool} negate
* @param {bool} [negate=false]
* @return {vector} The perpendicular vector
*/
Vector.perp = function(vector, negate) {
@ -154,7 +158,7 @@ var Vector = {};
};
/**
* Description
* Negates both components of a vector such that it points in the opposite direction.
* @method neg
* @param {vector} vector
* @return {vector} The negated vector
@ -164,7 +168,7 @@ var Vector = {};
};
/**
* Returns the angle in radians between the two vectors relative to the x-axis
* Returns the angle in radians between the two vectors relative to the x-axis.
* @method angle
* @param {vector} vectorA
* @param {vector} vectorB

30
src/geometry/Vertices.js
View file

@ -1,4 +1,8 @@
/**
* The `Matter.Vertices` module contains methods for creating and manipulating sets of vertices.
* A set of vertices is an array of `Matter.Vector` with additional indexing properties inserted by `Vertices.create`.
* A `Matter.Body` maintains a set of vertices to represent the shape of the object (its convex hull).
*
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
*
@ -12,7 +16,13 @@ var Vertices = {};
(function() {
/**
* Description
* Creates a new set of `Matter.Body` compatible vertices.
* The `vertices` argument accepts an array of `Matter.Vector` orientated around the origin `(0, 0)`, for example:
*
* [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
*
* The `Vertices.create` method then inserts additional indexing properties required for efficient collision detection routines.
*
* @method create
* @param {vertices} vertices
* @param {body} body
@ -25,7 +35,7 @@ var Vertices = {};
};
/**
* Description
* Parses a _simple_ SVG-style path into a set of `Matter.Vector` points.
* @method fromPath
* @param {string} path
* @return {vertices} vertices
@ -42,7 +52,7 @@ var Vertices = {};
};
/**
* Description
* Returns the centre (centroid) of the set of vertices.
* @method centre
* @param {vertices} vertices
* @return {vector} The centre point
@ -65,7 +75,7 @@ var Vertices = {};
};
/**
* Description
* Returns the area of the set of vertices.
* @method area
* @param {vertices} vertices
* @param {bool} signed
@ -87,11 +97,11 @@ var Vertices = {};
};
/**
* Description
* Returns the moment of inertia (second moment of area) of the set of vertices given the total mass.
* @method inertia
* @param {vertices} vertices
* @param {number} mass
* @return {number} The polygon's moment of inertia, using second moment of area
* @return {number} The polygon's moment of inertia
*/
Vertices.inertia = function(vertices, mass) {
var numerator = 0,
@ -113,7 +123,7 @@ var Vertices = {};
};
/**
* Description
* Translates the set of vertices in-place.
* @method translate
* @param {vertices} vertices
* @param {vector} vector
@ -135,7 +145,7 @@ var Vertices = {};
};
/**
* Description
* Rotates the set of vertices in-place.
* @method rotate
* @param {vertices} vertices
* @param {number} angle
@ -159,7 +169,7 @@ var Vertices = {};
};
/**
* Description
* Returns `true` if the `point` is inside the set of `vertices`.
* @method contains
* @param {vertices} vertices
* @param {vector} point
@ -178,7 +188,7 @@ var Vertices = {};
};
/**
* Scales the vertices from a point (default is centre)
* Scales the vertices from a point (default is centre) in-place.
* @method scale
* @param {vertices} vertices
* @param {number} scaleX

118
src/render/Render.js
View file

@ -1,21 +1,25 @@
/**
* See [Demo.js](https://github.com/liabru/matter-js/blob/master/demo/js/Demo.js)
* and [DemoMobile.js](https://github.com/liabru/matter-js/blob/master/demo/js/DemoMobile.js) for usage examples.
* The `Matter.Render` module is the default `render.controller` used by a `Matter.Engine`.
* This renderer is HTML5 canvas based and supports a number of drawing options including sprites and viewports.
*
* It is possible develop a custom renderer module based on `Matter.Render` and pass an instance of it to `Engine.create` via `options.render`.
* A minimal custom renderer object must define at least three functions: `create`, `clear` and `world` (see `Matter.Render`).
*
* See also `Matter.RenderPixi` for an alternate WebGL, scene-graph based renderer.
*
* @class Render
*/
// TODO: viewports
// TODO: two.js, pixi.js
var Render = {};
(function() {
/**
* Description
* Creates a new renderer. 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.
* See the properites section below for detailed information on what you can pass via the `options` object.
* @method create
* @param {object} options
* @param {object} [options]
* @return {render} A new renderer
*/
Render.create = function(options) {
@ -103,7 +107,8 @@ var Render = {};
};
/**
* Description
* Renders the given `engine`'s `Matter.World` object.
* This is the entry point for all rendering and should be called every time the scene changes.
* @method world
* @param {engine} engine
*/
@ -213,6 +218,7 @@ var Render = {};
/**
* Description
* @private
* @method debug
* @param {engine} engine
* @param {RenderingContext} context
@ -269,6 +275,7 @@ var Render = {};
/**
* Description
* @private
* @method constraints
* @param {constraint[]} constraints
* @param {RenderingContext} context
@ -307,6 +314,7 @@ var Render = {};
/**
* Description
* @private
* @method bodyShadows
* @param {engine} engine
* @param {body[]} bodies
@ -356,6 +364,7 @@ var Render = {};
/**
* Description
* @private
* @method bodies
* @param {engine} engine
* @param {body[]} bodies
@ -432,6 +441,7 @@ var Render = {};
/**
* Optimised method for drawing body wireframes in one pass
* @private
* @method bodyWireframes
* @param {engine} engine
* @param {body[]} bodies
@ -466,6 +476,7 @@ var Render = {};
/**
* Draws body bounds
* @private
* @method bodyBounds
* @param {engine} engine
* @param {body[]} bodies
@ -497,6 +508,7 @@ var Render = {};
/**
* Draws body angle indicators and axes
* @private
* @method bodyAxes
* @param {engine} engine
* @param {body[]} bodies
@ -544,6 +556,7 @@ var Render = {};
/**
* Draws body positions
* @private
* @method bodyPositions
* @param {engine} engine
* @param {body[]} bodies
@ -591,6 +604,7 @@ var Render = {};
/**
* Draws body velocity
* @private
* @method bodyVelocity
* @param {engine} engine
* @param {body[]} bodies
@ -620,6 +634,7 @@ var Render = {};
/**
* Draws body ids
* @private
* @method bodyIds
* @param {engine} engine
* @param {body[]} bodies
@ -642,6 +657,7 @@ var Render = {};
/**
* Description
* @private
* @method collisions
* @param {engine} engine
* @param {pair[]} pairs
@ -708,6 +724,7 @@ var Render = {};
/**
* Description
* @private
* @method grid
* @param {engine} engine
* @param {grid} grid
@ -746,6 +763,7 @@ var Render = {};
/**
* Description
* @private
* @method inspector
* @param {inspector} inspector
* @param {RenderingContext} context
@ -867,4 +885,88 @@ var Render = {};
return image;
};
/*
*
* Properties Documentation
*
*/
/**
* A back-reference to the `Matter.Render` module.
*
* @property controller
* @type render
*/
/**
* A reference to the element where the canvas is to be inserted (if `render.canvas` has not been specified)
*
* @property element
* @type HTMLElement
* @default null
*/
/**
* The canvas element to render to. If not specified, one will be created if `render.element` has been specified.
*
* @property canvas
* @type HTMLCanvasElement
* @default null
*/
/**
* The configuration options of the renderer.
*
* @property options
* @type {}
*/
/**
* The target width in pixels of the `render.canvas` to be created.
*
* @property options.width
* @type number
* @default 800
*/
/**
* The target height in pixels of the `render.canvas` to be created.
*
* @property options.height
* @type number
* @default 600
*/
/**
* A flag that specifies if `render.bounds` should be used when rendering.
*
* @property options.hasBounds
* @type boolean
* @default false
*/
/**
* A `Bounds` object that specifies the drawing view region.
* Rendering will be automatically transformed and scaled to fit within the canvas size (`render.options.width` and `render.options.height`).
* This allows for creating views that can pan or zoom around the scene.
* You must also set `render.options.hasBounds` to `true` to enable bounded rendering.
*
* @property bounds
* @type bounds
*/
/**
* The 2d rendering context from the `render.canvas` element.
*
* @property context
* @type CanvasRenderingContext2D
*/
/**
* The sprite texture cache.
*
* @property textures
* @type {}
*/
})();