Matter.Composite
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 the included usage examples.
Methods
Matter.Composite.add
Generic add function. Adds one or many body(s), constraint(s) or a composite(s) to the given composite.
Triggers beforeAdd
and afterAdd
events on the composite
.
Returns
The original composite with the objects added
Matter.Composite.addBody
Adds a body to the given composite.
Returns
The original composite with the body added
Matter.Composite.addComposite
Adds a composite to the given composite.
Returns
The original compositeA with the objects from compositeB added
Matter.Composite.addConstraint
Adds a constraint to the given composite.
Parameters
-
composite
Composite -
constraint
Constraint
Returns
The original composite with the constraint added
Matter.Composite.allBodies
Returns all bodies in the given composite, including all bodies in its children, recursively.
Parameters
-
composite
Composite
Returns
All the bodies
Matter.Composite.allComposites
Returns all composites in the given composite, including all composites in its children, recursively.
Parameters
-
composite
Composite
Returns
All the composites
Matter.Composite.allConstraints
Returns all constraints in the given composite, including all constraints in its children, recursively.
Parameters
-
composite
Composite
Returns
All the constraints
Matter.Composite.bounds
Returns the union of the bounds of all of the composite's bodies.
Parameters
-
composite
CompositeThe composite.
Returns
The composite bounds.
Matter.Composite.clear
Removes all bodies, constraints and composites from the given composite. Optionally clearing its children recursively.
Matter.Composite.create
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.
Parameters
-
[options]
Object optional
Returns
A new composite
Matter.Composite.get
Searches the composite recursively for an object matching the type and id supplied, null if not found.
Returns
The requested object, if found
Matter.Composite.move
Moves the given object(s) from compositeA to compositeB (equal to a remove followed by an add).
Parameters
-
compositeA
CompositeA -
objects
Object[] -
compositeB
CompositeB
Returns
Returns compositeA
Matter.Composite.rebase
Assigns new ids for all objects in the composite, recursively.
Parameters
-
composite
Composite
Returns
Returns composite
Matter.Composite.remove
Generic remove function. Removes one or many body(s), constraint(s) or a composite(s) to the given composite.
Optionally searching its children recursively.
Triggers beforeRemove
and afterRemove
events on the composite
.
Returns
The original composite with the objects removed
Matter.Composite.removeBody
Removes a body from the given composite, and optionally searching its children recursively.
Returns
The original composite with the body removed
Matter.Composite.removeBodyAt
Removes a body from the given composite.
Returns
The original composite with the body removed
Matter.Composite.removeComposite
Removes a composite from the given composite, and optionally searching its children recursively.
Returns
The original compositeA with the composite removed
Matter.Composite.removeCompositeAt
Removes a composite from the given composite.
Returns
The original composite with the composite removed
Matter.Composite.removeConstraint
Removes a constraint from the given composite, and optionally searching its children recursively.
Parameters
-
composite
Composite -
constraint
Constraint -
[deep=false]
Boolean optional
Returns
The original composite with the constraint removed
Matter.Composite.removeConstraintAt
Removes a body from the given composite.
Returns
The original composite with the constraint removed
Matter.Composite.rotate
Rotates all children in the composite by a given angle about the given point, without imparting any angular velocity.
Matter.Composite.scale
Scales all children in the composite, including updating physical properties (mass, area, axes, inertia), from a world-space point.
Parameters
Matter.Composite.setModified
Sets the composite's isModified
flag.
If updateParents
is true, all parents will be set (default: false).
If updateChildren
is true, all children will be set (default: false).
Parameters
Matter.Composite.translate
Translates all children in the composite by a given vector relative to their current positions, without imparting any velocity.
Item Index
Methods
Properties / Options
The following properties are specified for objects created by <span class="prefix">Matter.</span>.create
and for objects passed to it via the options
argument.
Events
Properties / Options
The following properties are specified for objects created by Matter.Composite.create
and may be passed to it as options
.
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.
Default: []
Composite.composites
Composite[]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.
Default: []
Composite.constraints
Constraint[]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.
Default: []
An integer Number
uniquely identifying number generated in Composite.create
by Common.nextId
.
Composite.isModified
BooleanA 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.
Default: false
An arbitrary String
name to help the user identify and manage composites.
Default: "Composite"
The Composite
that is the parent of this composite. It is automatically managed by the Matter.Composite
methods.
Default: null
Composite.plugin
An object reserved for storing plugin-specific properties.
A String
denoting the type of object.
Default: "composite"
Events
The following events are emitted by objects created by <span class="prefix">Matter.</span>Composite.create
to objects that have subscribed using Matter.Events.on
.
Events.on(Composite, "afterAdd
", callback)
Fired when a call to Composite.add
is made, after objects have been added.
Event Payload:
-
event
ObjectAn event object
-
object
The object(s) that have been added (may be a single body, constraint, composite or a mixed array of these)
-
source
The source object of the event
-
name
The name of the event
-
Events.on(Composite, "afterRemove
", callback)
Fired when a call to Composite.remove
is made, after objects have been removed.
Event Payload:
-
event
ObjectAn event object
-
object
The object(s) that have been removed (may be a single body, constraint, composite or a mixed array of these)
-
source
The source object of the event
-
name
The name of the event
-
Events.on(Composite, "beforeAdd
", callback)
Fired when a call to Composite.add
is made, before objects have been added.
Event Payload:
-
event
ObjectAn event object
-
object
The object(s) to be added (may be a single body, constraint, composite or a mixed array of these)
-
source
The source object of the event
-
name
The name of the event
-
Events.on(Composite, "beforeRemove
", callback)
Fired when a call to Composite.remove
is made, before objects have been removed.
Event Payload:
-
event
ObjectAn event object
-
object
The object(s) to be removed (may be a single body, constraint, composite or a mixed array of these)
-
source
The source object of the event
-
name
The name of the event
-