Show:
API

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

(composite, object)
Composite

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

  • composite Composite
  • object Object | Array

    A single or an array of body(s), constraint(s) or composite(s)

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])
private

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

Properties / Options

The following properties if specified below are for objects created by Matter.Composite.create and may be passed to it as options.

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

Composite.cache

private

An object used for storing cached results for performance reasons. This is used internally only and is automatically managed.

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.

Composite.isModified

Boolean

A flag that specifies whether the composite has been modified during the current step. This is automatically managed when bodies, constraints or composites are added or removed.

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 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.

Callback Parameters

  • 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.

Callback Parameters

  • 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.

Callback Parameters

  • 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.

Callback Parameters

  • 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