Skip to Content
defold-typescript libraries
astrochili

astrochili/defold-illumination/illumination

Forward shading lighting for 3D games, with ambient and directional light, point and spot lights, and linear or radial fog. Add illumination.go to the scene as the sunlight source, add light_point.go or light_spot.go for each light, and set /illumination/materials/model.material on the meshes. The lighting data reaches the shader as a texture, so no render script is needed. The module's functions toggle the debug meshes and set lights and the environment by hand.

  • GitHub: astrochili/defold-illumination — pinned to 1.0.3
    1. Pick a release from astrochili/defold-illumination releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as illumination from "illumination.illumination"

Functions

set_debug(is_enabled: boolean)

Shows or hides the debug meshes of the sun and the light sources.

Parameters

  • is_enabled: boolean — Whether the debug meshes show.

is_debug(): boolean

Returns whether the debug meshes show.

Returns

  • boolean

set_environment(environment: Environment)

Patches the environment with the fields given and leaves the others as they are. The fog fields apply only while the stored fog type, including one set in the same call, is not FOG_TYPE_NONE, and fog_color also posts clear_color to @render:. The bundled illumination.go patches each field from its own properties on its first update and whenever that property changes, overwriting a value set here. Raises until the bundled illumination.go has run its script's init.

Parameters

  • environment: Environment — The fields to change.

set_light(light: Light | undefined, url: Url | string | Hash)

Adds, updates or removes a light source by hand, for lights that are not light_point.go or light_spot.go. position, color, radius and cutoff are required, specular and smoothness default to 1, and each position axis must lie within -2048 to 2048. undefined, or a light whose color.w, radius or cutoff is 0 or below, removes the light. url keys the light, so pass the same value on every call for the same light. It receives a debug message carrying is_enabled when the light is added or removed and on every set_debug. Adding or updating a light raises until the bundled illumination.go has run its script's init.

Parameters

  • light: Light | undefined — The light, or undefined to remove it.
  • url: Url | string | Hash — The light's key and the address of its debug messages.

Variables

FOG_TYPE_NONE: 0

No fog.

FOG_TYPE_LINEAR: 1

Fog along the camera's view direction.

FOG_TYPE_RADIAL: 2

Fog around the camera's position.

Types

type FogType = typeof FOG_TYPE_NONE | typeof FOG_TYPE_LINEAR | typeof FOG_TYPE_RADIAL

Environment

Environment.fog_type?: FogType

The fog type. The fog fields below apply only while the fog type is not FOG_TYPE_NONE.

Environment.ambient_color?: Vector4

The ambient light color, its w the ambient strength.

Environment.sunlight_color?: Vector4

The directional light color, its w the sunlight brightness.

Environment.sunlight_direction?: Vector3

The direction the sunlight shines, normalized by upstream.

Environment.sunlight_specular?: number

The sunlight's specular component, from 0 to 1.

Environment.fog_color?: Vector4

The fog color, its w the fog's full strength. Also posted as clear_color to @render:.

Environment.fog_min?: number

The distance at which the fog begins. Values below 0 are raised to 0.

Environment.fog_max?: number

The distance at which the fog reaches full strength. Values below fog_min are raised to it.

Light

Light.position: Vector3

The light's world position. Each axis is encoded within -2048 to 2048.

Light.color: Vector4

The light color, multiplied with the diffuse color. Its w is the brightness.

Light.radius: number

The light radius. Upstream rounds it up and caps it at 255.

Light.cutoff: number

The spotlight cutoff, from 0 to 1: 0.3 is like a flashlight, 0.5 half of the sphere, and 1 no cutoff.

Light.direction?: Vector3

The direction a spotlight shines. Read only while cutoff is below 1.

Light.specular?: number

The light's specular component, from 0 to 1. Defaults to 1.

Light.smoothness?: number

The light's attenuation, from 0 to 1: 0 fills the radius evenly and 1 fades from the center to the edge. Defaults to 1.

On this page