afterglow/view/lighting.py

Part of Afterglow.

"""Per-world 3D lighting rigs for the Afterglow diorama.

The WorldEnvironment (environment.py) owns tone/bloom/grade; this module owns the
*direct* light that actually shapes the relief. Each world gets a deliberate
three-point rig plus a movable Wisp light the game attaches to the player:

  KEY   : the dominant shaping light, off to one side and in front.
  FILL  : a softer, cooler (or accent-tinted) light from the opposite side that
          lifts the shadows so the room stays readable (high contrast, not murky).
  RIM   : a hot back/edge light that separates platforms from the back wall and
          drives the bloom on bright surfaces (warm gold for glade/spire, an icy
          cyan accent for caverns).
  WISP  : a small, bright point light that rides the player so the Wisp casts its
          own pool of light onto nearby geometry; it brightens while glowing.

Lights are positioned in the diorama's world space (one tile == one world unit,
y-DOWN logical -> y-UP world). Every rig position is an OFFSET from the room
centre, so passing the room's tile size recentres the whole rig over that room;
rooms a little larger or smaller still read well because the ranges are generous
enough to cover the grid from the centre outward.

Construction is GPU-free (PointLight3D is plain Property data), so a rig builds
headlessly for the capture/verify loop and for tests.

Usage::

    rig = setup_world_lights("glade", room.w, room.h)
    rig.add_to(scene_root)
    # each frame, after the room steps:
    rig.update(player_world_pos, glowing=room.player.glowing)
"""

from __future__ import annotations

from dataclasses import dataclass

from simvx.core import DirectionalLight3D, Node3D, PointLight3D, Vec3

# Fallback room frame in tiles (== world units) for a rig built without a room,
# e.g. the title screen. Every authored room is this size (see rooms_data), and
# a rig built for a real room takes that room's own width / height.
ROOM_W = 56.0
ROOM_H = 30.0

# Wisp light: a soft warm halo that rides the player. With a bright base rig this
# is an ACCENT (a gentle pool near the hero), never the room's main light, so the
# "flashlight in the dark" look is gone; it lifts + warms a touch while glowing.
WISP_Z = 2.0
WISP_RANGE = 8.0
WISP_INTENSITY = 6.0
WISP_INTENSITY_GLOW = 12.0
WISP_COLOUR = (0.72, 1.0, 0.88)
WISP_COLOUR_GLOW = (1.0, 0.96, 0.76)

# Shadow-casting directional sun: intensity is a meaningful slice of the rig so
# its cast shadows actually read; the fill is softened so it does not flood the
# shadowed areas back to full brightness.
_SUN_INTENSITY = 10.0
_FILL_SCALE = 0.5


@dataclass(frozen=True)
class _LightDef:
    """One static rig light: colour, intensity, range and offset from the centre."""

    colour: tuple[float, float, float]
    intensity: float
    range: float
    offset: tuple[float, float, float]
    name: str


# Per-world three-point rigs. ``offset`` is (dx, dy, z) in world units measured
# from the room centre; +z is toward the camera, so all three sit WELL in front
# of the z=0 play plane (z ~ 22-26) and near the centre, making each one a broad,
# flat wash over the WHOLE room rather than a hot spot in one corner. Intensities
# are modest and ranges are large (the whole room is inside the falloff), giving
# a soft, near-uniform base light with gentle directionality: key slightly left,
# fill slightly right + cooler, rim high-centre + warm to lift the top edges.
_RIGS: dict[str, tuple[_LightDef, _LightDef, _LightDef]] = {
    # GLADE: bright warm daylight key, cool sky fill, golden rim. Sunny + clean.
    "glade": (
        _LightDef((1.0, 0.95, 0.80), 16.0, 90.0, (-9.0, 5.0, 24.0), "key_light"),
        _LightDef((0.66, 0.80, 0.96), 11.0, 90.0, (11.0, -4.0, 24.0), "fill_light"),
        _LightDef((1.0, 0.86, 0.52), 9.0, 80.0, (0.0, 9.0, 22.0), "rim_light"),
    ),
    # CAVERNS: cool blue key + crystal-cyan fill keep the moody hue, but the broad
    # wash makes the stone plainly read (not just a silhouette) across the room.
    "caverns": (
        _LightDef((0.70, 0.82, 1.0), 21.0, 92.0, (-9.0, 5.0, 24.0), "key_light"),
        _LightDef((0.50, 0.92, 1.0), 15.0, 92.0, (11.0, -4.0, 24.0), "fill_light"),
        _LightDef((0.55, 1.0, 0.98), 12.0, 82.0, (0.0, 9.0, 22.0), "rim_light"),
    ),
    # SPIRE: warm gold key + amber rim for a dramatic look, but the fill lifts the
    # bronze so the whole room reads brightly rather than crushing to black.
    "spire": (
        _LightDef((1.0, 0.86, 0.50), 21.0, 92.0, (-9.0, 5.0, 24.0), "key_light"),
        _LightDef((1.0, 0.70, 0.38), 15.0, 92.0, (11.0, -4.0, 24.0), "fill_light"),
        _LightDef((1.0, 0.78, 0.34), 12.0, 82.0, (0.0, 9.0, 22.0), "rim_light"),
    ),
}


class WorldLights:
    """A built three-point rig + a movable Wisp light for one world.

    Holds the four ``PointLight3D`` nodes (key, fill, rim, wisp) under a single
    ``Node3D`` so ``add_to`` parents the whole rig in one call and the game drives
    only the Wisp each frame via ``update``.

    ``room_w`` / ``room_h`` are the room's size in tiles; the rig centres itself
    on that room so the wash covers the whole grid instead of drifting toward one
    side of it.
    """

    def __init__(self, world_id: str, room_w: float = ROOM_W, room_h: float = ROOM_H) -> None:
        self.world_id = world_id
        self.root = Node3D(name=f"lights_{world_id}")
        self._cx = float(room_w) * 0.5
        self._cy = -float(room_h) * 0.5
        key_d, fill_d, rim_d = _RIGS.get(world_id, _RIGS["glade"])
        self.key = self._make(key_d)
        # The fill is deliberately softened (the rig was washing the room so flat
        # that no shadow could read); a dimmer fill lets the sun's cast shadows
        # show while still lifting the room out of black.
        self.fill = self._make(fill_d)
        self.fill.intensity *= _FILL_SCALE
        self.rim = self._make(rim_d)
        # Directional sun: a single DirectionalLight3D that rakes across the relief
        # to give the carved stone a consistent shaping light on top of the broad
        # point wash (the point rig alone is near-flat). It looks down-and-across
        # the play plane from the upper-left.
        #
        # CAST SHADOWS ARE DELIBERATELY OFF here, and that is the correct call for
        # THIS geometry, not an oversight. The diorama (diorama.py) is a wall of
        # unit cubes whose camera-facing +Z faces are all COPLANAR at z=0, sitting
        # just in front of a single flat back-wall; interior faces between adjacent
        # solids are culled. A cast shadow therefore has essentially no receiving
        # surface in the camera's view to fall on -- a caster's shadow lands on the
        # culled side face of its neighbour or on the hidden back wall. Verified by
        # A/B render: toggling CSM on/off (even with a steepened, brightened sun and
        # the point fill dimmed) moved the framed image by < 0.4 mean pixel value,
        # i.e. no readable shadow, while costing a full shadow-map pass per frame.
        # The contact darkening this shallow relief CAN express (crevice/silhouette
        # occlusion the camera does see) is delivered by SSAO in environment.py,
        # which is the right technique for a flat-fronted diorama. Re-enabling CSM
        # would need real depth separation between casters and receivers (a deeper,
        # multi-plane set), which would change the art direction.
        self.sun = DirectionalLight3D(
            colour=(1.0, 0.96, 0.9),
            intensity=_SUN_INTENSITY,
            position=Vec3(self._cx - 14.0, self._cy + 8.0, 22.0),
            name="sun_directional",
        )
        self.sun.shadows = False
        self.sun.look_at((self._cx + 6.0, self._cy - 4.0, 0.0))
        self.wisp = PointLight3D(
            colour=WISP_COLOUR,
            intensity=WISP_INTENSITY,
            range=WISP_RANGE,
            position=Vec3(self._cx, self._cy, WISP_Z),
            name="wisp_light",
        )
        for light in (self.sun, self.key, self.fill, self.rim, self.wisp):
            self.root.add_child(light)

    def _make(self, d: _LightDef) -> PointLight3D:
        pos = Vec3(self._cx + d.offset[0], self._cy + d.offset[1], d.offset[2])
        return PointLight3D(colour=d.colour, intensity=d.intensity, range=d.range, position=pos, name=d.name)

    def add_to(self, scene_root: Node3D) -> WorldLights:
        """Parent the whole rig under ``scene_root``; returns self for chaining."""
        scene_root.add_child(self.root)
        return self

    def update(self, player_world_pos, glowing: bool) -> None:
        """Move the Wisp light to the player and brighten/warm it while glowing.

        ``player_world_pos`` is the player centre in diorama world space (e.g.
        ``Vec3(cx * WORLD_SCALE, -cy * WORLD_SCALE, 0)``); the light sits a little
        in front of the play plane so it pools onto the relief.
        """
        x, y = float(player_world_pos[0]), float(player_world_pos[1])
        self.wisp.position = Vec3(x, y, WISP_Z)
        if glowing:
            self.wisp.intensity = WISP_INTENSITY_GLOW
            self.wisp.colour = WISP_COLOUR_GLOW
            self.wisp.range = WISP_RANGE * 1.25
        else:
            self.wisp.intensity = WISP_INTENSITY
            self.wisp.colour = WISP_COLOUR
            self.wisp.range = WISP_RANGE


def setup_world_lights(world_id: str, room_w: float = ROOM_W, room_h: float = ROOM_H) -> WorldLights:
    """Build the per-world three-point rig + Wisp light holder for ``world_id``.

    Pass the room's tile width / height so the rig centres on it; the defaults
    cover a rig built without a room (the title screen). Unknown ids fall back to
    the glade rig so the view never crashes on a not-yet-themed world.
    """
    return WorldLights(world_id, room_w, room_h)