Matter.Composite
A composite is a collection of Matter.Body, Matter.Constraint and other Matter.Composite objects.
They are a container that can represent complex objects made of multiple parts, even if they are not physically connected. A composite could contain anything from a single body all the way up to a whole world.
When making any changes to composites, use the included functions rather than changing their properties directly.
See the included usage examples.
Methods
Matter.Composite.add
Generic single or multi-add function. Adds a single or an array of body(s), constraint(s) or composite(s) to the given composite.
Triggers beforeAdd and afterAdd events on the composite.
Parameters
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
-
compositeComposite -
constraintConstraint
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
-
compositeComposite
Returns
All the bodies
Matter.Composite.allComposites
Returns all composites in the given composite, including all composites in its children, recursively.
Parameters
-
compositeComposite
Returns
All the composites
Matter.Composite.allConstraints
Returns all constraints in the given composite, including all constraints in its children, recursively.
Parameters
-
compositeComposite
Returns
All the constraints
Matter.Composite.bounds
Returns the union of the bounds of all of the composite's bodies.
Parameters
-
compositeCompositeThe 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
-
compositeACompositeA -
objectsObject[] -
compositeBCompositeB
Returns
Returns compositeA
Matter.Composite.rebase
Assigns new ids for all objects in the composite, recursively.
Parameters
-
compositeComposite
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
-
compositeComposite -
constraintConstraint -
[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.
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 Matter.Composite.create and received by 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:
-
eventObjectAn event object
-
objectThe object(s) that have been added (may be a single body, constraint, composite or a mixed array of these)
-
sourceThe source object of the event
-
nameThe 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:
-
eventObjectAn event object
-
objectThe object(s) that have been removed (may be a single body, constraint, composite or a mixed array of these)
-
sourceThe source object of the event
-
nameThe 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:
-
eventObjectAn event object
-
objectThe object(s) to be added (may be a single body, constraint, composite or a mixed array of these)
-
sourceThe source object of the event
-
nameThe 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:
-
eventObjectAn event object
-
objectThe object(s) to be removed (may be a single body, constraint, composite or a mixed array of these)
-
sourceThe source object of the event
-
nameThe name of the event
-