nebula-archetypes

nebula-archetypes.ts

Catalog of every nebula / sky / surface backdrop the game can render, plus the per-archetype side-tables (star colors, star types, surface flag) and the biome-pool resolver that feeds the renderer. Pure data + small pure functions; no I/O. ~1500 lines, the largest single data file in the repo.

Each archetype is a flat parameter bag passed wholesale to the WebGL nebula shader. Index in ARCHETYPES is the stable handle used everywhere else (SURF_MODE[i], STAR_COLORS[i], STAR_TYPES[i], PLANET_ARCHETYPE_IDX[id], biome pools).

Registry shape

The file mutates one growing array — ARCHETYPES: Archetype[] — declared as a literal of ~250 entries, then .push()’ed by the per-planet and close-up-surface sections. Order of pushes is load-bearing: planet archetypes capture ARCHETYPES.length at push time and store it in PLANET_*_IDX constants exported via PLANET_ARCHETYPE_IDX. Do not reorder.

Side tables are parallel arrays indexed by archetype:

Array	Type	Indexes
ARCHETYPES	Archetype[]	master list (~270 entries after pushes)
STAR_COLORS	[dR,dG,dB,bR,bG,bB][]	dim/bright RGB pair per archetype, far-layer to near-layer
SURF_MODE	Uint8Array	0 = space (parallax stars render), 1 = surface (nebula-only)
STAR_TYPES	string[]	10-char layer code, far→near; s=star, d=dust, r=rock

STAR_COLORS and STAR_TYPES cover the first 100 indices verbatim. Later v5.149/v5.154 archetypes fall through to defaults.

Archetype schema

interface Archetype (line 39) — required: name, four cosine-palette vec3s (pa/pb/pc/pd), warp, density, speed, thresh, bg, shape, nf, ec. Optional: nt (noise type), sat/lum, fg, ten surface-FX flags (hm wv gl ca pr ln sm sb sp ss), mode (NebulaMode 0..16), eight mode-knobs m1..m8, spk (sparkle intensity), ssa/ssv (shooting-star angle + variance).

Cosine-palette params follow Inigo Quilez’s a + b*cos(2π*(c*t + d)) formulation. bg is base color in 0–1 RGB; ec is emission tint in 0–255 RGB.

type NebulaMode = 0..16. Mode 0 (or unset) routes to the original single-program v1 renderer — all original 100 archetypes pixel-identical to ss_v15.html. Modes 1–7 are the v5.149 FS2 shader (enriched classic, spiral, blackhole, planet horizon, aurora, warp tunnel, cavern). Modes 8–16 are the v5.187 close-up “living surface” shaders (water, glass, lava, aurora curtain, cel water, sin-grid sea, lily pond, underwater rays). Mode 12 is reserved but currently unused — archetypes removed in v5.188 per user feedback.

Categories of archetype

Three authoring eras stack into ARCHETYPES, plus runtime-appended planet and surface entries:

v1 — original 100 (indices 0–99). Verbatim from ss_v15.html. Organized into 11 thematic zones via comment banners only:

Zone	Indices	Theme	Style flag
I — Outer Acheron	0–7	entry / threshold (Sparse Silent Void, Asteroid Belt, …)	space
II — Tartarus Grid	8–15	industrial / ruin (Ancient Ruins, Wireframe Sim, Cyber-Noir Rain, …)	space
III — Abyssal Styx	16–23	liquid / organic (Verdant Cavern, Bioluminescent Deep, Eldritch Abyss, …)	space
IV — Phlegethon Wastes	24–31	radiation / chaos (Chaos Warp, Solar Flare, Magma Core, …)	space
V — Elysian Anomaly	32–49	surreal / divine (Cosmic Rift, Princess Dreamland, Aurora Borealis, …)	space
VI — Aquatic Layer	50–54	atmospheric haze (Dusk Haze, Emerald Mist, Coral Dawn, …)	surface (fg)
VII — Fog Realm	55–64	fog overlays (Morning Mist, Poison Cloud, Ink Cloud, …)	surface (fg)
VIII — Molten Core	65–72	heat shimmer (Magma Flow, Blue Flame, Solar Surface, …)	surface (hm)
IX — Crystal Wastes	73–81	prismatic refraction (Black Ice, Frost Cathedral, Snowblind, …)	surface (pr)
X — Dark Sector	82–89	gravitational lensing (Event Horizon, Singularity, Void Bloom, …)	space (ln)
XI — Hybrid Nexus	90–99	creative FX combinations (Drowned Temple, Plasma Storm, Acid Ocean, …)	mixed

Zones are documentation only — biome pools do not group by zone.

v5.149 — 100 FS2-mode archetypes (indices 100–199). Routed by mode field. Seven blocks: 25× mode 1 enriched-classic, 15× mode 2 spirals, 12× mode 3 black holes, 15× mode 4 planet horizons, 12× mode 5 aurora ribbons, 10× mode 6 warp tunnels, 11× mode 7 caverns.

v5.154 — 50 more (indices 200–249). Same mode breakdown (12+10+6+10+6+4+2). Adds varied ssa/ssv shooting-star setups for the deterministic streak algorithm.

Per-planet archetypes (~10 entries pushed at module load). _PLANET_3_ARCH through _PLANET_37_ARCH — fixed look per planet ID used by hub and in-run for visual consistency. Some are bespoke (Void Nebula, Solaris Nebula, Network Nebula); others are tinted clones of existing archetypes (Planet 12 = Abandoned Station × 1.5 lum; Planet 21 = Dusk Haze × 1.95 lum). All pushed sequentially so PLANET_*_IDX captures correct indices.

Close-up surface archetypes (modes 8–16, ~12 entries pushed). Dynamic-feeling close-ups for the Nebula Viewer: Sun-Dappled Lagoon, Rippling Glass, Lava River, Aurora Curtain, Cel Lagoon, Stylized Open Sea, Lily Pad Pool, Sunken Light Shafts, etc. Different aesthetic from deep-space nebulae — each is meant to feel alive in isolation, not as a backdrop.

Public API

Constants

• ARCHETYPES: Archetype[] — master list. Index is the stable handle.
• STAR_COLORS: [number,number,number,number,number,number][] — [dimR,dimG,dimB,brightR,brightG,brightB], far layers blend toward dim, near toward bright. First 100 indices only.
• SURF_MODE: Uint8Array — 0 space (parallax stars on) / 1 surface (nebula-only, stars suppressed).
• STAR_TYPES: string[] — 10-character layer string per archetype, far-to-near. s/d/r per slot.
• BIOME_BACKGROUNDS: Record<string, number[]> — biome ID → archetype-index pool. All six biomes (landing_site, sunrise_city, the_voidstar, obsidian_spire, jungle_canopy, crystal_cavern) currently share SMOOTH_NEBULA_POOL.
• PLANET_ARCHETYPES: Record<number, Archetype> — planet ID → archetype object (used by hub NebulaBackground).
• PLANET_ARCHETYPE_IDX: Record<number, number> — planet ID → archetype index (used by in-run renderer).
• DISPLAY_ARCHETYPES: readonly Archetype[] — curated Nebula Viewer list. Each entry in FAVORITE_NAMES expands to 4 rows: [fav, fav·Tempest, fav·Hush, fav·Bloom].
• FAVORITE_NAMES: readonly string[] — Nate-curated favorite list. Names are matched punctuation- and case-insensitively against ARCHETYPES[*].name.

Functions

• getSmoothNebulaPool(): number[] — exposes SMOOTH_NEBULA_POOL for menu / level-select backdrops.
• getSpaceArchetypes(biomeId: string): number[] — biome pool filtered by SURF_MODE === 0. Falls back to all archetypes in the pool if none are space-mode, then to landing_site if biome ID is unknown.

SMOOTH_NEBULA_POOL — biome filter

Computed once at module load. Filters ARCHETYPES by SURF_MODE[i] === 0 and isSmoothArchetype(a). The latter (per Nate’s 2026-04-22 brief “I don’t see the nebula at all” + “smooth normal ones like landing site better than crazy ones like solaris”):

• Classic FBM noise only — nt === undefined || nt === 0. Ridged veins (1) and voronoi cells (2) read as chaos.
• Low-to-moderate domain warp — warp ≤ 0.7. Higher warp produces writhing shapes.
• Density in [0.4, 0.65]. Below 0.4 reads as empty void; above 0.65 competes with gameplay legibility.
• Saturation ≤ 1.0. No neon.

All six biome pools point to SMOOTH_NEBULA_POOL today, so biome choice does not affect backdrop variety. Per-planet archetypes (via PLANET_ARCHETYPE_IDX) override the biome pool when a planet has a fixed look.

DISPLAY_ARCHETYPES — favorites + variations

FAVORITE_NAMES (~34 entries) is the curated set shown in the Nebula Viewer. For each favorite, three procedurally-mutated variations are generated and pushed in sequence: Tempest (turbulent / fast / chaotic — palette rotated 180°, warp ×1.8, speed ×1.7, ridged FBM, fog added, shooting stars rotated 180°), Hush (slow / smooth / sparse — amplitude halved, warp ×0.5, speed ×0.35, broader FBM, low saturation), Bloom (granular / fine / warm — palette rotated 270°, noise ×1.95, voronoi cells, sparkles maxed, warm bg/emission).

Variation helpers variantTempest / variantHush / variantBloom preserve mode and structural fields — only palette, amplitude, warp, density, noise, and m-knobs are perturbed. Each m-knob mutates via mulIfSet / addIfSet helpers so unset knobs stay unset (FS1 archetypes don’t gain phantom values).

Final length: FAVORITE_NAMES.length × 4 when all names resolve. Unresolved names emit a single console.warn listing them — the resolver normalizes names by stripping non-alphanumerics and lowercasing.

Notes & invariants

• Index stability is load-bearing. Reordering or splicing ARCHETYPES breaks STAR_COLORS, STAR_TYPES, SURF_MODE, PLANET_ARCHETYPE_IDX, and any persisted save data referencing archetype indices. Append-only.
• STAR_COLORS and STAR_TYPES cover indices 0–99 only. v5.149+ archetypes (mode-routed) fall through to renderer defaults. Adding new indices does not require backfilling these arrays unless the archetype is mode 0 (classic) and needs custom parallax-star colors.
• SURF_MODE length must equal ARCHETYPES length pre-push. Currently sized for the first 100; subsequent archetypes (v5.149/v5.154 + planet + close-up) read out-of-bounds as 0 (space) — which is correct for mode-routed archetypes since their shader handles backgrounds internally.
• Network Nebula (Planet 34) workaround. Per Discord #588 (2026-05-13): original cross star shape + high nf + cyan emission combined into “lightspeed white wisp” streaks during the Protect mission. Swapped to dot + nf 1.4→0.9.

EXTRACT-CANDIDATE

This file does ~five things at once and is approaching limits of single-file maintainability:

1. Archetype schema (NebulaMode, Archetype) — type-only, could live in nebula-archetype-schema.ts.
2. The master ARCHETYPES literal (~600 lines) — pure data, could split per era (archetypes-v1.ts, archetypes-v5.149.ts, archetypes-v5.154.ts) or per mode (archetypes-mode1.ts, …).
3. Per-archetype side tables (STAR_COLORS, STAR_TYPES, SURF_MODE) — could co-locate with v1 archetypes or move to a nebula-star-tables.ts.
4. Per-planet archetypes + index capture — has runtime ordering invariants; safer extracted to its own planet-nebulae.ts that imports ARCHETYPES and appends.
5. Smooth-pool filter + biome resolver — pure computation, could live in nebula-biome-resolver.ts.
6. Favorites variation engine (variantTempest / variantHush / variantBloom + DISPLAY_ARCHETYPES builder) — independent feature, used only by the Nebula Viewer. Strong candidate for nebula-viewer-variations.ts.

Refactor risk is low (no behavior change, type-safe, one consumer per export) but moderate touch (every importer needs a rewritten path). Defer until a feature needs to add a new mode or era.