SpotLight

Adds a cone-shaped light source to an entity. Position comes from the entity's world transform; the cone axis is the entity's world rotation applied to the face direction, so a spot under a carrier turns with it. face defaults to "Front", the entity-local -Z that transform.forward reports and that entity:lookAt aims, so aiming the carrier at something is what puts the cone on it. Shares the 64-light scene cap with Light (point lights), and shares its intensity scale: the same intensity at the same range puts the same light on a surface either kind faces from the same place, and the cone decides how much of the room that light reaches rather than how bright it is where it lands. angle and innerAngle are half-angles from the cone axis, so angle = 30 opens a 60-degree cone.

Public fields: colorR/G/B, brightness (→ intensity), range (→ radius), angle (outer half-angle, deg), innerAngle (inner half-angle, deg), face (Front/Back/Left/Right/Top/Bottom), shadows, cookieLayer, mobility. intensity and radius are aliases of brightness and range, spelled the way the Light component spells them.

Methods: :setColor(color), :setBrightness(b), :setRange(r), :setAngle(deg), :setInnerAngle(deg), :setFace(face).

Falloff: 0..innerAngle = full bright, innerAngle..angle = smoothstep to 0, > angle = 0. Range falloff is UE4-style smooth windowed inverse-square clamped at range.

The cone is one further factor on that shared scale, and it is 1 inside innerAngle. So the reading that separates the two kinds is a room-wide or frame-wide average: a spot lifts it far less than a point light carrying the same number, because it reaches less of the room. Balance a mixed rig by the brightness of the surfaces each light is aimed at, not by how much of the frame each one lifts — and widen angle or range to cover more of the room where raising brightness would only deepen the spot's own pool.

A spot casts shadows by default; shadows = false keeps it purely additive. cookieLayer names a layer of the shared feature texture to project through the cone as a gobo, and -1 (the default) leaves the cone uniform — fill the layer with renderer.featureTexture.setLayer before pointing a spot at it.

entity(id).component.add("SpotLight", {
    color = {1, 0.95, 0.8},
    brightness = 3.0,
    range = 30,
    angle = 30,
    innerAngle = 20,
    face = "Front",
    shadows = true,
    cookieLayer = 0,
})