Skip to Content
defold-typescript libraries
Dragoshadefold-light-and-shadows

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
    1. Pick a release from Dragosha/defold-light-and-shadows 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 light_and_shadows from "light_and_shadows.light_and_shadows"

Functions

dof(enable: boolean, options?: DofOptions)

Turns depth of field on or off.

Parameters

  • enable: boolean — true turns 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 in rt_list.
  • w: number — The width in pixels.
  • h: number — The height in pixels.
  • no_depth?: boolean — true creates 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 is 500.

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 is 3.14 / 1.5.
  • aspect?: number — The aspect ratio. The default is 1.
  • near_z?: number — The near clipping plane. The default is 50.
  • far_z?: number — The far clipping plane. The default is 500.

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.

On this page