afterglow/assets/textures.py

Part of Afterglow.

"""Procedural placeholder PBR textures for the Afterglow diorama view.

PLACEHOLDER ART: generated in code; swap these for real PNGs later without
touching gameplay. The logical sim never imports this module: only the 3D view
layer consumes these maps. Every function returns a tileable RGBA uint8 ndarray
of shape (H, W, 4), the same contract as
``simvx.core.port_helpers.procedural_textures``.

Each material exposes three maps:
  albedo    : base colour (RGBA, A=255)
  normal    : tangent-space normal packed to RGB (B up), A=255
  emissive  : emitted light (RGB; A used as emission strength mask)

Tileability: noise is sampled at integer frequencies over the [0, 1) domain so
the left/right and top/bottom edges line up seamlessly (period == 1.0).

Palettes per world (gameplay-neutral, view-only):
  glade   : warm greens (overgrown light-glade)
  caverns : blue / violet (deep resonant caves)
  spire   : gold / black (the final ascent)
"""

from __future__ import annotations

from functools import cache

import numpy as np

from simvx.core.noise import FastNoiseLite, FractalType, NoiseType
from simvx.core.port_helpers.procedural_textures import solid

RGB = tuple[int, int, int]

# --------------------------------------------------------------------------
# Per-world palettes. Keys are stable; the view picks by Room.palette / world id.
# --------------------------------------------------------------------------
PALETTES: dict[str, dict[str, RGB]] = {
    # VIBRANT & PUNCHY: each world is saturated with a wide low->high stone
    # contrast so the relief reads crisply (not a flat grey-green wash) and the
    # crystal/metal hues stay distinct from the stone. Crystal colours are kept
    # bright + pure so they bloom cleanly.
    "glade": {
        "stone_low": (30, 58, 24),  # deep mossy green (clear shadow)
        "stone_high": (120, 196, 78),  # bright lit fern-green (saturated)
        "crystal": (110, 255, 150),  # vivid emerald glow
        "metal": (96, 140, 96),  # mossed bronze-green
        "accent": (212, 255, 150),  # golden-lime highlight
    },
    "caverns": {
        "stone_low": (18, 22, 56),  # near-black indigo (deep dark)
        "stone_high": (78, 96, 200),  # saturated electric blue (lit faces)
        "crystal": (120, 150, 255),  # intense glowing cyan-violet
        "metal": (60, 74, 130),  # cold steel-blue
        "accent": (150, 220, 255),  # icy cyan highlight
    },
    "spire": {
        "stone_low": (26, 19, 11),  # near-black warm shadow
        "stone_high": (140, 102, 40),  # rich glowing bronze (lit faces)
        "crystal": (255, 196, 70),  # hot molten gold
        "metal": (205, 162, 60),  # polished brass
        "accent": (255, 232, 140),  # bright gold highlight
    },
}

DEFAULT_SIZE = 64


# --------------------------------------------------------------------------
# Internal helpers
# --------------------------------------------------------------------------
def _tileable_noise(size: int, *, seed: int, period: int, octaves: int, ntype: NoiseType) -> np.ndarray:
    """Seamless [0, 1] noise field of shape (size, size).

    Sampling at frequency == period / size over pixel coords gives an integer
    number of feature cells across the image, so opposite edges match.
    """
    n = FastNoiseLite(seed=seed, noise_type=ntype, frequency=period / size)
    n.fractal_type = FractalType.FBM
    n.fractal_octaves = octaves
    img = n.get_image(size, size, scale=1.0)  # (size, size) in ~[-1, 1]
    return (img * 0.5 + 0.5).astype(np.float32)


def _height_to_normal(height: np.ndarray, strength: float = 2.0) -> np.ndarray:
    """Pack a height field (HxW, [0,1]) into a tangent-space RGBA normal map."""
    gx = np.roll(height, -1, axis=1) - np.roll(height, 1, axis=1)
    gy = np.roll(height, -1, axis=0) - np.roll(height, 1, axis=0)
    nx = -gx * strength
    ny = -gy * strength
    nz = np.ones_like(height)
    inv = 1.0 / np.sqrt(nx * nx + ny * ny + nz * nz)
    nx, ny, nz = nx * inv, ny * inv, nz * inv
    out = np.empty((*height.shape, 4), dtype=np.uint8)
    out[..., 0] = np.clip((nx * 0.5 + 0.5) * 255, 0, 255)
    out[..., 1] = np.clip((ny * 0.5 + 0.5) * 255, 0, 255)
    out[..., 2] = np.clip((nz * 0.5 + 0.5) * 255, 0, 255)
    out[..., 3] = 255
    return out


def _contrast(field: np.ndarray, power: float) -> np.ndarray:
    """Re-curve a [0,1] field around its midpoint to widen low->high contrast.

    ``power > 1`` deepens the dark end and brightens the light end about 0.5, so
    a tinted albedo spans more of its low->high palette range (crisper relief).
    """
    return np.clip((field - 0.5) * power + 0.5, 0.0, 1.0)


def _tint(height: np.ndarray, low: RGB, high: RGB) -> np.ndarray:
    """Lerp two colours by a [0,1] field into an opaque RGBA albedo."""
    lo = np.array(low, dtype=np.float32)
    hi = np.array(high, dtype=np.float32)
    rgb = lo[None, None, :] + height[..., None] * (hi - lo)[None, None, :]
    out = np.empty((*height.shape, 4), dtype=np.uint8)
    out[..., :3] = np.clip(rgb, 0, 255).astype(np.uint8)
    out[..., 3] = 255
    return out


# --------------------------------------------------------------------------
# Material generators (cached: textures are pure functions of their inputs)
# --------------------------------------------------------------------------
@cache
def stone(world: str, size: int = DEFAULT_SIZE) -> dict[str, np.ndarray]:
    """Rough solid-tile rock for a world. Returns {albedo, normal, emissive}."""
    pal = PALETTES[world]
    h = _tileable_noise(size, seed=11 + hash(world) % 64, period=4, octaves=4, ntype=NoiseType.PERLIN)
    # Push the low->high contrast so lit and shadowed rock read distinctly under
    # the three-point rig (gamma < 1 lifts midtones; the >1 power deepens it).
    h = _contrast(h, 1.6)
    return {
        "albedo": _tint(h, pal["stone_low"], pal["stone_high"]),
        "normal": _height_to_normal(h, strength=4.5),
        "emissive": solid((size, size), (0, 0, 0, 0)),
    }


@cache
def crystal(world: str, size: int = DEFAULT_SIZE) -> dict[str, np.ndarray]:
    """Emissive resonance crystal. Cellular facets + bright glow core."""
    pal = PALETTES[world]
    n = FastNoiseLite(seed=29 + hash(world) % 64, noise_type=NoiseType.CELLULAR, frequency=3 / size)
    n.cellular_return_type = "distance2"
    facets = (n.get_image(size, size, scale=1.0) * 0.5 + 0.5).astype(np.float32)
    albedo = _tint(facets, pal["crystal"], pal["accent"])
    glow = np.array(pal["crystal"], dtype=np.float32)
    emissive = np.empty((size, size, 4), dtype=np.uint8)
    emissive[..., :3] = np.clip(glow[None, None, :] * (0.4 + 0.6 * facets[..., None]), 0, 255).astype(np.uint8)
    emissive[..., 3] = np.clip(facets * 255, 0, 255).astype(np.uint8)
    return {"albedo": albedo, "normal": _height_to_normal(facets, strength=4.0), "emissive": emissive}


@cache
def metal(world: str, size: int = DEFAULT_SIZE) -> dict[str, np.ndarray]:
    """Brushed metal for light-gates. Anisotropic streaks via value noise."""
    pal = PALETTES[world]
    n = FastNoiseLite(seed=53 + hash(world) % 64, noise_type=NoiseType.VALUE, frequency=1 / size)
    # Stretch vertically for a brushed look: sample at high x freq, low y freq.
    iy, ix = np.meshgrid(np.arange(size), np.arange(size), indexing="ij")
    streak = n.get_noise_2d_array(ix.ravel() * 12.0, iy.ravel() * 1.0).reshape(size, size)
    h = (streak * 0.5 + 0.5).astype(np.float32)
    h = _contrast(h, 1.4)
    return {
        "albedo": _tint(h, pal["metal"], pal["accent"]),
        "normal": _height_to_normal(h, strength=2.2),
        "emissive": solid((size, size), (0, 0, 0, 0)),
    }


def world_palette(world: str) -> dict[str, RGB]:
    """Return the colour palette dict for a world id."""
    return PALETTES[world]


def all_materials(world: str, size: int = DEFAULT_SIZE) -> dict[str, dict[str, np.ndarray]]:
    """Convenience: every material for a world, keyed by material name.

    The diorama only maps ``stone`` onto geometry today and asks for it directly;
    ``crystal`` and ``metal`` are swap-in placeholders for crystal / gate meshes,
    so build the whole set only when you actually want all three.
    """
    return {"stone": stone(world, size), "crystal": crystal(world, size), "metal": metal(world, size)}


if __name__ == "__main__":
    for w in PALETTES:
        mats = all_materials(w)
        print(f"world={w!r} palette_keys={list(world_palette(w))}")
        for name, maps in mats.items():
            shapes = {k: (v.shape, str(v.dtype)) for k, v in maps.items()}
            print(f"  {name}: {shapes}")