Phaser API Documentation

  Version: 
Filter

Manages Lights for a Scene.

Affects the rendering of Game Objects using the Light2D pipeline.

Constructor:

new LightsManager()
Since: 3.0.0

Members

active: boolean
Focus
Focus

Description:

Whether the Lights Manager is enabled.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
ambientColor: Phaser.Display.RGB
Focus
Focus

Description:

The ambient color.

Type:
Since: 3.50.0
Focus
Focus
lights: Array.<Phaser.GameObjects.Light>
Focus
Focus

Description:

The Lights in the Scene.

Type:
Default: []
Since: 3.0.0
Focus
Focus
<readonly> maxLights: number
Focus
Focus

Description:

The maximum number of lights that a single Camera and the lights shader can process. Change this via the maxLights property in your game config, as it cannot be changed at runtime.

Type:
number
Since: 3.15.0
Focus
Focus
<readonly> visibleLights: number
Focus
Focus

Description:

The number of lights that the LightPipeline processed in the previous frame.

Type:
number
Since: 3.50.0
Focus
Focus

Methods

addLight([x], [y], [radius], [rgb], [intensity])
Focus
Focus

Description:

Add a Light.

Parameters:

name type arguments Default description
x number <optional> 0

The horizontal position of the Light.

y number <optional> 0

The vertical position of the Light.

radius number <optional> 128

The radius of the Light.

rgb number <optional> 0xffffff

The integer RGB color of the light.

intensity number <optional> 1

The intensity of the Light.

Returns:
Description:

The Light that was added.

Since: 3.0.0
Focus
Focus
addPointLight(x, y, [color], [radius], [intensity], [attenuation])
Focus
Focus

Description:

Creates a new Point Light Game Object and adds it to the Scene.

Note: This method will only be available if the Point Light Game Object has been built into Phaser.

The Point Light Game Object provides a way to add a point light effect into your game, without the expensive shader processing requirements of the traditional Light Game Object.

The difference is that the Point Light renders using a custom shader, designed to give the impression of a point light source, of variable radius, intensity and color, in your game. However, unlike the Light Game Object, it does not impact any other Game Objects, or use their normal maps for calcuations. This makes them extremely fast to render compared to Lights and perfect for special effects, such as flickering torches or muzzle flashes.

For maximum performance you should batch Point Light Game Objects together. This means ensuring they follow each other consecutively on the display list. Ideally, use a Layer Game Object and then add just Point Lights to it, so that it can batch together the rendering of the lights. You don't have to do this, and if you've only a handful of Point Lights in your game then it's perfectly safe to mix them into the dislay list as normal. However, if you're using a large number of them, please consider how they are mixed into the display list.

The renderer will automatically cull Point Lights. Those with a radius that does not intersect with the Camera will be skipped in the rendering list. This happens automatically and the culled state is refreshed every frame, for every camera.

The origin of a Point Light is always 0.5 and it cannot be changed.

Point Lights are a WebGL only feature and do not have a Canvas counterpart.

Parameters:

name type arguments Default description
x number

The horizontal position of this Point Light in the world.

y number

The vertical position of this Point Light in the world.

color number <optional> 0xffffff

The color of the Point Light, given as a hex value.

radius number <optional> 128

The radius of the Point Light.

intensity number <optional> 1

The intensity, or color blend, of the Point Light.

attenuation number <optional> 0.1

The attenuation of the Point Light. This is the reduction of light from the center point.

Returns:
Description:

The Game Object that was created.

Since: 3.50.0
Focus
Focus
destroy()
Focus
Focus

Description:

Destroy the Lights Manager.

Cleans up all references by calling Phaser.GameObjects.LightsManager#shutdown.

Since: 3.0.0
Focus
Focus
disable()
Focus
Focus

Description:

Disable the Lights Manager.

Returns:
Description:

This Lights Manager instance.

Since: 3.0.0
Focus
Focus
enable()
Focus
Focus

Description:

Enable the Lights Manager.

Returns:
Description:

This Lights Manager instance.

Since: 3.0.0
Focus
Focus
getLightCount()
Focus
Focus

Description:

Get the number of Lights managed by this Lights Manager.

Returns:
Description:

The number of Lights managed by this Lights Manager.

Type:
  • number
Since: 3.0.0
Focus
Focus
getLights(camera)
Focus
Focus

Description:

Get all lights that can be seen by the given Camera.

It will automatically cull lights that are outside the world view of the Camera.

If more lights are returned than supported by the pipeline, the lights are then culled based on the distance from the center of the camera. Only those closest are rendered.

Parameters:

name type description
camera Phaser.Cameras.Scene2D.Camera

The Camera to cull Lights for.

Returns:
Description:

The culled Lights.

Type:
Since: 3.50.0
Focus
Focus
getMaxVisibleLights()
Focus
Focus

Description:

Returns the maximum number of Lights allowed to appear at once.

Returns:
Description:

The maximum number of Lights allowed to appear at once.

Type:
  • number
Since: 3.0.0
Focus
Focus
removeLight(light)
Focus
Focus

Description:

Remove a Light.

Parameters:

name type description
light Phaser.GameObjects.Light

The Light to remove.

Returns:
Description:

This Lights Manager instance.

Since: 3.0.0
Focus
Focus
setAmbientColor(rgb)
Focus
Focus

Description:

Set the ambient light color.

Parameters:

name type description
rgb number

The integer RGB color of the ambient light.

Returns:
Description:

This Lights Manager instance.

Since: 3.0.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Shut down the Lights Manager.

Recycles all active Lights into the Light pool, resets ambient light color and clears the lists of Lights and culled Lights.

Since: 3.0.0
Focus
Focus