Show:

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

(composite, object)
Composite

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.

Parameters

Returns

Composite

The original composite with the objects added

Matter.Composite.addBody

(composite, body)
Composite private

Adds a body to the given composite.

Parameters

Returns

Composite

The original composite with the body added

Matter.Composite.addComposite

(compositeA, compositeB)
Composite private

Adds a composite to the given composite.

Parameters

Returns

Composite

The original compositeA with the objects from compositeB added

Matter.Composite.addConstraint

(composite, constraint)
Composite private

Adds a constraint to the given composite.

Parameters

Returns

Composite

The original composite with the constraint added

Matter.Composite.allBodies

(composite)
Body[]

Returns all bodies in the given composite, including all bodies in its children, recursively.

Parameters

Returns

Body[]

All the bodies

Matter.Composite.allComposites

(composite)
Composite[]

Returns all composites in the given composite, including all composites in its children, recursively.

Parameters

Returns

Composite[]

All the composites

Matter.Composite.allConstraints

(composite)
Constraint[]

Returns all constraints in the given composite, including all constraints in its children, recursively.

Parameters

Returns

Constraint[]

All the constraints

Matter.Composite.bounds

(composite)
Bounds

Returns the union of the bounds of all of the composite's bodies.

Parameters

Returns

Bounds

The composite bounds.

Matter.Composite.clear

(composite, keepStatic, [deep=false])

Removes all bodies, constraints and composites from the given composite. Optionally clearing its children recursively.

Parameters

Matter.Composite.create

([options])
Composite

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

Returns

Composite

A new composite

Matter.Composite.get

(composite, id, type)
Object

Searches the composite recursively for an object matching the type and id supplied, null if not found.

Parameters

Returns

Object

The requested object, if found

Matter.Composite.move

(compositeA, objects, compositeB)
Composite

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

Composite

Returns compositeA

Matter.Composite.rebase

(composite)
Composite

Assigns new ids for all objects in the composite, recursively.

Parameters

Returns

Composite

Returns composite

Matter.Composite.remove

(composite, object, [deep=false])
Composite

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.

Parameters

Returns

Composite

The original composite with the objects removed

Matter.Composite.removeBody

(composite, body, [deep=false])
Composite private

Removes a body from the given composite, and optionally searching its children recursively.

Parameters

Returns

Composite

The original composite with the body removed

Matter.Composite.removeBodyAt

(composite, position)
Composite private

Removes a body from the given composite.

Parameters

Returns

Composite

The original composite with the body removed

Matter.Composite.removeComposite

(compositeA, compositeB, [deep=false])
Composite private

Removes a composite from the given composite, and optionally searching its children recursively.

Parameters

Returns

Composite

The original compositeA with the composite removed

Matter.Composite.removeCompositeAt

(composite, position)
Composite private

Removes a composite from the given composite.

Parameters

Returns

Composite

The original composite with the composite removed

Matter.Composite.removeConstraint

(composite, constraint, [deep=false])
Composite private

Removes a constraint from the given composite, and optionally searching its children recursively.

Parameters

Returns

Composite

The original composite with the constraint removed

Matter.Composite.removeConstraintAt

(composite, position)
Composite private

Removes a body from the given composite.

Parameters

Returns

Composite

The original composite with the constraint removed

Matter.Composite.rotate

(composite, rotation, point, [recursive=true])

Rotates all children in the composite by a given angle about the given point, without imparting any angular velocity.

Parameters

Matter.Composite.scale

(composite, scaleX, scaleY, point, [recursive=true])

Scales all children in the composite, including updating physical properties (mass, area, axes, inertia), from a world-space point.

Parameters

Matter.Composite.setModified

(composite, isModified, [updateParents=false], [updateChildren=false])

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

(composite, translation, [recursive=true])

Translates all children in the composite by a given vector relative to their current positions, without imparting any velocity.

Parameters

Item Index

Properties

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.

Properties

The following properties are specified for objects created by Matter.Composite.create and for objects passed to it via the options argument.

Composite.bodies

Body[]

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: []

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: []

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: []

Composite.id

Number

An integer Number uniquely identifying number generated in Composite.create by Common.nextId.

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.

Default: false

Composite.label

String

An arbitrary String name to help the user identify and manage composites.

Default: "Composite"

Composite.parent

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.

Composite.type

String

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 Object

    An 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 Object

    An 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 Object

    An 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 Object

    An 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

0.13.0