entangled-worlds-orbiters-shared 2.10.0 → 2.12.0

package/dist/star/layout.js

@@ -0,0 +1,307 @@
+// Pure star-system layout: per-star colour / radius / glow and the orbits, derived deterministically
+// from the params + seed (same string hash + LCG the moons use, so a seed means the same thing in
+// both). No three — the renderer consumes these numbers.
+import { blackbodyColor } from './blackbody.js';
+import { normalizeStarParams } from './params.js';
+/** How much of the glow (in star radii) the focus sphere keeps around each disc. */
+export const FOCUS_GLOW_RADII = 1.5;
+/** Focus radius of a layout (pure): max over stars of (distance from barycentre + glow radius). */
+export function starFocusRadius(layout) {
+    let r = 0;
+    for (const s of layout.stars) {
+        const reach = s.orbit.radius + (s.role !== 'wide' && layout.pairOrbit ? layout.pairOrbit.radius : 0);
+        r = Math.max(r, reach + s.radius * FOCUS_GLOW_RADII);
+    }
+    return r;
+}
+/** 32-bit string hash (the same one `generateMoons` uses). */
+export function hashSeed(seed) {
+    if (typeof seed === 'number')
+        return Math.abs(Math.trunc(seed)) >>> 0;
+    let h = 0;
+    for (let i = 0; i < seed.length; i++) {
+        h = ((h << 5) - h) + seed.charCodeAt(i);
+        h = h & h;
+    }
+    return Math.abs(h) >>> 0;
+}
+/** Linear congruential generator in [0, 1) (Numerical Recipes constants, as in the moons). */
+export function createLcg(seed) {
+    let s = hashSeed(seed);
+    return () => {
+        s = (s * 1664525 + 1013904223) % 4294967296;
+        return s / 4294967296;
+    };
+}
+const TAU = Math.PI * 2;
+/** Orbital period of a pair at separation 2 (in summed radii), seconds. Slow enough to feel celestial. */
+const BASE_PAIR_PERIOD_SEC = 90;
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Linear limb-darkening coefficient vs temperature: ~0.85 for M dwarfs, ~0.6 Sun, ~0.3 O stars. */
+export function limbDarkeningFor(temperatureK) {
+    const x = Math.min(1, Math.max(0, (Math.log(temperatureK) - Math.log(2400)) / (Math.log(40000) - Math.log(2400))));
+    return lerp(0.85, 0.3, x);
+}
+/** Corona half-size in radii for a luminosity 0..1. */
+export function coronaExtentFor(luminosity) {
+    return 2.2 + 3.8 * Math.min(1, Math.max(0, luminosity));
+}
+function makeStar(role, temperatureK, radius, luminosity, activity, noiseSeed, orbit) {
+    return {
+        role,
+        temperatureK,
+        color: blackbodyColor(temperatureK),
+        radius,
+        luminosity,
+        activity,
+        coronaExtent: coronaExtentFor(luminosity),
+        limbDarkening: limbDarkeningFor(temperatureK),
+        noiseSeed,
+        gain: 1,
+        orbit,
+    };
+}
+function wrapDeg(deg) {
+    const w = ((((deg + 180) % 360) + 360) % 360) - 180;
+    return w === -180 ? 180 : w;
+}
+/**
+ * Debris-disc orientation (pure, from the seed): the ring's plane is near-horizontal, tilted
+ * `tilt` radians towards a viewer on +Z (so it reads as a thin ellipse, ~0.2–0.45 axis ratio) and
+ * rolled `roll` radians about the view axis. Independent of the orbital plane so a face-on-ish
+ * binary orbit never turns the disc into a flat halo.
+ */
+export function discOrientation(seed) {
+    const r = createLcg(`${seed}|disc`);
+    return { tilt: lerp(0.2, 0.46, r()), roll: lerp(-0.45, 0.45, r()) };
+}
+/** Distant companion (independent seed stream so it never shifts the system's own layout). */
+const DEG = Math.PI / 180;
+/** Unit vector for an azimuth/elevation in degrees (same convention as `starSystemPosition`). */
+function dirOf(azDeg, elDeg) {
+    const az = azDeg * DEG;
+    const el = elDeg * DEG;
+    return [Math.sin(az) * Math.cos(el), Math.sin(el), -Math.cos(az) * Math.cos(el)];
+}
+/**
+ * Keep the distant companion's direction at least `minAngle` (radians) away from the system's,
+ * rotating it away along the great circle (or straight up when they coincide). Pure.
+ */
+export function separateDirection(sys, far, minAngle) {
+    const u = dirOf(sys.azimuth, sys.elevation);
+    const v = dirOf(far.azimuth, far.elevation);
+    const dot = Math.max(-1, Math.min(1, u[0] * v[0] + u[1] * v[1] + u[2] * v[2]));
+    if (Math.acos(dot) >= minAngle)
+        return far;
+    let w = [v[0] - u[0] * dot, v[1] - u[1] * dot, v[2] - u[2] * dot];
+    let wl = Math.hypot(w[0], w[1], w[2]);
+    if (wl < 1e-6) {
+        // Same direction: move it up (or down near the zenith).
+        const up = u[1] < 0.9 ? [0, 1, 0] : [0, -1, 0];
+        const k = up[0] * u[0] + up[1] * u[1] + up[2] * u[2];
+        w = [up[0] - u[0] * k, up[1] - u[1] * k, up[2] - u[2] * k];
+        wl = Math.hypot(w[0], w[1], w[2]);
+    }
+    const c = Math.cos(minAngle);
+    const s = Math.sin(minAngle);
+    const x = u[0] * c + (w[0] / wl) * s;
+    const y = u[1] * c + (w[1] / wl) * s;
+    const z = u[2] * c + (w[2] / wl) * s;
+    return { azimuth: Math.atan2(x, -z) / DEG, elevation: Math.asin(Math.max(-1, Math.min(1, y))) / DEG };
+}
+/** Farthest any system star's disc reaches from the barycentre (orbits + radius; no glow). */
+export function starsReach(layout) {
+    let r = 0;
+    for (const s of layout.stars) {
+        const reach = s.orbit.radius + (s.role !== 'wide' && layout.pairOrbit ? layout.pairOrbit.radius : 0);
+        r = Math.max(r, reach + s.radius);
+    }
+    return r;
+}
+function distantFor(p, reach) {
+    if (!p.distantCompanion)
+        return null;
+    const r = createLcg(`${p.seed}|distant`);
+    // Default: up and back towards the frame's centre from the host — above the planet rather than
+    // behind it, and inside a typical frame when the host itself is placed beside the planet.
+    const inward = p.azimuth >= 0 ? -1 : 1;
+    let azimuth = p.distantAzimuth ?? wrapDeg(p.azimuth + inward * lerp(12, 22, r()));
+    let elevation = p.distantElevation ?? Math.min(60, p.elevation + lerp(6, 11, r()));
+    // Never inside the system: both sit at `distance`, so the chord between them must clear the
+    // system's reach + the companion's radius (with room to spare). Hosts may push the system
+    // farther (scene bounds), which only widens the gap.
+    const chord = 1.3 * (reach + p.distantRadius);
+    const minAngle = 2 * Math.asin(Math.min(1, chord / (2 * p.distance)));
+    ({ azimuth, elevation } = separateDirection({ azimuth: p.azimuth, elevation: p.elevation }, { azimuth, elevation }, minAngle));
+    azimuth = wrapDeg(azimuth);
+    const star = makeStar('distant', p.distantTemperatureK, p.distantRadius, p.distantBrightness * 0.8, p.activity * 0.8, r(), {
+        radius: 0,
+        phase: 0,
+        angularSpeed: 0,
+    });
+    star.gain = 0.7 + 0.3 * p.distantBrightness; // dimmer, but never grey
+    return { star, azimuth, elevation };
+}
+/**
+ * Lay out the system for (possibly raw) params. Companions are always cooler and smaller than the
+ * primary and derived from it + the seed; the trinary's third is a small, cool, wide companion
+ * (an Alpha Centauri-like hierarchy). Deterministic: same params → same layout.
+ */
+export function starLayout(rawParams) {
+    const p = normalizeStarParams(rawParams);
+    const rand = createLcg(p.seed);
+    const inclination = lerp(1.0, 1.35, rand()); // tilted towards the viewer: reads as an ellipse, never edge-on
+    const node = rand() * TAU;
+    const primarySeed = rand();
+    const r1 = p.radius;
+    const t1 = p.temperatureK;
+    if (p.multiplicity === 1) {
+        const star = makeStar('primary', t1, r1, p.luminosity, p.activity, primarySeed, { radius: 0, phase: 0, angularSpeed: 0 });
+        return {
+            stars: [star],
+            inclination,
+            node,
+            pairOrbit: null,
+            distant: distantFor(p, r1),
+            boundingRadius: r1 * star.coronaExtent,
+            focusRadius: r1 * FOCUS_GLOW_RADII,
+        };
+    }
+    // Close companion: cooler and smaller than the primary — unless real values were given (e.g. from
+    // the companion's mass). The random draws always happen so the rest of the layout stays put.
+    const t2Seeded = Math.max(2000, t1 * lerp(0.55, 0.9, rand()));
+    const r2Seeded = r1 * lerp(0.45, 0.85, rand());
+    const t2 = p.companionTemperatureK > 0 ? p.companionTemperatureK : t2Seeded;
+    const r2 = p.companionRadius > 0 ? p.companionRadius : r2Seeded;
+    const lum2 = p.luminosity * Math.min(1, Math.max(0.25, Math.pow(t2 / t1, 2) * (r2 / r1)));
+    const act2 = Math.min(1, p.activity * lerp(0.9, 1.4, rand()));
+    const pairPhase = rand() * TAU;
+    const d = p.separation * (r1 + r2); // centre-to-centre
+    // Mass ratio ~ radius^1.5 (main-sequence-ish) sets how far each orbits from the pair barycentre.
+    const q = Math.pow(r2 / r1, 1.5); // m2 / m1
+    const pairOmega = TAU / (BASE_PAIR_PERIOD_SEC * Math.pow(p.separation / 2, 1.5));
+    const primary = makeStar('primary', t1, r1, p.luminosity, p.activity, primarySeed, {
+        radius: (d * q) / (1 + q),
+        phase: pairPhase,
+        angularSpeed: pairOmega,
+    });
+    const companion = makeStar('companion', t2, r2, lum2, act2, rand(), {
+        radius: d / (1 + q),
+        phase: pairPhase + Math.PI,
+        angularSpeed: pairOmega,
+    });
+    const stars = [primary, companion];
+    let pairOrbit = null;
+    let boundingRadius = Math.max(primary.orbit.radius + r1 * primary.coronaExtent, companion.orbit.radius + r2 * companion.coronaExtent);
+    if (p.multiplicity === 3) {
+        const t3 = Math.max(2000, t1 * lerp(0.4, 0.65, rand()));
+        const r3 = r1 * lerp(0.25, 0.45, rand());
+        const lum3 = p.luminosity * Math.min(1, Math.max(0.2, Math.pow(t3 / t1, 2) * (r3 / r1)));
+        const act3 = Math.min(1, Math.max(p.activity, lerp(0.5, 0.9, rand()))); // small cool stars flare
+        // Pair barycentre ↔ third. Never closer than the pair's own reach plus a clear gap, so the third
+        // can't graze either pair star whatever the radii (e.g. a tiny forced companion radius).
+        const a1 = (d * q) / (1 + q);
+        const a2 = d / (1 + q);
+        const minD = Math.max(a1 + 1.5 * (r1 + r3), a2 + 1.5 * (r2 + r3));
+        const D = Math.max(d * lerp(2.0, 2.8, rand()), minD);
+        const wideRatio = D / d;
+        const q3 = Math.pow(r3, 1.5) / (Math.pow(r1, 1.5) + Math.pow(r2, 1.5)); // m3 / (m1 + m2)
+        const wideOmega = pairOmega / Math.pow(wideRatio, 1.5);
+        const widePhase = rand() * TAU;
+        pairOrbit = { radius: (D * q3) / (1 + q3), phase: widePhase + Math.PI, angularSpeed: wideOmega };
+        const third = makeStar('wide', t3, r3, lum3, act3, rand(), { radius: D / (1 + q3), phase: widePhase, angularSpeed: wideOmega });
+        stars.push(third);
+        boundingRadius = Math.max(boundingRadius + pairOrbit.radius, third.orbit.radius + r3 * third.coronaExtent);
+    }
+    return { stars, inclination, node, pairOrbit, distant: distantFor(p, starsReach({ stars, pairOrbit })), boundingRadius, focusRadius: starFocusRadius({ stars, pairOrbit }) };
+}
+/**
+ * Local positions (relative to the system barycentre) of every star at `timeSec`, written as
+ * xyz triplets into `out` (allocated when omitted). Orbits are circular, in a plane tilted by
+ * `inclination` about X and rotated by `node` about Y. Allocation-free when `out` is passed.
+ */
+export function starPositions(layout, timeSec, out) {
+    const n = layout.stars.length;
+    const res = out ?? new Float32Array(n * 3);
+    const ci = Math.cos(layout.inclination);
+    const si = Math.sin(layout.inclination);
+    const cn = Math.cos(layout.node);
+    const sn = Math.sin(layout.node);
+    const t = Number.isFinite(timeSec) ? timeSec : 0;
+    // Pair barycentre offset (trinary only), in the orbital plane.
+    let bx = 0;
+    let bz = 0;
+    if (layout.pairOrbit) {
+        const a = layout.pairOrbit.phase + layout.pairOrbit.angularSpeed * t;
+        bx = Math.cos(a) * layout.pairOrbit.radius;
+        bz = Math.sin(a) * layout.pairOrbit.radius;
+    }
+    for (let i = 0; i < n; i++) {
+        const s = layout.stars[i];
+        const a = s.orbit.phase + s.orbit.angularSpeed * t;
+        let x = Math.cos(a) * s.orbit.radius;
+        let z = Math.sin(a) * s.orbit.radius;
+        if (s.role !== 'wide') {
+            x += bx;
+            z += bz;
+        }
+        // Tilt about X (plane gains height), then rotate about Y.
+        const y = z * si;
+        const zt = z * ci;
+        res[i * 3] = x * cn + zt * sn;
+        res[i * 3 + 1] = y;
+        res[i * 3 + 2] = -x * sn + zt * cn;
+    }
+    return res;
+}
+/** World-space position of the system barycentre for a distance/azimuth/elevation placement. */
+export function starSystemPosition(p) {
+    const az = (p.azimuth * Math.PI) / 180;
+    const el = (p.elevation * Math.PI) / 180;
+    const h = Math.cos(el) * p.distance;
+    return [Math.sin(az) * h, Math.sin(el) * p.distance, -Math.cos(az) * h];
+}
+/** Fractional part of a hash — a stateless [0,1) random for (seed, slot) pairs. */
+function hash01(a, b) {
+    let h = (Math.imul(a | 0, 0x27d4eb2d) ^ Math.imul(b | 0, 0x165667b1)) >>> 0;
+    h = Math.imul(h ^ (h >>> 15), 0x85ebca6b) >>> 0;
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35) >>> 0;
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+/** Length of one flare slot; at most one flare starts per slot. */
+export const FLARE_SLOT_SEC = 6;
+const FLARE_RISE_SEC = 0.25;
+const FLARE_DECAY_SEC = 1.6;
+/**
+ * Deterministic flare envelope for a star at `timeSec`: fast rise, exponential decay. The chance a
+ * slot holds a flare grows with `activity` (0 → never). Same (seed, time) → same answer on every
+ * machine, so all views of one world flare together.
+ */
+export function flareAt(noiseSeed, activity, timeSec, out) {
+    const res = out ?? { intensity: 0, angle: 0 };
+    res.intensity = 0;
+    res.angle = 0;
+    const act = Math.min(1, Math.max(0, activity));
+    if (act <= 0 || !Number.isFinite(timeSec))
+        return res;
+    const seedInt = Math.floor(noiseSeed * 1e6);
+    const slot = Math.floor(timeSec / FLARE_SLOT_SEC);
+    const chance = 0.08 + 0.5 * act * act;
+    for (let k = slot - 1; k <= slot; k++) {
+        if (hash01(seedInt, k) >= chance)
+            continue;
+        const start = (k + hash01(seedInt + 7, k) * 0.7) * FLARE_SLOT_SEC;
+        const dt = timeSec - start;
+        if (dt < 0)
+            continue;
+        const env = dt < FLARE_RISE_SEC ? dt / FLARE_RISE_SEC : Math.exp(-(dt - FLARE_RISE_SEC) / FLARE_DECAY_SEC);
+        const amp = (0.4 + 0.6 * hash01(seedInt + 13, k)) * act * env;
+        if (amp > res.intensity) {
+            res.intensity = amp;
+            res.angle = hash01(seedInt + 29, k) * TAU;
+        }
+    }
+    return res;
+}

package/dist/star/lighting.d.ts

@@ -0,0 +1,65 @@
+import type { RGB } from './blackbody.js';
+import type { StarLayout } from './layout.js';
+/** Author lighting controls. `tint` multiplies the key colour; null (or white) = none. */
+export interface StarLighting {
+    /** Key light multiplier (1 = the star's natural brightness). */
+    intensity: number;
+    /** Camera-side fill light, as a multiplier (0 = none). */
+    fill: number;
+    /** Colour multiplied into the key light: '#rrggbb', 0xrrggbb, {r,g,b} 0..1, or null. */
+    tint: string | number | RGB | null;
+}
+export declare const DEFAULT_STAR_LIGHTING: Readonly<StarLighting>;
+/**
+ * Ambient intensity to pair with the star's key + fill (instead of the old white hemisphere +
+ * ambient at 1). Output is sRGB, which lifts shadows a lot (4% linear ≈ 22% on screen), so night
+ * sides need very little: with the default fill this keeps a hint of the night side (~5% linear)
+ * while the terminator reads clearly.
+ */
+export declare const DEFAULT_AMBIENT = 0.06;
+/**
+ * Key light colour: the stars' blackbody colours weighted by their emitted power (R² · T⁴), so a
+ * dim companion barely shifts the Sun but a close pair of equals blends. The distant companion is
+ * not part of `layout.stars` and never contributes. Brightest channel = 1. Writes into `out`.
+ */
+export declare function systemLightColor(layout: Pick<StarLayout, 'stars'>, out?: RGB): RGB;
+/**
+ * Key light intensity for a luminosity 0..1 (three r155+ physical units, no tone mapping): the Sun
+ * at 0.5 gives ≈ π, i.e. a white MeshStandard surface facing the star renders at its albedo.
+ */
+export declare function keyLightIntensity(luminosity: number, multiplier?: number): number;
+/** Fill (camera-side hemisphere) intensity for the author `fill` multiplier. */
+export declare function fillLightIntensity(fill: number): number;
+/** Parse a tint to RGB 0..1, or null for none / white / unparseable. */
+export declare function parseTint(tint: StarLighting['tint'] | undefined): RGB | null;
+/** Validate a (partial) lighting patch against a base. Never throws. */
+export declare function normalizeStarLighting(raw: unknown, base?: Readonly<StarLighting>): StarLighting;
+/** Old per-world lighting as saved by hosts before the star lit the scene. */
+export interface LegacyLighting {
+    ambientIntensity?: number | null;
+    diffuseIntensity?: number | null;
+    lightColor?: string | number | null;
+    /** Ignored: the light now comes from the star. */
+    lightDirection?: unknown;
+}
+/** The ambient the old flat-lit look was tuned around (the host's former default). */
+export declare const LEGACY_AMBIENT_REFERENCE = 0.6;
+/** Upper bound for a mapped legacy ambient (keeps night sides from washing out). */
+export declare const LEGACY_AMBIENT_MAX: number;
+export interface LegacyLightingResult extends Partial<StarLighting> {
+    /** Ambient intensity to use with the star lights (always set). */
+    ambient: number;
+}
+/**
+ * Map OLD saved lighting onto the star's — the single place this rule lives, so every app reads a
+ * legacy world the same way. Only the legacy keys go through here (`ambientIntensity`,
+ * `diffuseIntensity`, `lightColor`, `lightDirection`); saves made with star lighting use the new
+ * keys (`ambient`, `intensity`, `fill`, `tint`) and are read raw.
+ *
+ * - `diffuseIntensity` → `intensity` (key multiplier).
+ * - `lightColor` → `tint` (white → none).
+ * - `ambientIntensity` → `ambient = DEFAULT_AMBIENT × saved / 0.6` (0.6 was the old default), clamped
+ *   to [0, 3 × DEFAULT_AMBIENT]; missing → `DEFAULT_AMBIENT`.
+ * - `lightDirection` is dropped: the star's position decides.
+ */
+export declare function lightingFromLegacy(lighting: LegacyLighting | null | undefined): LegacyLightingResult;

package/dist/star/lighting.js

@@ -0,0 +1,115 @@
+// Star-as-scene-light: pure helpers (colour, intensities, legacy mapping). The lights themselves are
+// owned by StarManager; these stay pure so hosts and tests can use them without WebGL.
+export const DEFAULT_STAR_LIGHTING = Object.freeze({ intensity: 1, fill: 1, tint: null });
+/**
+ * Ambient intensity to pair with the star's key + fill (instead of the old white hemisphere +
+ * ambient at 1). Output is sRGB, which lifts shadows a lot (4% linear ≈ 22% on screen), so night
+ * sides need very little: with the default fill this keeps a hint of the night side (~5% linear)
+ * while the terminator reads clearly.
+ */
+export const DEFAULT_AMBIENT = 0.06;
+const SUN_TEFF_K = 5778;
+/**
+ * Key light colour: the stars' blackbody colours weighted by their emitted power (R² · T⁴), so a
+ * dim companion barely shifts the Sun but a close pair of equals blends. The distant companion is
+ * not part of `layout.stars` and never contributes. Brightest channel = 1. Writes into `out`.
+ */
+export function systemLightColor(layout, out = { r: 1, g: 1, b: 1 }) {
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    for (const s of layout.stars) {
+        const w = s.radius * s.radius * Math.pow(s.temperatureK / SUN_TEFF_K, 4);
+        r += s.color.r * w;
+        g += s.color.g * w;
+        b += s.color.b * w;
+    }
+    const m = Math.max(r, g, b);
+    if (!(m > 0)) {
+        out.r = out.g = out.b = 1;
+        return out;
+    }
+    out.r = r / m;
+    out.g = g / m;
+    out.b = b / m;
+    return out;
+}
+/**
+ * Key light intensity for a luminosity 0..1 (three r155+ physical units, no tone mapping): the Sun
+ * at 0.5 gives ≈ π, i.e. a white MeshStandard surface facing the star renders at its albedo.
+ */
+export function keyLightIntensity(luminosity, multiplier = 1) {
+    const l = Number.isFinite(luminosity) ? Math.min(1, Math.max(0, luminosity)) : 0.5;
+    const k = Number.isFinite(multiplier) ? Math.max(0, multiplier) : 1;
+    return k * Math.PI * (0.35 + 1.3 * l);
+}
+/** Fill (camera-side hemisphere) intensity for the author `fill` multiplier. */
+export function fillLightIntensity(fill) {
+    return (Number.isFinite(fill) ? Math.max(0, fill) : DEFAULT_STAR_LIGHTING.fill) * 0.3;
+}
+/** Parse a tint to RGB 0..1, or null for none / white / unparseable. */
+export function parseTint(tint) {
+    if (tint == null)
+        return null;
+    let rgb = null;
+    if (typeof tint === 'number' && Number.isFinite(tint)) {
+        rgb = { r: ((tint >> 16) & 255) / 255, g: ((tint >> 8) & 255) / 255, b: (tint & 255) / 255 };
+    }
+    else if (typeof tint === 'string') {
+        const m = /^#?([0-9a-f]{6}|[0-9a-f]{3})$/i.exec(tint.trim());
+        if (m) {
+            const hex = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
+            const n = parseInt(hex, 16);
+            rgb = { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+        }
+    }
+    else if (typeof tint === 'object' && [tint.r, tint.g, tint.b].every((v) => typeof v === 'number' && Number.isFinite(v))) {
+        rgb = { r: Math.min(1, Math.max(0, tint.r)), g: Math.min(1, Math.max(0, tint.g)), b: Math.min(1, Math.max(0, tint.b)) };
+    }
+    if (!rgb)
+        return null;
+    return rgb.r >= 0.999 && rgb.g >= 0.999 && rgb.b >= 0.999 ? null : rgb;
+}
+/** Validate a (partial) lighting patch against a base. Never throws. */
+export function normalizeStarLighting(raw, base = DEFAULT_STAR_LIGHTING) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const out = { ...base };
+    if (typeof src.intensity === 'number' && Number.isFinite(src.intensity))
+        out.intensity = Math.min(10, Math.max(0, src.intensity));
+    if (typeof src.fill === 'number' && Number.isFinite(src.fill))
+        out.fill = Math.min(5, Math.max(0, src.fill));
+    if ('tint' in src)
+        out.tint = parseTint(src.tint);
+    return out;
+}
+/** The ambient the old flat-lit look was tuned around (the host's former default). */
+export const LEGACY_AMBIENT_REFERENCE = 0.6;
+/** Upper bound for a mapped legacy ambient (keeps night sides from washing out). */
+export const LEGACY_AMBIENT_MAX = 3 * DEFAULT_AMBIENT;
+/**
+ * Map OLD saved lighting onto the star's — the single place this rule lives, so every app reads a
+ * legacy world the same way. Only the legacy keys go through here (`ambientIntensity`,
+ * `diffuseIntensity`, `lightColor`, `lightDirection`); saves made with star lighting use the new
+ * keys (`ambient`, `intensity`, `fill`, `tint`) and are read raw.
+ *
+ * - `diffuseIntensity` → `intensity` (key multiplier).
+ * - `lightColor` → `tint` (white → none).
+ * - `ambientIntensity` → `ambient = DEFAULT_AMBIENT × saved / 0.6` (0.6 was the old default), clamped
+ *   to [0, 3 × DEFAULT_AMBIENT]; missing → `DEFAULT_AMBIENT`.
+ * - `lightDirection` is dropped: the star's position decides.
+ */
+export function lightingFromLegacy(lighting) {
+    const out = { ambient: DEFAULT_AMBIENT };
+    if (!lighting || typeof lighting !== 'object')
+        return out;
+    const a = lighting.ambientIntensity;
+    if (typeof a === 'number' && Number.isFinite(a)) {
+        out.ambient = Math.min(LEGACY_AMBIENT_MAX, Math.max(0, (DEFAULT_AMBIENT * a) / LEGACY_AMBIENT_REFERENCE));
+    }
+    const d = lighting.diffuseIntensity;
+    if (typeof d === 'number' && Number.isFinite(d))
+        out.intensity = Math.min(10, Math.max(0, d));
+    if (lighting.lightColor != null)
+        out.tint = parseTint(lighting.lightColor);
+    return out;
+}

package/dist/star/params.d.ts

@@ -0,0 +1,79 @@
+/** How many stars the system shows. The audio Star is always one; companions are appearance only. */
+export type StarMultiplicity = 1 | 2 | 3;
+export interface StarParams {
+    /** Effective (surface) temperature in kelvin, ≈2400 (cool M dwarf) … 40000 (O star). Drives colour. */
+    temperatureK: number;
+    /** Radius of the primary in scene units (the same units as the host's planet and camera). */
+    radius: number;
+    /** 0..1 — corona intensity and extent. */
+    luminosity: number;
+    /** 0..1 — surface granulation, flicker and how often flares happen. */
+    activity: number;
+    /** 1 single, 2 binary (the planet is circumbinary), 3 trinary (a close pair plus a wide third). */
+    multiplicity: StarMultiplicity;
+    /** Centre distance of the close pair, in units of the two radii summed (≥1.2 so discs never merge). */
+    separation: number;
+    /** Deterministic seed for companion properties and orbital phases. */
+    seed: number | string;
+    /** Distance of the star system from the scene origin (the planet), scene units. */
+    distance: number;
+    /** Degrees around the vertical axis; 0 = straight behind the planet (−Z), positive = to the right (+X). */
+    azimuth: number;
+    /** Degrees above the horizon plane. */
+    elevation: number;
+    /** Close companion (binary/trinary pair) temperature, K. 0 = derived from the primary + seed. */
+    companionTemperatureK: number;
+    /** Close companion radius, scene units. 0 = derived from the primary + seed. */
+    companionRadius: number;
+    /** Show a distant companion: a small, dimmer star elsewhere in the sky (the planet orbits one star of a wide pair). */
+    distantCompanion: boolean;
+    /** Distant companion temperature, K. */
+    distantTemperatureK: number;
+    /** Distant companion radius, scene units (it sits at `distance`, like the host). */
+    distantRadius: number;
+    /** 0..1 — distant companion brightness (disc gain + corona). */
+    distantBrightness: number;
+    /** Distant companion direction, degrees (same convention as `azimuth`). null = from the seed. */
+    distantAzimuth: number | null;
+    /** Distant companion elevation, degrees. null = from the seed. */
+    distantElevation: number | null;
+    /** 0..1 — faint debris disc around the system (0 = none; no draw call). */
+    disc: number;
+}
+/** A Sun-like G star sitting behind and to the upper right of the planet. */
+export declare const DEFAULT_STAR_PARAMS: Readonly<StarParams>;
+/**
+ * Accepted ranges; values outside are clamped (azimuth wraps). Sized so the star reads as a
+ * background host star: at the minimum (and default) distance the largest radius spans ~10° from the
+ * planet, 220 stays inside a 500-unit skybox, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
+ * exact, non-colliding minimum — see `minStarDistance`).
+ */
+export declare const STAR_PARAM_RANGES: Readonly<{
+    readonly temperatureK: readonly [2000, 50000];
+    readonly radius: readonly [0.05, 3.5];
+    readonly luminosity: readonly [0, 1];
+    readonly activity: readonly [0, 1];
+    readonly separation: readonly [1.2, 6];
+    readonly distance: readonly [20, 220];
+    readonly elevation: readonly [-89, 89];
+    /** 0 = auto; any other value is at least 2000. */
+    readonly companionTemperatureK: readonly [0, 50000];
+    /** 0 = auto; any other value is at least 0.05. */
+    readonly companionRadius: readonly [0, 3.5];
+    readonly distantTemperatureK: readonly [2000, 50000];
+    readonly distantRadius: readonly [0.02, 1.4];
+    readonly distantBrightness: readonly [0, 1];
+    readonly distantElevation: readonly [-89, 89];
+    readonly disc: readonly [0, 1];
+}>;
+/** Wrap degrees into (−180, 180]. */
+export declare function wrapDegrees(deg: number): number;
+/**
+ * Validate + complete raw params (e.g. from a stored world description). Missing, non-finite or
+ * wrongly-typed fields fall back to `base` (default: `DEFAULT_STAR_PARAMS`); numbers are clamped
+ * to `STAR_PARAM_RANGES`; unknown fields are ignored. Never throws.
+ */
+export declare function normalizeStarParams(raw: unknown, base?: Readonly<StarParams>): StarParams;
+export type SpectralClass = 'O' | 'B' | 'A' | 'F' | 'G' | 'K' | 'M';
+/** Harvard spectral class for an effective temperature (main-sequence boundaries). */
+export declare function spectralClass(temperatureK: number): SpectralClass;