entangled-worlds-orbiters-shared 1.5.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",

package/src/core/lights.js

@@ -1,11 +1,5 @@
 import * as THREE from 'three';
 
-// `hemiRef`/`ambientRef` track the MOST-RECENTLY ensured scene's lights, only so the legacy
-// `updateDefaultLights()` (which takes no scene) keeps targeting the active scene. They are NOT a
-// "lights already created" cache — see ensureDefaultLights.
-let hemiRef = null;
-let ambientRef = null;
-
 /**
  * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
  *
@@ -29,29 +23,39 @@ export function ensureDefaultLights(scene) {
     ambient.name = 'ew_AmbientLight';
     scene.add(ambient);
   }
-  // updateDefaultLights() (no scene arg) targets the most-recently ensured scene's lights.
-  hemiRef = hemi;
-  ambientRef = ambient;
   return { hemi, ambient };
 }
 
-export function updateDefaultLights({ ambientIntensity, diffuseIntensity, lightColor, lightDirection } = {}) {
-  if (typeof ambientIntensity === 'number' && ambientRef) ambientRef.intensity = Math.max(0, ambientIntensity);
-  if (hemiRef) {
-    if (typeof diffuseIntensity === 'number') hemiRef.intensity = Math.max(0, diffuseIntensity);
-    if (lightColor != null) {
-      if (lightColor instanceof THREE.Color) {
-        hemiRef.color.copy(lightColor);
-      } else if (typeof lightColor === 'number') {
-        hemiRef.color.setHex(lightColor);
-      } else if (typeof lightColor === 'string') {
-        hemiRef.color.set(lightColor);
-      }
-    }
-    if (lightDirection && typeof lightDirection.x === 'number') {
-      hemiRef.position.set(lightDirection.x, lightDirection.y ?? 0, lightDirection.z ?? 0).normalize();
+/**
+ * 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.
+ *
+ * @param {import('three').Scene} scene
+ */
+export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection } = {}) {
+  if (!scene?.isObject3D) {
+    console.error('[lights] updateDefaultLights(scene, patch) requires the scene to update; ignoring patch.');
+    return;
+  }
+  const { hemi, ambient } = ensureDefaultLights(scene);
+
+  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();
+  }
 }
 
 // Back-compat helper

package/src/loaders/cubeMapLoader.js

@@ -140,10 +140,14 @@ function resolveUrls(faceKeys) {
   return resolved;
 }
 
-// Main loader function - always uses explicit face URLs
-export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow } = {}) {
-  const renderer = window.__EW_RENDERER;
-  
+/**
+ * Main loader function - always uses explicit face URLs.
+ * `renderer` binds the KTX2 transcoder to the right WebGL context; it falls back to the standalone
+ * app's `window.__EW_RENDERER` only transitionally. Pass it explicitly.
+ */
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer: rendererOpt } = {}) {
+  const renderer = rendererOpt ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+
   // If no face URLs provided, build them from skycube name
   if (!faceKeys && skycubeName) {
     const low = typeof forceLow === 'boolean' ? forceLow : isLowPerformanceDevice();
@@ -175,19 +179,19 @@ export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, fo
     try {
       return await loadFacesKTX2(resolvedUrls, renderer);
     } catch (e) {
-      console.warn('[CubeMapLoader] KTX2 load failed, trying JPG fallback:', e);
-      // Fall through to JPG attempt
+      console.warn('[CubeMapLoader] KTX2 load failed, trying PNG fallback:', e);
+      // Fall through to PNG attempt
     }
   }
   
-  // Try JPG fallback (convert URLs if needed)
-  const jpgUrls = {};
+  // Try PNG fallback (convert URLs if needed)
+  const pngUrls = {};
   FACE_ORDER.forEach(face => {
-    jpgUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.jpg');
+    pngUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.png');
   });
   
   try {
-    return await loadFacesJPG(jpgUrls);
+    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');
@@ -248,8 +252,8 @@ export function setBackground(scene, resource) {
   }
 }
 
-export async function initSpaceScene(scene) {
+export async function initSpaceScene(scene, { renderer } = {}) {
   const faceKeys = buildSkycubefaceKeys('001');
-  const cube = await loadCubeMap({ faceKeys, preferKTX2: true });
+  const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });
   setBackground(scene, cube);
 }

package/src/loaders/glbLoader.js

@@ -3,8 +3,14 @@ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
 import { getKTX2LoaderForRenderer } from './ktx2.js';
 
-export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false } = {}) {
-  const renderer = window.__EW_RENDERER;
+/**
+ * @param {object} [opts]
+ * @param {import('three').WebGLRenderer} [opts.renderer]  the renderer this GLB's textures bind to.
+ *   Transitional default: `window.__EW_RENDERER` (the standalone app's publisher). Pass it explicitly
+ *   — a page with several renderers has no single correct global, and the default goes away with it.
+ */
+export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false, renderer: rendererOpt } = {}) {
+  const renderer = rendererOpt ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
   if (!renderer) throw new Error('Renderer not ready for KTX2');
 
   let attempt = 0;

package/src/loaders/index.js

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

package/src/loaders/ktx2.js

@@ -25,11 +25,14 @@ function makeLoader(renderer) {
  * @param {import('three').WebGLRenderer} [renderer]
  * @returns {KTX2Loader}
  */
-export function getKTX2LoaderForRenderer(
-  renderer = (typeof window !== 'undefined' ? window.__EW_RENDERER : null),
-) {
+export function getKTX2LoaderForRenderer(rendererArg) {
+  // `??` not a default param: callers thread an OPTIONAL renderer down several layers, so `null`
+  // arrives as often as `undefined` and must fall back the same way.
+  const renderer = rendererArg ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
   if (!renderer) {
-    if (!fallbackLoader) fallbackLoader = makeLoader(renderer);
+    // No renderer anywhere: an unbound loader can't transcode (detectSupport needs a context), but
+    // returning one keeps the caller's error local to the texture instead of throwing mid-scene.
+    if (!fallbackLoader) fallbackLoader = new KTX2Loader().setTranscoderPath('/basis/');
     return fallbackLoader;
   }
   let loader = loadersByRenderer.get(renderer);

package/src/moons/moonsGeneration.js

@@ -40,6 +40,9 @@ export async function generateMoons({
   // behavior flags
   preserveInstanceTint = false,      // keep per-instance color even when textured
   useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
+  // The renderer whose KTX2 transcoder decodes the moon texture. Required on any page with more than
+  // one renderer; falls back to the standalone app's global inside the loader.
+  renderer,
 } = {}) {
   if (count <= 0) return null;
 
@@ -95,11 +98,11 @@ export async function generateMoons({
     const fallbackTexture = textureFallback || texturePNG;
     
     try {
-      sharedTexture = await loadTexture(primaryTexture);
+      sharedTexture = await loadTexture(primaryTexture, { renderer });
     } catch (eKTX) {
       if (debug) console.warn('[Moons] Primary texture failed, trying fallback:', eKTX);
       try {
-        sharedTexture = await loadTexture(fallbackTexture);
+        sharedTexture = await loadTexture(fallbackTexture, { renderer });
       } catch (ePNG) {
         if (debug) console.warn('[Moons] Both primary and fallback texture loading failed');
       }
@@ -195,15 +198,7 @@ export async function generateMoons({
   group.add(instanced);
   group.name = 'moonsGroup';
 
-  // Add disposal method for cleanup
-  group.dispose = () => {
-    if (moonGeometry) moonGeometry.dispose();
-    if (moonMaterial.map && moonMaterial.map !== sharedTexture) moonMaterial.map.dispose();
-    if (moonMaterial.emissiveMap && moonMaterial.emissiveMap !== sharedTexture) moonMaterial.emissiveMap.dispose();
-    if (moonMaterial.bumpMap && moonMaterial.bumpMap !== sharedTexture) moonMaterial.bumpMap.dispose();
-    moonMaterial.dispose();
-    instanced.dispose();
-  };
-
+  // Teardown goes through `disposeObject3D` (MoonsManager.dispose / setAmount), which frees the
+  // geometry, the material's textures and the instance buffers.
   return group;
 }

package/src/moons/moonsManager.js

@@ -3,8 +3,14 @@ import * as THREE from 'three';
 import { generateMoons } from './moonsGeneration.js';
 
 export class MoonsManager {
-  constructor(scene) {
+  /**
+   * @param {import('three').Scene} scene
+   * @param {object} [opts]
+   * @param {import('three').WebGLRenderer} [opts.renderer]  renderer the moon texture binds to (KTX2).
+   */
+  constructor(scene, { renderer } = {}) {
     this.scene = scene;
+    this.renderer = renderer;
     this.group = null;
     this._opId = 0; // concurrency guard
   }
@@ -44,6 +50,7 @@ export class MoonsManager {
         textureKey, // Pass texture key for custom moon textures
         textureFallback,
         moonColor, // Pass moon color to generator
+        renderer: this.renderer,
       });
     } catch (e) {
       console.warn('[MoonsManager] Failed to generate moons:', e);
@@ -63,4 +70,16 @@ export class MoonsManager {
       console.warn('[MoonsManager] generateMoons did not return an Object3D');
     }
   }
+
+  /**
+   * Remove the moons from the scene and free their GPU resources. `scene.remove(group)` alone leaks
+   * the instanced geometry, materials and the shared moon texture on every view teardown.
+   */
+  dispose() {
+    this._opId++; // abandon any in-flight setAmount
+    if (this.group) {
+      disposeObject3D(this.group);
+      this.group = null;
+    }
+  }
 }

package/src/utils/dispose.js

@@ -30,6 +30,9 @@ export function disposeObject3D(obj) {
     if (child.isMesh) {
       if (child.geometry) child.geometry.dispose();
       disposeMaterial(child.material);
+      // An InstancedMesh also owns `instanceMatrix` / `instanceColor` GPU buffers, which hang off the
+      // mesh rather than the (shared) geometry — only its own dispose() frees them.
+      if (child.isInstancedMesh) child.dispose();
     }
   });
   if (obj.parent) obj.parent.remove(obj);

package/src/world/worldGLB.js

@@ -1,7 +1,7 @@
 import { loadGLB } from '../loaders/glbLoader.js';
 
-export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false } = {}) {
+export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false, renderer } = {}) {
   if (!modelUrl) throw new Error('modelUrl is required');
-  const obj = await loadGLB(modelUrl, { retries, applyFlags: flags, withCredentials });
+  const obj = await loadGLB(modelUrl, { retries, applyFlags: flags, withCredentials, renderer });
   return obj;
 }