Dragosha/defold-light-and-shadows/light_and_shadows.light_and_shadows
Real-time shadows from one light source, the sun, and many point light sources,
wired into a render script. Call init(self) from the render script's init,
update(self) from its update, and draw_upscaled(self) after drawing the world
when a post effect is on (see light_and_shadows/render/default.render_script, the
lines marked -- L_S Injection). The settings fields are read every frame. Vector
fields are mutated in place; assigning a new value to any other field goes through a
cast, since a namespace import is read-only:
(light_and_shadows as { fxaa: boolean }).fxaa = true.
- GitHub: Dragosha/defold-light-and-shadows — pinned to
v0.9.1- Pick a release from Dragosha/defold-light-and-shadows 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 light_and_shadows from "light_and_shadows.light_and_shadows"
- Pick a release from Dragosha/defold-light-and-shadows releases and add its Source code (zip) URL (or a packaged
Functions
dof(enable: boolean, options?:DofOptions)render_target(name: string, w: number, h: number, no_depth?: boolean):SizedRenderTargetset_orthographic_projection(proj_w: number, proj_h: number, near_z?: number, far_z?: number)set_perspective_projection(fov?: number, aspect?: number, near_z?: number, far_z?: number)init(self: object)update_light(self: object)render_shadows(self: object)update(self: object)draw_upscaled(self: object)
dof(enable: boolean, options?: DofOptions)
Turns depth of field on or off.
Parameters
enable:boolean—trueturns depth of field on.options?:DofOptions— The depth-of-field options. Omitted, every setting keeps its value.
render_target(name: string, w: number, h: number, no_depth?: boolean): SizedRenderTarget
Returns the render target named name, creating it with a color buffer and, unless
no_depth is set, a depth texture. A target that exists at another size is resized.
Parameters
name:string— The render target name, also its key inrt_list.w:number— The width in pixels.h:number— The height in pixels.no_depth?:boolean—truecreates the target without a depth buffer.
Returns
SizedRenderTarget
set_orthographic_projection(proj_w: number, proj_h: number, near_z?: number, far_z?: number)
Sets an orthographic shadow projection, used for directional light. init sets one.
Parameters
proj_w:number— The width of the area the shadow is projected on.proj_h:number— The height of the area the shadow is projected on.near_z?:number— The near clipping plane. The default is-500.far_z?:number— The far clipping plane. The default is500.
set_perspective_projection(fov?: number, aspect?: number, near_z?: number, far_z?: number)
Sets a perspective shadow projection, cast in the direction of sun_dir in
light_and_shadows.constants. Experimental.
Parameters
fov?:number— The field of view in radians. The default is3.14 / 1.5.aspect?:number— The aspect ratio. The default is1.near_z?:number— The near clipping plane. The default is50.far_z?:number— The far clipping plane. The default is500.
init(self: object)
Sets up the shadow map, the orthographic shadow projection and the render
constants on the render script. Call it from the render script's init.
Parameters
self:object— The render script instance.
update_light(self: object)
Writes the sun, the point light sources, the ambient and fog values and the camera
values from light_and_shadows.constants into the render constants. update calls it.
Parameters
self:object— The render script instance.
render_shadows(self: object)
Draws every object tagged shadow into the shadow map. update calls it while
shadow is on. The render script's self.predicates must carry shadow,
shadow_local, shadow_instanced, shadow_instanced_billboard,
shadow_instanced_textured, shadow_skinned_instanced and shadow_skinned.
Parameters
self:object— The render script instance.
update(self: object)
Updates the light constants, draws the shadow map, and creates or resizes the main
and blur render targets a post effect needs. Call it from the render script's
update.
Parameters
self:object— The render script instance.
draw_upscaled(self: object)
Blurs the main render target when depth of field or blur is on, then draws it to the
screen, with FXAA when fxaa is on. Call it after the world is drawn to the main
render target. The render script's self.predicates must carry upscale.
Parameters
self:object— The render script instance.
Variables
shadow: boolean
Whether the sun casts shadows. The default is true.
upscale: boolean
Whether the main render target is upscaled. When on, every object is first rendered
to a render target no larger than the project settings size, which is then placed on
the screen with linear scaling. Add light_and_shadows/props/render_target_quad.go
to the main scene to use it. The default is false.
fxaa: boolean
Whether FXAA anti-aliasing is applied to the final image. The default is false.
mix: boolean
Whether depth of field is on. dof sets it. The default is false.
discard_threshold: number
The alpha below which the sprite shader discards semitransparent pixels. The default is 0.5.
get_far_near_z_from_camera: boolean
Whether the reference render script reads the near and far Z planes from the camera component into light_and_shadows.constants. Set it to false to set near_z and far_z by hand. The default is true.
blur: boolean
Whether the game scene is blurred, so an unblurred GUI can be drawn on top. It uses the same render target as upscaling. The default is false.
blur_power: number
How strong the blur is, 1 to 10. The default is 2.5.
blur_resolution: number
How much the blur render target is reduced in size, for speed. The default is 2.
focus: Vector4
The depth-of-field focus position, in z.
depth_bias: number
The shadow depth bias. Too high a bias detaches shadows from their objects; too low a bias causes shadow acne. The default is 0.0004.
max_lights: number
How many point light sources the shader processes at once, at most 16. The default is 8.
rt_list: LuaTable<string, SizedRenderTarget>
Every render target render_target created, keyed by name.
polygon_offset: { factor: number; units: number; }
The polygon offset applied while drawing the shadow map. Raise it to reduce shadow acne; lower it if shadows detach from their casters.
zoom: number
The zoom update computed for upscaling, 1 when upscale is off.
Types
SizedRenderTarget
SizedRenderTarget.rt: render.RenderTarget
The render target.
SizedRenderTarget.w: number
The width in pixels.
SizedRenderTarget.h: number
The height in pixels.
DofOptions
DofOptions.blur_power?: number
How strong the blur effect is, 2 to 10. Omitted, blur_power keeps its value.
DofOptions.focus_range?: number
How wide the focus zone is, 0.1 to 4. Omitted, focus_range in light_and_shadows.constants keeps its value.
DofOptions.blur_resolution: number
How much the blur render target is reduced in size, for speed; 1 to 2 is enough.
dof copies it with no fallback, so it is required: an options table without it
leaves blur_resolution nil and the next update fails.
DofOptions.upscale?: boolean
Whether to upscale the main render target. dof sets upscale to false when it is omitted.