Client Light API

Attaching dynamic lights to entities and interactables from client-side Lua — light table fields, updating lights, and reading them back.

Client-side scripts can attach dynamic lights to entities and static objects — a torch glow, a boss aura, a machine’s status lamp. Lights are plain Lua tables: you create one with the global create_new_light(), fill in its fields, and attach it with add_light (see lua-client-entity.md). Lights are purely visual and exist only on the local client.

Creating and Attaching

return function(static_object)
    local light = create_new_light()
    light.magnitude = 10.0
    light.dropoff_distance = 5.0
    light.intensity = 1.0
    light.color = { 1.0, 0.85, 0.5, 1.0 }   -- warm yellow: {r, g, b, a}, 0.0–1.0
    static_object:add_light(0.0, -4.0, light)

    -- Keep the id if you want to update the light later.
    static_object.lua_data.light_id = light.id
end

create_new_light() returns a light table with a fresh unique id and default values; the light does nothing until attached. add_light(offset_x, offset_y, light) positions it at a pixel offset from the object’s origin, and the light then follows the object.

Light Table Fields

FieldTypeDescription
idnumberUnique identity of the light. create_new_light() assigns one — keep it; attaching another light with the same id updates the existing light instead of adding a new one.
magnitudenumberRadius of the light’s full-strength core, in blocks.
dropoff_distancenumberDistance over which the light fades to nothing beyond the core. Total reach = magnitude + dropoff_distance.
intensitynumberBrightness multiplier (1.0 = normal).
colortable{r, g, b, a} list, each channel 0.0–1.0.
is_staticbooleantrue for lights that never move or change — the renderer can treat them more cheaply. Use false for anything you plan to move, flicker, or recolor.
light_typenumberLight style selector; 0 is the standard light.
origin_x / origin_ynumberBase origin of the light. Usually leave at 0 — add_light’s offsets place the light relative to the object.

Updating a Light

Re-attach with the same id to change a light in place — this is how you animate one:

-- client-update: flicker by nudging intensity each frame.
return function(static_object)
    local data = static_object.lua_data
    if data.light_id == nil then return end

    local light = create_new_light()      -- fresh table...
    light.id = data.light_id              -- ...but reuse the attached id = update in place
    light.magnitude = 8.0
    light.dropoff_distance = 4.0
    light.intensity = 0.9 + math.random() * 0.2
    light.color = { 1.0, 0.75, 0.4, 1.0 }
    light.is_static = false
    static_object:add_light(0.0, -6.0, light)
end

Note that create_new_light() allocates a new id each call — when updating, overwrite the id field with the one you stored, as above.

Reading Lights Back

get_lights() returns a list (1-indexed) of all lights attached to the object. Each entry is a light table with the fields above, plus:

FieldTypeDescription
x_offset / y_offsetnumberThe attach offsets passed to add_light.
max_distancenumberThe computed total reach (magnitude + dropoff_distance).

See Also