LightMaskOptions

A texture laid over the world from above that dims the sun by region, and the sky’s fill and the fog with it, so a region reads unlit, such as a dark side of the world with lit circles in it. Named apart from Unity’s cookie and Unreal’s light function, which hang on one light, read along it and scale its direct light only, while its sunMap is a cookie read from above for every directional light; nor is it a layer mask, as Unity’s culling mask and Godot’s cull mask are.

Properties

Property	Type	Default value	Description
boundary?	LightMaskBoundaryOptions	undefined	Reads the red channel as a signed distance and draws the line between light and dark as sharp as blendWidth asks, with a band on its dark side and a rim on its lit side. Left out, red is a share, blended as written.
center?	readonly [number, number]	[0, 0]	The point on the ground under the texture’s middle.
fill?	number	1	The share of the sky’s fill kept where the mask is 0, 0 to 1: the hemisphere light, the environment’s light and reflections, any ambient light, light probe or light map, and the look’s character light. 1 leaves the fill alone, as the other engines’ cookies do; 0.2 is a region in deep shade.
fillLight?	LightMaskFillLightOptions	undefined	Lights the land the mask lights with a light of its own, read from the texture’s green, blue and alpha as linear RGB, such as the warm pool round a lantern at night. Left out, the texture’s green, blue and alpha are not read.
fog?	LightMaskFogOptions	undefined	The fog where the mask is 0. Left out, the fog stays as the look sets it.
groundFog?	GroundFogOptions	undefined	A body of the dark’s air lying on the ground over the mask’s dark, with a top that follows the ground, such as a night that lies like smoke or a fog of war. It hides what stands in it as much at every quality level, and draws through the look’s post-processing stack, which mounts for it at every level. Left out, none.
litSun?	number	1	The share of the sun’s light kept where the mask is 1, 0 to 1, with its shadows, as sun keeps it where the mask is 0. 1 lights the lit land as the look lights it. At night, where the lit land is a lamp’s pool, 0.3 lets the pool outshine the moon as an eye used to the lamp sees it, while sun keeps the moon in the dark. Every spot red counts as lit takes it, a day’s circle as well as a pool, so a mask kept by day sets it back to 1 for the day.
localLights?	LightMaskLocalLightOptions	undefined	Puts out point and spot lights in the dark under a height above the ground, so a lamp whose range reaches past its pool lights what stands in the dark, a trunk or a shade’s shoulders, while the ground and the low plants past the line stay dark. It reads what each surface stands at, not the light’s path, and every point and spot light in the scene takes it. Left out, local lights light all they reach, in the dark too, as three draws them.
size	readonly [number, number]	undefined	Metres the texture spans along x and along z. Past its edge, the edge’s value holds.
sun?	number	0	The share of the sun’s light kept where the mask is 0, 0 to 1, with its shadows: every directional light, the rig’s sun by day and its moon by night and any of the game’s own, and by day the sun’s light under a canopy, off the ground and scattered in the height fog. 0 leaves the dark unlit by them; 1 keeps a moonlit night whole outside a lamp’s pool, whose line then reads as the step from litSun to this share.
sunMap?	Texture<unknown, TextureEventMap>	undefined	A cookie for the sun: a texture whose red multiplies the share of the sun’s light that sun and litSun keep, by region, with its shadows. 1 keeps the share, 0 puts the sun out there, so a moonless rim past a moonlit wood is one mask, and a lamp’s pool inside the rim keeps no moon unless the map keeps it there. It only takes light away: to keep the moon in part of the dark, set sun to the share the brightest region keeps, such as 1, and paint the map lower where less is kept. Read from above over the mask’s own size and center, as texture is, and moving with them, its edge’s value holding past it. Only red is read. Keep its colour space NoColorSpace, and give it a LinearFilter unless a region’s edge should step from texel to texel, as a tile map’s may. Left out, sun and litSun hold everywhere.
texture	Texture	undefined	Read from above: its red channel is the share of light at each spot, 1 lit as the look lights it, 0 the dark fill and fog set, or, with a boundary, the distance to the line between them. Its u runs along +x and its v along +z, so a DataTexture’s first texel is the -x, -z corner, its columns run along +x and its rows along +z; a canvas reads the same, its top row along -z. Write it as the game runs and set its needsUpdate. Its colour space stays NoColorSpace, so the shares are read as written.