entangled-worlds-orbiters-shared 3.3.0 → 4.1.0

package/dist/loaders/cubeMapLoader.js

@@ -0,0 +1,291 @@
+import * as THREE from 'three';
+import { getPublicBase } from '../config/env.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+/** A skycube id (`'7'`, `'07_skycube'`, `'skybox-007'`, …) as its three-digit folder name; `'001'` when none. */
+export function normalizeSkycubeName(raw) {
+    if (!raw)
+        return '001';
+    const legacy = raw.match(/^(\d{1,2})_skycube(?:_low)?$/);
+    if (legacy)
+        return String(parseInt(legacy[1], 10)).padStart(3, '0');
+    const num = raw.match(/(\d{1,3})/);
+    if (num)
+        return String(parseInt(num[1], 10)).padStart(3, '0');
+    return '001';
+}
+// Standard face order for cube maps
+const FACE_ORDER = ['right', 'left', 'top', 'bottom', 'front', 'back'];
+// Build complete face URL sets for a given skycube ID (now returns relative paths)
+export function buildSkycubefaceKeys(skycubeId, extension = 'ktx2') {
+    const id = normalizeSkycubeName(skycubeId);
+    const base = `/default/skybox/${id}`;
+    return {
+        right: `${base}/right.${extension}`,
+        left: `${base}/left.${extension}`,
+        top: `${base}/top.${extension}`,
+        bottom: `${base}/bottom.${extension}`,
+        front: `${base}/front.${extension}`,
+        back: `${base}/back.${extension}`
+    };
+}
+// Heuristic low-performance detection
+function isLowPerformanceDevice() {
+    try {
+        const ua = navigator.userAgent.toLowerCase();
+        const isMobileUA = /mobi|android|iphone|ipad|ipod/.test(ua);
+        // `deviceMemory` is not in every browser, nor in the DOM types.
+        const mem = navigator.deviceMemory || 0; // GB
+        const cores = navigator.hardwareConcurrency || 0;
+        const dpr = window.devicePixelRatio || 1;
+        return isMobileUA || mem && mem <= 4 || cores && cores <= 4 || (dpr > 2 && cores <= 6);
+    }
+    catch {
+        return false;
+    }
+}
+// Validate face URLs object
+function validatefaceKeys(faceKeys) {
+    if (!faceKeys || typeof faceKeys !== 'object')
+        return false;
+    const keys = faceKeys;
+    return FACE_ORDER.every(face => keys[face] && typeof keys[face] === 'string');
+}
+// Detect extension type from face URLs
+function detectExtension(faceKeys) {
+    const url = faceKeys.right || '';
+    if (url.toLowerCase().includes('.ktx2'))
+        return 'ktx2';
+    if (url.toLowerCase().match(/\.(jpg|jpeg|png)$/))
+        return 'jpg';
+    return 'ktx2'; // default assumption
+}
+// How many faces may be in flight at once. Not six: the KTX2 worker pool three.js gives us holds
+// four transcoder workers, each carrying its own copy of the basis wasm, and that same pool also
+// serves body textures and GLBs. Asking for all six together spawned every worker and queued the
+// other loaders behind the whole sky; measured on cold fetches it was no faster than three.
+const FACES_IN_FLIGHT = 3;
+// Load KTX2 faces and create skybox mesh
+async function loadFacesKTX2(faceKeys, renderer) {
+    const loader = getKTX2LoaderForRenderer(renderer);
+    const anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+    const loadFace = async (face) => {
+        const tex = await loader.loadAsync(faceKeys[face]);
+        tex.flipY = false;
+        tex.wrapS = THREE.ClampToEdgeWrapping;
+        tex.wrapT = THREE.ClampToEdgeWrapping;
+        tex.anisotropy = anisotropy;
+        return { face, tex };
+    };
+    // Faces overlap instead of chaining. Awaiting each one in turn made every face wait on the
+    // previous face's download *and* its transcode, so the sky arrived six round trips deep.
+    const settled = [];
+    for (let i = 0; i < FACE_ORDER.length; i += FACES_IN_FLIGHT) {
+        const wave = FACE_ORDER.slice(i, i + FACES_IN_FLIGHT).map(face => loadFace(face));
+        settled.push(...await Promise.allSettled(wave));
+    }
+    // allSettled, not all: a bare Promise.all rejects on the first failure and leaks the faces that
+    // land after it. Settle every face first, then dispose everything that arrived before rethrowing.
+    const loaded = [];
+    let failure = null;
+    for (const result of settled) {
+        if (result.status === 'fulfilled')
+            loaded.push(result.value);
+        else if (!failure)
+            failure = result.reason;
+    }
+    if (failure) {
+        // Dispose already loaded textures on failure
+        loaded.forEach(f => f.tex.dispose?.());
+        throw failure;
+    }
+    const size = 500;
+    const box = new THREE.BoxGeometry(size, size, size);
+    // Map faces to geometry indices (corrected for orientation)
+    const orderMap = { right: 0, left: 1, top: 3, bottom: 2, front: 4, back: 5 };
+    const mats = new Array(6).fill(null);
+    loaded.forEach(({ face, tex }) => {
+        mats[orderMap[face]] = new THREE.MeshBasicMaterial({
+            map: tex,
+            side: THREE.BackSide,
+            depthWrite: false
+        });
+    });
+    // Fill any missing materials with black
+    for (let i = 0; i < 6; i++) {
+        if (!mats[i]) {
+            mats[i] = new THREE.MeshBasicMaterial({
+                color: 0x000000,
+                side: THREE.BackSide,
+                depthWrite: false
+            });
+        }
+    }
+    // Every slot is filled by now (a face's material or black).
+    const mesh = new THREE.Mesh(box, mats);
+    mesh.name = 'SkyboxKTX2Mesh';
+    return { __ewType: 'skybox-mesh', mesh };
+}
+// Load JPG/PNG faces and create CubeTexture
+function loadFacesJPG(faceKeys) {
+    const urls = FACE_ORDER.map(face => faceKeys[face]);
+    return new Promise((resolve, reject) => {
+        new THREE.CubeTextureLoader().load(urls, tex => {
+            tex.magFilter = THREE.LinearFilter;
+            tex.minFilter = THREE.LinearMipMapLinearFilter;
+            tex.anisotropy = 8;
+            resolve(tex);
+        }, undefined, err => reject(err));
+    });
+}
+// Resolve relative paths to full URLs
+function resolveUrls(faceKeys) {
+    const PUBLIC_BASE = getPublicBase();
+    // Every face is set below.
+    const resolved = {};
+    FACE_ORDER.forEach(face => {
+        const url = faceKeys[face];
+        if (url && url.startsWith('/')) {
+            resolved[face] = `${PUBLIC_BASE}${url}`;
+        }
+        else {
+            resolved[face] = url; // already absolute or invalid
+        }
+    });
+    return resolved;
+}
+/**
+ * Main loader function - always uses explicit face URLs.
+ * `renderer` binds the KTX2 transcoder to the right WebGL context. REQUIRED (3.0) when the KTX2
+ * path is taken — the old `window.__EW_RENDERER` fallback is gone; thread the owning view's
+ * renderer. (The PNG/JPG path is renderer-agnostic, so its absence only bites on KTX2.)
+ *
+ * - `faceKeys`: explicit face URLs; when absent they are built from `skycubeName`.
+ * - `skycubeName`: skybox id (e.g. `'001'`), used when `faceKeys` is absent.
+ * - `preferKTX2` (true).
+ * - `forceLow`: force (or forbid) the low-resolution faces; omitted = detect the device.
+ *
+ * Resolves to what `setBackground` takes.
+ */
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer, } = {}) {
+    // If no face URLs provided, build them from skycube name
+    if (!faceKeys && skycubeName) {
+        const low = typeof forceLow === 'boolean' ? forceLow : isLowPerformanceDevice();
+        const extension = preferKTX2 ? 'ktx2' : 'jpg';
+        const id = normalizeSkycubeName(skycubeName);
+        const suffix = low ? '_low' : '';
+        const relativePath = `/default/skybox/${id}${suffix}`;
+        faceKeys = {
+            right: `${relativePath}/right.${extension}`,
+            left: `${relativePath}/left.${extension}`,
+            top: `${relativePath}/top.${extension}`,
+            bottom: `${relativePath}/bottom.${extension}`,
+            front: `${relativePath}/front.${extension}`,
+            back: `${relativePath}/back.${extension}`
+        };
+    }
+    if (!validatefaceKeys(faceKeys)) {
+        throw new Error('Invalid face URLs provided');
+    }
+    // Resolve relative paths to full URLs
+    const resolvedUrls = resolveUrls(faceKeys);
+    const extension = detectExtension(resolvedUrls);
+    // Try KTX2 first if preferred and supported
+    if (preferKTX2 && extension === 'ktx2' && renderer) {
+        try {
+            return await loadFacesKTX2(resolvedUrls, renderer);
+        }
+        catch (e) {
+            console.warn('[CubeMapLoader] KTX2 load failed, trying PNG fallback:', e);
+            // Fall through to PNG attempt
+        }
+    }
+    // Try PNG fallback (convert URLs if needed)
+    // Every face is set below.
+    const pngUrls = {};
+    FACE_ORDER.forEach(face => {
+        pngUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.png');
+    });
+    try {
+        return await loadFacesJPG(pngUrls);
+    }
+    catch (e) {
+        console.error('[CubeMapLoader] All loading attempts failed:', e);
+        throw new Error('Failed to load cube map with any format');
+    }
+}
+// Dispose helpers to ensure clean swaps
+function disposeSkyboxMesh(mesh) {
+    try {
+        // The skybox mesh's materials are the MeshBasicMaterials `loadFacesKTX2` made.
+        const material = mesh.material;
+        const mats = Array.isArray(material) ? material : [material];
+        mats.forEach(mat => {
+            if (!mat)
+                return;
+            if (mat.map && mat.map.dispose)
+                mat.map.dispose();
+            if (mat.dispose)
+                mat.dispose();
+        });
+        if (mesh.geometry && mesh.geometry.dispose)
+            mesh.geometry.dispose();
+    }
+    catch (e) {
+        console.warn('[CubeMapLoader] Disposal error:', e);
+    }
+}
+/**
+ * Show a loaded skybox as the scene's background. A previous skybox mesh or cube-texture background is
+ * disposed (a plain-texture background is not). Takes what `loadCubeMap` resolved to (or any texture);
+ * anything else, `null` included, clears it.
+ *
+ */
+export function setBackground(scene, resource) {
+    const sky = scene;
+    // Read as whatever it may be: a skybox wrapper, a texture, or anything else (which clears).
+    const res = resource;
+    // Clean up previous skybox mesh
+    if (sky.__EW_SKYBOX_MESH && sky.__EW_SKYBOX_MESH.parent === scene) {
+        const oldMesh = sky.__EW_SKYBOX_MESH;
+        scene.remove(oldMesh);
+        disposeSkyboxMesh(oldMesh);
+        sky.__EW_SKYBOX_MESH = null;
+    }
+    // Dispose previous CubeTexture background
+    // A Color or a Texture; `dispose` is only called once it is a CubeTexture.
+    const background = scene.background;
+    if (background && background.isCubeTexture) {
+        try {
+            background.dispose();
+        }
+        catch (e) {
+            console.warn('[CubeMapLoader] Background disposal error:', e);
+        }
+    }
+    // Set new background
+    if (res?.__ewType === 'skybox-mesh') {
+        scene.background = null;
+        sky.__EW_SKYBOX_MESH = res.mesh;
+        scene.add(res.mesh);
+    }
+    else if (res?.isCubeTexture || res?.isTexture) {
+        scene.background = resource;
+    }
+    else {
+        scene.background = null;
+    }
+    // Dispatch update event for reactive systems
+    try {
+        window.dispatchEvent(new CustomEvent('ew:skycube-updated', {
+            detail: { type: res?.__ewType || 'texture' }
+        }));
+    }
+    catch (e) {
+        console.warn('[CubeMapLoader] Event dispatch error:', e);
+    }
+}
+export async function initSpaceScene(scene, { renderer } = {}) {
+    const faceKeys = buildSkycubefaceKeys('001');
+    const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });
+    setBackground(scene, cube);
+}

package/dist/loaders/glbLoader.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from 'three';
+import { type MaterialFlags } from '../utils/materials.js';
+/**
+ * `renderer` is REQUIRED at runtime (throws without one).
+ * - `retries` (3): load attempts before giving up.
+ * - `signal`: rejects the load on abort.
+ * - `applyFlags`: material flags (`forceOpaque`, `wireframe`) applied to every mesh.
+ * - `withCredentials` (false).
+ * - `emissiveIntensity` (1): self-glow of textured materials (their map doubles as the emissive
+ *   map). 1 keeps the old flat-lit look; with a directional star light pass ≈0.1–0.15 so the night
+ *   side reads.
+ * - `renderer`: REQUIRED (3.0): the renderer this GLB's textures bind to. A page with several
+ *   renderers has no single correct global, so the old `window.__EW_RENDERER` fallback is gone —
+ *   thread the owning view's renderer.
+ */
+export declare function loadGLB(url: string, { retries, signal, onProgress, applyFlags, withCredentials, renderer, emissiveIntensity, }?: {
+    retries?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((event: ProgressEvent) => void) | undefined;
+    applyFlags?: MaterialFlags | undefined;
+    withCredentials?: boolean | undefined;
+    emissiveIntensity?: number | undefined;
+    renderer: THREE.WebGLRenderer;
+}): Promise<THREE.Group | undefined>;

package/dist/loaders/glbLoader.js

@@ -0,0 +1,85 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+import { disposeObject3D } from '../utils/dispose.js';
+/**
+ * `renderer` is REQUIRED at runtime (throws without one).
+ * - `retries` (3): load attempts before giving up.
+ * - `signal`: rejects the load on abort.
+ * - `applyFlags`: material flags (`forceOpaque`, `wireframe`) applied to every mesh.
+ * - `withCredentials` (false).
+ * - `emissiveIntensity` (1): self-glow of textured materials (their map doubles as the emissive
+ *   map). 1 keeps the old flat-lit look; with a directional star light pass ≈0.1–0.15 so the night
+ *   side reads.
+ * - `renderer`: REQUIRED (3.0): the renderer this GLB's textures bind to. A page with several
+ *   renderers has no single correct global, so the old `window.__EW_RENDERER` fallback is gone —
+ *   thread the owning view's renderer.
+ */
+export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false, renderer, emissiveIntensity = 1.0, } = {}) {
+    if (!renderer)
+        throw new Error('[glb] loadGLB requires the owning renderer (KTX2 textures bind per WebGL context).');
+    let attempt = 0;
+    while (attempt < retries) {
+        // An abort during the pause between attempts must stop here: a listener added to an
+        // already-aborted signal never fires, so the next attempt would load and resolve anyway.
+        if (signal?.aborted)
+            throw new Error('aborted');
+        try {
+            const loader = new GLTFLoader()
+                .setCrossOrigin(withCredentials ? 'use-credentials' : 'anonymous')
+                .setWithCredentials(Boolean(withCredentials))
+                .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
+            const root = await new Promise((resolve, reject) => {
+                const onAbort = () => reject(new Error('aborted'));
+                signal?.addEventListener('abort', onAbort, { once: true });
+                loader.load(url, (gltf) => {
+                    signal?.removeEventListener('abort', onAbort);
+                    // Aborted while loading: the promise has already rejected and nobody will own this
+                    // scene, so free its geometry, materials and textures now instead of leaking them.
+                    if (signal?.aborted) {
+                        disposeObject3D(gltf.scene);
+                        return;
+                    }
+                    resolve(gltf.scene);
+                }, onProgress, (err) => { signal?.removeEventListener('abort', onAbort); reject(err); });
+            });
+            // Post-process materials
+            root.traverse((object) => {
+                // The meshes a GLB loads carry one material each, and `ensureStandardMaterial` just made it a
+                // MeshStandardMaterial, which is what the lines below write to.
+                const child = object;
+                if (child.isMesh && child.material) {
+                    ensureStandardMaterial(child);
+                    if (applyFlags)
+                        applyFlagsToMaterial(child.material, applyFlags);
+                    // Force texture updates for KTX2
+                    if (child.material.map) {
+                        child.material.map.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+                        child.material.map.needsUpdate = true;
+                        // Ensure proper color space for compressed textures
+                        child.material.map.colorSpace = THREE.SRGBColorSpace;
+                        // Ensure material color doesn't block the texture
+                        child.material.color.setHex(0xffffff);
+                        // Add strong emissive to ensure visibility
+                        child.material.emissive.setHex(0x888888);
+                        child.material.emissiveMap = child.material.map;
+                        child.material.emissiveIntensity = Number.isFinite(emissiveIntensity) ? Math.max(0, emissiveIntensity) : 1.0;
+                    }
+                    child.material.needsUpdate = true;
+                    child.castShadow = false;
+                    child.receiveShadow = false;
+                }
+            });
+            root.position.set(0, 0, 0);
+            return root;
+        }
+        catch (e) {
+            console.warn(`GLB load attempt ${attempt + 1} failed:`, e.message);
+            if (signal?.aborted || attempt >= retries - 1)
+                throw e;
+            attempt++;
+            await new Promise(resolve => setTimeout(resolve, 500)); // Brief delay between retries
+        }
+    }
+}

package/dist/loaders/index.d.ts

@@ -0,0 +1,5 @@
+export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys } from './cubeMapLoader.js';
+export { loadGLB } from './glbLoader.js';
+export { loadTexture } from './bodyTextureLoader.js';
+export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
+export type { SkyboxResource } from './cubeMapLoader.js';

package/{src → dist}/loaders/index.js

@@ -3,5 +3,3 @@ export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys
 export { loadGLB } from './glbLoader.js';
 export { loadTexture } from './bodyTextureLoader.js';
 export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
-
-/** @typedef {import('./cubeMapLoader.js').SkyboxResource} SkyboxResource */

package/dist/{types/loaders → loaders}/ktx2.d.ts

@@ -1,16 +1,14 @@
+import type * as THREE from 'three';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 /**
  * The KTX2Loader bound to `renderer` — REQUIRED (3.0). The old `window.__EW_RENDERER` fallback let
  * call sites compile while silently binding the transcoder to whichever renderer a page published
  * last; on any multi-view page that meant untextured worlds. Every caller now threads its own
  * renderer, so a missing one is a caller bug and fails loudly here rather than as a dark planet.
- * @param {import('three').WebGLRenderer} renderer
- * @returns {KTX2Loader}
  */
-export function getKTX2LoaderForRenderer(renderer: import("three").WebGLRenderer): KTX2Loader;
+export declare function getKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): KTX2Loader;
 /**
  * Dispose and forget the KTX2Loader for a renderer — call on that renderer's / scene's teardown so the
  * transcoder workers are terminated (avoids leaking worker threads + GPU memory across view churn).
- * @param {import('three').WebGLRenderer} renderer
  */
-export function disposeKTX2LoaderForRenderer(renderer: import("three").WebGLRenderer): void;
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+export declare function disposeKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): void;

package/dist/loaders/ktx2.js

@@ -0,0 +1,48 @@
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/**
+ * One KTX2Loader PER RENDERER.
+ *
+ * `KTX2Loader.detectSupport(renderer)` binds the loader's Basis transcoder worker pool to ONE WebGL
+ * context. A single shared loader therefore only decodes textures for the FIRST renderer it saw —
+ * every other view's planets/skyboxes silently fail and render untextured (dark). That breaks any
+ * multi-view page: N orbiters in one realm, or N Entangled World planets shown together.
+ *
+ * Keying the loader by renderer gives each view its own correctly-bound loader. Single-renderer apps
+ * (a single orbiter, today's Entangled World) get exactly ONE entry, so behaviour is byte-identical.
+ * (Was: a single `window.__EW_KTX2_LOADER` global shared by bodyTexture/glb/cubeMap loaders.)
+ */
+const loadersByRenderer = new WeakMap();
+function makeLoader(renderer) {
+    return new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+}
+/**
+ * The KTX2Loader bound to `renderer` — REQUIRED (3.0). The old `window.__EW_RENDERER` fallback let
+ * call sites compile while silently binding the transcoder to whichever renderer a page published
+ * last; on any multi-view page that meant untextured worlds. Every caller now threads its own
+ * renderer, so a missing one is a caller bug and fails loudly here rather than as a dark planet.
+ */
+export function getKTX2LoaderForRenderer(renderer) {
+    if (!renderer) {
+        throw new Error('[ktx2] getKTX2LoaderForRenderer requires the owning renderer — thread it from the view that renders this texture.');
+    }
+    let loader = loadersByRenderer.get(renderer);
+    if (!loader) {
+        loader = makeLoader(renderer);
+        loadersByRenderer.set(renderer, loader);
+    }
+    return loader;
+}
+/**
+ * Dispose and forget the KTX2Loader for a renderer — call on that renderer's / scene's teardown so the
+ * transcoder workers are terminated (avoids leaking worker threads + GPU memory across view churn).
+ */
+export function disposeKTX2LoaderForRenderer(renderer) {
+    const loader = renderer && loadersByRenderer.get(renderer);
+    if (loader) {
+        try {
+            loader.dispose?.();
+        }
+        catch { /* already gone */ }
+        loadersByRenderer.delete(renderer);
+    }
+}

package/dist/moons/index.d.ts

@@ -0,0 +1,3 @@
+export { MoonsManager } from './moonsManager.js';
+export type { MoonAmountOptions } from './moonsManager.js';
+export { generateMoons, DEFAULT_MOON_TEX_KTX2, DEFAULT_MOON_TEX_PNG, MOON_BASE_RADIUS, MOON_SCALE_MIN, MOON_SCALE_SPAN, MOON_MAX_RADIUS, MOON_ORBIT_SCATTER, MOON_HEIGHT_SCATTER, } from './moonsGeneration.js';

package/dist/moons/index.js

@@ -0,0 +1,3 @@
+// Moons system exports
+export { MoonsManager } from './moonsManager.js';
+export { generateMoons, DEFAULT_MOON_TEX_KTX2, DEFAULT_MOON_TEX_PNG, MOON_BASE_RADIUS, MOON_SCALE_MIN, MOON_SCALE_SPAN, MOON_MAX_RADIUS, MOON_ORBIT_SCATTER, MOON_HEIGHT_SCATTER, } from './moonsGeneration.js';

package/dist/moons/moonsGeneration.d.ts

@@ -0,0 +1,64 @@
+import * as THREE from 'three';
+export declare const DEFAULT_MOON_TEX_KTX2: string;
+export declare const DEFAULT_MOON_TEX_PNG: string;
+/** Radius of the shared moon sphere before per-moon scale. */
+export declare const MOON_BASE_RADIUS = 0.1;
+/** Per-moon scale range: MIN + random * SPAN. */
+export declare const MOON_SCALE_MIN = 0.07;
+export declare const MOON_SCALE_SPAN = 0.15;
+/** Largest moon radius in scene units (base radius × largest scale). */
+export declare const MOON_MAX_RADIUS: number;
+/** Each moon's orbit radius varies by ± half of this around the requested orbit. */
+export declare const MOON_ORBIT_SCATTER = 0.22;
+/** Each moon sits up to ± half of this above or below the orbit plane. */
+export declare const MOON_HEIGHT_SCATTER = 0.12;
+/**
+ * - `count` (0): 0 or less resolves to null. `orbitRadius` 1.5.
+ * - `textureFallback`: used instead of `texturePNG` when set.
+ * - `seed`: deterministic positions when set.
+ * - `textureKey`: replaces `textureKTX2` when set (the fallback stays `textureFallback` or
+ *   `texturePNG`).
+ * - `emissiveLift`: night-side self-glow 0..1; omitted = `emissiveIntensity`.
+ * - `renderer`: binds the KTX2 moon texture.
+ * - Defaults: `moonColor` '#ffffff', `brightness` 1.15, `emissiveColor` 0x333333,
+ *   `emissiveIntensity` 0.18, `roughness` 0.85, `metalness` 0, `debug` true, `smooth` true,
+ *   `geometryWidthSegments` 16, `geometryHeightSegments` 12, `useBumpFromColor` true, `bumpScale`
+ *   0.15, `debugShowUvGrid` false, `debugShowReferenceMoon` false, `referenceMoonScale` 0.25,
+ *   `useEmissiveMapFromTexture` true.
+ */
+export declare function generateMoons({ count, orbitRadius, textureKTX2, texturePNG, textureFallback, useTexture, seed, // if provided, ensures consistent moon positions
+textureKey, // if provided, overrides textureKTX2/texturePNG
+moonColor, // NEW: moon color
+brightness, emissiveColor, emissiveIntensity, emissiveLift, roughness, metalness, debug, smooth, // set false to keep flatShading
+geometryWidthSegments, // Reduced from 24 for better performance
+geometryHeightSegments, // Reduced from 24 for better performance
+useBumpFromColor, bumpScale, debugShowUvGrid, debugShowReferenceMoon, // changed from true to prevent extra moon
+referenceMoonScale, useEmissiveMapFromTexture, // reuse color texture as emissiveMap to lift dark sides
+renderer, }?: {
+    count?: number | undefined;
+    orbitRadius?: number | undefined;
+    textureKTX2?: string | undefined;
+    texturePNG?: string | undefined;
+    textureFallback?: string | null | undefined;
+    useTexture?: boolean | undefined;
+    seed?: string | number | null | undefined;
+    textureKey?: string | null | undefined;
+    moonColor?: string | undefined;
+    brightness?: number | undefined;
+    emissiveColor?: number | undefined;
+    emissiveIntensity?: number | undefined;
+    emissiveLift?: number | undefined;
+    roughness?: number | undefined;
+    metalness?: number | undefined;
+    debug?: boolean | undefined;
+    smooth?: boolean | undefined;
+    geometryWidthSegments?: number | undefined;
+    geometryHeightSegments?: number | undefined;
+    useBumpFromColor?: boolean | undefined;
+    bumpScale?: number | undefined;
+    debugShowUvGrid?: boolean | undefined;
+    debugShowReferenceMoon?: boolean | undefined;
+    referenceMoonScale?: number | undefined;
+    useEmissiveMapFromTexture?: boolean | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Group<THREE.Object3DEventMap> | null>;