entangled-worlds-orbiters-shared 3.3.0 → 4.1.0

package/dist/config/textureConfig.js

@@ -0,0 +1,318 @@
+/**
+ * Texture Configuration Loader
+ * Loads texture definitions from remote endpoint or uses passed config
+ */
+import { resolvePublicUrl } from './env.js';
+/** The catalogue a public function was handed, or the loaded one. */
+async function resolveConfig(config) {
+    return config || (await loadTextureConfig());
+}
+function buildTextureUrl(baseUrl, categoryPath, value) {
+    if (!value)
+        return null;
+    if (/^https?:\/\//i.test(value))
+        return value;
+    if (value.startsWith('/'))
+        return resolvePublicUrl(value);
+    const prefix = `${baseUrl || ''}${categoryPath || ''}`;
+    return resolvePublicUrl(`${prefix}/${value}`);
+}
+function findTextureItem(textureConfig, category, textureUrl) {
+    if (!textureUrl || !textureConfig)
+        return null;
+    const categoryConfig = textureConfig.textures?.[category];
+    if (!categoryConfig || !categoryConfig.items)
+        return null;
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    for (const item of categoryConfig.items) {
+        const resolved = buildTextureUrl(baseUrl, categoryPath, item.filename || item.id);
+        if (!resolved)
+            continue;
+        if (resolved === textureUrl) {
+            return { item, baseUrl, categoryPath };
+        }
+    }
+    return null;
+}
+let cachedConfig = null;
+let configPromise = null;
+let lastConfigUrl = null;
+/**
+ * Load texture configuration from remote endpoint or use passed config
+ * @param {string} configUrl - Override config URL
+ * @param {boolean} useCache - Whether to use cached config if available
+ * @returns {Promise<TextureConfig>} Texture configuration object
+ */
+export async function loadTextureConfig(configUrl, useCache = true) {
+    if (useCache && cachedConfig) {
+        return cachedConfig;
+    }
+    if (configPromise) {
+        return configPromise;
+    }
+    if (configUrl) {
+        lastConfigUrl = configUrl;
+    }
+    const targetUrl = configUrl || lastConfigUrl;
+    configPromise = (async () => {
+        try {
+            if (!targetUrl) {
+                throw new Error('No texture config URL provided');
+            }
+            const response = await fetch(targetUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const config = (await response.json());
+            // Validate configuration structure
+            if (!config.textures || typeof config.textures !== 'object') {
+                throw new Error('Invalid configuration: missing textures object');
+            }
+            cachedConfig = config;
+            return config;
+        }
+        catch (error) {
+            console.error('[TextureConfig] Failed to load config:', error);
+            // Return minimal fallback configuration when loading fails
+            console.warn('[TextureConfig] Using hardcoded fallback config');
+            const fallback = getHardcodedFallback();
+            cachedConfig = fallback;
+            return fallback;
+        }
+        finally {
+            configPromise = null;
+        }
+    })();
+    return configPromise;
+}
+/**
+ * Get the full choice records for a category (clouds, moons, etc.) — label, texture URL, and the
+ * picture to show for it. The single resolution point for a category's items; `getTextureOptions`
+ * is the flat `{ label: url }` projection of this.
+ * @param {string} category - Texture category (clouds, moons)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
+ */
+export async function getTextureChoices(category, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig) {
+        console.warn(`[TextureConfig] Category '${category}' not found`);
+        return [];
+    }
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    return (categoryConfig.items || []).flatMap((item) => {
+        const url = buildTextureUrl(baseUrl, categoryPath, item.filename || item.id);
+        if (!url)
+            return [];
+        return [{
+                id: item.id,
+                label: item.label || item.id,
+                url,
+                still: item.still ? buildTextureUrl(baseUrl, categoryPath, item.still) : null,
+            }];
+    });
+}
+/**
+ * Get texture options for a specific category (clouds, moons, etc.)
+ * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
+ */
+export async function getTextureOptions(category, config) {
+    const choices = await getTextureChoices(category, config);
+    return Object.fromEntries(choices.map(c => [c.label, c.url]));
+}
+/**
+ * Get default texture for a category
+ * @param {string} category - Texture category
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Default texture path, or null when the category has no texture
+ */
+export async function getDefaultTexture(category, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig) {
+        return null;
+    }
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    const defaultFilename = categoryConfig.defaultTexture;
+    if (defaultFilename) {
+        return resolvePublicUrl(`${baseUrl}${categoryPath}/${defaultFilename}`);
+    }
+    // Fallback to first item
+    if (categoryConfig.items && categoryConfig.items.length > 0) {
+        const firstItem = categoryConfig.items[0];
+        return resolvePublicUrl(`${baseUrl}${categoryPath}/${firstItem.filename || firstItem.id}`);
+    }
+    return null;
+}
+/**
+ * Return the configured fallback URL for a given texture if defined.
+ * @param {string} category - Texture category (clouds, moons, etc.)
+ * @param {string} textureUrl - Resolved texture URL
+ * @param {TextureConfig|null} config - Optional texture config override
+ * @returns {string|null} Resolved fallback texture URL or null
+ */
+export function getTextureFallbackUrl(category, textureUrl, config = null) {
+    const textureConfig = config || cachedConfig;
+    if (!textureConfig)
+        return null;
+    const found = findTextureItem(textureConfig, category, textureUrl);
+    if (!found || !found.item?.fallback)
+        return null;
+    return buildTextureUrl(found.baseUrl, found.categoryPath, found.item.fallback);
+}
+/**
+ * Get texture by ID within a category
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem|null>} Texture definition object
+ */
+export async function getTextureById(category, textureId, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig || !categoryConfig.items) {
+        return null;
+    }
+    return categoryConfig.items.find(item => item.id === textureId) || null;
+}
+/**
+ * Get full URL for a texture
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export async function getTextureUrl(category, textureId, config) {
+    const texture = await getTextureById(category, textureId, config);
+    if (!texture)
+        return null;
+    const textureConfig = await resolveConfig(config);
+    // `getTextureById` just found the item in this category, so it is there (unless the catalogue
+    // was reloaded in between, which throws here, as it always did).
+    const categoryConfig = textureConfig.textures[category];
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    return resolvePublicUrl(`${baseUrl}${categoryPath}/${texture.filename || texture.id}`);
+}
+/**
+ * Search textures by tags
+ * @param {string} category - Texture category
+ * @param {string[]} tags - Tags to search for
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem[]>} Array of matching texture definitions
+ */
+export async function searchTexturesByTags(category, tags, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig || !categoryConfig.items) {
+        return [];
+    }
+    return categoryConfig.items.filter(item => item.tags && tags.some(tag => item.tags.includes(tag)));
+}
+/**
+ * Get skybox options formatted for GUI dropdowns
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: id }`
+ */
+export async function getSkyboxOptions(config) {
+    const textureConfig = await resolveConfig(config);
+    const skyboxConfig = textureConfig.textures.skyboxes;
+    if (!skyboxConfig) {
+        console.warn('[TextureConfig] Skyboxes category not found');
+        return {};
+    }
+    const options = {};
+    // Reads `items` unguarded, unlike the other readers: a skyboxes category without items throws here.
+    skyboxConfig.items.forEach(item => {
+        const label = item.label || item.id;
+        const id = item.id;
+        options[label] = id;
+    });
+    return options;
+}
+/**
+ * Get default skybox ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export async function getDefaultSkybox(config) {
+    const textureConfig = await resolveConfig(config);
+    const skyboxConfig = textureConfig.textures.skyboxes;
+    if (!skyboxConfig) {
+        return '001'; // fallback
+    }
+    return skyboxConfig.defaultSkybox || '001';
+}
+/**
+ * Hardcoded fallback configuration (minimal)
+ * Used when remote config loading fails
+ */
+function getHardcodedFallback() {
+    return {
+        version: "1.0-fallback",
+        lastUpdated: new Date().toISOString(),
+        baseUrl: "/default",
+        textures: {
+            clouds: {
+                category: "atmospheric",
+                basePath: "/clouds",
+                defaultTexture: "04-clouds.ktx2",
+                items: [
+                    { id: "clouds-1", filename: "04-clouds.ktx2", label: "Clouds", tags: ["natural"] },
+                    { id: "entangled-1", filename: "06-entangled.ktx2", label: "Entangled", tags: ["quantum"] }
+                ]
+            },
+            moons: {
+                category: "celestial",
+                basePath: "/textures/moons",
+                defaultTexture: "moon-equirectangular.ktx2",
+                items: [
+                    { id: "default-moon", filename: "moon-equirectangular.ktx2", label: "Default Moon", tags: ["lunar"] }
+                ]
+            },
+            skyboxes: {
+                category: "environment",
+                basePath: "/skybox",
+                defaultSkybox: "001",
+                items: [
+                    { id: "001", label: "Deep Space", tags: ["space"] }
+                ]
+            }
+        }
+    };
+}
+/**
+ * Reload configuration (force refresh)
+ * @param {string} configUrl - Override config URL
+ * @returns {Promise<TextureConfig>} Fresh configuration object
+ */
+export async function reloadTextureConfig(configUrl) {
+    cachedConfig = null;
+    configPromise = null;
+    return loadTextureConfig(configUrl || lastConfigUrl || undefined, false);
+}
+/**
+ * Get configuration metadata
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureConfigMetadata>} Configuration metadata
+ */
+export async function getConfigMetadata(config) {
+    const textureConfig = await resolveConfig(config);
+    return {
+        version: textureConfig.version,
+        lastUpdated: textureConfig.lastUpdated,
+        categories: Object.keys(textureConfig.textures),
+        totalTextures: Object.values(textureConfig.textures).reduce(
+        // Only listed categories are values; a missing one is a key that is not there.
+        (sum, cat) => {
+            const items = cat.items;
+            return sum + (items ? items.length : 0);
+        }, 0)
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,2 @@
+export { ensureDefaultLights, updateDefaultLights, setHemisphereEnabled } from './lights.js';
+export { getLightFresnel } from './lightFresnel.js';

package/dist/core/index.js

@@ -0,0 +1,3 @@
+// Core rendering exports
+export { ensureDefaultLights, updateDefaultLights, setHemisphereEnabled } from './lights.js';
+export { getLightFresnel } from './lightFresnel.js';

package/dist/core/lightFresnel.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from "three";
+declare function getLightFresnel({ rimHex, facingHex }?: {
+    rimHex?: number;
+    facingHex?: number;
+}): THREE.ShaderMaterial;
+export { getLightFresnel };

package/dist/core/lightFresnel.js

@@ -0,0 +1,63 @@
+import * as THREE from "three";
+function getLightFresnel({ rimHex = 0x0088ff, facingHex = 0x000000 } = {}) {
+    const uniforms = {
+        color1: { value: new THREE.Color(rimHex) },
+        color2: { value: new THREE.Color(facingHex) },
+        fresnelBias: { value: 0.1 },
+        fresnelScale: { value: 1.0 },
+        fresnelPower: { value: 4.0 },
+    };
+    const vs = `
+  uniform float fresnelBias;
+  uniform float fresnelScale;
+  uniform float fresnelPower;
+  
+  varying float vReflectionFactor;
+  
+  void main() {
+    vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+    vec4 worldPosition = modelMatrix * vec4( position, 1.0 );
+  
+    // Transform normal to world space
+    vec3 worldNormal = normalize( mat3( modelMatrix[0].xyz, modelMatrix[1].xyz, modelMatrix[2].xyz ) * normal );
+  
+    // Proper view direction (from surface point towards camera)
+    vec3 viewDir = normalize( cameraPosition - worldPosition.xyz );
+
+    // Classic rim: stronger at grazing angles
+    float ndotv = max( dot( worldNormal, viewDir ), 0.0 );
+    vReflectionFactor = fresnelBias + fresnelScale * pow( 1.0 - ndotv, fresnelPower );
+  
+    gl_Position = projectionMatrix * mvPosition;
+  }
+  `;
+    const fs = `
+  uniform vec3 color1;
+  uniform vec3 color2;
+  
+  varying float vReflectionFactor;
+  
+  void main() {
+    float f = clamp( vReflectionFactor, 0.0, 1.0 );
+    gl_FragColor = vec4(mix(color2, color1, vec3(f)), f);
+  }
+  `;
+    const lightFresnel = new THREE.ShaderMaterial({
+        uniforms: uniforms,
+        vertexShader: vs,
+        fragmentShader: fs,
+        transparent: true,
+        blending: THREE.CustomBlending,
+        blendSrc: THREE.OneFactor,
+        blendDst: THREE.OneFactor,
+        blendEquation: THREE.AddEquation,
+        depthWrite: false,
+        depthTest: true,
+        depthFunc: THREE.LessDepth,
+        side: THREE.FrontSide,
+        toneMapped: false,
+        // wireframe: true,
+    });
+    return lightFresnel;
+}
+export { getLightFresnel };

package/dist/core/lights.d.ts

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+/**
+ * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
+ *
+ * A multi-orbiter realm renders N independent scenes through one renderer. A module-level
+ * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
+ * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
+ * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
+ * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
+ */
+export declare function ensureDefaultLights(scene: THREE.Scene): {
+    hemi: THREE.HemisphereLight;
+    ambient: THREE.AmbientLight;
+};
+/**
+ * Apply a lighting patch to ONE scene's default lights.
+ *
+ * The scene is required. This used to address module-global light refs pointing at whichever scene
+ * was ensured last, so on a page rendering several scenes every lighting update landed on one of
+ * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
+ *
+ * Every field is optional; an omitted one leaves that part of the lighting as it is.
+ */
+export declare function updateDefaultLights(scene: THREE.Scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere }?: {
+    /** ambient light intensity (clamped at 0) */
+    ambientIntensity?: number;
+    /** hemisphere light intensity (clamped at 0) */
+    diffuseIntensity?: number;
+    /** hemisphere light colour */
+    lightColor?: THREE.Color | number | string;
+    /** hemisphere light direction */
+    lightDirection?: {
+        x: number;
+        y?: number;
+        z?: number;
+    };
+    /** switch the hemisphere light on or off */
+    hemisphere?: boolean;
+}): void;
+/**
+ * Switch a scene's default hemisphere light on or off (the ambient light is untouched). Hosts turn it
+ * off when a directional light — the star — lights the scene, so night sides can read.
+ */
+export declare function setHemisphereEnabled(scene: THREE.Scene, on: boolean): void;
+export declare function addDefaultLights(scene: THREE.Scene): {
+    hemi: THREE.HemisphereLight;
+    ambient: THREE.AmbientLight;
+};

package/dist/core/lights.js

@@ -0,0 +1,79 @@
+import * as THREE from 'three';
+/**
+ * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
+ *
+ * A multi-orbiter realm renders N independent scenes through one renderer. A module-level
+ * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
+ * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
+ * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
+ * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
+ */
+export function ensureDefaultLights(scene) {
+    // Found by name: the objects under these names are the lights this function added.
+    let hemi = scene.getObjectByName('ew_HemisphereLight');
+    if (!hemi) {
+        hemi = new THREE.HemisphereLight(0xffffff, 0xffffff, 1.0);
+        hemi.position.set(1, 1, 1);
+        hemi.name = 'ew_HemisphereLight';
+        scene.add(hemi);
+    }
+    let ambient = scene.getObjectByName('ew_AmbientLight');
+    if (!ambient) {
+        ambient = new THREE.AmbientLight(0xffffff, 1.0);
+        ambient.name = 'ew_AmbientLight';
+        scene.add(ambient);
+    }
+    return { hemi, ambient };
+}
+/**
+ * Apply a lighting patch to ONE scene's default lights.
+ *
+ * The scene is required. This used to address module-global light refs pointing at whichever scene
+ * was ensured last, so on a page rendering several scenes every lighting update landed on one of
+ * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
+ *
+ * Every field is optional; an omitted one leaves that part of the lighting as it is.
+ */
+export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere } = {}) {
+    if (!scene?.isObject3D) {
+        console.error('[lights] updateDefaultLights(scene, patch) requires the scene to update; ignoring patch.');
+        return;
+    }
+    const { hemi, ambient } = ensureDefaultLights(scene);
+    // `hemisphere: false` switches the white hemisphere off (e.g. when a star lights the scene);
+    // omitted = unchanged, so old callers keep today's look.
+    if (typeof hemisphere === 'boolean')
+        hemi.visible = hemisphere;
+    if (typeof ambientIntensity === 'number')
+        ambient.intensity = Math.max(0, ambientIntensity);
+    if (typeof diffuseIntensity === 'number')
+        hemi.intensity = Math.max(0, diffuseIntensity);
+    if (lightColor != null) {
+        if (lightColor instanceof THREE.Color) {
+            hemi.color.copy(lightColor);
+        }
+        else if (typeof lightColor === 'number') {
+            hemi.color.setHex(lightColor);
+        }
+        else if (typeof lightColor === 'string') {
+            hemi.color.set(lightColor);
+        }
+    }
+    if (lightDirection && typeof lightDirection.x === 'number') {
+        hemi.position.set(lightDirection.x, lightDirection.y ?? 0, lightDirection.z ?? 0).normalize();
+    }
+}
+/**
+ * Switch a scene's default hemisphere light on or off (the ambient light is untouched). Hosts turn it
+ * off when a directional light — the star — lights the scene, so night sides can read.
+ */
+export function setHemisphereEnabled(scene, on) {
+    if (!scene?.isObject3D)
+        return;
+    const { hemi } = ensureDefaultLights(scene);
+    hemi.visible = Boolean(on);
+}
+// Back-compat helper
+export function addDefaultLights(scene) {
+    return ensureDefaultLights(scene);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './world/index.js';
+export * from './moons/index.js';
+export * from './loaders/index.js';
+export * from './core/index.js';
+export * from './config/index.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+// Main exports for entangled-worlds-orbiters-shared library
+export * from './world/index.js';
+export * from './moons/index.js';
+export * from './loaders/index.js';
+export * from './core/index.js';
+export * from './config/index.js';
+export * from './utils/index.js';

package/dist/loaders/bodyTextureLoader.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three';
+/**
+ * `url`: `.ktx2` goes through the renderer's KTX2 transcoder; anything else through
+ * THREE.TextureLoader. `signal`: an abort during the load rejects the promise. `renderer`: REQUIRED
+ * for a `.ktx2` url.
+ */
+export declare function loadTexture(url: string, { signal, renderer }?: {
+    signal?: AbortSignal | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Texture>;

package/dist/loaders/bodyTextureLoader.js

@@ -0,0 +1,28 @@
+import * as THREE from 'three';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+const textureLoader = new THREE.TextureLoader();
+/**
+ * `url`: `.ktx2` goes through the renderer's KTX2 transcoder; anything else through
+ * THREE.TextureLoader. `signal`: an abort during the load rejects the promise. `renderer`: REQUIRED
+ * for a `.ktx2` url.
+ */
+export function loadTexture(url, { signal, renderer } = {}) {
+    return new Promise((resolve, reject) => {
+        if (url && url.endsWith('.ktx2')) {
+            // A missing renderer throws inside (as before): the type allows `null` only because the
+            // non-KTX2 path never needs one.
+            const ktx2 = getKTX2LoaderForRenderer(renderer);
+            const onAbort = () => reject(new Error('aborted'));
+            if (signal)
+                signal.addEventListener('abort', onAbort, { once: true });
+            ktx2.load(url, (tex) => { if (signal)
+                signal.removeEventListener('abort', onAbort); resolve(tex); }, undefined, (err) => { if (signal)
+                signal.removeEventListener('abort', onAbort); reject(err); });
+            return;
+        }
+        const tex = textureLoader.load(url, () => resolve(tex), undefined, (err) => reject(err));
+        if (signal) {
+            signal.addEventListener('abort', () => reject(new Error('aborted')));
+        }
+    });
+}

package/dist/loaders/cubeMapLoader.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+/** A skycube id (`'7'`, `'07_skycube'`, `'skybox-007'`, …) as its three-digit folder name; `'001'` when none. */
+export declare function normalizeSkycubeName(raw: string | null | undefined): string;
+export declare function buildSkycubefaceKeys(skycubeId: string | null | undefined, extension?: string): {
+    right: string;
+    left: string;
+    top: string;
+    bottom: string;
+    front: string;
+    back: string;
+};
+/**
+ * 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 declare function loadCubeMap({ faceKeys, skycubeName, preferKTX2, forceLow, renderer, }?: {
+    faceKeys?: {
+        right: string;
+        left: string;
+        top: string;
+        bottom: string;
+        front: string;
+        back: string;
+    } | undefined;
+    skycubeName?: string | undefined;
+    preferKTX2?: boolean | undefined;
+    forceLow?: boolean | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<SkyboxResource>;
+/**
+ * What `loadCubeMap` resolves to: a skybox mesh wrapper (the KTX2 path) or a cube texture (the
+ * PNG/JPG path). Read `mesh` to tell them apart.
+ */
+export type SkyboxResource = {
+    __ewType: 'skybox-mesh';
+    mesh: THREE.Mesh;
+} | (THREE.CubeTexture & {
+    mesh?: undefined;
+});
+/**
+ * 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 declare function setBackground(scene: THREE.Scene, resource: unknown): void;
+export declare function initSpaceScene(scene: THREE.Scene, { renderer }?: {
+    renderer?: THREE.WebGLRenderer | null;
+}): Promise<void>;