LightEffect

Defined in: packages/three-flatland/src/lights/LightEffect.ts:159

Base class for lighting effects applied to Flatland sprites.

Mirrors the PassEffect pattern: class-based, schema-driven, with property accessors. Uses TSL uniform() nodes for zero-cost runtime parameter updates.

LightEffect produces a ColorTransformFn that is automatically assigned to all lit sprites. The transform runs in the material shader, reading light data from shared DataTextures managed by LightStore.

Subclasses may also override lifecycle methods (init/update/resize/dispose) to manage GPU resources like Forward+ tiling or Radiance Cascades.

Example

class DefaultLightEffect extends LightEffect {
  static readonly lightName = 'defaultLight'
  static readonly lightSchema = { ambientIntensity: 0.2 } as const
  static readonly needsShadows = false
  declare ambientIntensity: number

  static buildLightFn({ uniforms, lightStore }: LightEffectBuildContext): ColorTransformFn {
    // build shader using lightStore.readLightData()
  }
}

Constructors

Constructor

new LightEffect(): LightEffect

Defined in: packages/three-flatland/src/lights/LightEffect.ts:297

Returns

LightEffect

Properties

name

readonly name: string

Defined in: packages/three-flatland/src/lights/LightEffect.ts:259

Effect name (from static).

---

lightName

readonly static lightName: string

Defined in: packages/three-flatland/src/lights/LightEffect.ts:165

Unique light effect name. Must be overridden by subclass.

---

lightSchema

readonly static lightSchema: EffectSchema

Defined in: packages/three-flatland/src/lights/LightEffect.ts:167

Per-effect data schema with default values. Must be overridden by subclass.

---

needsShadows

readonly static needsShadows: boolean = false

Defined in: packages/three-flatland/src/lights/LightEffect.ts:169

Whether this effect needs the shadow/SDF pipeline.

---

requires

readonly static requires: readonly keyof ChannelNodeMap[] = []

Defined in: packages/three-flatland/src/lights/LightEffect.ts:171

Per-fragment channels this effect requires (e.g., [‘normal’]).

Accessors

dirty

Get Signature

get dirty(): boolean

Defined in: packages/three-flatland/src/lights/LightEffect.ts:434

Whether this effect has been marked dirty since last clearDirty().

Returns

boolean

---

enabled

Get Signature

get enabled(): boolean

Defined in: packages/three-flatland/src/lights/LightEffect.ts:402

Whether this effect is enabled.

Returns

boolean

Set Signature

set enabled(value): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:407

Toggle enabled state. Structural change — marks lighting dirty.

Parameters

value

boolean

Returns

void

---

resolutionScale

Get Signature

get resolutionScale(): number

Defined in: packages/three-flatland/src/lights/LightEffect.ts:423

Processing-resolution multiplier for resources owned by this effect. The default 1 receives the full physical drawing-buffer size; 0.5 receives half-width/half-height dimensions while camera framing and the renderer output stay unchanged. Values must be finite and greater than 0.

Returns

number

Set Signature

set resolutionScale(value): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:427

Parameters

value

number

Returns

void

Methods

build()

build(lightStore, worldSizeNode, worldOffsetNode, sdfTexture?): ColorTransformFn

Defined in: packages/three-flatland/src/lights/LightEffect.ts:516

Build the ColorTransformFn for standalone use (no Flatland, no ECS).

Returns the lighting function that can be assigned directly to a sprite material’s colorTransform. For batched sprites, wrap with wrapWithLightFlags() to gate per-instance.

Parameters

lightStore

LightStore

worldSizeNode

UniformNode <"vec2", Vector2 >

worldOffsetNode

UniformNode <"vec2", Vector2 >

sdfTexture?

Texture <unknown, TextureEventMap > | null

Returns

ColorTransformFn

Example

const lightStore = new LightStore()
const lighting = new DefaultLightEffect()
const lightFn = lighting.build(lightStore)

sprite.material.colorTransform = lightFn
sprite.material.requiredChannels = new Set(DefaultLightEffect.requires)

---

clearDirty()

clearDirty(): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:439

Clear the dirty flag. Called by lighting systems after processing.

Returns

void

---

dispose()

dispose(): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:555

Dispose GPU resources owned by this effect. Override in subclasses that own ForwardPlusLighting or other GPU resources.

Returns

void

---

init()

init(_ctx): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:448

Initialize GPU resources. Called lazily before the first resize and update.

Parameters

_ctx

LightEffectRuntimeContext

Returns

void

---

resize()

resize(_width, _height): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:459

Handle processing-surface resize. Flatland derives this from the physical render surface multiplied by resolutionScale. Once a valid size exists, this is called after init and before the next update. An initial update may run first while a newly mounted canvas still reports 0×0.

Parameters

_width

number

_height

number

Returns

void

---

update()

update(_ctx): void

Defined in: packages/three-flatland/src/lights/LightEffect.ts:451

Per-frame GPU passes (tiling, SDF, radiance cascades).

Parameters

_ctx

LightEffectRuntimeContext

Returns

void

---

buildLightFn()

static buildLightFn(_context): ColorTransformFn

Defined in: packages/three-flatland/src/lights/LightEffect.ts:189

Build the lighting ColorTransformFn. Must be overridden by subclass. Called once when the effect is attached to Flatland. The returned function closes over uniform nodes for zero-cost parameter updates.

Parameters

_context

LightEffectBuildContext

Returns

ColorTransformFn