Matter.Composite

Defined in: src/body/Composite.js:1

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

CompositeThe original composite with the objects added

@ src/body/Composite.js:69

Matter.Composite.addBody

(composite, body)

→ Compositeprivate

Adds a body to the given composite.

Parameters

Returns

CompositeThe original composite with the body added

@ src/body/Composite.js:209

Matter.Composite.addComposite

(compositeA, compositeB)

→ Compositeprivate

Adds a composite to the given composite.

Parameters

Returns

CompositeThe original compositeA with the objects from compositeB added

@ src/body/Composite.js:155

Matter.Composite.addConstraint

(composite, constraint)

→ Compositeprivate

Adds a constraint to the given composite.

Parameters

Returns

CompositeThe original composite with the constraint added

@ src/body/Composite.js:262

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

@ src/body/Composite.js:342

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

@ src/body/Composite.js:372

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

@ src/body/Composite.js:357

Matter.Composite.bounds

(composite)

→ Bounds

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

Parameters

The composite.

Returns

BoundsThe composite bounds.

@ src/body/Composite.js:536

Matter.Composite.clear

(composite, keepStatic, [deep=false])

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

Parameters

@ src/body/Composite.js:314

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

CompositeA new composite

@ src/body/Composite.js:23

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

ObjectThe requested object, if found

@ src/body/Composite.js:387

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
  • compositeB CompositeB

Returns

CompositeReturns compositeA

@ src/body/Composite.js:421

Matter.Composite.rebase

(composite)

→ Composite

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

Parameters

Returns

CompositeReturns composite

@ src/body/Composite.js:435

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

CompositeThe original composite with the objects removed

@ src/body/Composite.js:114

Matter.Composite.removeBody

(composite, body, [deep=false])

→ Compositeprivate

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

Parameters

Returns

CompositeThe original composite with the body removed

@ src/body/Composite.js:223

Matter.Composite.removeBodyAt

(composite, position)

→ Compositeprivate

Removes a body from the given composite.

Parameters

Returns

CompositeThe original composite with the body removed

@ src/body/Composite.js:248

Matter.Composite.removeComposite

(compositeA, compositeB, [deep=false])

→ Compositeprivate

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

Parameters

Returns

CompositeThe original compositeA with the composite removed

@ src/body/Composite.js:170

Matter.Composite.removeCompositeAt

(composite, position)

→ Compositeprivate

Removes a composite from the given composite.

Parameters

Returns

CompositeThe original composite with the composite removed

@ src/body/Composite.js:195

Matter.Composite.removeConstraint

(composite, constraint, [deep=false])

→ Compositeprivate

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

Parameters

Returns

CompositeThe original composite with the constraint removed

@ src/body/Composite.js:276

Matter.Composite.removeConstraintAt

(composite, position)

→ Compositeprivate

Removes a body from the given composite.

Parameters

Returns

CompositeThe original composite with the constraint removed

@ src/body/Composite.js:300

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

  • [recursive=true] Booloptional

@ src/body/Composite.js:475

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

  • [recursive=true] Booloptional

@ src/body/Composite.js:506

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

  • [updateParents=false] Booleanoptional
  • [updateChildren=false] Booleanoptional

@ src/body/Composite.js:44

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

  • [recursive=true] Booloptional

@ src/body/Composite.js:455

Item Index

Methods

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.

Events

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

@ src/body/Composite.js:648

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

@ src/body/Composite.js:668

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

@ src/body/Composite.js:658

Composite.id

Number

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

@ src/body/Composite.js:606

Composite.isModified

Boolean

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

@ src/body/Composite.js:630

Composite.label

String

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

Default: "Composite"

@ src/body/Composite.js:622

Composite.parent

Composite

The Composite that is the parent of this composite. It is automatically managed by the Matter.Composite methods.

Default: null

@ src/body/Composite.js:640

Composite.plugin

An object reserved for storing plugin-specific properties.

@ src/body/Composite.js:678

Composite.type

String

A String denoting the type of object.

Default: "composite"

@ src/body/Composite.js:613

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:

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

@ src/body/Composite.js:570

Events.on(Composite, "afterRemove", callback)

Fired when a call to Composite.remove is made, after objects have been removed.

Event Payload:

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

@ src/body/Composite.js:590

Events.on(Composite, "beforeAdd", callback)

Fired when a call to Composite.add is made, before objects have been added.

Event Payload:

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

@ src/body/Composite.js:560

Events.on(Composite, "beforeRemove", callback)

Fired when a call to Composite.remove is made, before objects have been removed.

Event Payload:

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

@ src/body/Composite.js:580