Lighting system

---

This section covers the LUA API for controlling lights in Brakeza3D.

tip

For conceptual understanding of the ADS model, light types, and shadow mapping, see Global Illumination Concepts.

Global Illumination API

---

Access global illumination through the Render component:

local render = Components:Render()

ADS Component Methods

Method	Parameter	Description
setGlobalIlluminationAmbient(v)	Vertex3D	Sets the ambient light color/intensity
setGlobalIlluminationDiffuse(v)	Vertex3D	Sets the diffuse light color/intensity
setGlobalIlluminationSpecular(v)	Vertex3D	Sets the specular light color/intensity
setGlobalIlluminationDirection(v)	Vertex3D	Sets the light direction (sun angle)

note

ADS components use Vertex3D (values 0-1) instead of Color for convenience.

Examples

-- Set warm ambient light
Components:Render():setGlobalIlluminationAmbient(Vertex3D.new(0.3, 0.2, 0.1))

-- Set bright white diffuse
Components:Render():setGlobalIlluminationDiffuse(Vertex3D.new(1, 1, 1))

-- Set subtle specular
Components:Render():setGlobalIlluminationSpecular(Vertex3D.new(0.5, 0.5, 0.5))

-- Sun coming from top-right
Components:Render():setGlobalIlluminationDirection(Vertex3D.new(1, -1, 0.5))

LightPoint

---

A point light emits light in all directions from a single position. It inherits from Object3D.

Creating a LightPoint

local light = ObjectFactory.LightPoint(
    Vertex3D.new(10, 20, 30),       -- position
    Color.new(0.1, 0.1, 0.1),       -- ambient component
    Color.new(0.8, 0.6, 0.4),       -- diffuse component
    Color.new(1.0, 1.0, 1.0)        -- specular component
)

Attenuation Methods

Control how light intensity decreases with distance:

Method	Parameter	Description
setConstant(v)	float	Base intensity (default: 1.0)
setLinear(v)	float	Linear falloff factor
setCuadratic(v)	float	Quadratic falloff factor

-- Soft, far-reaching light
light:setConstant(1.0)
light:setLinear(0.09)
light:setCuadratic(0.032)

-- Intense, short-range light
light:setConstant(1.0)
light:setLinear(0.7)
light:setCuadratic(1.8)

Color Methods

Method	Parameter	Description
setAmbient(c)	Color	Sets ambient contribution
setColor(c)	Color	Sets diffuse color
setColorSpecular(c)	Color	Sets specular color

-- Change to red light
light:setColor(Color.new(1, 0, 0, 1))
light:setColorSpecular(Color.new(1, 0.5, 0.5, 1))

Frustum Culling

LightPoint supports frustum culling to skip the lighting pass for lights that are not visible from the camera. This can improve performance when many lights are in the scene.

Method	Parameter	Description
setFrustumCullingEnabled(v)	bool	Enables or disables frustum culling for this light
getFrustumCullingEnabled()	—	Returns whether frustum culling is active
setFrustumCullingOffset(v)	float	Expands the culling sphere radius (use if light bleeds at edges)
getFrustumCullingOffset()	—	Returns the current offset value

-- Skip lighting pass when the light leaves the camera frustum
light:setFrustumCullingEnabled(true)
light:setFrustumCullingOffset(2.0)  -- expand by 2 units to avoid popping

Position and Transformation

As an Object3D, use standard methods:

light:setPosition(Vertex3D.new(x, y, z))
light:setEnabled(true)
light:setRemoved(true)  -- delete light

LightSpot

---

A spotlight emits light in a specific direction with a cone shape. It inherits from LightPoint.

Creating a LightSpot

local spot = ObjectFactory.LightSpot(
    Vertex3D.new(0, 10, 0),         -- position
    Color.new(0.0, 0.0, 0.0),       -- ambient
    Color.new(1.0, 1.0, 1.0),       -- diffuse
    Color.new(1.0, 1.0, 1.0)        -- specular
)

Spotlight-Specific Methods

Method	Parameter	Description
setCutOff(v)	float	Inner cone angle (sharp edge)
setOuterCutOff(v)	float	Outer cone angle (soft edge)

-- Narrow flashlight beam
spot:setCutOff(12.5)
spot:setOuterCutOff(17.5)

-- Wide floodlight
spot:setCutOff(30.0)
spot:setOuterCutOff(45.0)

Shadow Casting

LightSpot can cast dynamic shadows using PCF shadow mapping (3×3 kernel). Shadow casting is disabled by default.

Method	Parameter	Description
setCastsShadow(v)	bool	Enables or disables shadow casting for this spotlight
getCastsShadow()	—	Returns whether shadow casting is active

spot:setCastsShadow(true)

note

Shadow casting requires ENABLE_SHADOW_MAPPING to be active globally (toolbar toggle or Config). The engine supports up to 64 spotlights total.

Direction Control

Use LookAt or rotation to aim the spotlight:

-- Point at an object
local target = Brakeza:getObjectByName("Enemy")
spot:LookAt(target)

-- Or set position to follow player and look down
spot:setPosition(player:getPosition() + Vertex3D.new(0, 10, 0))
spot:LookAt(player)

Practical Examples

---

Day/Night Cycle

local timeOfDay = 0

function onUpdate()
    local dt = Brakeza:getDeltaTime()
    timeOfDay = timeOfDay + dt * 0.1  -- slow cycle

    local render = Components:Render()

    -- Sun angle
    local sunY = math.sin(timeOfDay)
    local sunX = math.cos(timeOfDay)
    render:setGlobalIlluminationDirection(Vertex3D.new(sunX, sunY, 0.3))

    -- Adjust colors based on time
    if sunY > 0 then
        -- Daytime
        render:setGlobalIlluminationAmbient(Vertex3D.new(0.3, 0.3, 0.35))
        render:setGlobalIlluminationDiffuse(Vertex3D.new(1, 0.95, 0.9))
    else
        -- Nighttime
        render:setGlobalIlluminationAmbient(Vertex3D.new(0.05, 0.05, 0.1))
        render:setGlobalIlluminationDiffuse(Vertex3D.new(0.2, 0.2, 0.3))
    end
end

Flickering Torch

local torch

function onStart()
    torch = ObjectFactory.LightPoint(
        Vertex3D.new(0, 5, 0),
        Color.new(0.1, 0.05, 0.0),
        Color.new(1.0, 0.6, 0.2),
        Color.new(1.0, 0.8, 0.4)
    )
    torch:setLinear(0.14)
    torch:setCuadratic(0.07)
end

function onUpdate()
    local time = Brakeza:getExecutionTime()

    -- Random flicker
    local flicker = 0.8 + math.random() * 0.4
    local pulse = 0.9 + math.sin(time * 10) * 0.1

    local intensity = flicker * pulse
    torch:setColor(Color.new(intensity, intensity * 0.6, intensity * 0.2, 1))
end

Flashlight Following Player

local flashlight

function onStart()
    flashlight = ObjectFactory.LightSpot(
        Vertex3D.new(0, 0, 0),
        Color.new(0, 0, 0),
        Color.new(1, 1, 0.9),
        Color.new(1, 1, 1)
    )
    flashlight:setCutOff(15)
    flashlight:setOuterCutOff(20)
end

function onUpdate()
    local camera = Components:Camera():getCamera()

    -- Position at camera
    flashlight:setPosition(camera:getPosition())

    -- Match camera rotation
    flashlight:setRotation(camera:getRotation())
end

Method Summary

---

Global Illumination (via Components:Render())

Method	Description
setGlobalIlluminationAmbient(Vertex3D)	Set ambient color
setGlobalIlluminationDiffuse(Vertex3D)	Set diffuse color
setGlobalIlluminationSpecular(Vertex3D)	Set specular color
setGlobalIlluminationDirection(Vertex3D)	Set light direction

LightPoint

Method	Description
setConstant(float)	Base attenuation
setLinear(float)	Linear attenuation
setCuadratic(float)	Quadratic attenuation
setAmbient(Color)	Ambient color
setColor(Color)	Diffuse color
setColorSpecular(Color)	Specular color
setFrustumCullingEnabled(bool)	Skip lighting pass when light is off-screen
getFrustumCullingEnabled()	Query frustum culling state
setFrustumCullingOffset(float)	Expand culling sphere to avoid edge popping
getFrustumCullingOffset()	Query current offset

LightSpot (inherits LightPoint)

Method	Description
setCutOff(float)	Inner cone angle
setOuterCutOff(float)	Outer cone angle
setCastsShadow(bool)	Enable PCF shadow casting
getCastsShadow()	Query shadow casting state