afterglow/view/sprites.py

Part of Afterglow.

"""EntityView: billboarded visuals for every dynamic sim entity, synced each frame.

This is the *dynamic* half of the 3D view. It spawns one visual node per sim
entity (plus the player Wisp) on first ``sync`` for a room, then on every later
``sync`` reads room state to drive each visual: position, animation, visibility,
and emissive/modulate pulses. It never mutates the sim.

Visuals:
  Wisp (player)  : AnimatedSprite3D from build_wisp_sheet(); state->animation,
                   facing->flip_h, glow boosts modulate toward warm-white.
  Crystal        : emissive billboard, hidden when not alive.
  GlowOrb        : pulsing emissive billboard, dimmed when not available.
  LightGate      : thin emissive box, lit/opaque only while .solid (player glowing).
  Spring         : small metal pad billboard with a contact flash.
  Shard          : sparkling billboard, hidden once collected.
  MovingPlatform : a metal box that tracks the platform's oscillation.
  exit           : a soft glowing portal billboard.

GPU-free to instantiate: sprite textures are numpy arrays, meshes are pure data.
"""

from __future__ import annotations

import math

import numpy as np

from simvx.core import (
    AnimatedSprite3D,
    Material,
    MeshInstance3D,
    Node3D,
    Sprite3D,
    create_box,
)

from ..assets.sprite_gen import (
    FRAMES_HORIZONTAL,
    FRAMES_VERTICAL,
    build_wisp_sheet,
)
from ..assets.textures import world_palette
from ..sim.entities import (
    Crystal,
    GlowOrb,
    LightGate,
    MovingPlatform,
    Shard,
    Spring,
)

TILE_SIZE = 8
WORLD_SCALE = 1.0 / TILE_SIZE

#: Seconds a spring stays lit after launching the Wisp.
_SPRING_FLASH = 0.25

# sim player.state -> wisp animation name (sprite_gen ANIMATIONS keys).
_STATE_ANIM = {
    "idle": "idle-bob",
    "run": "run",
    "jump": "jump",
    "fall": "fall",
    "wallslide": "wallslide",
    "dash": "dash",
}

# One tile == 1.0 world unit (the diorama places a tile per world unit), so a
# sprite's world size is just its desired tile-extent / its source pixel count.
# Wisp: a 24px frame drawn ~2.4 tiles tall so the hero reads large and clearly
# above its 8px (~1 tile) hitbox and dominates the frame as the brightest element.
_WISP_PIXEL = 2.4 / 24.0
# Pickups (crystal/orb/shard/exit/spring) ~1 tile across from a 16px source.
_PICKUP_PIXEL = 1.0 / 16.0

# The EXIT portal's ring colour: a bright warm white, deliberately NOT any
# world's palette accent so the goal contrasts against the green/blue/amber
# rooms instead of camouflaging into them.
_EXIT_COLOUR = (255, 244, 214)


# Sprites sit a touch in front of the z=0 play plane so they read clearly
# against the carved relief and never z-fight the back wall.
_SPRITE_Z = 2.0  # in FRONT of the extruded diorama boxes (which reach ~+1.5),
# so pickups (shard / crystal / orb / exit) are never occluded by level geometry
# from the tilted camera. At 0.4 they sat behind the boxes and vanished.
# The Wisp rides further forward so the extruded diorama relief can never
# occlude the hero, and is drawn HDR-bright (modulate > 1) so it survives the
# scene's punchy exposure + ACES tonemap and always blooms / pops.
_WISP_Z = 2.2


def _centre_world(e, z: float = _SPRITE_Z) -> tuple[float, float, float]:
    """World position of an entity centre via the authoritative pixel mapping.

    ``e.cx``/``e.cy`` are logical *pixels*; ``WORLD_SCALE`` converts them into
    the diorama's tile-unit world space (one tile == one world unit).
    """
    return (e.cx * WORLD_SCALE, -e.cy * WORLD_SCALE, z)


def _radial_sprite(colour: tuple[int, int, int], size: int = 16, soft: float = 1.4) -> np.ndarray:
    """A bright emissive radial dot for pickups: saturated tint, only a tiny hot pip.

    Drawn UNLIT, so the dot carries its own light. The tint is held at full
    saturation across the whole disc (the HDR modulate in ``_sync_entity`` lifts
    it over the bloom threshold so it blooms in its OWN colour), and only a small
    central pip is pushed toward white -- enough to read as a "core" without
    washing the crystal cyan / orb gold to a colourless white blob.
    """
    yy, xx = np.mgrid[0:size, 0:size].astype(np.float32)
    c = (size - 1) / 2.0
    d = np.sqrt((xx - c) ** 2 + (yy - c) ** 2) / (size * 0.5)
    field = np.clip(1.0 - d, 0.0, 1.0) ** soft
    # A SMALL, gentle white pip only at the very centre: a wider plateau would
    # bleach the dot, and the hue has to survive across the whole disc.
    core = np.clip((field - 0.78) / 0.22, 0.0, 1.0) ** 1.3 * 0.55
    glow = 0.62 + 0.38 * field  # lift the tint floor so the halo glows, not dims
    out = np.zeros((size, size, 4), dtype=np.uint8)
    for ch, cc in enumerate(colour):
        tint = cc * glow
        out[..., ch] = np.clip(tint + (255.0 - tint) * core, 0, 255)
    out[..., 3] = np.clip(field * 255, 0, 255)
    return out


def _portal_sprite(colour: tuple[int, int, int], size: int = 32) -> np.ndarray:
    """A glowing ring (annulus) for the EXIT: a clearly different shape to pickups.

    Pickups are filled dots; the exit is a bright open ring with a soft halo, so
    the goal reads as a doorway/portal at a glance and never blends into the room
    (a filled green dot on the glade's green stone would). The ring is drawn in a
    saturated, high-contrast colour and runs HDR-bright so it blooms.
    """
    yy, xx = np.mgrid[0:size, 0:size].astype(np.float32)
    c = (size - 1) / 2.0
    r = np.sqrt((xx - c) ** 2 + (yy - c) ** 2) / (size * 0.5)
    # Ring centred at r~0.62, plus a soft outer halo so it glows.
    ring = np.exp(-(((r - 0.62) / 0.16) ** 2))
    halo = np.clip(1.0 - r, 0.0, 1.0) ** 2.2 * 0.45
    field = np.clip(ring + halo, 0.0, 1.0)
    # A small white pip on the ring crest keeps it crisp without killing the hue.
    crest = np.clip((ring - 0.85) / 0.15, 0.0, 1.0) * 0.5
    out = np.zeros((size, size, 4), dtype=np.uint8)
    for ch, cc in enumerate(colour):
        tint = cc * (0.7 + 0.3 * field)
        out[..., ch] = np.clip(tint * field + (255.0 - tint) * crest, 0, 255)
    out[..., 3] = np.clip(field * 255, 0, 255)
    return out


def _star_sprite(colour: tuple[int, int, int], size: int = 32) -> np.ndarray:
    """A bold, FILLED 4-point star with a white-hot core + glow halo.

    A chunky filled star (thick tapering arms + a round body + a soft halo) so
    the collectible reads clearly from across the room. Arm thickness scales with
    the sprite: fixed thin arms would vanish at gameplay distance.
    """
    yy, xx = np.mgrid[0:size, 0:size].astype(np.float32)
    c = (size - 1) / 2.0
    dx, dy = np.abs(xx - c), np.abs(yy - c)
    r = np.sqrt(dx * dx + dy * dy) / (size * 0.5)
    half = size * 0.5
    arm_w = size * 0.16  # thick arms, sized relative to the sprite
    bar_h = np.clip(1.0 - dy / arm_w, 0, 1) * np.clip(1.0 - dx / half, 0, 1)
    bar_v = np.clip(1.0 - dx / arm_w, 0, 1) * np.clip(1.0 - dy / half, 0, 1)
    star = np.maximum(bar_h, bar_v)
    body = np.clip(1.0 - r, 0, 1) ** 1.4  # round filled centre
    glow = np.clip(1.12 - r, 0, 1) ** 2 * 0.55  # soft outer halo
    field = np.clip(np.maximum(np.maximum(star, body), glow), 0.0, 1.0)
    hot = np.clip(1.0 - r * 1.6, 0, 1) ** 1.5  # white-hot centre
    out = np.zeros((size, size, 4), dtype=np.uint8)
    for ch, cc in enumerate(colour):
        out[..., ch] = np.clip(cc * field + (255.0 - cc) * hot, 0, 255)
    out[..., 3] = np.clip(field * 255, 0, 255)
    return out


class EntityView(Node3D):
    """Billboard visuals for one room's entities + the Wisp. ``sync`` per frame.

    Usage::

        ev = EntityView()
        parent.add_child(ev)
        ev.build(room)        # (re)spawn visuals for a room
        # each frame, after room.step(...):
        ev.sync(room, dt)
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._world: str | None = None
        self._wisp: AnimatedSprite3D | None = None
        self._wisp_anim: str | None = None
        # Parallel list aligned with room.entities; each slot is the visual node.
        self._entity_views: list[Node3D | None] = []
        self._spring_flash: dict[int, float] = {}
        self._t = 0.0
        self._sheet: np.ndarray | None = None

    # -- public ------------------------------------------------------------

    def clear(self) -> None:
        self.clear_children()
        self._wisp = None
        self._wisp_anim = None
        self._entity_views = []
        self._spring_flash.clear()
        self._t = 0.0

    def build(self, room) -> None:
        """Spawn one visual per entity plus the player Wisp for ``room``."""
        self.clear()
        self._world = room.palette
        pal = world_palette(self._world)

        self._wisp = self.add_child(self._build_wisp())
        # Build one visual per entity AND parent it under this view, so every
        # shard / crystal / orb / gate / spring / platform / EXIT actually
        # renders (entities with no visual stay None and are skipped in sync).
        self._entity_views = []
        for e in room.entities:
            view = self._build_entity(e, pal)
            if view is not None:
                self.add_child(view)
            self._entity_views.append(view)
        self.sync(room, 0.0)

    def sync(self, room, dt: float = 0.0) -> None:
        """Read room state and update every visual. Read-only over the sim."""
        self._t += dt
        self._sync_wisp(room.player)
        for i, e in enumerate(room.entities):
            view = self._entity_views[i]
            if view is None:
                continue
            self._sync_entity(i, e, view, dt)

    # -- wisp --------------------------------------------------------------

    def _build_wisp(self) -> AnimatedSprite3D:
        sheet, anims = build_wisp_sheet()
        self._sheet = sheet
        spr = AnimatedSprite3D(
            texture=sheet,
            frames_h=FRAMES_HORIZONTAL,
            frames_v=FRAMES_VERTICAL,
            pixel_size=_WISP_PIXEL,
            billboard=True,
            name="wisp",
        )
        for name, a in anims.items():
            spr.add_animation(name, frames=a["frames"], fps=a["fps"], loop=a["loop"])
        spr.play("idle-bob")
        self._wisp_anim = "idle-bob"
        return spr

    def _sync_wisp(self, player) -> None:
        w = self._wisp
        if w is None:
            return
        # Dead: the scatter burst is the Wisp now, so hide the sprite until the
        # room respawns a live one rather than freezing it at the death spot.
        w.visible = player.alive
        if not player.alive:
            return
        w.position = _centre_world(player, _WISP_Z)
        w.flip_h = player.facing < 0

        # Glow overrides the state animation with the warm pulsing 'glow' clip.
        anim = "glow" if player.glowing else _STATE_ANIM.get(player.state, "idle-bob")
        if anim != self._wisp_anim:
            w.play(anim)
            self._wisp_anim = anim

        # HDR-bright modulate (>1) so the unlit Wisp always pops + blooms against
        # the dark, punchy worlds; glowing pushes it brighter and warm.
        if player.glowing:
            pulse = 0.5 + 0.5 * math.sin(self._t * 8.0)
            b = 3.4 + 0.9 * pulse
            w.modulate = (b, b * (0.94 + 0.06 * pulse), b * (0.74 + 0.18 * pulse), 1.0)
        else:
            b = 2.6
            w.modulate = (b, b, b, 1.0)

    # -- per-entity visuals ------------------------------------------------

    def _build_entity(self, e, pal) -> Node3D | None:
        if isinstance(e, Crystal):
            # Larger (1.6 tiles) so the resonance crystal reads clearly; the HDR
            # pulse in _sync_entity makes it bloom out of the dark caverns.
            return self._pickup_sprite(pal["crystal"], "crystal_view", soft=1.6, tiles=1.6)
        if isinstance(e, GlowOrb):
            return self._pickup_sprite(pal["accent"], "orb_view", soft=2.0, tiles=1.7)
        if isinstance(e, Shard):
            # ~3.6 tiles, a bold GOLD star: a distinct colour + filled shape so it
            # never blends into the white Wisp or the world's stone. HDR pulse in
            # _sync_entity makes it bloom brightly.
            spr = Sprite3D(
                texture=_star_sprite((255, 205, 70), size=32),
                pixel_size=3.6 / 32.0,
                billboard=True,
                name="shard_view",
            )
            return spr
        if isinstance(e, Spring):
            return self._pickup_sprite(pal["metal"], "spring_view", soft=1.2, size=16)
        if isinstance(e, LightGate):
            return self._gate_box(pal)
        if isinstance(e, MovingPlatform):
            return self._platform_box(e, pal)
        if getattr(e, "kind", "") == "exit":
            return self._exit_portal()
        return None

    def _exit_portal(self) -> Sprite3D:
        # A bright warm-white ring so the goal reads as a doorway of light on
        # every world (green glade / blue caverns / amber spire), never blending
        # into the room the way a palette-accent dot did.
        return Sprite3D(
            texture=_portal_sprite(_EXIT_COLOUR, size=32),
            pixel_size=2.4 / 32.0,
            billboard=True,
            name="exit_view",
        )

    def _pickup_sprite(self, colour, name, *, soft=1.5, size=16, tiles=1.0) -> Sprite3D:
        return Sprite3D(
            texture=_radial_sprite(colour, size=size, soft=soft),
            pixel_size=tiles / size,
            billboard=True,
            name=name,
        )

    def _gate_box(self, pal) -> MeshInstance3D:
        mesh = create_box((1.0, 1.0, 0.6))
        colour = np.array(pal["crystal"], dtype=np.float32) / 255.0
        mat = Material(
            colour=(*colour, 0.5),
            blend="alpha",
            emissive_colour=tuple(colour),
            emissive_strength=2.0,
        )
        return MeshInstance3D(mesh=mesh, material=mat, name="gate_view")

    def _platform_box(self, e, pal) -> MeshInstance3D:
        # Platform is 16x4 px: 2.0 x 0.5 world units, shallow in Z.
        mesh = create_box((e.w * WORLD_SCALE, e.h * WORLD_SCALE, 0.6))
        colour = np.array(pal["metal"], dtype=np.float32) / 255.0
        mat = Material(colour=(*colour, 1.0), roughness=0.5, metallic=0.6)
        return MeshInstance3D(mesh=mesh, material=mat, name="platform_view")

    def _sync_entity(self, i: int, e, view: Node3D, dt: float) -> None:
        # Flat billboard pickups ride forward (_SPRITE_Z) so the diorama relief
        # never occludes them; the box-mesh entities (gate / moving platform) are
        # real 3D geometry and stay at the level's play-plane depth.
        z = 0.0 if isinstance(e, LightGate | MovingPlatform) else _SPRITE_Z
        view.position = _centre_world(e, z)

        if isinstance(e, Crystal):
            view.visible = e.alive
            # HDR-bright (>1), pulsing so the unlit billboard clears the bloom
            # threshold and the resonance crystal visibly glows + breathes.
            pulse = 0.5 + 0.5 * math.sin(self._t * 4.0 + i)
            b = 2.8 + 1.0 * pulse
            view.modulate = (b, b, b, 1.0)
        elif isinstance(e, GlowOrb):
            view.visible = True
            # Same HDR-bright pulse; dims (but stays lit) once consumed so the
            # spent orb still reads as a fading ember rather than vanishing.
            pulse = 0.5 + 0.5 * math.sin(self._t * 4.0 + i)
            b = (3.0 + 1.2 * pulse) if e.available else 0.6
            view.modulate = (b, b, b, 1.0)
        elif isinstance(e, Shard):
            view.visible = not e.collected
            # Bright + pulsing so it blooms, but modest enough that the GOLD colour
            # still reads (a high HDR multiplier washes it to white).
            b = 1.9 + 0.4 * math.sin(self._t * 6.0 + i)
            view.modulate = (b, b, b, 1.0)
        elif isinstance(e, Spring):
            # Contact flash: latched full on launch, then drained in REAL time so
            # the flash lasts the same 0.25s at any frame rate.
            flash = self._spring_flash.get(i, 0.0)
            if e.cooldown > 0.0:
                self._spring_flash[i] = _SPRING_FLASH
                flash = _SPRING_FLASH
            elif flash > 0.0:
                flash = max(0.0, flash - dt)
                self._spring_flash[i] = flash
            view.modulate = (1.0, 1.0, 1.0, min(1.0, 0.6 + 2.0 * flash))
        elif isinstance(e, LightGate):
            view.visible = True
            mat: Material = view.material
            if e.solid:
                mat.colour = (*mat.colour[:3], 0.9)
                mat.emissive_strength = 2.5
            else:
                # Untriggered: a barely-there ghost so it clearly reads as passable
                # (you can walk/dash through it until you are glowing).
                mat.colour = (*mat.colour[:3], 0.05)
                mat.emissive_strength = 0.12
        elif isinstance(e, MovingPlatform):
            pass  # position already tracked above
        elif getattr(e, "kind", "") == "exit":
            # HDR-bright and gently breathing so the portal ring clears the bloom
            # threshold and beckons (was a dim alpha pulse that barely showed).
            pulse = 0.5 + 0.5 * math.sin(self._t * 2.5)
            b = 2.4 + 0.8 * pulse
            view.modulate = (b, b, b, 1.0)