LittleJS 1.31.0

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(textureSize, ambientColor)lightSystem.js:54

Create the global light system plugin

textureSize Vector2 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)

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

// simplest usage
new LightSystemPlugin();

Members

Methods

Members

ambientColor : ColorlightSystem.js:74

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.

backgroundMap : WebGLTexture|undefinedlightSystem.js:125

The background map, objects with castBackgroundShadow drawn black on white, the shadow map's size and place, made by a directional light when something casts into it and kept while the light is, read only

compositeShader : WebGLProgram|undefinedlightSystem.js:92

Shader for compositing the lightmap over the main scene

compositeVAO : WebGLVertexArrayObject|undefinedlightSystem.js:98

Vertex array object for the composite shader

directionalLight : DirectionalLight|undefinedlightSystem.js:153

The scene's directional light, a sun, or undefined, read only

directionalPrograms : Object<string, (WebGLProgram|WebGLVertexArrayObject)>lightSystem.js:168
directionalTexture : WebGLTexture|undefinedlightSystem.js:160

The directional light as built this frame, white where it reaches, over the shadow map's area, read only

directionalTextureA : WebGLTexture|undefinedlightSystem.js:162
directionalTextureB : WebGLTexture|undefinedlightSystem.js:164
directionalTextureSize : numberlightSystem.js:156

Pixels across the square textures a directional light is built in, covering the shadow map's area; larger is sharper and slower; a power of two, as shadowMapSize, so their texels line up

emissivePass : booleanlightSystem.js:118

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

enabled : booleanlightSystem.js:71

When false, the render pass is skipped entirely

lightShader : WebGLProgram|undefinedlightSystem.js:89

Shader for drawing per-Light falloff blobs into the lightmap

lightVAO : WebGLVertexArrayObject|undefinedlightSystem.js:95

Vertex array object for the light shader

normalMaps : booleanlightSystem.js:176

Shade objects by their normalMap: each frame every object draws into a normal buffer, its normal map turned with it or flat without one, and the lights shade by it with their height; off by default and free when off; it about doubles the scene's draw work, and since every surface is shaded, lights fall off faster than with it off; a textureSize given that is not the canvas's shape skews a turned sprite's normals a little

normalPass : booleanlightSystem.js:181

True while the normal pass runs, read only, so a render() can skip parts

normalShader : Shader|undefinedlightSystem.js:189
normalTexture : WebGLTexture|undefinedlightSystem.js:185

The normal buffer, the lightmap's size, each pixel's normal facing the screen as a color, made while normalMaps is on, read only

normalTextureSize : Vector2|undefinedlightSystem.js:187
shadowContext : OffscreenCanvasRenderingContext2D|undefinedlightSystem.js:146

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

shadowCopyShader : WebGLProgram|undefinedlightSystem.js:134

Copies the shadow map around a light into its texture

shadowCopyVAO : WebGLVertexArrayObject|undefinedlightSystem.js:140

Vertex array object for the copy shader

shadowMap : WebGLTexture|undefinedlightSystem.js:121

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

shadowMapOrigin : Vector2lightSystem.js:148

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

shadowMapScale : numberlightSystem.js:105

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

shadowMapSize : numberlightSystem.js:103

Pixels across the square shadow map, made again when changed

shadowMapWorldSize : numberlightSystem.js:150

World size the shadow map covers, set each shadow pass

shadowPass : booleanlightSystem.js:116

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

shadowPassCount : numberlightSystem.js:110

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

shadows : booleanlightSystem.js:101

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

shadowSoftness : numberlightSystem.js:114

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

shadowStretchShader : WebGLProgram|undefinedlightSystem.js:137

One stretch pass of a light's shadow texture

shadowStretchVAO : WebGLVertexArrayObject|undefinedlightSystem.js:143

Vertex array object for the stretch shader

shadowTextureA : WebGLTexture|undefinedlightSystem.js:128

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

shadowTextureB : WebGLTexture|undefinedlightSystem.js:131

The other

shadowTextureSize : numberlightSystem.js:108

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

texture : WebGLTexture|undefinedlightSystem.js:86

The lightmap texture

textureSize : Vector2|undefinedlightSystem.js:77

Size of the lightmap texture, follows mainCanvasSize (css pixels, so it is not scaled by canvasPixelRatio) unless a size was passed; undefined until the system starts when none was; a new size set later makes the lightmap again at it, and turns textureSizeAuto off so the canvas does not set it back

textureSizeAllocated : Vector2lightSystem.js:82
textureSizeAuto : booleanlightSystem.js:80

True when no size was passed, so the lightmap follows mainCanvasSize; a textureSize set later turns it off, and setting it true again follows the canvas again

Methods

clampTextureSizes()lightSystem.js:1097

Bring the sizes of the textures it makes down to what the device can make: shadowMapSize, shadowTextureSize, directionalTextureSize and textureSize; called before they are made, so a size too big falls back instead of failing

drawLight(light)lightSystem.js:1114

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

light Light
renderLightShadow(light)lightSystem.js:1174

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.

light Light
setShadowTransparent(transparent)lightSystem.js:1230

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.

transparent boolean optional, default true