LightSystem. LightSystemPlugin

LightSystemPlugin

  • Owns the offscreen lightmap texture, falloff/composite shaders, and the per-frame render pass that multiplies the lightmap onto the WebGL scene
  • The composite is MULTIPLICATIVE: unlit areas get the ambient color, lit areas show the scene tinted by the accumulated light color. So you should draw your world at full brightness — the lightmap handles the darkening.

Constructor

new LightSystemPlugin(textureSizeopt, ambientColoropt)

Create the global light system plugin.

Parameters:
NameTypeAttributesDescription
textureSizeVector2<optional>

Size of the lightmap texture (defaults to following mainCanvasSize, which is css pixels, so the lightmap is not scaled by canvasPixelRatio; pass mainCanvasSize.scale(getCanvasPixelRatio()) for a full resolution lightmap)

ambientColorColor<optional>

Color applied to unlit areas of the scene (defaults to BLACK = pitch dark). Set a small RGB like rgb(0.1,0.1,0.15) for a faint "moonlight" baseline so unlit areas aren't fully black.

Source
Example
// simplest usage
 new LightSystemPlugin();

Members

ambientColor

Properties
TypeDescription
Color

Baseline color applied to unlit areas of the scene. Defaults to BLACK (pitch dark). Set to a small RGB for a faint ambient. The lightmap is cleared to this color each frame, then lights add on top, then the result multiplies the scene.

Source

compositeShader :WebGLProgram|undefined

Type:
  • WebGLProgram | undefined
Properties
TypeDescription
WebGLProgram | undefined

Shader for compositing the lightmap over the main scene

Source

compositeVAO :WebGLVertexArrayObject|undefined

Type:
  • WebGLVertexArrayObject | undefined
Properties
TypeDescription
WebGLVertexArrayObject | undefined

Vertex array object for the composite shader

Source

emissivePass

Properties
TypeDescription
boolean

True while emissive objects draw into the lightmap, read only, see EngineObject.emissive

Source

enabled

Properties
TypeDescription
boolean

When false, the render pass is skipped entirely

Source

lightShader :WebGLProgram|undefined

Type:
  • WebGLProgram | undefined
Properties
TypeDescription
WebGLProgram | undefined

Shader for drawing per-Light falloff blobs into the lightmap

Source

lightVAO :WebGLVertexArrayObject|undefined

Type:
  • WebGLVertexArrayObject | undefined
Properties
TypeDescription
WebGLVertexArrayObject | undefined

Vertex array object for the light shader

Source

shadowContext :OffscreenCanvasRenderingContext2D|undefined

Type:
  • OffscreenCanvasRenderingContext2D | undefined
Properties
TypeDescription
OffscreenCanvasRenderingContext2D | undefined

Where Canvas2D draws go during the shadow and emissive passes, a 1x1 canvas, so text in a render() is not drawn twice

Source

shadowCopyShader :WebGLProgram|undefined

Type:
  • WebGLProgram | undefined
Properties
TypeDescription
WebGLProgram | undefined

Copies the shadow map around a light into its texture

Source

shadowCopyVAO :WebGLVertexArrayObject|undefined

Type:
  • WebGLVertexArrayObject | undefined
Properties
TypeDescription
WebGLVertexArrayObject | undefined

Vertex array object for the copy shader

Source

shadowMap :WebGLTexture|undefined

Type:
  • WebGLTexture | undefined
Properties
TypeDescription
WebGLTexture | undefined

The shadow map, casters drawn black on white around the camera, read only

Source

shadowMapOrigin

Properties
TypeDescription
Vector2

World position of the shadow map's bottom left corner, set each shadow pass

Source

shadowMapScale

Properties
TypeDescription
number

How many times the larger side of the view the shadow map covers, so casters just off screen still cast in; raise it when lights reach further than a view past the screen

Source

shadowMapSize

Properties
TypeDescription
number

Pixels across the square shadow map, made again when changed

Source

shadowMapWorldSize

Properties
TypeDescription
number

World size the shadow map covers, set each shadow pass

Source

shadowPass

Properties
TypeDescription
boolean

True while the shadow pass runs, read only, so a render() can skip parts that should not cast

Source

shadowPassCount

Properties
TypeDescription
number

Stretch passes per shadow casting light, fewer is cheaper and shorter shadows

Source

shadowSoftness

Properties
TypeDescription
number

How much light bleeds into a caster's near side, 0 for hard edged casters, 1 for most; the bleed reaches further in under a bigger light, so a thin wall under a big one lets some through, lower it for those

Source

shadowStretchShader :WebGLProgram|undefined

Type:
  • WebGLProgram | undefined
Properties
TypeDescription
WebGLProgram | undefined

One stretch pass of a light's shadow texture

Source

shadowStretchVAO :WebGLVertexArrayObject|undefined

Type:
  • WebGLVertexArrayObject | undefined
Properties
TypeDescription
WebGLVertexArrayObject | undefined

Vertex array object for the stretch shader

Source

shadowTextureA :WebGLTexture|undefined

Type:
  • WebGLTexture | undefined
Properties
TypeDescription
WebGLTexture | undefined

One of the two textures each light's shadow is built in

Source

shadowTextureB :WebGLTexture|undefined

Type:
  • WebGLTexture | undefined
Properties
TypeDescription
WebGLTexture | undefined

The other

Source

shadowTextureSize

Properties
TypeDescription
number

Pixels across each light's own shadow texture, made again when changed; larger is sharper, and a gap between casters narrower than about 4*radius/shadowTextureSize world units closes

Source

shadows

Properties
TypeDescription
boolean

Cast shadows: every object draws black into a shadow map once a frame and each light's rays stop at them; off by default and free when off

Source

texture :WebGLTexture|undefined

Type:
  • WebGLTexture | undefined
Properties
TypeDescription
WebGLTexture | undefined

The lightmap texture

Source

textureSize

Properties
TypeDescription
Vector2

Size of the lightmap texture, follows mainCanvasSize (css pixels, so it is not scaled by canvasPixelRatio) unless a size was passed

Source

textureSizeAuto

Properties
TypeDescription
boolean

True when no size was passed, so the lightmap follows mainCanvasSize

Source

Methods

drawLight(light)

Draw a single Light's falloff blob into the currently bound lightmap. Called by Light.renderLight() during the plugin's render pass.

Parameters:
NameTypeDescription
lightLight
Source

renderLightShadow(light)

Build a light's shadow texture from the shadow map: the map around the light, its casters stretched away from the light a little further each pass with light bled into their near sides. Leaves the result on texture unit 1 and the lightmap bound again. Called by drawLight.

Parameters:
NameTypeDescription
lightLight
Source

setShadowTransparent(transparentopt)

In the shadow pass, let the draws that follow keep their color in the shadow map, so light passing through them is tinted instead of blocked: a stained glass window, colored smoke. Any draw blocks light by its alpha, so a fading sprite casts a fading shadow; this keeps the color as well. It covers what was drawn under it in the map as any draw does, so glass drawn after a wall cuts a tinted window in the wall's shadow, and a wall drawn after the glass covers it. Does nothing outside the pass, so a render() can call it around those draws unconditionally; set it back to false after them.

Parameters:
NameTypeAttributesDefaultDescription
transparentboolean<optional>
true
Source