Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Physics . Matter . TileBody

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Physics . Matter . TileBody

A wrapper around a Tile that provides access to a corresponding Matter body. A tile can only have one Matter body associated with it. You can either pass in an existing Matter body for the tile or allow the constructor to create the corresponding body for you. If the Tile has a collision group (defined in Tiled), those shapes will be used to create the body. If not, the tile's rectangle bounding box will be used.

The corresponding body will be accessible on the Tile itself via Tile.physics.matterBody.

Note: not all Tiled collision shapes are supported. See Phaser.Physics.Matter.TileBody#setFromTileCollision for more information.

Constructor:

new TileBody(world, tile, [options])

Parameters:

name type arguments description
world Phaser.Physics.Matter.World

The Matter world instance this body belongs to.

tile Phaser.Tilemaps.Tile

The target tile that should have a Matter body.

options Phaser.Types.Physics.Matter.MatterTileOptions <optional>

Options to be used when creating the Matter body.

Since: 3.0.0

Extends


Members

<readonly> centerOfMass: Phaser.Math.Vector2
Focus
Focus

Description:

The body's center of mass.

Calling this creates a new `Vector2 each time to avoid mutation.

If you only need to read the value and won't change it, you can get it from GameObject.body.centerOfMass.

Type:
Inherited from: Phaser.Physics.Matter.Components.Mass#centerOfMass
Since: 3.10.0
Focus
Focus

Description:

The tile object the body is associated with.

Type:
Since: 3.0.0
Focus
Focus

Description:

The Matter world the body exists within.

Type:
Since: 3.0.0
Focus
Focus

Methods

addListener(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#addListener
Examples:
Since: 3.0.0
Focus
Focus
destroy()
Focus
Focus

Description:

Removes the current body from the tile and the world.

Returns:
Description:

This TileBody object.

Overrides: Phaser.Events.EventEmitter#destroy
Examples:
Since: 3.0.0
Focus
Focus
emit(event, [args])
Focus
Focus

Description:

Calls each of the listeners registered for a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

args * <optional>

Additional arguments that will be passed to the event handler.

Returns:
Description:

true if the event had listeners, else false.

Type:
  • boolean
Inherited from: Phaser.Events.EventEmitter#emit
Examples:
Since: 3.0.0
Focus
Focus
eventNames()
Focus
Focus

Description:

Return an array listing the events for which the emitter has registered listeners.

Type:
  • Array.<(string
  • symbol)>
Inherited from: Phaser.Events.EventEmitter#eventNames
Examples:
Since: 3.0.0
Focus
Focus
isSensor()
Focus
Focus

Description:

Is the body belonging to this Game Object a sensor or not?

Returns:
Description:

true if the body is a sensor, otherwise false.

Type:
  • boolean
Inherited from: Phaser.Physics.Matter.Components.Sensor#isSensor
Examples:
Since: 3.0.0
Focus
Focus
isStatic()
Focus
Focus

Description:

Returns true if the body is static, otherwise false for a dynamic body.

Returns:
Description:

true if the body is static, otherwise false.

Type:
  • boolean
Inherited from: Phaser.Physics.Matter.Components.Static#isStatic
Examples:
Since: 3.0.0
Focus
Focus
listenerCount(event)
Focus
Focus

Description:

Return the number of listeners listening to a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The number of listeners.

Type:
  • number
Inherited from: Phaser.Events.EventEmitter#listenerCount
Examples:
Since: 3.0.0
Focus
Focus
listeners(event)
Focus
Focus

Description:

Return the listeners registered for a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The registered listeners.

Type:
  • Array.
Inherited from: Phaser.Events.EventEmitter#listeners
Examples:
Since: 3.0.0
Focus
Focus
off(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#off
Examples:
Since: 3.0.0
Focus
Focus
on(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#on
Examples:
Since: 3.0.0
Focus
Focus
once(event, fn, [context])
Focus
Focus

Description:

Add a one-time listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#once
Examples:
Since: 3.0.0
Focus
Focus
removeAllListeners([event])
Focus
Focus

Description:

Remove all listeners, or those of the specified event.

Parameters:

name type arguments description
event string | symbol <optional>

The event name.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeAllListeners
Examples:
Since: 3.0.0
Focus
Focus
removeBody()
Focus
Focus

Description:

Removes the current body from the TileBody and from the Matter world

Returns:
Description:

This TileBody object.

Examples:
Since: 3.0.0
Focus
Focus
removeListener(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeListener
Examples:
Since: 3.0.0
Focus
Focus
setAwake()
Focus
Focus

Description:

Wakes this Body if asleep.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setAwake
Examples:
Since: 3.22.0
Focus
Focus
setBody(body, [addToWorld])
Focus
Focus

Description:

Sets the current body to the given body. This will remove the previous body, if one already exists.

Parameters:

name type arguments Default description
body MatterJS.BodyType

The new Matter body to use.

addToWorld boolean <optional> true

Whether or not to add the body to the Matter world.

Returns:
Description:

This TileBody object.

Examples:
Since: 3.0.0
Focus
Focus
setBounce(value)
Focus
Focus

Description:

Sets the restitution on the physics object.

Parameters:

name type description
value number

A Number that defines the restitution (elasticity) of the body. The value is always positive and is in the range (0, 1). A value of 0 means collisions may be perfectly inelastic and no bouncing may occur. A value of 0.8 means the body may bounce back with approximately 80% of its kinetic energy. Note that collision response is based on pairs of bodies, and that restitution values are combined with the following formula: Math.max(bodyA.restitution, bodyB.restitution)

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Bounce#setBounce
Examples:
Since: 3.0.0
Focus
Focus
setCollidesWith(categories)
Focus
Focus

Description:

Sets the collision mask for this Game Object's Matter Body. Two Matter Bodies with different collision groups will only collide if each one includes the other's category in its mask based on a bitwise AND, i.e. (categoryA & maskB) !== 0 and (categoryB & maskA) !== 0 are both true.

Parameters:

name type description
categories number | Array.<number>

A unique category bitfield, or an array of them.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setCollidesWith
Examples:
Focus
Focus
setCollisionCategory(value)
Focus
Focus

Description:

Sets the collision category of this Game Object's Matter Body. This number must be a power of two between 2^0 (= 1) and 2^31. Two bodies with different collision groups (see #setCollisionGroup) will only collide if their collision categories are included in their collision masks (see #setCollidesWith).

Parameters:

name type description
value number

Unique category bitfield.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setCollisionCategory
Examples:
Focus
Focus
setCollisionGroup(value)
Focus
Focus

Description:

Sets the collision group of this Game Object's Matter Body. If this is zero or two Matter Bodies have different values, they will collide according to the usual rules (see #setCollisionCategory and #setCollisionGroup). If two Matter Bodies have the same positive value, they will always collide; if they have the same negative value, they will never collide.

Parameters:

name type description
value number

Unique group index.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setCollisionGroup
Examples:
Focus
Focus
setDensity(value)
Focus
Focus

Description:

Sets density of the body.

Parameters:

name type description
value number

The new density of the body.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Mass#setDensity
Examples:
Since: 3.0.0
Focus
Focus
setFriction(value, [air], [fstatic])
Focus
Focus

Description:

Sets new friction values for this Game Object's Matter Body.

Parameters:

name type arguments description
value number

The new friction of the body, between 0 and 1, where 0 allows the Body to slide indefinitely, while 1 allows it to stop almost immediately after a force is applied.

air number <optional>

If provided, the new air resistance of the Body. The higher the value, the faster the Body will slow as it moves through space. 0 means the body has no air resistance.

fstatic number <optional>

If provided, the new static friction of the Body. The higher the value (e.g. 10), the more force it will take to initially get the Body moving when it is nearly stationary. 0 means the body will never "stick" when it is nearly stationary.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Friction#setFriction
Examples:
Since: 3.0.0
Focus
Focus
setFrictionAir(value)
Focus
Focus

Description:

Sets a new air resistance for this Game Object's Matter Body. A value of 0 means the Body will never slow as it moves through space. The higher the value, the faster a Body slows when moving through space.

Parameters:

name type description
value number

The new air resistance for the Body.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Friction#setFrictionAir
Examples:
Since: 3.0.0
Focus
Focus
setFrictionStatic(value)
Focus
Focus

Description:

Sets a new static friction for this Game Object's Matter Body. A value of 0 means the Body will never "stick" when it is nearly stationary. The higher the value (e.g. 10), the more force it will take to initially get the Body moving when it is nearly stationary.

Parameters:

name type description
value number

The new static friction for the Body.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Friction#setFrictionStatic
Examples:
Since: 3.0.0
Focus
Focus
setFromTileCollision([options])
Focus
Focus

Description:

Sets the current body from the collision group associated with the Tile. This is typically set up in Tiled's collision editor.

Note: Matter doesn't support all shapes from Tiled. Rectangles and polygons are directly supported. Ellipses are converted into circle bodies. Polylines are treated as if they are closed polygons. If a tile has multiple shapes, a multi-part body will be created. Concave shapes are supported if poly-decomp library is included. Decomposition is not guaranteed to work for complex shapes (e.g. holes), so it's often best to manually decompose a concave polygon into multiple convex polygons yourself.

Parameters:

name type arguments description
options Phaser.Types.Physics.Matter.MatterBodyTileOptions <optional>

Options to be used when creating the Matter body. See MatterJS.Body for a list of what Matter accepts.

Returns:
Description:

This TileBody object.

Examples:
Since: 3.0.0
Focus
Focus
setFromTileRectangle([options])
Focus
Focus

Description:

Sets the current body to a rectangle that matches the bounds of the tile.

Parameters:

name type arguments description
options Phaser.Types.Physics.Matter.MatterBodyTileOptions <optional>

Options to be used when creating the Matter body. See MatterJS.Body for a list of what Matter accepts.

Returns:
Description:

This TileBody object.

Examples:
Since: 3.0.0
Focus
Focus
setIgnoreGravity(value)
Focus
Focus

Description:

A togglable function for ignoring world gravity in real-time on the current body.

Parameters:

name type description
value boolean

Set to true to ignore the effect of world gravity, or false to not ignore it.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Gravity#setIgnoreGravity
Examples:
Since: 3.0.0
Focus
Focus
setMass(value)
Focus
Focus

Description:

Sets the mass of the Game Object's Matter Body.

Parameters:

name type description
value number

The new mass of the body.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Mass#setMass
Examples:
Since: 3.0.0
Focus
Focus
setOnCollide(callback)
Focus
Focus

Description:

The callback is sent a Phaser.Types.Physics.Matter.MatterCollisionData object.

This does not change the bodies collision category, group or filter. Those must be set in addition to the callback.

Parameters:

name type description
callback function

The callback to invoke when this body starts colliding with another.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setOnCollide
Examples:
Since: 3.22.0
Focus
Focus
setOnCollideActive(callback)
Focus
Focus

Description:

The callback is sent a Phaser.Types.Physics.Matter.MatterCollisionData object.

This does not change the bodies collision category, group or filter. Those must be set in addition to the callback.

Parameters:

name type description
callback function

The callback to invoke for the duration of this body colliding with another.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setOnCollideActive
Examples:
Since: 3.22.0
Focus
Focus
setOnCollideEnd(callback)
Focus
Focus

Description:

The callback is sent a Phaser.Types.Physics.Matter.MatterCollisionData object.

This does not change the bodies collision category, group or filter. Those must be set in addition to the callback.

Parameters:

name type description
callback function

The callback to invoke when this body stops colliding with another.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setOnCollideEnd
Examples:
Since: 3.22.0
Focus
Focus
setOnCollideWith(body, callback)
Focus
Focus

Description:

The callback is sent a reference to the other body, along with a Phaser.Types.Physics.Matter.MatterCollisionData object.

This does not change the bodies collision category, group or filter. Those must be set in addition to the callback.

Parameters:

name type description
body MatterJS.Body | Array.<MatterJS.Body>

The body, or an array of bodies, to test for collisions with.

callback function

The callback to invoke when this body collides with the given body or bodies.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Collision#setOnCollideWith
Examples:
Since: 3.22.0
Focus
Focus
setSensor(value)
Focus
Focus

Description:

Set the body belonging to this Game Object to be a sensor. Sensors trigger collision events, but don't react with colliding body physically.

Parameters:

name type description
value boolean

true to set the body as a sensor, or false to disable it.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sensor#setSensor
Examples:
Since: 3.0.0
Focus
Focus
setSleepEndEvent(value)
Focus
Focus

Description:

Enables or disables the Sleep End event for this body.

Parameters:

name type description
value boolean

true to enable the sleep event, or false to disable it.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setSleepEndEvent
Examples:
Since: 3.0.0
Focus
Focus
setSleepEvents(start, end)
Focus
Focus

Description:

Enable sleep and wake events for this body.

By default when a body goes to sleep, or wakes up, it will not emit any events.

The events are emitted by the Matter World instance and can be listened to via the SLEEP_START and SLEEP_END events.

Parameters:

name type description
start boolean

true if you want the sleep start event to be emitted for this body.

end boolean

true if you want the sleep end event to be emitted for this body.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setSleepEvents
Examples:
Since: 3.0.0
Focus
Focus
setSleepStartEvent(value)
Focus
Focus

Description:

Enables or disables the Sleep Start event for this body.

Parameters:

name type description
value boolean

true to enable the sleep event, or false to disable it.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setSleepStartEvent
Examples:
Since: 3.0.0
Focus
Focus
setSleepThreshold([value])
Focus
Focus

Description:

Sets the number of updates in which this body must have near-zero velocity before it is set as sleeping (if sleeping is enabled by the engine).

Parameters:

name type arguments Default description
value number <optional> 60

A Number that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setSleepThreshold
Examples:
Since: 3.0.0
Focus
Focus
setStatic(value)
Focus
Focus

Description:

Changes the physics body to be either static true or dynamic false.

Parameters:

name type description
value boolean

true to set the body as being static, or false to make it dynamic.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Static#setStatic
Examples:
Since: 3.0.0
Focus
Focus
setToSleep()
Focus
Focus

Description:

Sets this Body to sleep.

Returns:
Description:

This Game Object.

Inherited from: Phaser.Physics.Matter.Components.Sleep#setToSleep
Examples:
Since: 3.22.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

Inherited from: Phaser.Events.EventEmitter#shutdown
Examples:
Since: 3.0.0
Focus
Focus