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- Pick a release from astrochili/defold-illumination releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as illumination from "illumination.illumination"
- Pick a release from astrochili/defold-illumination releases and add its Source code (zip) URL (or a packaged
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, orundefinedto remove it.url:Url | string | Hash— The light's key and the address of itsdebugmessages.
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.