shrike/artkit.py

Part of SHRIKE.

"""Procedural art kit for SHRIKE: every mesh, material, sky and grade is generated.

No asset file ships with the game. Hulls, enemies, stations, wrecks and rocks
are kitbashed from engine primitives, CSG cuts, swept extrusions and noise
displacement; materials are metallic-roughness with the emissive accents that
carry the readability contract; the sky is a synthesized nebula cubemap that
also drives image-based lighting; and the per-act look is a grade applied to a
``WorldEnvironment``.

Nothing here needs a GPU or a window: every entry point produces plain CPU data
and ordinary scene nodes, so the whole kit constructs headlessly.

Conventions
===========

* Ships and enemies are built nose-along local **+X**, matching
  :func:`runtime.heading_to_direction` at heading 0, so yawing a node about +Y
  by its heading aims it where the gameplay code says it points.
* Y is up. A build is centred on its own origin, so a node sitting at
  ``y = runtime.PLANE_Y`` puts the hull's waist on the flight plane.
* Every build returns a :class:`Node3D` carrying at most three
  :class:`MeshInstance3D` children, named :data:`ROLE_HULL`, :data:`ROLE_TRIM`
  and :data:`ROLE_ACCENT`. ``Accent`` holds the emissive geometry;
  :func:`apply_faction_materials` re-skins all three from one palette.

The readability contract
========================

Ownership reads off emissive colour against low-albedo surroundings: player
warm gold and white, enemy cold magenta, telegraphs pure white, environments
near-black. :data:`PALETTES` is the single place those three values live, and
:func:`apply_faction_materials` is the only way geometry acquires them.
"""

from __future__ import annotations

import math
from dataclasses import dataclass
from functools import cache

import numpy as np

from simvx.core import (
    CSGOperation,
    FastNoiseLite,
    FractalType,
    Material,
    Mesh,
    MeshInstance3D,
    Node3D,
    NoiseType,
    Quat,
    Vec3,
    WorldEnvironment,
    csg_combine,
)
from simvx.core.math.matrices import quat_to_mat4

from . import balance
from .runtime import PLANE_Y

# ============================================================================
# Module-local constants
#
# None of these is a balance number: they are proportions and render settings,
# which balance.py deliberately does not carry.
# ============================================================================

#: Mesh instance names, one per material role in a build.
ROLE_HULL = "Hull"
ROLE_TRIM = "Trim"
ROLE_ACCENT = "Accent"
ROLES = (ROLE_HULL, ROLE_TRIM, ROLE_ACCENT)

#: Every faction :func:`apply_faction_materials` accepts.
FACTIONS = ("player", "enemy", "hunter", "environment", "telegraph")

#: Per-face resolution of the synthesized nebula cubemap. A face covers 90
#: degrees, so the face size sets how small a star can be: at 256 one texel
#: spanned a third of a degree, which is five screen pixels, and a star stamped
#: into a single texel came out as a hard white square the size of a die. 512
#: halves that, and the soft stamp below spreads a star over it.
NEBULA_FACE_SIZE = 512

#: Resolution the cloud noise is actually evaluated at, before it is resampled
#: up to the face size. Clouds are soft and dim, so they cost the same few
#: milliseconds they always did however sharp the star layer gets.
NEBULA_CLOUD_SIZE = 64

#: How bright the cloud layer is allowed to get. The readability contract wants
#: a near-black sky so emissive accents own the screen; the raw noise is graded
#: for shape, and this is what keeps it a backdrop rather than a light box.
NEBULA_CLOUD_ENERGY = 0.5

#: Stars stamped into one cube face at :data:`NEBULA_FACE_SIZE`, scaled by area
#: for any other bake size, and the energy band one star peaks at. Only the top of the band clears the bloom threshold,
#: so a sky has a handful of bright stars in a field of faint ones rather than
#: several hundred lamps.
STARS_PER_FACE = 70
STAR_ENERGY_MIN = 0.35
STAR_ENERGY_MAX = 2.4
#: However small a face is baked, it gets at least this many stars: a 16-pixel
#: test bake must still contain a sky.
STAR_MIN_PER_FACE = 3
#: A star is a Gaussian splat, not a texel: this is its standard deviation in
#: texels and the radius, in texels, the splat is evaluated out to.
STAR_SIGMA = 0.85
STAR_KERNEL_RADIUS = 2
#: How far a star's hue is pushed from white toward warm or cold. Real skies
#: are not monochrome, and the variation is what stops a field of dots reading
#: as a texture artefact.
STAR_TINT = 0.16

#: Silent running drops the whole scene's exposure by this factor.
SILENT_RUNNING_EXPOSURE_MULT = 0.65

#: Body segments the Shrike is built from (head plus tail sections).
SHRIKE_SEGMENT_COUNT = 7

# Cube face bases in Vulkan order [+X, -X, +Y, -Y, +Z, -Z]: (right, up, forward).
_FACE_BASIS = (
    ((0.0, 0.0, -1.0), (0.0, -1.0, 0.0), (1.0, 0.0, 0.0)),
    ((0.0, 0.0, 1.0), (0.0, -1.0, 0.0), (-1.0, 0.0, 0.0)),
    ((1.0, 0.0, 0.0), (0.0, 0.0, 1.0), (0.0, 1.0, 0.0)),
    ((1.0, 0.0, 0.0), (0.0, 0.0, -1.0), (0.0, -1.0, 0.0)),
    ((1.0, 0.0, 0.0), (0.0, -1.0, 0.0), (0.0, 0.0, 1.0)),
    ((-1.0, 0.0, 0.0), (0.0, -1.0, 0.0), (0.0, 0.0, -1.0)),
)

# Quaternions that reorient a +Y primitive (cylinder, cone) onto another axis.
_Y_TO_X = Quat.from_axis_angle(Vec3(0.0, 0.0, 1.0), -math.pi / 2.0)
_Y_TO_Z = Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), math.pi / 2.0)
_Y_TO_NEG_Z = Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), -math.pi / 2.0)
_Y_TO_NEG_X = Quat.from_axis_angle(Vec3(0.0, 0.0, 1.0), math.pi / 2.0)


# ============================================================================
# Kitbash builder
# ============================================================================


class Kit:
    """Accumulates transformed primitives into one merged :class:`Mesh`.

    This is the kitbash itself: a build places scaled, rotated copies of a
    handful of shared unit primitives and ends with a single mesh, so a whole
    archetype costs one draw rather than one per greeble.

    Mirrored parts are ordinary: a negative scale factor flips the winding and
    the normals back, so ``scale=(1, 1, -1)`` gives a correct opposite wing.
    """

    def __init__(self) -> None:
        self._positions: list[np.ndarray] = []
        self._normals: list[np.ndarray] = []
        self._texcoords: list[np.ndarray] = []
        self._indices: list[np.ndarray] = []
        self._vertex_count = 0

    @property
    def empty(self) -> bool:
        return self._vertex_count == 0

    def add(
        self,
        mesh: Mesh,
        *,
        position: tuple[float, float, float] = (0.0, 0.0, 0.0),
        rotation: Quat | None = None,
        scale: float | tuple[float, float, float] = 1.0,
    ) -> Kit:
        """Place a transformed copy of *mesh*. The source is never mutated."""
        if mesh.indices is None:
            raise ValueError("Kit.add requires an indexed mesh")
        factors = np.asarray(scale if isinstance(scale, (tuple, list, np.ndarray)) else (scale,) * 3, dtype=np.float32)
        positions = mesh.positions * factors
        normals = mesh.normals if mesh.normals is not None else np.zeros_like(mesh.positions)
        # Normals transform by the inverse transpose, which for a diagonal
        # scale is the reciprocal; renormalised below.
        normals = normals / np.where(np.abs(factors) < 1e-9, 1e-9, factors)
        if rotation is not None:
            rot = np.asarray(quat_to_mat4(rotation), dtype=np.float32)[:3, :3]
            positions = positions @ rot.T
            normals = normals @ rot.T
        positions = positions + np.asarray(position, dtype=np.float32)
        lengths = np.linalg.norm(normals, axis=1, keepdims=True)
        normals = np.divide(normals, lengths, where=lengths > 1e-9, out=np.zeros_like(normals))

        texcoords = mesh.texcoords if mesh.texcoords is not None else np.zeros((len(positions), 2), dtype=np.float32)
        triangles = mesh.indices.reshape(-1, 3) + self._vertex_count
        if float(np.prod(factors)) < 0.0:
            # A mirroring scale turns every triangle inside out. The reciprocal
            # above has already flipped the normals; the winding needs the same.
            triangles = triangles[:, ::-1]

        self._positions.append(positions.astype(np.float32))
        self._normals.append(normals.astype(np.float32))
        self._texcoords.append(np.asarray(texcoords, dtype=np.float32))
        self._indices.append(triangles.astype(np.uint32))
        self._vertex_count += len(positions)
        return self

    def build(self) -> Mesh:
        """Merge everything placed so far into one mesh."""
        if self.empty:
            raise ValueError("Kit.build called with nothing placed")
        return Mesh(
            np.concatenate(self._positions),
            np.concatenate(self._indices).ravel(),
            np.concatenate(self._normals),
            np.concatenate(self._texcoords),
        )


@cache
def _unit_cube() -> Mesh:
    return Mesh.cube(1.0)


@cache
def _unit_cylinder(segments: int = 12) -> Mesh:
    return Mesh.cylinder(radius=0.5, height=1.0, segments=segments)


@cache
def _unit_cone(segments: int = 10) -> Mesh:
    return Mesh.cone(radius=0.5, height=1.0, segments=segments)


@cache
def _unit_sphere(rings: int = 8, segments: int = 12) -> Mesh:
    return Mesh.sphere(radius=0.5, rings=rings, segments=segments)


def _greeble(kit: Kit, rng: np.random.Generator, *, span: tuple[float, float, float], count: int, size: float) -> None:
    """Scatter small plated boxes over a body of the given half-extents.

    Greebling is what makes one kit read as a whole faction: the same hull with
    a different scatter seed is a different ship at a glance.
    """
    for _ in range(count):
        along = float(rng.uniform(-span[0], span[0]))
        side = float(rng.uniform(-span[2], span[2]))
        top = span[1] * float(rng.choice([-1.0, 1.0])) * float(rng.uniform(0.75, 1.0))
        block = (
            size * float(rng.uniform(0.6, 2.2)),
            size * float(rng.uniform(0.3, 0.8)),
            size * float(rng.uniform(0.6, 1.8)),
        )
        kit.add(
            _unit_cube(),
            position=(along, top, side),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), float(rng.uniform(0.0, math.tau))),
            scale=block,
        )


def _displaced_rock(seed: int, radius: float, *, relief: float = 0.34, rings: int = 12, segments: int = 16) -> Mesh:
    """A sphere pushed around by fractal noise: the asteroid and deposit body.

    The UV sphere's seam and pole vertices are coincident, so sampling the
    noise in object space displaces them identically and the surface stays
    watertight.
    """
    mesh = Mesh.sphere(radius=radius, rings=rings, segments=segments)
    noise = FastNoiseLite(seed=int(seed), noise_type=NoiseType.SIMPLEX, frequency=1.05 / max(radius, 1e-3))
    noise.fractal_type = FractalType.FBM
    noise.fractal_octaves = 4
    points = mesh.positions
    amount = noise.get_noise_3d_array(points[:, 0], points[:, 1], points[:, 2])
    mesh.positions = (points * (1.0 + amount[:, None] * relief)).astype(np.float32)
    # The mesh is no longer the primitive its factory spec claims.
    mesh.factory_spec = None
    mesh.generate_normals()
    # A UV sphere's pole fan is degenerate, so face-averaged normals there come
    # out zero. The body stays star-shaped under displacement, so the radial
    # direction is the right normal for exactly those vertices.
    radius_per_vertex = np.linalg.norm(mesh.positions, axis=1, keepdims=True)
    radial = np.divide(
        mesh.positions,
        radius_per_vertex,
        where=radius_per_vertex > 1e-9,
        out=np.zeros_like(mesh.positions),
    )
    degenerate = np.linalg.norm(mesh.normals, axis=1) < 1e-6
    mesh.normals[degenerate] = radial[degenerate]
    return mesh


def _mesh_instance(name: str, mesh: Mesh, material: Material) -> MeshInstance3D:
    return MeshInstance3D(name=name, mesh=mesh, material=material)


# ============================================================================
# Materials: the readability contract
# ============================================================================


@dataclass(frozen=True)
class FactionPalette:
    """One faction's metallic-roughness look plus its emissive signature.

    ``accent`` and ``accent_strength`` are the readability contract: they are
    what the player reads at a glance through two hundred particles, so they
    are deliberately few and far apart in hue.
    """

    id: str
    hull_colour: tuple[float, float, float, float]
    hull_metallic: float
    hull_roughness: float
    trim_colour: tuple[float, float, float, float]
    trim_metallic: float
    trim_roughness: float
    accent: tuple[float, float, float]
    accent_strength: float
    #: Faint hull self-light, as an emissive strength on the hull's own colour.
    #: Zero for everything that is allowed to read as a silhouette. A highly
    #: metallic hull under a dark skybox reflects mostly nothing, and a blind
    #: playtest read the flown ship as a black cutout against the bright acts'
    #: nebulae; the glow floors the hull's brightness without touching the
    #: emissive accents that own the readability contract, and it sits far
    #: under the bloom threshold.
    hull_glow: float = 0.0


#: Player warm gold and white, enemy cold magenta, telegraph white, hunter a
#: bruised violet, environments near-black so all four still win.
PALETTES: dict[str, FactionPalette] = {
    "player": FactionPalette(
        "player",
        hull_colour=(0.60, 0.62, 0.66, 1.0),
        hull_metallic=0.62,
        hull_roughness=0.42,
        trim_colour=(0.24, 0.25, 0.28, 1.0),
        trim_metallic=0.70,
        trim_roughness=0.52,
        accent=(1.0, 0.80, 0.42),
        accent_strength=5.0,
        hull_glow=0.30,
    ),
    "enemy": FactionPalette(
        "enemy",
        hull_colour=(0.26, 0.23, 0.30, 1.0),
        hull_metallic=0.72,
        hull_roughness=0.48,
        trim_colour=(0.14, 0.12, 0.17, 1.0),
        trim_metallic=0.55,
        trim_roughness=0.68,
        accent=(1.0, 0.10, 0.72),
        accent_strength=5.0,
    ),
    "hunter": FactionPalette(
        "hunter",
        hull_colour=(0.10, 0.09, 0.13, 1.0),
        hull_metallic=0.48,
        hull_roughness=0.72,
        trim_colour=(0.05, 0.05, 0.07, 1.0),
        trim_metallic=0.40,
        trim_roughness=0.82,
        accent=(0.86, 0.62, 1.0),
        accent_strength=6.5,
    ),
    "environment": FactionPalette(
        "environment",
        hull_colour=(0.045, 0.048, 0.055, 1.0),
        hull_metallic=0.12,
        hull_roughness=0.88,
        trim_colour=(0.030, 0.032, 0.038, 1.0),
        trim_metallic=0.30,
        trim_roughness=0.74,
        accent=(0.95, 0.55, 0.20),
        accent_strength=2.0,
    ),
    "telegraph": FactionPalette(
        "telegraph",
        hull_colour=(0.90, 0.90, 0.90, 1.0),
        hull_metallic=0.0,
        hull_roughness=1.0,
        trim_colour=(0.90, 0.90, 0.90, 1.0),
        trim_metallic=0.0,
        trim_roughness=1.0,
        accent=(1.0, 1.0, 1.0),
        accent_strength=8.0,
    ),
}

#: Ceiling on any environment albedo channel. Emissive readability only works
#: against surroundings that stay dark, so this is asserted, not hoped for.
ENVIRONMENT_ALBEDO_CEILING = 0.12


def palette(faction: str) -> FactionPalette:
    """The palette for *faction*, raising on anything outside :data:`FACTIONS`."""
    try:
        return PALETTES[faction]
    except KeyError:
        raise ValueError(f"Unknown faction {faction!r}; expected one of {', '.join(FACTIONS)}") from None


def faction_material(faction: str, role: str = ROLE_HULL) -> Material:
    """A fresh material for one *role* of one *faction*.

    Fresh rather than shared: consumers flash accents white for telegraphs and
    tint hulls for elites, and a shared material would leak that across every
    instance in the sector.
    """
    if role not in ROLES:
        raise ValueError(f"Unknown material role {role!r}; expected one of {', '.join(ROLES)}")
    pal = palette(faction)
    if role == ROLE_ACCENT:
        return Material(
            colour=(*pal.accent, 1.0),
            metallic=0.0,
            roughness=0.45,
            emissive_colour=pal.accent,
            emissive_strength=pal.accent_strength,
        )
    if role == ROLE_TRIM:
        return Material(colour=pal.trim_colour, metallic=pal.trim_metallic, roughness=pal.trim_roughness)
    if pal.hull_glow > 0.0:
        return Material(
            colour=pal.hull_colour,
            metallic=pal.hull_metallic,
            roughness=pal.hull_roughness,
            emissive_colour=pal.hull_colour[:3],
            emissive_strength=pal.hull_glow,
        )
    return Material(colour=pal.hull_colour, metallic=pal.hull_metallic, roughness=pal.hull_roughness)


def apply_faction_materials(node: Node3D, faction: str) -> None:
    """Re-skin every mesh under *node* from one faction palette.

    The single enforcement point for the readability contract: geometry gets
    its ownership colour here and nowhere else, so a telegraph flash is a
    re-skin to ``"telegraph"`` and back rather than an ad hoc colour poke.
    """
    palette(faction)  # Validate before touching anything.
    for instance in node.find_all(MeshInstance3D):
        role = instance.name if instance.name in ROLES else ROLE_HULL
        instance.material = faction_material(faction, role)


# ============================================================================
# Player hulls
# ============================================================================


@dataclass(frozen=True)
class HullSpec:
    """Proportions of one player hull. Socket counts come from balance."""

    id: str
    length: float
    beam: float
    depth: float
    engines: int
    greebles: int


HULLS: dict[str, HullSpec] = {
    "vagrant": HullSpec("vagrant", length=2.6, beam=1.7, depth=0.62, engines=2, greebles=14),
    "barge": HullSpec("barge", length=3.2, beam=2.6, depth=0.92, engines=2, greebles=22),
    "dart": HullSpec("dart", length=3.4, beam=1.1, depth=0.48, engines=1, greebles=8),
    "hive": HullSpec("hive", length=2.8, beam=2.2, depth=0.78, engines=4, greebles=16),
}

#: The reference hull length the Shrike is sized against.
PLAYER_SHIP_LENGTH = HULLS["vagrant"].length

#: Where the weapon rack bolts a gun, in the kit's own nose-along-+X frame.
#: ``weapons.HARDPOINT_OFFSETS`` names the same four places in the hull's local
#: frame, where the nose runs down -Z; the ship mounts this build with a quarter
#: turn about +Y, which sends art +X onto ship -Z, so ``(art_x, art_z)`` is
#: ``(-ship_z, ship_x)``. The table is restated rather than imported because
#: ``weapons`` sits above the art kit in the import order; ``test_ship`` pins the
#: two together so they cannot drift apart in silence.
HARDPOINT_MOUNTS = ((-0.15, -0.85), (-0.15, 0.85), (0.55, -1.45), (0.55, 1.45))

#: How many mounts a hull carries unless the caller says otherwise. A bare mount
#: is still built: an empty pylon is what tells a pilot the hull has room, and it
#: is the only reason a third and fourth gun look like they belong on the ship
#: rather than floating a metre off its flank.
HARDPOINTS_DEFAULT = balance.HARDPOINTS_STARTER


def hull_spec(hull: str) -> HullSpec:
    """The :class:`HullSpec` for *hull*, raising on an unknown id."""
    try:
        return HULLS[hull]
    except KeyError:
        raise ValueError(f"Unknown hull {hull!r}; expected one of {', '.join(HULLS)}") from None


def _add_hardpoint_mounts(trim: Kit, spec: HullSpec, hardpoints: int) -> None:
    """Bolt a pylon and a collar under each of the hull's first *hardpoints* mounts.

    Mounts go in the trim mesh rather than the hull mesh on purpose: the hull
    mesh is the silhouette, and four pylons at fixed offsets would give every
    hull the same beam and erase the difference between a Dart and a Barge.
    """
    for mount_x, mount_z in HARDPOINT_MOUNTS[: max(0, int(hardpoints))]:
        root_z = math.copysign(spec.beam * 0.30, mount_z)
        drop = -spec.depth * 0.22
        trim.add(
            _unit_cube(),
            position=(mount_x, drop, (root_z + mount_z) * 0.5),
            scale=(spec.length * 0.09, spec.depth * 0.24, abs(mount_z - root_z)),
        )
        trim.add(
            _unit_cylinder(10),
            position=(mount_x, drop, mount_z),
            rotation=_Y_TO_X,
            scale=(spec.depth * 0.36, spec.length * 0.11, spec.depth * 0.36),
        )


def _build_player_meshes(hull: str, seed: int, hardpoints: int) -> tuple[Mesh, Mesh, Mesh]:
    spec = hull_spec(hull)
    rng = np.random.default_rng((seed, hash(hull) & 0xFFFF))
    half = spec.length / 2.0

    body = Kit()
    # Spine: a tapered fuselage cut from a box by a wedge, so the nose reads
    # sharp without a separate cone joint.
    fuselage = csg_combine(
        _scaled(_unit_cube(), (spec.length * 0.78, spec.depth, spec.beam * 0.46)),
        _scaled(_unit_cone(12), (spec.beam * 1.9, spec.length * 1.4, spec.beam * 1.9), rotation=_Y_TO_X),
        CSGOperation.INTERSECT,
    )
    body.add(fuselage)
    body.add(
        _unit_cone(10),
        position=(half * 0.86, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(spec.beam * 0.34, half * 0.5, spec.depth * 0.9),
    )
    # Swept wings, mirrored across the spine.
    for side in (1.0, -1.0):
        body.add(
            _unit_cube(),
            position=(-spec.length * 0.06, 0.0, side * spec.beam * 0.34),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.26),
            scale=(spec.length * 0.42, spec.depth * 0.42, spec.beam * 0.5),
        )
    _greeble(body, rng, span=(spec.length * 0.34, spec.depth * 0.5, spec.beam * 0.4), count=spec.greebles, size=0.1)

    trim = Kit()
    engine_spacing = spec.beam * 0.62 / max(spec.engines, 1)
    for index in range(spec.engines):
        offset = (index - (spec.engines - 1) / 2.0) * engine_spacing * 2.0
        trim.add(
            _unit_cylinder(12),
            position=(-half * 0.82, 0.0, offset),
            rotation=_Y_TO_X,
            scale=(spec.depth * 0.72, spec.length * 0.26, spec.depth * 0.72),
        )
    # Dorsal sensor spine and the shield-emitter ring collar.
    trim.add(
        _unit_cube(),
        position=(half * 0.1, spec.depth * 0.52, 0.0),
        scale=(spec.length * 0.22, spec.depth * 0.3, spec.beam * 0.12),
    )
    trim.add(
        _unit_cylinder(12),
        position=(0.0, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(spec.beam * 0.5, spec.length * 0.05, spec.beam * 0.5),
    )
    _add_hardpoint_mounts(trim, spec, hardpoints)

    accent = Kit()
    for index in range(spec.engines):
        offset = (index - (spec.engines - 1) / 2.0) * engine_spacing * 2.0
        accent.add(
            _unit_cylinder(12),
            position=(-half * 0.94, 0.0, offset),
            rotation=_Y_TO_X,
            scale=(spec.depth * 0.58, spec.length * 0.04, spec.depth * 0.58),
        )
    # Cockpit strip: the one warm line that says which end is the nose.
    accent.add(
        _unit_cube(), position=(half * 0.42, spec.depth * 0.34, 0.0), scale=(spec.length * 0.16, 0.04, spec.beam * 0.1)
    )
    return body.build(), trim.build(), accent.build()


def _scaled(
    mesh: Mesh,
    scale: tuple[float, float, float],
    *,
    rotation: Quat | None = None,
    position: tuple[float, float, float] = (0.0, 0.0, 0.0),
) -> Mesh:
    """A standalone transformed copy of *mesh*, for feeding CSG operands."""
    return Kit().add(mesh, scale=scale, rotation=rotation, position=position).build()


def build_player_ship(seed: int = 0, *, hull: str = "vagrant", hardpoints: int = HARDPOINTS_DEFAULT) -> Node3D:
    """The player's ship, nose along +X, as one hull, trim and accent mesh.

    *hull* selects one of the four flyable hulls in :data:`HULLS`; the default
    is the starting Vagrant. *seed* only moves the greeble scatter, so two
    ships of the same hull read as the same class of ship. *hardpoints* builds
    that many gun pylons at :data:`HARDPOINT_MOUNTS`, so a hull that carries
    four mounts looks like a hull that carries four mounts even before the
    third and fourth guns are bought.
    """
    hardpoints = max(0, min(int(hardpoints), len(HARDPOINT_MOUNTS)))
    body, trim, accent = _cached(
        ("player_ship", hull, seed, hardpoints), lambda: _build_player_meshes(hull, seed, hardpoints)
    )
    node = Node3D(name="ShipArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("player", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_TRIM, trim, faction_material("player", ROLE_TRIM)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("player", ROLE_ACCENT)))
    return node


# ============================================================================
# The exhaust plume
# ============================================================================

#: Names of the two meshes an exhaust plume is made of.
PLUME_FLARE = "PlumeFlare"
PLUME_CORE = "PlumeCore"

#: The flare is squashed vertically: seen down a camera that is 60 degrees off
#: the plane, a flattened plume reads as a streak laid along the thrust vector
#: where a round one reads as a ball of fire behind the ship.
PLUME_FLATTEN = 0.45
#: Radius of the core relative to the flare's mouth, and its share of the length.
PLUME_CORE_RADIUS = 0.34
PLUME_CORE_LENGTH = 0.62


def _build_plume_meshes() -> tuple[Mesh, Mesh]:
    """The flare and core cones of one exhaust plume, as unit meshes.

    Both are built mouth-first: the wide end sits on the node's origin, which is
    the nozzle, and the taper runs down local -Z, which is the axis
    :meth:`Node3D.face_along` aims. A caller therefore points a plume by facing
    the node along the exhaust vector and scales it by throttle, with no
    offset to keep in step.
    """
    flare = Kit().add(_unit_cone(14), position=(0.0, 0.0, -0.5), rotation=_Y_TO_NEG_Z, scale=(2.0, 1.0, 2.0)).build()
    flare = Kit().add(flare, scale=(1.0, PLUME_FLATTEN, 1.0)).build()
    core = (
        Kit()
        .add(
            _unit_cone(12),
            position=(0.0, 0.0, -PLUME_CORE_LENGTH * 0.5),
            rotation=_Y_TO_NEG_Z,
            scale=(PLUME_CORE_RADIUS * 2.0, PLUME_CORE_LENGTH, PLUME_CORE_RADIUS * 2.0),
        )
        .build()
    )
    return flare, Kit().add(core, scale=(1.0, PLUME_FLATTEN, 1.0)).build()


def plume_meshes() -> tuple[Mesh, Mesh]:
    """The shared unit flare and core meshes of the exhaust plume."""
    return _cached(("plume",), _build_plume_meshes)


def build_engine_plume(faction: str = "player") -> Node3D:
    """One nozzle's plume: a tapered flare with a hotter core inside it.

    Continuous geometry rather than particles, because a plume is one jet of
    burning gas and a scatter of grains behind a ship reads as debris coming
    off it. :class:`shrike.vfx.EngineRibbon` owns one of these, stretches it
    with the throttle and points it down the thrust vector; the fast mote
    stream it also carries is the texture on top, not the plume itself.
    """
    accent = palette(faction).accent
    flare_mesh, core_mesh = plume_meshes()
    node = Node3D(name="Plume")
    node.add_child(
        _mesh_instance(
            PLUME_FLARE,
            flare_mesh,
            Material(
                colour=(*accent, 0.5),
                blend="alpha",
                metallic=0.0,
                roughness=1.0,
                double_sided=True,
                emissive_colour=accent,
                emissive_strength=palette(faction).accent_strength,
            ),
        )
    )
    node.add_child(
        _mesh_instance(
            PLUME_CORE,
            core_mesh,
            Material(
                colour=(1.0, 1.0, 1.0, 0.85),
                blend="alpha",
                metallic=0.0,
                roughness=1.0,
                double_sided=True,
                emissive_colour=(1.0, 0.96, 0.88),
                emissive_strength=palette(faction).accent_strength * 1.6,
            ),
        )
    )
    return node


# ============================================================================
# Power modules
#
# The three generation modules are gameplay-real (they widen the hitbox, they
# take fire, they pay in fuel and noise) and until now they had no geometry at
# all: a pilot pressed X, the wings signal fired, the capacitor started filling
# and the ship on screen did not change in any way. Everything below exists so
# that the power economy is something the pilot watches rather than infers.
# ============================================================================

#: The two wing pivots of a solar array, in the order a build returns them.
SOLAR_WING_PORT = "WingPort"
SOLAR_WING_STARBOARD = "WingStarboard"
SOLAR_WING_NAMES = (SOLAR_WING_PORT, SOLAR_WING_STARBOARD)

#: One wing, root to tip and fore to aft, in world units, plus how thick a panel
#: is. Sized against the Vagrant's 1.7-unit beam: a deployed array is about as
#: wide again as the hull, which is what makes the widened hitbox honest.
SOLAR_WING_SPAN = 1.15
SOLAR_WING_CHORD = 0.85
SOLAR_PANEL_THICKNESS = 0.05
#: Where a wing's root sits outboard of the module's own origin.
SOLAR_ROOT_OFFSET = 0.22
#: Cells in one panel array: along the hull, then out along the span. The grid
#: is the whole point of the accent mesh; a single lit slab reads as a mirror.
SOLAR_CELLS_CHORDWISE = 3
SOLAR_CELLS_SPANWISE = 4
#: Fraction of a cell's footprint left as the frame between cells.
SOLAR_CELL_GAP = 0.22

#: The generator's block, its vent face and the cowling ribs over it.
GENERATOR_BLOCK = (0.72, 0.46, 0.58)
GENERATOR_VENT_BARS = 5
GENERATOR_RIBS = 3

#: The RTG: a small finned drum with one glowing window band.
RTG_LENGTH = 0.56
RTG_RADIUS = 0.19
RTG_FINS = 6


def _panel_grid(kit: Kit, *, chord: float, span: float, root: float, thickness: float) -> None:
    """Lay a grid of emissive cells over one wing's planform."""
    cell_chord = chord / SOLAR_CELLS_CHORDWISE
    cell_span = span / SOLAR_CELLS_SPANWISE
    for i in range(SOLAR_CELLS_CHORDWISE):
        along = (i - (SOLAR_CELLS_CHORDWISE - 1) / 2.0) * cell_chord
        for j in range(SOLAR_CELLS_SPANWISE):
            out = root + (j + 0.5) * cell_span
            kit.add(
                _unit_cube(),
                position=(along, thickness * 0.6, out),
                scale=(cell_chord * (1.0 - SOLAR_CELL_GAP), thickness * 0.5, cell_span * (1.0 - SOLAR_CELL_GAP)),
            )


def _build_solar_wing_meshes(seed: int) -> tuple[Mesh, Mesh]:
    """The starboard wing's spar and cell grid, span running out along +Z."""
    rng = np.random.default_rng((seed, 0x5011))
    span = SOLAR_WING_SPAN
    chord = SOLAR_WING_CHORD

    spar = Kit()
    # The hinge boom out to the root, then the panel's own frame.
    spar.add(
        _unit_cylinder(8),
        position=(0.0, 0.0, SOLAR_ROOT_OFFSET * 0.5),
        rotation=_Y_TO_Z,
        scale=(0.11, SOLAR_ROOT_OFFSET, 0.11),
    )
    spar.add(
        _unit_cube(),
        position=(0.0, 0.0, SOLAR_ROOT_OFFSET + span * 0.5),
        scale=(chord * 1.02, SOLAR_PANEL_THICKNESS, span),
    )
    # Two stiffeners along the span, angled so the array is not a plain slab.
    for side in (1.0, -1.0):
        spar.add(
            _unit_cube(),
            position=(side * chord * 0.44, SOLAR_PANEL_THICKNESS * 0.9, SOLAR_ROOT_OFFSET + span * 0.5),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.06),
            scale=(chord * 0.1, SOLAR_PANEL_THICKNESS * 1.4, span * 0.98),
        )
    _greeble(spar, rng, span=(chord * 0.3, SOLAR_PANEL_THICKNESS, span * 0.4), count=4, size=0.05)

    cells = Kit()
    _panel_grid(cells, chord=chord, span=span, root=SOLAR_ROOT_OFFSET, thickness=SOLAR_PANEL_THICKNESS)
    return spar.build(), cells.build()


def build_solar_wings(seed: int = 0) -> Node3D:
    """A folding solar array: two named wing pivots, each its own spar and cells.

    The pivots are the animation surface. ``power.SolarWings`` yaws each one
    about the hull's fore-aft axis to fold it and scales it along the span, and
    dims or hides one when its cells are shot away, so the deployment state and
    the wing damage the gameplay already tracks are both on the hull.
    """
    spar, cells = _cached(("solar_wing", seed), lambda: _build_solar_wing_meshes(seed))
    flip = (1.0, 1.0, -1.0)
    mirrored = _cached(("solar_wing_port", seed), lambda: (_scaled(spar, flip), _scaled(cells, flip)))
    node = Node3D(name="SolarArray")
    for name, (spar_mesh, cell_mesh) in zip(SOLAR_WING_NAMES, (mirrored, (spar, cells)), strict=True):
        wing = node.add_child(Node3D(name=name))
        wing.add_child(_mesh_instance(ROLE_TRIM, spar_mesh, faction_material("player", ROLE_TRIM)))
        wing.add_child(_mesh_instance(ROLE_ACCENT, cell_mesh, faction_material("player", ROLE_ACCENT)))
    return node


def _build_generator_meshes(seed: int) -> tuple[Mesh, Mesh, Mesh]:
    """The generator's casing, its cowling ribs and the emissive vent bars."""
    rng = np.random.default_rng((seed, 0x6E17))
    length, height, width = GENERATOR_BLOCK

    body = Kit()
    body.add(_unit_cube(), scale=(length, height, width))
    body.add(
        _unit_cylinder(10),
        position=(-length * 0.42, height * 0.24, 0.0),
        rotation=_Y_TO_X,
        scale=(height * 0.34, length * 0.5, height * 0.34),
    )
    _greeble(body, rng, span=(length * 0.35, height * 0.5, width * 0.35), count=5, size=0.07)

    trim = Kit()
    for index in range(GENERATOR_RIBS):
        along = (index - (GENERATOR_RIBS - 1) / 2.0) * length * 0.3
        trim.add(_unit_cube(), position=(along, height * 0.54, 0.0), scale=(length * 0.09, height * 0.14, width * 1.04))
    # The exhaust stack: what the vent light spills out of.
    trim.add(
        _unit_cylinder(8),
        position=(length * 0.3, height * 0.72, 0.0),
        scale=(width * 0.28, height * 0.5, width * 0.28),
    )

    accent = Kit()
    for index in range(GENERATOR_VENT_BARS):
        along = (index - (GENERATOR_VENT_BARS - 1) / 2.0) * length * 0.17
        accent.add(
            _unit_cube(),
            position=(along, 0.0, width * 0.52),
            scale=(length * 0.1, height * 0.62, 0.04),
        )
    accent.add(_unit_cylinder(8), position=(length * 0.3, height * 0.97, 0.0), scale=(width * 0.2, 0.06, width * 0.2))
    return body.build(), trim.build(), accent.build()


def build_generator(seed: int = 0) -> Node3D:
    """The fuel generator: a plated block whose vent glows while it is running.

    The vent is the accent mesh, so ``power.Generator`` pulses one emissive
    strength in step with the hum that is the game's signature warning, and a
    running generator is visible on the hull from across the sector.
    """
    body, trim, accent = _cached(("generator", seed), lambda: _build_generator_meshes(seed))
    node = Node3D(name="GeneratorArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("player", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_TRIM, trim, faction_material("player", ROLE_TRIM)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("player", ROLE_ACCENT)))
    return node


def _build_rtg_meshes(seed: int) -> tuple[Mesh, Mesh]:
    """The RTG's finned drum and its one steady window band."""
    del seed
    body = Kit()
    body.add(_unit_cylinder(10), rotation=_Y_TO_X, scale=(RTG_RADIUS * 2.0, RTG_LENGTH, RTG_RADIUS * 2.0))
    for index in range(RTG_FINS):
        angle = index * math.tau / RTG_FINS
        body.add(
            _unit_cube(),
            position=(0.0, math.sin(angle) * RTG_RADIUS * 1.2, math.cos(angle) * RTG_RADIUS * 1.2),
            rotation=Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), -angle),
            scale=(RTG_LENGTH * 0.82, RTG_RADIUS * 0.6, 0.035),
        )
    accent = Kit()
    accent.add(
        _unit_cylinder(10),
        rotation=_Y_TO_X,
        scale=(RTG_RADIUS * 1.9, RTG_LENGTH * 0.22, RTG_RADIUS * 1.9),
    )
    return body.build(), accent.build()


def build_rtg(seed: int = 0) -> Node3D:
    """The radioisotope trickle: a small finned drum with a steady glow band.

    Steady is the whole reading. It is the one source that survives silent
    running, so its light never pulses and never goes out, and a dark hull with
    one warm band still lit is the picture of what silent running costs.
    """
    body, accent = _cached(("rtg", seed), lambda: _build_rtg_meshes(seed))
    node = Node3D(name="RtgArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("player", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("player", ROLE_ACCENT)))
    return node


# ============================================================================
# Enemy archetypes
# ============================================================================


@dataclass(frozen=True)
class EnemyShape:
    """Silhouette anchors for one archetype. Read only by the builders below.

    ``length`` runs nose to tail along +X, ``beam`` across the flight plane and
    ``depth`` through it; ``limbs`` counts whatever the archetype repeats, be
    that spikes, arms or mortar tubes.
    """

    length: float
    beam: float
    depth: float
    limbs: int
    greebles: int


#: One entry per archetype in ``balance.ENEMIES``. The player's hull is 2.6
#: units long, so these are read against that: a Mite is a splinter a third of
#: the ship's length, a Bombardier is heavier than the ship in every dimension.
#: Nothing here is smaller than it needs to be to be told apart in a fight,
#: because an enemy the player cannot name is an enemy the player cannot answer.
ENEMY_SHAPES: dict[str, EnemyShape] = {
    "mite": EnemyShape(1.15, 0.36, 0.20, 2, 0),
    "skimmer": EnemyShape(2.4, 3.2, 0.42, 2, 5),
    "lancer": EnemyShape(4.0, 0.80, 0.52, 2, 5),
    "mag_mine": EnemyShape(2.0, 2.0, 2.0, 12, 0),
    "welder": EnemyShape(2.6, 2.5, 0.95, 2, 10),
    "bombardier": EnemyShape(3.2, 2.4, 1.5, 3, 12),
    "screamer": EnemyShape(1.6, 1.6, 3.0, 4, 4),
    "husk_turret": EnemyShape(2.8, 2.8, 1.7, 1, 10),
    "herald": EnemyShape(3.2, 2.3, 0.6, 3, 6),
}


def _align_y(direction: tuple[float, float, float]) -> Quat:
    """The rotation that takes a +Y primitive onto *direction*."""
    target = Vec3(*direction).normalized()
    along = float(target.y)
    if along > 1.0 - 1e-9:
        return Quat()
    if along < -1.0 + 1e-9:
        return Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), math.pi)
    axis = Vec3(0.0, 1.0, 0.0).cross(target).normalized()
    return Quat.from_axis_angle(axis, math.acos(max(-1.0, min(1.0, along))))


def _sphere_directions(count: int) -> list[tuple[float, float, float]]:
    """*count* roughly even directions on the unit sphere, for radial spikes."""
    golden = math.pi * (3.0 - math.sqrt(5.0))
    directions = []
    for index in range(count):
        y = 1.0 - 2.0 * (index + 0.5) / count
        radius = math.sqrt(max(0.0, 1.0 - y * y))
        angle = golden * index
        directions.append((math.cos(angle) * radius, y, math.sin(angle) * radius))
    return directions


def _build_mite(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A splinter: all nose, no hull, one spark of drive at the back."""
    half = shape.length / 2.0
    body.add(
        _unit_cone(4),
        position=(half * 0.14, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam, shape.length * 0.92, shape.depth),
    )
    for side in (1.0, -1.0):
        body.add(
            _unit_cube(),
            position=(-half * 0.42, 0.0, side * shape.beam * 0.36),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.55),
            scale=(shape.length * 0.28, shape.depth * 0.7, shape.beam * 0.5),
        )
    accent.add(_unit_sphere(5, 6), position=(-half * 0.62, 0.0, 0.0), scale=(shape.beam * 0.85,) * 3)


def _build_skimmer(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A winged wedge with two claw prongs: a thief built to close and grab."""
    half = shape.length / 2.0
    body.add(
        _unit_cone(6),
        position=(half * 0.18, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam * 0.30, shape.length * 0.8, shape.depth * 1.7),
    )
    # Wings, swept back hard so the outline is a delta from any distance.
    for side in (1.0, -1.0):
        body.add(
            _unit_cube(),
            position=(-shape.length * 0.14, 0.0, side * shape.beam * 0.28),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.52),
            scale=(shape.length * 0.5, shape.depth * 0.4, shape.beam * 0.52),
        )
    # The claws: two prongs reaching past the nose, canted inward around the maw.
    for side in (1.0, -1.0):
        body.add(
            _unit_cone(6),
            position=(half * 0.66, 0.0, side * shape.beam * 0.2),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.2) * _Y_TO_X,
            scale=(shape.depth * 0.55, shape.length * 0.62, shape.depth * 0.55),
        )
    _greeble(body, rng, span=(shape.length * 0.22, shape.depth * 0.4, shape.beam * 0.3), count=shape.greebles, size=0.1)
    # The maw between the claws is the emissive: a Skimmer is read by its grab.
    accent.add(
        _unit_cube(),
        position=(half * 0.5, 0.0, 0.0),
        scale=(shape.length * 0.1, shape.depth * 0.5, shape.beam * 0.3),
    )
    for side in (1.0, -1.0):
        accent.add(
            _unit_sphere(5, 6),
            position=(half * 0.94, 0.0, side * shape.beam * 0.14),
            scale=(shape.depth * 0.42,) * 3,
        )


def _build_lancer(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A needle with a lit tip: the whole ship is the weapon, and it points."""
    half = shape.length / 2.0
    body.add(
        _unit_cone(8),
        position=(half * 0.08, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam * 0.42, shape.length * 0.94, shape.beam * 0.42),
    )
    body.add(
        _unit_cylinder(10),
        position=(-half * 0.5, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam * 0.85, shape.length * 0.1, shape.beam * 0.85),
    )
    for side in (1.0, -1.0):
        body.add(
            _unit_cube(),
            position=(-half * 0.72, 0.0, side * shape.beam * 0.45),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.55),
            scale=(shape.length * 0.24, shape.depth * 0.55, shape.beam * 0.62),
        )
    _greeble(body, rng, span=(shape.length * 0.2, shape.depth * 0.3, shape.beam * 0.2), count=shape.greebles, size=0.09)
    # The lit tip: the one part of a Lancer a player must watch.
    accent.add(_unit_sphere(6, 8), position=(half * 0.9, 0.0, 0.0), scale=(shape.beam * 0.62,) * 3)
    accent.add(
        _unit_cube(),
        position=(half * 0.1, 0.0, 0.0),
        scale=(shape.length * 0.52, shape.depth * 0.14, shape.depth * 0.14),
    )


def _build_mag_mine(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A spiked sphere: radially symmetric, so it reads the same from any bearing."""
    radius = shape.length / 2.0
    body.add(_unit_sphere(10, 14), scale=(shape.length * 0.62,) * 3)
    for direction in _sphere_directions(shape.limbs):
        body.add(
            _unit_cone(5),
            position=tuple(component * radius * 0.62 for component in direction),
            rotation=_align_y(direction),
            scale=(radius * 0.3, radius * 0.95, radius * 0.3),
        )
        # A lit spike tip on every spine: the thing has no front, so the glow
        # has to be everywhere the hull is.
        accent.add(
            _unit_sphere(4, 6),
            position=tuple(component * radius * 1.02 for component in direction),
            scale=(radius * 0.17,) * 3,
        )


def _build_welder(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A crab: a squat body carried behind two long beam arms."""
    half = shape.length / 2.0
    body.add(
        _unit_sphere(8, 12),
        position=(-half * 0.24, 0.0, 0.0),
        scale=(shape.length * 0.52, shape.depth * 1.05, shape.beam * 0.62),
    )
    body.add(
        _unit_cube(),
        position=(-half * 0.62, 0.0, 0.0),
        scale=(shape.length * 0.22, shape.depth * 0.7, shape.beam * 0.42),
    )
    # Two arms, each an upper limb angled out and a forearm angled back in, so
    # the pair frames the space the umbilical crosses.
    for side in (1.0, -1.0):
        body.add(
            _unit_cylinder(8),
            position=(half * 0.06, 0.0, side * shape.beam * 0.28),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), -side * 0.5) * _Y_TO_X,
            scale=(shape.depth * 0.34, shape.length * 0.62, shape.depth * 0.34),
        )
        body.add(
            _unit_cylinder(8),
            position=(half * 0.62, 0.0, side * shape.beam * 0.4),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.42) * _Y_TO_X,
            scale=(shape.depth * 0.28, shape.length * 0.5, shape.depth * 0.28),
        )
        # The emitter head at the end of each arm.
        accent.add(
            _unit_sphere(6, 8),
            position=(half * 0.88, 0.0, side * shape.beam * 0.26),
            scale=(shape.depth * 0.55,) * 3,
        )
    _greeble(
        body, rng, span=(shape.length * 0.24, shape.depth * 0.5, shape.beam * 0.24), count=shape.greebles, size=0.11
    )
    accent.add(
        _unit_cube(),
        position=(-half * 0.24, shape.depth * 0.42, 0.0),
        scale=(shape.length * 0.3, shape.depth * 0.12, shape.beam * 0.16),
    )


def _build_bombardier(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A barrel with mortar tubes: heavy, slow and obviously carrying shells."""
    half = shape.length / 2.0
    body.add(
        _unit_cylinder(14),
        rotation=_Y_TO_X,
        scale=(shape.depth * 1.05, shape.length * 0.78, shape.beam * 0.9),
    )
    # Hoops, which is what makes a cylinder read as a barrel rather than a pipe.
    for offset in (-0.28, 0.06, 0.34):
        body.add(
            _unit_cylinder(16),
            position=(shape.length * offset, 0.0, 0.0),
            rotation=_Y_TO_X,
            scale=(shape.depth * 1.18, shape.length * 0.05, shape.beam * 1.0),
        )
    body.add(
        _unit_cone(10),
        position=(-half * 0.52, 0.0, 0.0),
        rotation=_Y_TO_NEG_X,
        scale=(shape.depth * 0.9, shape.length * 0.3, shape.beam * 0.8),
    )
    _greeble(
        body, rng, span=(shape.length * 0.28, shape.depth * 0.55, shape.beam * 0.3), count=shape.greebles, size=0.13
    )
    # Mortar tubes on the spine, tilted up: the shells come from up there.
    for index in range(shape.limbs):
        offset = (index - (shape.limbs - 1) / 2.0) * shape.beam * 0.3
        tilt = Quat.from_axis_angle(Vec3(0.0, 0.0, 1.0), -0.5)
        body.add(
            _unit_cylinder(10),
            position=(shape.length * 0.1, shape.depth * 0.6, offset),
            rotation=tilt,
            scale=(shape.depth * 0.28, shape.length * 0.42, shape.depth * 0.28),
        )
        accent.add(
            _unit_cylinder(8),
            position=(shape.length * 0.28, shape.depth * 0.86, offset),
            rotation=tilt,
            scale=(shape.depth * 0.22, shape.length * 0.05, shape.depth * 0.22),
        )
    accent.add(
        _unit_cylinder(16),
        position=(shape.length * 0.2, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.depth * 1.12, shape.length * 0.04, shape.beam * 0.96),
    )


def _build_screamer(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """An antenna cluster: a small hull under a mast that is all broadcast."""
    body.add(_unit_cylinder(10), scale=(shape.length * 0.5, shape.depth * 0.28, shape.beam * 0.5))
    body.add(
        _unit_cylinder(8),
        position=(0.0, shape.depth * 0.34, 0.0),
        scale=(shape.length * 0.11, shape.depth * 0.62, shape.length * 0.11),
    )
    # A stack of crossbars, each shorter than the one below, each ending in a
    # dish: an aerial, from the outline alone.
    for index in range(shape.limbs):
        height = shape.depth * (0.34 + 0.16 * (index + 1))
        reach = shape.beam * (0.62 - 0.09 * index)
        angle = math.tau * index / shape.limbs + 0.4
        for sign in (1.0, -1.0):
            direction = (math.cos(angle) * sign, 0.0, math.sin(angle) * sign)
            body.add(
                _unit_cube(),
                position=(direction[0] * reach * 0.5, height, direction[2] * reach * 0.5),
                rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), -angle),
                scale=(reach, shape.depth * 0.05, shape.depth * 0.05),
            )
            accent.add(
                _unit_cone(6),
                position=(direction[0] * reach, height, direction[2] * reach),
                rotation=_align_y(direction),
                scale=(shape.depth * 0.11, shape.depth * 0.1, shape.depth * 0.11),
            )
    _greeble(body, rng, span=(shape.length * 0.2, shape.depth * 0.12, shape.beam * 0.2), count=shape.greebles, size=0.1)
    accent.add(_unit_sphere(7, 9), position=(0.0, shape.depth * 0.98, 0.0), scale=(shape.length * 0.2,) * 3)


def _build_husk_turret(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A gun bolted to a dead hull: broken base, live drum, one barrel."""
    half = shape.length / 2.0
    # The wreck it is built on: a torn slab with a plate or two still standing.
    body.add(
        _displaced_rock(int(rng.integers(0, 1 << 20)), shape.length * 0.42, relief=0.3, rings=8, segments=12),
        scale=(1.15, 0.34, 1.0),
    )
    for _ in range(2):
        body.add(
            _unit_cube(),
            position=(
                float(rng.uniform(-half * 0.6, half * 0.6)),
                shape.depth * 0.16,
                float(rng.uniform(-half * 0.6, half * 0.6)),
            ),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), float(rng.uniform(0.0, math.tau))),
            scale=(shape.length * 0.3, shape.depth * 0.28, shape.beam * 0.1),
        )
    _greeble(body, rng, span=(shape.length * 0.3, shape.depth * 0.2, shape.beam * 0.3), count=shape.greebles, size=0.13)
    # The drum: the live half, sat proud of the wreck so it is unmistakable.
    body.add(
        _unit_cylinder(14),
        position=(0.0, shape.depth * 0.42, 0.0),
        scale=(shape.length * 0.44, shape.depth * 0.45, shape.beam * 0.44),
    )
    accent.add(
        _unit_cylinder(16),
        position=(0.0, shape.depth * 0.6, 0.0),
        scale=(shape.length * 0.46, shape.depth * 0.06, shape.beam * 0.46),
    )


def _build_turret_barrel_meshes(shape: EnemyShape) -> tuple[Mesh, Mesh]:
    """The Husk turret's barrel, as its own build: the class swivels it."""
    body, accent = Kit(), Kit()
    body.add(
        _unit_cylinder(10),
        position=(shape.length * 0.32, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.depth * 0.3, shape.length * 0.9, shape.depth * 0.3),
    )
    body.add(
        _unit_cylinder(10),
        position=(0.0, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.depth * 0.46, shape.length * 0.22, shape.depth * 0.46),
    )
    accent.add(
        _unit_cylinder(10),
        position=(shape.length * 0.76, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.depth * 0.34, shape.length * 0.06, shape.depth * 0.34),
    )
    return body.build(), accent.build()


def build_turret_barrel(seed: int = 0) -> Node3D:
    """The Husk turret's swivelling barrel, pointing along +X."""
    body, accent = _cached(("turret_barrel", seed), lambda: _build_turret_barrel_meshes(ENEMY_SHAPES["husk_turret"]))
    node = Node3D(name="BarrelArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("enemy", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("enemy", ROLE_ACCENT)))
    return node


def _build_herald(body: Kit, accent: Kit, shape: EnemyShape, rng: np.random.Generator) -> None:
    """A shard of the Shrike: angular, bladed, lit down its spine."""
    half = shape.length / 2.0
    body.add(
        _unit_cone(3),
        position=(half * 0.12, 0.0, 0.0),
        rotation=Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), 0.5) * _Y_TO_X,
        scale=(shape.beam * 0.34, shape.length * 0.95, shape.depth * 1.5),
    )
    # Two quills swept back off the shard, the Shrike's own signature.
    for side in (1.0, -1.0):
        body.add(
            _unit_cone(3),
            position=(-half * 0.34, 0.0, side * shape.beam * 0.3),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 1.05 + math.pi) * _Y_TO_X,
            scale=(shape.depth * 0.9, shape.length * 0.62, shape.depth * 0.9),
        )
    _greeble(body, rng, span=(shape.length * 0.22, shape.depth * 0.4, shape.beam * 0.3), count=shape.greebles, size=0.1)
    # Slits down the spine: lit segments, the way the Shrike's own body is lit.
    for index in range(shape.limbs):
        offset = (index - (shape.limbs - 1) / 2.0) * shape.length * 0.22
        accent.add(
            _unit_cube(),
            position=(offset, shape.depth * 0.2, 0.0),
            scale=(shape.length * 0.05, shape.depth * 0.16, shape.beam * 0.26),
        )
    accent.add(_unit_sphere(5, 7), position=(half * 0.82, 0.0, 0.0), scale=(shape.depth * 0.5,) * 3)


#: One builder per archetype. Silhouette follows role: a player who has met a
#: Lancer once can name the next one from its outline before it is in range.
ENEMY_BUILDERS = {
    "mite": _build_mite,
    "skimmer": _build_skimmer,
    "lancer": _build_lancer,
    "mag_mine": _build_mag_mine,
    "welder": _build_welder,
    "bombardier": _build_bombardier,
    "screamer": _build_screamer,
    "husk_turret": _build_husk_turret,
    "herald": _build_herald,
}


def _build_enemy_meshes(archetype: str, seed: int) -> tuple[Mesh, Mesh]:
    shape = ENEMY_SHAPES[archetype]
    rng = np.random.default_rng((seed, hash(archetype) & 0xFFFF))
    body, accent = Kit(), Kit()
    ENEMY_BUILDERS[archetype](body, accent, shape, rng)
    return body.build(), accent.build()


def enemy_mesh(archetype: str, seed: int = 0) -> Mesh:
    """The merged hull mesh for *archetype*, for multimesh instancing.

    ``MiteShoal`` draws its whole shoal from one ``MultiMeshInstance3D``, which
    wants a mesh rather than a node; this is that mesh, cached so every shoal
    in a sector shares it.
    """
    return _enemy_meshes(archetype, seed)[0]


def _enemy_meshes(archetype: str, seed: int) -> tuple[Mesh, Mesh]:
    if archetype not in balance.ENEMIES:
        raise ValueError(f"Unknown archetype {archetype!r}; expected one of {', '.join(balance.ENEMIES)}")
    return _cached(("enemy", archetype, seed), lambda: _build_enemy_meshes(archetype, seed))


def build_enemy(archetype: str, seed: int = 0) -> Node3D:
    """One enemy archetype's art, nose along +X.

    *archetype* must be a key of ``balance.ENEMIES``; anything else raises, so
    a typo in a wave recipe fails where it is written rather than spawning an
    invisible enemy.
    """
    body, accent = _enemy_meshes(archetype, seed)
    node = Node3D(name="EnemyArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("enemy", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("enemy", ROLE_ACCENT)))
    return node


# ============================================================================
# Bounty set pieces
# ============================================================================

#: Silhouette anchors for the two set-piece hostiles, read against the same
#: player-hull yardstick as :data:`ENEMY_SHAPES`. The Warden is a bastion as
#: broad as it is long; the Magistrates share one hunter frame leaner than a
#: Lancer and half again the length of the player's hull.
WARDEN_SHAPE = EnemyShape(6.2, 6.2, 2.0, 8, 16)
MAGISTRATE_SHAPE = EnemyShape(4.2, 2.0, 0.66, 2, 8)

#: Radius the Warden's shield emitters orbit at, and how many blocks draw the
#: visible cone. The cone spans ``balance.SHIELD_ARC_DEGREES``, the same arc
#: the class blocks with, so what the player sees is what the maths honours.
WARDEN_ARC_RADIUS = 4.1
WARDEN_ARC_SEGMENTS = 5


def _build_warden_meshes(seed: int) -> tuple[Mesh, Mesh, Mesh, Mesh]:
    """The bastion drum, its static trim, the shield cone, and the gun."""
    shape = WARDEN_SHAPE
    rng = np.random.default_rng((seed, 0xBA57))
    body, accent, arc, gun = Kit(), Kit(), Kit(), Kit()
    radius = shape.length / 2.0

    # The drum: broad and squat, a fort rather than a hull, with an armour
    # skirt of leaning slabs the whole way round.
    body.add(_unit_cylinder(16), scale=(shape.length * 0.84, shape.depth, shape.beam * 0.84))
    body.add(
        _unit_cylinder(16),
        position=(0.0, shape.depth * 0.3, 0.0),
        scale=(shape.length * 0.6, shape.depth * 0.5, shape.beam * 0.6),
    )
    for index in range(shape.limbs):
        angle = math.tau * index / shape.limbs
        direction = (math.cos(angle), 0.0, math.sin(angle))
        body.add(
            _unit_cube(),
            position=(direction[0] * radius * 0.78, -shape.depth * 0.08, direction[2] * radius * 0.78),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), -angle),
            scale=(shape.length * 0.1, shape.depth * 0.85, shape.beam * 0.28),
        )
    _greeble(
        body, rng, span=(shape.length * 0.26, shape.depth * 0.5, shape.beam * 0.26), count=shape.greebles, size=0.16
    )

    # Static light: the crown ring and the core lamp, lit whether it is awake
    # or not, because a Warden is a landmark before it is a fight.
    accent.add(
        _unit_cylinder(18),
        position=(0.0, shape.depth * 0.46, 0.0),
        scale=(shape.length * 0.64, shape.depth * 0.06, shape.beam * 0.64),
    )
    accent.add(_unit_sphere(8, 10), position=(0.0, shape.depth * 0.66, 0.0), scale=(shape.beam * 0.2,) * 3)

    # The visible arc: emitter blocks spread over the shield cone, centred on
    # local +X, with a taller pylon on each edge so the gap reads at a glance.
    half_arc = math.radians(balance.SHIELD_ARC_DEGREES) / 2.0
    for index in range(WARDEN_ARC_SEGMENTS):
        angle = -half_arc + 2.0 * half_arc * index / (WARDEN_ARC_SEGMENTS - 1)
        direction = (math.cos(angle), 0.0, -math.sin(angle))
        arc.add(
            _unit_cube(),
            position=(direction[0] * WARDEN_ARC_RADIUS, shape.depth * 0.1, direction[2] * WARDEN_ARC_RADIUS),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), angle),
            scale=(0.26, shape.depth * 0.7, 1.05),
        )
    for sign in (1.0, -1.0):
        angle = sign * half_arc
        direction = (math.cos(angle), 0.0, -math.sin(angle))
        arc.add(
            _unit_cone(6),
            position=(
                direction[0] * (WARDEN_ARC_RADIUS + 0.35),
                shape.depth * 0.45,
                direction[2] * (WARDEN_ARC_RADIUS + 0.35),
            ),
            scale=(0.55, shape.depth * 0.75, 0.55),
        )

    # The emplacement: a mantlet and one long barrel down local +X.
    gun.add(_unit_cube(), position=(0.0, shape.depth * 0.58, 0.0), scale=(1.3, shape.depth * 0.45, 1.05))
    gun.add(
        _unit_cylinder(10),
        position=(shape.length * 0.3, shape.depth * 0.58, 0.0),
        rotation=_Y_TO_X,
        scale=(0.5, shape.length * 0.56, 0.5),
    )
    return body.build(), accent.build(), arc.build(), gun.build()


def build_warden(seed: int = 0) -> Node3D:
    """The Warden's bastion, with the arc and the gun on children of their own.

    The drum and its trim are static. ``ArcArt`` carries the emissive shield
    cone, centred on local +X, so the class shows the live arc by yawing that
    one node; ``GunArt`` carries the emplacement, barrel along local +X, and is
    yawed at whatever the Warden is shooting.
    """
    body, accent, arc, gun = _cached(("warden", seed), lambda: _build_warden_meshes(seed))
    node = Node3D(name="WardenArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("enemy", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("enemy", ROLE_ACCENT)))
    arc_art = node.add_child(Node3D(name="ArcArt"))
    arc_art.add_child(_mesh_instance(ROLE_ACCENT, arc, faction_material("enemy", ROLE_ACCENT)))
    gun_art = node.add_child(Node3D(name="GunArt"))
    gun_art.add_child(_mesh_instance(ROLE_HULL, gun, faction_material("enemy", ROLE_HULL)))
    return node


def _magistrate_frame(body: Kit, accent: Kit, rng: np.random.Generator) -> None:
    """The hunter frame all three Magistrates share: a sleek dart, finned aft.

    Sharing the frame is the point: a Magistrate is recognised twice, once as
    "a hunter is here" from the family outline, and once by name from the
    variant geometry bolted onto it.
    """
    shape = MAGISTRATE_SHAPE
    half = shape.length / 2.0
    body.add(
        _unit_cone(8),
        position=(half * 0.22, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam * 0.34, shape.length * 0.8, shape.depth * 1.1),
    )
    body.add(
        _unit_cone(8),
        position=(-half * 0.5, 0.0, 0.0),
        rotation=_Y_TO_NEG_X,
        scale=(shape.beam * 0.3, shape.length * 0.36, shape.depth * 0.95),
    )
    for side in (1.0, -1.0):
        body.add(
            _unit_cube(),
            position=(-half * 0.42, 0.0, side * shape.beam * 0.3),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), side * 0.6),
            scale=(shape.length * 0.34, shape.depth * 0.32, shape.beam * 0.4),
        )
    _greeble(
        body, rng, span=(shape.length * 0.2, shape.depth * 0.35, shape.beam * 0.16), count=shape.greebles, size=0.08
    )
    # The family's shared light: one strip down the spine, nose to waist.
    accent.add(
        _unit_cube(),
        position=(half * 0.2, shape.depth * 0.28, 0.0),
        scale=(shape.length * 0.44, shape.depth * 0.1, shape.depth * 0.16),
    )


def _variant_harrier(body: Kit, accent: Kit) -> None:
    """Marshal Harrier: twin booms around the needle nose, tips lit."""
    shape = MAGISTRATE_SHAPE
    half = shape.length / 2.0
    for side in (1.0, -1.0):
        body.add(
            _unit_cylinder(8),
            position=(half * 0.1, 0.0, side * shape.beam * 0.52),
            rotation=_Y_TO_X,
            scale=(shape.depth * 0.5, shape.length * 0.95, shape.depth * 0.5),
        )
        accent.add(
            _unit_sphere(5, 7),
            position=(half * 0.6, 0.0, side * shape.beam * 0.52),
            scale=(shape.depth * 0.42,) * 3,
        )


def _variant_caracara(body: Kit, accent: Kit) -> None:
    """Vice-Marshal Caracara: a broad waist ring and two claws past the nose."""
    shape = MAGISTRATE_SHAPE
    half = shape.length / 2.0
    body.add(
        _unit_cylinder(16),
        position=(-half * 0.1, 0.0, 0.0),
        scale=(shape.beam * 1.5, shape.depth * 0.34, shape.beam * 1.5),
    )
    accent.add(
        _unit_cylinder(18),
        position=(-half * 0.1, shape.depth * 0.18, 0.0),
        scale=(shape.beam * 1.52, shape.depth * 0.05, shape.beam * 1.52),
    )
    for side in (1.0, -1.0):
        body.add(
            _unit_cone(6),
            position=(half * 0.7, 0.0, side * shape.beam * 0.34),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), -side * 0.18) * _Y_TO_X,
            scale=(shape.depth * 0.5, shape.length * 0.52, shape.depth * 0.5),
        )
        accent.add(
            _unit_sphere(4, 6),
            position=(half * 0.95, 0.0, side * shape.beam * 0.28),
            scale=(shape.depth * 0.32,) * 3,
        )


def _variant_nightjar(body: Kit, accent: Kit) -> None:
    """Magistrate Nightjar: the stretched shard, and the one shuttered lamp."""
    shape = MAGISTRATE_SHAPE
    half = shape.length / 2.0
    body.add(
        _unit_cone(6),
        position=(half * 0.05, shape.depth * 0.34, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.beam * 0.2, shape.length * 1.05, shape.depth * 0.5),
    )
    # The cowl, then the lamp half-proud of it: shuttered, not hidden.
    body.add(
        _unit_cylinder(8),
        position=(half * 0.42, shape.depth * 0.2, 0.0),
        rotation=_Y_TO_X,
        scale=(shape.depth * 1.05, shape.length * 0.16, shape.depth * 1.05),
    )
    accent.add(
        _unit_sphere(7, 9),
        position=(half * 0.5, shape.depth * 0.2, 0.0),
        scale=(shape.depth * 0.62,) * 3,
    )


#: One variant builder per named bounty hunter, keyed the way bounty.py spells
#: them. Each earns the silhouette its codex line promises.
MAGISTRATE_VARIANTS = {
    "harrier": _variant_harrier,
    "caracara": _variant_caracara,
    "nightjar": _variant_nightjar,
}


def _build_magistrate_meshes(magistrate_id: str, seed: int) -> tuple[Mesh, Mesh]:
    # Seeded from integers only: a hull must build the same way in every
    # process, and Python's string hashing is salted per run.
    rng = np.random.default_rng((seed, list(MAGISTRATE_VARIANTS).index(magistrate_id)))
    body, accent = Kit(), Kit()
    _magistrate_frame(body, accent, rng)
    MAGISTRATE_VARIANTS[magistrate_id](body, accent)
    return body.build(), accent.build()


def build_magistrate(magistrate_id: str, seed: int = 0, *, accent: tuple | None = None) -> Node3D:
    """One named bounty hunter's art, nose along +X.

    All three ride the same sleek hunter frame in the enemy palette's magenta
    accent language; the variant geometry is what carries the name. *accent*,
    when given, tints the emissive to that Magistrate's own shade of it.
    """
    if magistrate_id not in MAGISTRATE_VARIANTS:
        raise ValueError(f"Unknown magistrate {magistrate_id!r}; expected one of {', '.join(MAGISTRATE_VARIANTS)}")
    body, glow = _cached(("magistrate", magistrate_id, seed), lambda: _build_magistrate_meshes(magistrate_id, seed))
    node = Node3D(name="MagistrateArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("enemy", ROLE_HULL)))
    accent_material = faction_material("enemy", ROLE_ACCENT)
    if accent is not None:
        shade = tuple(float(channel) for channel in accent[:3])
        accent_material.colour = (*shade, 1.0)
        accent_material.emissive_colour = shade
    node.add_child(_mesh_instance(ROLE_ACCENT, glow, accent_material))
    return node


# ============================================================================
# The Shrike
# ============================================================================


def _build_shrike_meshes(index: int, seed: int) -> tuple[Mesh, Mesh]:
    total_length = PLAYER_SHIP_LENGTH * balance.SHRIKE_LENGTH_MULT
    segment_length = total_length / SHRIKE_SEGMENT_COUNT
    # Taper from the head back down the body.
    taper = 1.0 - 0.62 * (index / max(SHRIKE_SEGMENT_COUNT - 1, 1))
    girth = segment_length * 0.62 * taper
    rng = np.random.default_rng((seed, index))

    body, accent = Kit(), Kit()
    body.add(_unit_sphere(8, 12), scale=(segment_length * 0.95, girth, girth * 1.15))
    # Quill fins: the shearable plating along the spine.
    for side in (1.0, -1.0):
        body.add(
            _unit_cone(8),
            position=(0.0, girth * 0.2, side * girth * 0.55),
            rotation=Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), side * 0.5) * _Y_TO_Z,
            scale=(girth * 0.34, girth * 1.5, girth * 0.14),
        )
    _greeble(body, rng, span=(segment_length * 0.3, girth * 0.5, girth * 0.4), count=6, size=girth * 0.18)

    if index == 0:
        # The head carries the lantern housing and the jaw shear.
        jaw = csg_combine(
            _scaled(_unit_cone(12), (girth * 1.3, segment_length * 1.1, girth * 1.3), rotation=_Y_TO_X),
            _scaled(_unit_cube(), (segment_length * 0.5, girth * 0.5, girth * 2.0)),
            CSGOperation.SUBTRACT,
        )
        body.add(jaw, position=(segment_length * 0.55, 0.0, 0.0))
        accent.add(
            _unit_sphere(8, 12),
            position=(segment_length * 0.62, 0.0, 0.0),
            scale=(girth * 0.5, girth * 0.5, girth * 0.5),
        )
    else:
        accent.add(
            _unit_cylinder(10),
            position=(0.0, 0.0, 0.0),
            rotation=_Y_TO_X,
            scale=(girth * 0.72, segment_length * 0.06, girth * 0.72),
        )
    return body.build(), accent.build()


def build_shrike_segment(index: int, seed: int = 0) -> Node3D:
    """One body segment of the Shrike, index 0 being the lantern head.

    Segments are built along +X and chained by the hunter module; the taper and
    the quill count fall off with *index*, so the eel reads as one animal.
    """
    if index < 0:
        raise ValueError(f"Shrike segment index must be non-negative, got {index}")
    body, accent = _cached(("shrike", index, seed), lambda: _build_shrike_meshes(index, seed))
    node = Node3D(name="ShrikeSegmentArt")
    node.add_child(_mesh_instance(ROLE_HULL, body, faction_material("hunter", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("hunter", ROLE_ACCENT)))
    return node


# ============================================================================
# Environment geometry: rocks, deposits, wrecks, stations
# ============================================================================


def _build_deposit_meshes(rich: bool, seed: int) -> tuple[Mesh, Mesh]:
    radius = 2.2 if rich else 1.6
    rock = _displaced_rock(seed, radius, relief=0.38)
    rng = np.random.default_rng((seed, int(rich)))
    veins = Kit()
    # Ore veins sit in the deepest folds, so the surface layer visibly runs out
    # before the core the design pays double for.
    points = rock.positions
    picks = rng.choice(len(points), size=10 if rich else 6, replace=False)
    for pick in picks:
        spot = points[int(pick)] * 0.97
        veins.add(
            _unit_sphere(5, 6),
            position=(float(spot[0]), float(spot[1]), float(spot[2])),
            scale=radius * (0.22 if rich else 0.15),
        )
    return rock, veins.build()


def build_deposit(rich: bool, seed: int = 0) -> Node3D:
    """A minable deposit: a noise-displaced rock veined with visible ore.

    A rich node is bigger and more heavily veined, which is the only warning
    the player gets that tapping it costs signature.
    """
    rock, veins = _cached(("deposit", bool(rich), seed), lambda: _build_deposit_meshes(bool(rich), seed))
    node = Node3D(name="DepositArt")
    node.add_child(_mesh_instance(ROLE_HULL, rock, faction_material("environment", ROLE_HULL)))
    accent = faction_material("environment", ROLE_ACCENT)
    if rich:
        accent.emissive_strength = palette("environment").accent_strength * 2.0
    node.add_child(_mesh_instance(ROLE_ACCENT, veins, accent))
    return node


def build_asteroid(seed: int = 0, radius: float = 3.0) -> Node3D:
    """A plain noise-displaced rock: cover, collision and clutter.

    Not in the module contract but wanted by every sector layout, so it lives
    beside the deposit it shares its displacement with.
    """
    if radius <= 0.0:
        raise ValueError(f"Asteroid radius must be positive, got {radius}")
    rock = _cached(("asteroid", seed, round(float(radius), 3)), lambda: (_displaced_rock(seed, radius),))[0]
    node = Node3D(name="AsteroidArt")
    node.add_child(_mesh_instance(ROLE_HULL, rock, faction_material("environment", ROLE_HULL)))
    return node


def _build_wreck_meshes(seed: int) -> tuple[Mesh, Mesh, Mesh]:
    rng = np.random.default_rng(seed)
    length = float(rng.uniform(5.0, 8.0))
    beam = length * 0.34
    # A torn hull: the blast hole is a real subtraction, so the break reads as
    # a break from any angle rather than a painted-on decal.
    torso = csg_combine(
        _scaled(_unit_cube(), (length * 0.5, beam * 0.6, beam)),
        _scaled(_unit_sphere(6, 8), (beam * 1.5, beam * 1.5, beam * 1.5)),
        CSGOperation.SUBTRACT,
    )
    hull = Kit()
    hull.add(torso)
    hull.add(
        _unit_cone(10),
        position=(length * 0.36, 0.0, 0.0),
        rotation=_Y_TO_X,
        scale=(beam * 0.7, length * 0.28, beam * 0.7),
    )
    _greeble(hull, rng, span=(length * 0.3, beam * 0.3, beam * 0.4), count=18, size=0.22)

    # Exposed spars, swept as extruded ribs out of the break.
    trim = Kit()
    for _ in range(4):
        start = (float(rng.uniform(-length * 0.1, length * 0.2)), 0.0, 0.0)
        centreline = [
            start,
            (start[0] + float(rng.uniform(0.6, 1.4)), float(rng.uniform(-0.5, 0.5)), float(rng.uniform(-0.9, 0.9))),
            (start[0] + float(rng.uniform(1.6, 2.8)), float(rng.uniform(-0.9, 0.9)), float(rng.uniform(-1.8, 1.8))),
        ]
        trim.add(Mesh.extrude_path(centreline, sides=5, radius=float(rng.uniform(0.06, 0.14))))

    # A cargo lamp still running on the wreck's last cell.
    accent = Kit()
    accent.add(_unit_cube(), position=(-length * 0.3, beam * 0.32, 0.0), scale=(0.5, 0.05, 0.12))
    return hull.build(), trim.build(), accent.build()


def build_wreck(seed: int = 0) -> Node3D:
    """A salvageable hulk: torn plating, exposed spars and one live lamp."""
    hull, trim, accent = _cached(("wreck", seed), lambda: _build_wreck_meshes(seed))
    node = Node3D(name="WreckArt")
    node.add_child(_mesh_instance(ROLE_HULL, hull, faction_material("environment", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_TRIM, trim, faction_material("environment", ROLE_TRIM)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("environment", ROLE_ACCENT)))
    return node


def _build_depot_meshes(seed: int) -> tuple[Mesh, Mesh, Mesh]:
    rng = np.random.default_rng(seed)
    radius = 5.0
    height = 2.6
    # Core drum with the docking bay cut through the rim: the cutter is offset
    # past the radius so the bay opens outward instead of leaving a sealed void.
    drum = csg_combine(
        _scaled(_unit_cylinder(16), (radius * 2.0, height, radius * 2.0)),
        _scaled(_unit_cube(), (radius * 1.4, height * 0.55, radius * 0.7), position=(radius * 0.7, 0.0, 0.0)),
        CSGOperation.SUBTRACT,
    )
    hull = Kit()
    hull.add(drum)
    _greeble(hull, rng, span=(radius * 0.7, height * 0.5, radius * 0.7), count=24, size=0.3)

    # Habitation ring, swept as a closed extrusion around the drum.
    ring_points = [
        (math.cos(math.tau * i / 24) * radius * 1.5, 0.0, math.sin(math.tau * i / 24) * radius * 1.5) for i in range(24)
    ]
    trim = Kit()
    trim.add(Mesh.extrude_path(ring_points, sides=6, radius=0.32, closed=True))
    for index in range(4):
        angle = math.tau * index / 4
        trim.add(
            _unit_cube(),
            position=(math.cos(angle) * radius * 1.25, 0.0, math.sin(angle) * radius * 1.25),
            rotation=Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), -angle),
            scale=(radius * 0.6, 0.16, 0.3),
        )
    trim.add(_unit_cylinder(8), position=(0.0, height * 0.9, 0.0), scale=(0.22, height * 0.9, 0.22))

    # Approach lights around the bay mouth, the thing a docking pilot reads.
    accent = Kit()
    for index in range(10):
        angle = math.tau * index / 10
        accent.add(
            _unit_sphere(5, 6),
            position=(math.cos(angle) * radius * 1.02, height * 0.42, math.sin(angle) * radius * 1.02),
            scale=0.22,
        )
    accent.add(_unit_cube(), position=(radius * 0.75, 0.0, 0.0), scale=(0.12, height * 0.4, radius * 0.62))
    return hull.build(), trim.build(), accent.build()


def build_depot(seed: int = 0) -> Node3D:
    """A drift depot: drum, habitation ring, cut docking bay and approach lights."""
    hull, trim, accent = _cached(("depot", seed), lambda: _build_depot_meshes(seed))
    node = Node3D(name="DepotArt")
    node.add_child(_mesh_instance(ROLE_HULL, hull, faction_material("environment", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_TRIM, trim, faction_material("environment", ROLE_TRIM)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("environment", ROLE_ACCENT)))
    return node


def _build_vault_meshes(seed: int) -> tuple[Mesh, Mesh]:
    rng = np.random.default_rng(seed)
    size = 2.8
    # A sealed block with a recessed hatch: the Shrike's shear opens it later.
    shell = csg_combine(
        _scaled(_unit_cube(), (size, size * 0.8, size)),
        _scaled(_unit_cylinder(12), (size * 0.66, size * 0.3, size * 0.66), rotation=_Y_TO_X),
        CSGOperation.SUBTRACT,
    )
    hull = Kit()
    hull.add(shell)
    _greeble(hull, rng, span=(size * 0.35, size * 0.4, size * 0.35), count=10, size=0.22)
    accent = Kit()
    accent.add(
        _unit_cylinder(12), position=(size * 0.42, 0.0, 0.0), rotation=_Y_TO_X, scale=(size * 0.5, 0.06, size * 0.5)
    )
    return hull.build(), accent.build()


def build_vault(seed: int = 0) -> Node3D:
    """A sealed vault: the twenty-second hack, and what the Shrike shears open.

    Not in the module contract but the sector needs one, and it belongs with
    the station kit it is cut from.
    """
    hull, accent = _cached(("vault", seed), lambda: _build_vault_meshes(seed))
    node = Node3D(name="VaultArt")
    node.add_child(_mesh_instance(ROLE_HULL, hull, faction_material("environment", ROLE_HULL)))
    node.add_child(_mesh_instance(ROLE_ACCENT, accent, faction_material("environment", ROLE_ACCENT)))
    return node


# ============================================================================
# Mesh cache
# ============================================================================

_MESH_CACHE: dict[tuple, tuple[Mesh, ...]] = {}


def _cached(key: tuple, factory) -> tuple:
    """Build once per key and share the result: meshes here are never mutated."""
    cached = _MESH_CACHE.get(key)
    if cached is None:
        cached = tuple(factory())
        _MESH_CACHE[key] = cached
    return cached


def clear_mesh_cache() -> None:
    """Drop every cached build. For tests and for a sector teardown."""
    _MESH_CACHE.clear()


# ============================================================================
# The nebula sky
# ============================================================================


@dataclass(frozen=True)
class ActGrade:
    """The look of one act: ambient, fog, exposure, bloom and nebula tints."""

    id: str
    ambient_colour: tuple[float, float, float, float]
    ambient_energy: float
    fog_colour: tuple[float, float, float, float]
    fog_density: float
    tonemap_exposure: float
    bloom_threshold: float
    bloom_intensity: float
    sky_top: tuple[float, float, float, float]
    nebula_deep: tuple[float, float, float]
    nebula_bright: tuple[float, float, float]


#: Shallows cold cyan, Claims amber rust, Deep blood-violet on black. Exposure
#: falls act by act: the Deep is the darkest screen in the game.
ACT_GRADES: dict[int, ActGrade] = {
    1: ActGrade(
        "shallows",
        ambient_colour=(0.06, 0.11, 0.14, 1.0),
        ambient_energy=0.85,
        fog_colour=(0.05, 0.12, 0.16, 1.0),
        fog_density=0.010,
        tonemap_exposure=1.05,
        bloom_threshold=1.0,
        bloom_intensity=0.75,
        sky_top=(0.014, 0.030, 0.042, 1.0),
        nebula_deep=(0.02, 0.10, 0.14),
        nebula_bright=(0.16, 0.52, 0.60),
    ),
    2: ActGrade(
        "claims",
        ambient_colour=(0.12, 0.08, 0.05, 1.0),
        ambient_energy=0.70,
        fog_colour=(0.13, 0.08, 0.04, 1.0),
        fog_density=0.014,
        tonemap_exposure=0.95,
        bloom_threshold=1.05,
        bloom_intensity=0.85,
        sky_top=(0.036, 0.022, 0.012, 1.0),
        nebula_deep=(0.12, 0.06, 0.02),
        nebula_bright=(0.58, 0.32, 0.12),
    ),
    3: ActGrade(
        "deep",
        ambient_colour=(0.09, 0.03, 0.07, 1.0),
        ambient_energy=0.55,
        fog_colour=(0.09, 0.02, 0.06, 1.0),
        fog_density=0.020,
        tonemap_exposure=0.82,
        bloom_threshold=1.15,
        bloom_intensity=1.0,
        sky_top=(0.026, 0.006, 0.018, 1.0),
        nebula_deep=(0.10, 0.01, 0.05),
        nebula_bright=(0.48, 0.08, 0.26),
    ),
}


def act_grade(act: int) -> ActGrade:
    """The grade for *act* (1 to ``balance.CHART_ACTS``), raising outside that."""
    try:
        return ACT_GRADES[act]
    except KeyError:
        raise ValueError(f"No grade for act {act!r}; acts are 1 to {balance.CHART_ACTS}") from None


def _resample_square(field: np.ndarray, size: int) -> np.ndarray:
    """Bilinearly resize a square field to ``size`` by ``size``.

    Sampling at texel centres, so the cloud layer arrives at the face
    resolution as a smooth gradient rather than as visible blocks.
    """
    source = field.shape[0]
    if source == size:
        return field
    coords = (np.arange(size, dtype=np.float64) + 0.5) * source / size - 0.5
    low = np.clip(np.floor(coords).astype(np.int64), 0, source - 1)
    high = np.clip(low + 1, 0, source - 1)
    weight = np.clip(coords - low, 0.0, 1.0)
    rows = field[low] * (1.0 - weight)[:, None] + field[high] * weight[:, None]
    return rows[:, low] * (1.0 - weight)[None, :] + rows[:, high] * weight[None, :]


def nebula_cubemap_faces(seed: int = 0, act: int = 1, size: int = NEBULA_FACE_SIZE) -> list[np.ndarray]:
    """Six float32 RGBA cube faces of a procedural nebula, in Vulkan face order.

    The result is linear HDR: the clouds stay dim so environments read
    near-black, and the star field runs above 1.0 so bloom picks it up. Feeding
    it to ``WorldEnvironment.environment_map`` drives both the skybox and the
    image-based lighting from the same bake.

    The two layers are baked at different resolutions on purpose. Clouds are
    evaluated on a :data:`NEBULA_CLOUD_SIZE` grid and resampled up, because
    noise is the expensive half and a soft cloud gains nothing from detail;
    stars are stamped at the full face resolution, because the face size is
    what decides how small a star can be.

    Stars are Gaussian splats at sub-texel centres rather than single texels.
    A texel of a cube face is a third of a degree of arc even at this
    resolution, and a lone hot texel magnified onto the screen is a square: the
    splat is what makes it a round point of light instead.
    """
    if size < 8:
        raise ValueError(f"Nebula face size must be at least 8, got {size}")
    cloud_size = min(int(size), NEBULA_CLOUD_SIZE)
    grade = act_grade(act)
    clouds = FastNoiseLite(seed=int(seed), noise_type=NoiseType.SIMPLEX, frequency=1.0)
    clouds.fractal_type = FractalType.FBM
    clouds.fractal_octaves = 5
    filaments = FastNoiseLite(seed=int(seed) + 977, noise_type=NoiseType.SIMPLEX, frequency=2.4)
    filaments.fractal_type = FractalType.RIDGED
    filaments.fractal_octaves = 4

    grid = (np.arange(cloud_size, dtype=np.float64) + 0.5) / cloud_size * 2.0 - 1.0
    u, v = np.meshgrid(grid, grid)
    deep = np.asarray(grade.nebula_deep, dtype=np.float32)
    bright = np.asarray(grade.nebula_bright, dtype=np.float32)
    scale = (size / NEBULA_FACE_SIZE) ** 2
    star_count = max(STAR_MIN_PER_FACE, int(round(STARS_PER_FACE * scale)))

    faces: list[np.ndarray] = []
    for index, (right, up, forward) in enumerate(_FACE_BASIS):
        direction = (
            np.asarray(forward)[None, None, :]
            + u[..., None] * np.asarray(right)[None, None, :]
            + v[..., None] * np.asarray(up)[None, None, :]
        )
        direction /= np.linalg.norm(direction, axis=-1, keepdims=True)
        x = direction[..., 0].ravel()
        y = direction[..., 1].ravel()
        z = direction[..., 2].ravel()

        body = (np.asarray(clouds.get_noise_3d_array(x, y, z)).reshape(cloud_size, cloud_size) * 0.5 + 0.5) ** 2.2
        threads = np.asarray(filaments.get_noise_3d_array(x, y, z)).reshape(cloud_size, cloud_size)
        thread = np.clip(threads, 0.0, 1.0) ** 3.0
        mix = _resample_square(np.clip(body * 0.8 + thread * 0.45, 0.0, 1.0), size).astype(np.float32)

        face = np.empty((size, size, 4), dtype=np.float32)
        cloud = deep[None, None, :] * 0.35 + (bright - deep)[None, None, :] * mix[..., None]
        face[..., :3] = cloud * NEBULA_CLOUD_ENERGY
        _stamp_stars(face, seed=seed, act=act, face_index=index, count=star_count)
        face[..., 3] = 1.0
        faces.append(np.maximum(face, 0.0))
    return faces


def _stamp_stars(face: np.ndarray, *, seed: int, act: int, face_index: int, count: int) -> None:
    """Add *count* soft, tinted stars to one cube face, in place.

    Seeded per face so no two skies repeat, and splatted rather than masked, so
    the cost is the star count and not the face area.
    """
    size = face.shape[0]
    rng = np.random.default_rng((int(seed), act, face_index))
    centres = rng.uniform(0.0, float(size), size=(count, 2))
    energy = rng.uniform(STAR_ENERGY_MIN, STAR_ENERGY_MAX, count)
    # One number per star bends its hue from cold blue-white to warm amber.
    temperature = rng.uniform(-1.0, 1.0, count)
    tint = np.stack(
        (
            1.0 + STAR_TINT * temperature,
            np.ones(count),
            1.0 - STAR_TINT * temperature,
        ),
        axis=1,
    )

    steps = np.arange(-STAR_KERNEL_RADIUS, STAR_KERNEL_RADIUS + 1)
    offset_rows, offset_columns = (axis.ravel() for axis in np.meshgrid(steps, steps, indexing="ij"))
    anchor = np.floor(centres).astype(np.int64)
    delta_rows = anchor[:, 0, None] + offset_rows[None, :] + 0.5 - centres[:, 0, None]
    delta_columns = anchor[:, 1, None] + offset_columns[None, :] + 0.5 - centres[:, 1, None]
    weights = np.exp(-(delta_rows**2 + delta_columns**2) / (2.0 * STAR_SIGMA**2))

    # Wrapping rather than clipping: a star near an edge keeps its round
    # profile instead of piling its whole splat into the last texel.
    rows = np.mod(anchor[:, 0, None] + offset_rows[None, :], size)
    columns = np.mod(anchor[:, 1, None] + offset_columns[None, :], size)
    light = (weights * energy[:, None])[..., None] * tint[:, None, :]
    np.add.at(face, (rows.ravel(), columns.ravel(), slice(0, 3)), light.reshape(-1, 3).astype(np.float32))


def apply_nebula_sky(env: WorldEnvironment, seed: int = 0, act: int = 1, size: int = NEBULA_FACE_SIZE) -> None:
    """Install a freshly baked nebula as the scene's skybox and IBL source."""
    grade = act_grade(act)
    env.sky_mode = "colour"
    env.sky_colour_top = grade.sky_top
    env.sky_colour_bottom = grade.sky_top
    env.environment_map = {"faces": nebula_cubemap_faces(seed, act, size)}


# ============================================================================
# Per-act grading and exposure
# ============================================================================


def apply_act_grading(env: WorldEnvironment, act: int, *, silent_running: bool = False) -> None:
    """Grade the scene for *act*, optionally under silent running.

    Silent running drops the whole scene's exposure by
    :data:`SILENT_RUNNING_EXPOSURE_MULT`: the quietest screen is also the
    darkest, which is the point.
    """
    grade = act_grade(act)
    env.ambient_light_colour = grade.ambient_colour
    env.ambient_light_energy = grade.ambient_energy
    env.fog_enabled = True
    env.fog_colour = grade.fog_colour
    env.fog_density = grade.fog_density
    env.tonemap_mode = "aces"
    env.tonemap_exposure = grade.tonemap_exposure * (SILENT_RUNNING_EXPOSURE_MULT if silent_running else 1.0)
    env.bloom_enabled = True
    env.bloom_threshold = grade.bloom_threshold
    env.bloom_intensity = grade.bloom_intensity


def configure_environment(
    env: WorldEnvironment,
    act: int = 1,
    seed: int = 0,
    *,
    silent_running: bool = False,
    nebula_size: int = NEBULA_FACE_SIZE,
) -> WorldEnvironment:
    """Set a run scene's whole look in one call: sky, grade and post chain.

    SSAO grounds the wrecks, screen-space reflections carry the plating, and
    bloom is driven entirely by the emissives the readability contract owns.
    """
    apply_nebula_sky(env, seed, act, nebula_size)
    apply_act_grading(env, act, silent_running=silent_running)
    env.ssao_enabled = True
    env.ssao_radius = 0.6
    env.ssao_intensity = 1.1
    env.ssr_enabled = True
    env.ssr_intensity = 0.55
    env.ssr_roughness_cutoff = 0.45
    env.fxaa_enabled = True
    return env


def build_environment(
    act: int = 1,
    seed: int = 0,
    *,
    silent_running: bool = False,
    nebula_size: int = NEBULA_FACE_SIZE,
) -> WorldEnvironment:
    """A fully configured ``WorldEnvironment`` for a run scene."""
    return configure_environment(
        WorldEnvironment(name="Environment"),
        act,
        seed,
        silent_running=silent_running,
        nebula_size=nebula_size,
    )


# ============================================================================
# Placement helper
# ============================================================================


def place_on_plane(node: Node3D, x: float, z: float, *, heading: float = 0.0) -> Node3D:
    """Put *node* on the flight plane at ``(x, z)`` facing *heading*.

    A build points along +X, so a yaw about +Y by the heading matches
    :func:`runtime.heading_to_direction` exactly.
    """
    node.position = Vec3(float(x), PLANE_Y, float(z))
    node.rotation = Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), float(heading))
    return node