Lighting

This section provides guidance on setting up lights and shadows.

Lights and shadows can be added to the entity via the Studio interface or in code. Adding them in Studio is done via the (+) button on the Hierarchy or adding "New Component" via the Inspector for a selected entity. The Light and Shadow components feature various settings.

Light Component:

Shadow Component:

Lights

Add a light source

ecs.Light.set(world, eid, {type: 'directional'})

Setting custom light properties

ecs.Light.set(world, component.id, {
  type: 'directional',
  castShadow: true,
  intensity: 0.5,
  r: 255,
  g: 0,
  b: 0,
  targetX: 10,
  targetY: 10,
  targetZ: 10,
  shadowBias: 0,
})

Light properties

note

• Keep the rotation of the entity that the light component is on to (0, 0, 0). The light will act unpredictably if it is not.
• Shadow Camera can not be configured through the light configurator.
• If an entity with a light is selected, a helper will appear to show the shadow camera of the light.

Property Name	Type	Default	Required	Description
type	string	directional	true	The type of light: directional, point, ambient
castShadow	boolean	true	false	Enables light to cast shadows
intensity	number	0.5	false	The light's intensity, or strength.
r	number	255	false	The red component of the light’s color.
g	number	255	false	The green component of the light’s color.
b	number	255	false	The blue component of the light’s color.
targetX	number	0	false	The x coordinate of the point the light is targeting.
targetY	number	0	false	The y coordinate of the point the light is targeting.
targetZ	number	0	false	The z coordinate of the point the light is targeting.
shadowBias	number	-0.005	false	How much to add or subtract from the normalized depth when deciding whether a surface is in shadow.
shadowNormalBias	number	0	false	Defines how much the position used to query the shadow map is offset along the object normal.
shadowRadius	number	1	false	The radius of the shadow.
shadowAutoUpdate	boolean	true	false	Enables automatic updates of the light's shadow. Default is true. If you do not require dynamic lighting / shadows, you may set this to false.
shadowBlurSamples	number	8	false	The amount of samples to use when blurring a VSM shadow map.
shadowMapSizeheight	number	1024	false	Height of the shadow map. Higher values give better quality shadows at the cost of computation time. Values must be powers of 2
shadowMapSizeWidth	number	1024	false	Width of the shadow map. Higher values give better quality shadows at the cost of computation time. Values must be powers of 2
shadowCameraNear	number	0.5	false	Camera frustum near plane. The valid range is between 0 and the current value of the far plane.
shadowCameraFar	number	200	false	Camera frustum far plane. Must be greater than the current value of the near plane.
shadowCameraLeft	number	-50	false	Camera frustum left plane.
shadowCameraRight	number	50	false	Camera frustum right plane.
shadowCameraTop	number	50	false	Camera frustum top plane.
shadowCameraBottom	number	-50	false	Camera frustum bottom plane.

Shadows

Cast and receive shadows

ecs.Shadow.set(world, eid, {castShadow: true, receiveShadow: true})

Shadow Properties

Property Name	Type	Default	Required	Description
castShadow	boolean	false	false	Indicates if an entity can cast shadows.
receiveShadow	boolean	false	false	Indicates if an entity can receive shadows.