Skip to content

SgLightsource

Represents a light-emitting object in the scene, such as a directional, point, or spot light. Affects how nearby objects are lit, casting shadows and influencing material appearance. Supports adjustable intensity, color, range, and falloff based on light type.

Inherits from

SceneObject

Usage

To use this class, add the following require at the top of your script:

local SgLightsource = require 'engine/sceneobjects/sglightsource'

Reference

create

static create(self, options, parent)

Create a new lightsource object in the scenegraph.

Parameters

  • self
  • options (table): A table of options to fill the parameters
  • parent (SceneObject): The parent scene object to add this to

Returns

  • Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgLightsource.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    castShadows = false,
    type = SgLightsource.LightType.Point,
    color = Color.new(255, 255, 255),
    groundColor = Color.new(64, 64, 64),
    intensity = 10,
    distance = 100,
    decay = 2,
    angle = 0.5,
    penumbra = 0,
    target = nil,
    shadowBias = 0,
    shadowSize = SgLightsource.ShadowSize.x512,
    shadowCameraNear = 0.5,
    shadowCameraFar = 500,
    shadowAreaWidth = 10,
    shadowAreaHeight = 10,
    shadowRadius = 4,
    vsmBlurSamples = 8
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

Property Type Default Description
active Boolean true A Boolean attribute indicating whether the 3D object is active or not. When set to true, the object is considered active in the scene.
static Boolean false Marks the object as immovable during play. Static objects ignore transform changes at runtime and use a fixed physics collider with zero mass.
transform Transform Transform.new() Specifies the transformation properties of the 3D object, including its position, rotation, and scale in the scene.
layers Layers [0] Determines the layers the 3D object belongs to. Layers are used to organize objects in the scene for various purposes like rendering and interaction.
tags Tags [] A list of tags associated with the 3D object. Tags are used for categorizing and identifying objects for scripting and scene management.
rendered Boolean true When disabled, the object and its descendants are not drawn, but may still simulate physics or run scripts.
type Enum Point Light type: directional, point, spot, or hemisphere. | Options: Point, Directional, Ambient, Hemisphere, Spot
color Color Color.new(255, 255, 255, 255) Emitted light color multiplied with intensity.
intensity Float 10 Brightness of the light in physically based units (candela/lux depending on type).

Enum: LightType

Enumeration of the available lightsource types

Field Name Description
Point string: point light
Directional string: directional light
Ambient string: ambient light
Hemisphere string: hemisphere light
Spot string: spot light

Enum: ShadowSize

Enumeration of the available shadow sizes

Field Name Description
x128 string: 128 x 128 pixels
x256 string: 256 x 256 pixels
x512 string: 512 x 512 pixels
x1024 string: 1024 x 1024 pixels
x2048 string: 2048 x 2048 pixels