entangled-worlds-orbiters-shared 1.0.0

package/src/loaders/cubeMapLoader.js

@@ -0,0 +1,264 @@
+import * as THREE from 'three';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+
+// Base URL
+const PUBLIC_BASE = (import.meta?.env?.VITE_PUBLIC_HERBARIUM_BASE) || (window?.VITE_PUBLIC_HERBARIUM_BASE) || 'https://dev-herbarium.plantasia.space';
+
+// Shared loader + caches
+const ktx2SupportCache = new Map(); // base -> true|false
+
+function getSharedKTX2Loader(renderer) {
+  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
+  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+  window.__EW_KTX2_LOADER = loader;
+  return loader;
+}
+
+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);
+    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;
+  return FACE_ORDER.every(face => faceKeys[face] && typeof faceKeys[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
+}
+
+// Load KTX2 faces and create skybox mesh
+async function loadFacesKTX2(faceKeys, renderer) {
+  const loader = getSharedKTX2Loader(renderer);
+  const loaded = [];
+  
+  for (const face of FACE_ORDER) {
+    const url = faceKeys[face];
+    try {
+      const tex = await loader.loadAsync(url);
+      tex.flipY = false;
+      tex.wrapS = THREE.ClampToEdgeWrapping;
+      tex.wrapT = THREE.ClampToEdgeWrapping;
+      tex.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+      loaded.push({ face, tex });
+    } catch (e) {
+      // Dispose already loaded textures on failure
+      loaded.forEach(f => f.tex.dispose?.());
+      throw e;
+    }
+  }
+  
+  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 
+      });
+    }
+  }
+  
+  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 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
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow } = {}) {
+  const renderer = window.__EW_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 JPG fallback:', e);
+      // Fall through to JPG attempt
+    }
+  }
+  
+  // Try JPG fallback (convert URLs if needed)
+  const jpgUrls = {};
+  FACE_ORDER.forEach(face => {
+    jpgUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.jpg');
+  });
+  
+  try {
+    return await loadFacesJPG(jpgUrls);
+  } 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 {
+    const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.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);
+  }
+}
+
+export function setBackground(scene, resource) {
+  // Clean up previous skybox mesh
+  if (scene.__EW_SKYBOX_MESH && scene.__EW_SKYBOX_MESH.parent === scene) {
+    const oldMesh = scene.__EW_SKYBOX_MESH;
+    scene.remove(oldMesh);
+    disposeSkyboxMesh(oldMesh);
+    scene.__EW_SKYBOX_MESH = null;
+  }
+  
+  // Dispose previous CubeTexture background
+  if (scene.background && scene.background.isCubeTexture) {
+    try { 
+      scene.background.dispose(); 
+    } catch(e) {
+      console.warn('[CubeMapLoader] Background disposal error:', e);
+    }
+  }
+  
+  // Set new background
+  if (resource?.__ewType === 'skybox-mesh') {
+    scene.background = null;
+    scene.__EW_SKYBOX_MESH = resource.mesh;
+    scene.add(resource.mesh);
+  } else if (resource?.isCubeTexture || resource?.isTexture) {
+    scene.background = resource;
+  } else {
+    scene.background = null;
+  }
+  
+  // Dispatch update event for reactive systems
+  try {
+    window.dispatchEvent(new CustomEvent('ew:skycube-updated', { 
+      detail: { type: resource?.__ewType || 'texture' } 
+    }));
+  } catch(e) {
+    console.warn('[CubeMapLoader] Event dispatch error:', e);
+  }
+}
+
+export async function initSpaceScene(scene) {
+  const faceKeys = buildSkycubefaceKeys('001');
+  const cube = await loadCubeMap({ faceKeys, preferKTX2: true });
+  setBackground(scene, cube);
+}

package/src/loaders/glbLoader.js

@@ -0,0 +1,71 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
+
+function getSharedKTX2Loader(renderer) {
+  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
+  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+  window.__EW_KTX2_LOADER = loader;
+  return loader;
+}
+
+export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags } = {}) {
+  const renderer = window.__EW_RENDERER;
+  if (!renderer) throw new Error('Renderer not ready for KTX2');
+
+  let attempt = 0;
+  while (attempt < retries) {
+    try {
+      const loader = new GLTFLoader()
+        .setCrossOrigin('anonymous')
+        .setKTX2Loader(getSharedKTX2Loader(renderer));
+
+      const root = await new Promise((resolve, reject) => {
+        loader.load(
+          url,
+            (gltf) => resolve(gltf.scene),
+            onProgress,
+            reject
+        );
+        if (signal) {
+          signal.addEventListener('abort', () => reject(new Error('aborted')));
+        }
+      });
+
+      // Post-process materials
+      root.traverse((child) => {
+        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 = 1.0;
+            console.log('✅ KTX2 texture loaded:', child.material.map.constructor.name, `${child.material.map.image.width}x${child.material.map.image.height}`);
+          }
+          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/src/loaders/index.js

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

package/src/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 } from './moonsGeneration.js';

package/src/moons/moonsGeneration.js

@@ -0,0 +1,228 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+
+// Resolve public herbarium base (strip trailing slash)
+const HERBARIUM_BASE = (import.meta?.env?.VITE_PUBLIC_HERBARIUM_BASE || 'https://dev-herbarium.plantasia.space').replace(/\/$/, '');
+function moonTexPath(file) { return `${HERBARIUM_BASE}/default/textures/moons/${file}`; }
+export const DEFAULT_MOON_TEX_KTX2 = moonTexPath('moon-equirectangular.ktx2');
+export const DEFAULT_MOON_TEX_PNG = moonTexPath('moon-equirectangular.png');
+
+export async function generateMoons({
+  count = 0,
+  orbitRadius = 1.5,
+  textureKTX2 = DEFAULT_MOON_TEX_KTX2,
+  texturePNG = DEFAULT_MOON_TEX_PNG,
+  useTexture = true,
+  // NEW: seed for deterministic positioning
+  seed = null, // if provided, ensures consistent moon positions
+  // NEW: specific texture key/path
+  textureKey = null, // if provided, overrides textureKTX2/texturePNG
+  moonColor = '#ffffff', // NEW: moon color
+  // lighting tweaks
+  brightness = 1.15,
+  emissiveColor = 0x333333,
+  emissiveIntensity = 0.18,
+  roughness = 0.85,
+  metalness = 0.0,
+  // debug & appearance controls
+  debug = true,
+  smooth = true, // set false to keep flatShading
+  // debug / appearance params
+  geometryWidthSegments = 16, // Reduced from 24 for better performance
+  geometryHeightSegments = 12, // Reduced from 24 for better performance
+  useBumpFromColor = true,
+  bumpScale = 0.15,
+  debugShowUvGrid = false,
+  debugShowReferenceMoon = false, // changed from true to prevent extra moon
+  referenceMoonScale = 0.25,
+  // behavior flags
+  preserveInstanceTint = false,      // keep per-instance color even when textured
+  useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
+} = {}) {
+  if (count <= 0) return null;
+
+  // Seeded random number generator for deterministic positioning
+  let seedValue = seed;
+  if (typeof seed === 'string') {
+    // Convert string seed to number using simple hash
+    seedValue = 0;
+    for (let i = 0; i < seed.length; i++) {
+      const char = seed.charCodeAt(i);
+      seedValue = ((seedValue << 5) - seedValue) + char;
+      seedValue = seedValue & seedValue; // Convert to 32-bit integer
+    }
+  }
+  
+  // Seeded random function (Linear Congruential Generator)
+  let currentSeed = seedValue !== null ? Math.abs(seedValue) : Date.now();
+  const seededRandom = () => {
+    if (seedValue !== null) {
+      currentSeed = (currentSeed * 1664525 + 1013904223) % 4294967296;
+      return currentSeed / 4294967296;
+    }
+    return Math.random(); // Use regular random if no seed
+  };
+
+  // Log the seed being used for debugging
+  if (debug) {
+    console.log('[Moons] Using seed for deterministic positioning:', {
+      originalSeed: seed,
+      seedValue: seedValue,
+      seedType: typeof seed,
+      isSeeded: seedValue !== null
+    });
+  }
+
+  const moonGeometry = new THREE.SphereGeometry(0.1, geometryWidthSegments, geometryHeightSegments);
+
+  // Optional UV grid override
+  let sharedTexture = null;
+  let usedUvGrid = false;
+  async function buildUvGridTexture() {
+    const w = 512, h = 256; // 2:1 aspect
+    const canvas = document.createElement('canvas');
+    canvas.width = w; canvas.height = h;
+    const ctx = canvas.getContext('2d');
+    ctx.fillStyle = '#101018'; ctx.fillRect(0,0,w,h);
+    for (let lon=0; lon<=12; lon++) {
+      const x = (lon/12)*w; ctx.strokeStyle = lon % 3 ===0 ? '#ff4d4d':'#444'; ctx.lineWidth = lon%3===0?2:1; ctx.beginPath(); ctx.moveTo(x,0); ctx.lineTo(x,h); ctx.stroke();
+    }
+    for (let lat=0; lat<=6; lat++) {
+      const y = (lat/6)*h; ctx.strokeStyle = lat % 3 ===0 ? '#4dff7a':'#444'; ctx.lineWidth = lat%3===0?2:1; ctx.beginPath(); ctx.moveTo(0,y); ctx.lineTo(w,y); ctx.stroke();
+    }
+    ctx.fillStyle = 'white'; ctx.font = '20px monospace'; ctx.fillText('UV GRID', 10, 24);
+    const tex = new THREE.CanvasTexture(canvas);
+    tex.colorSpace = THREE.SRGBColorSpace; tex.anisotropy = 4; return tex;
+  }
+
+  if (debugShowUvGrid) {
+    try { sharedTexture = await buildUvGridTexture(); usedUvGrid = true; } catch(_) {}
+  } else if (useTexture) {
+    // Use textureKey if provided, otherwise fall back to default textures
+    let primaryTexture = textureKey || textureKTX2;
+    const fallbackTexture = texturePNG;
+    
+    // Resolve textureKey to absolute URL if it's relative
+    if (textureKey && textureKey.startsWith('/')) {
+      primaryTexture = `${HERBARIUM_BASE}${textureKey}`;
+      if (debug) console.log('[Moons] Using custom texture key:', textureKey, '-> resolved:', primaryTexture);
+    } else if (textureKey) {
+      primaryTexture = textureKey; // already absolute
+      if (debug) console.log('[Moons] Using absolute texture URL:', primaryTexture);
+    }
+    
+    try {
+      sharedTexture = await loadTexture(primaryTexture);
+      if (debug) console.log('[Moons] Loaded texture from:', primaryTexture);
+    } catch (eKTX) {
+      if (debug) console.warn('[Moons] Primary texture failed, trying fallback:', eKTX);
+      try {
+        sharedTexture = await loadTexture(fallbackTexture);
+        if (debug) console.log('[Moons] Fallback texture loaded from:', fallbackTexture);
+      } catch (ePNG) {
+        if (debug) console.warn('[Moons] Both primary and fallback texture loading failed');
+      }
+    }
+  }
+
+  if (sharedTexture) {
+    try {
+      sharedTexture.colorSpace = THREE.SRGBColorSpace;
+      sharedTexture.anisotropy = 2; // Reduced from 4 for better performance
+    } catch (e) { 
+      if (debug) console.warn('[Moons] Texture processing failed:', e); 
+    }
+  }
+
+  const enableVertexColors = !sharedTexture || preserveInstanceTint;
+  const moonMaterial = new THREE.MeshStandardMaterial({
+    map: sharedTexture || null,
+    vertexColors: enableVertexColors,
+    roughness,
+    metalness,
+    emissive: new THREE.Color(emissiveColor),
+    emissiveIntensity,
+    flatShading: !smooth,
+    transparent: false,
+    depthWrite: true,
+    depthTest: true,
+  });
+  if (sharedTexture && useEmissiveMapFromTexture) {
+    moonMaterial.emissiveMap = sharedTexture; // boosts subtle texture detail
+  }
+
+  if (!sharedTexture && debug && !debugShowUvGrid) {
+    console.warn('[Moons] No texture assigned (using pure color instancing).');
+  }
+  if (sharedTexture) {
+    moonMaterial.map = sharedTexture;
+    if (useBumpFromColor) {
+      moonMaterial.bumpMap = sharedTexture;
+      moonMaterial.bumpScale = bumpScale;
+    }
+  }
+
+  // Pre-computed color palette for variation (white to dark gray)
+  const colorPalette = [
+    0xffffff, 0xf5f5f5, 0xeeeeee, 0xe8e8e8, 0xdddddd, 0xd3d3d3,
+    0xcccccc, 0xc0c0c0, 0xb8b8b8, 0xaaaaaa, 0x999999, 0x888888
+  ].map(hex => new THREE.Color(hex));
+
+  const instanced = new THREE.InstancedMesh(moonGeometry, moonMaterial, count + (debugShowReferenceMoon ? 1 : 0));
+  
+  // Set render order to ensure proper rendering above glow effects
+  instanced.renderOrder = 2000;
+  
+  const dummy = new THREE.Object3D();
+
+  let instanceIndex = 0;
+  for (let i = 0; i < count; i++) {
+    const angle = (i / Math.max(1, count)) * Math.PI * 2;
+    const radiusVar = orbitRadius + (seededRandom() - 0.5) * 0.22;
+    const yOffset = (seededRandom() - 0.5) * 0.12;
+    dummy.position.set(radiusVar * Math.cos(angle), yOffset, radiusVar * Math.sin(angle));
+    const s = 0.07 + seededRandom() * 0.15;
+    dummy.scale.set(s, s, s);
+    dummy.rotation.y = seededRandom() * Math.PI * 2;
+    dummy.rotation.x = seededRandom() * 0.3 - 0.15;
+    dummy.updateMatrix();
+    instanced.setMatrixAt(instanceIndex, dummy.matrix);
+    
+    // Always set instance color as tint, even if texture is present
+    const base = new THREE.Color(moonColor || '#ffffff');
+    instanced.setColorAt(instanceIndex, base);
+
+    instanceIndex++;
+  }
+
+  if (debugShowReferenceMoon) {
+    dummy.position.set(orbitRadius * 0.6, 0.05, orbitRadius * 0.2);
+    dummy.scale.set(referenceMoonScale, referenceMoonScale, referenceMoonScale);
+    dummy.rotation.y = seededRandom() * Math.PI * 2;
+    dummy.rotation.x = seededRandom() * 0.3 - 0.15;
+    dummy.updateMatrix();
+    instanced.setMatrixAt(instanceIndex, dummy.matrix);
+    const refColor = new THREE.Color('#ffffff');
+    instanced.setColorAt(instanceIndex, refColor);
+  }
+
+  instanced.instanceMatrix.needsUpdate = true;
+  if (instanced.instanceColor) instanced.instanceColor.needsUpdate = true;
+
+  const group = new THREE.Group();
+  group.rotation.x = THREE.MathUtils.degToRad(15);
+  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();
+  };
+
+  return group;
+}

package/src/moons/moonsManager.js

@@ -0,0 +1,64 @@
+import { disposeObject3D } from '../utils/dispose.js';
+import * as THREE from 'three';
+import { generateMoons } from './moonsGeneration.js';
+
+export class MoonsManager {
+  constructor(scene) {
+    this.scene = scene;
+    this.group = null;
+    this._opId = 0; // concurrency guard
+  }
+
+  async setAmount(count, opts = {}) {
+    // Increment operation id to invalidate older async calls
+    const opId = ++this._opId;
+
+    // remove existing
+    if (this.group) {
+      disposeObject3D(this.group);
+      this.group = null;
+    }
+    if (!count || count <= 0) return;
+
+    // Gather options for texture sharing / orbit params
+    const {
+      orbitRadius = 1.5,
+      textureKTX2,
+      texturePNG,
+      useTexture = true,
+      seed = null, // seed for deterministic positioning
+      textureKey = null, // NEW: specific texture key/path to use
+      moonColor = '#ffffff', // NEW: moon color
+    } = opts;
+
+    let newGroup = null;
+    try {
+      newGroup = await generateMoons({
+        count,
+        orbitRadius,
+        textureKTX2,
+        texturePNG,
+        useTexture,
+        seed,
+        textureKey, // Pass texture key for custom moon textures
+        moonColor, // Pass moon color to generator
+      });
+    } catch (e) {
+      console.warn('[MoonsManager] Failed to generate moons:', e);
+      return;
+    }
+
+    // If another call started meanwhile, abandon this result
+    if (opId !== this._opId) {
+      if (newGroup) disposeObject3D(newGroup);
+      return;
+    }
+
+    if (newGroup instanceof THREE.Object3D) {
+      this.group = newGroup;
+      this.scene.add(this.group);
+    } else if (newGroup) {
+      console.warn('[MoonsManager] generateMoons did not return an Object3D');
+    }
+  }
+}

package/src/utils/dispose.js

@@ -0,0 +1,20 @@
+export function disposeMaterial(material) {
+  if (!material) return;
+  for (const key in material) {
+    const val = material[key];
+    if (val && typeof val.dispose === 'function') {
+      try { val.dispose(); } catch {}
+    }
+  }
+}
+
+export function disposeObject3D(obj) {
+  if (!obj) return;
+  obj.traverse((child) => {
+    if (child.isMesh) {
+      if (child.geometry) child.geometry.dispose();
+      disposeMaterial(child.material);
+    }
+  });
+  if (obj.parent) obj.parent.remove(obj);
+}

package/src/utils/index.js

@@ -0,0 +1,3 @@
+// Utilities exports
+export { ensureStandardMaterial, applyFlagsToMaterial } from './materials.js';
+export { disposeObject3D } from './dispose.js';

package/src/utils/materials.js

@@ -0,0 +1,31 @@
+import * as THREE from 'three';
+
+export function ensureStandardMaterial(mesh) {
+  if (!mesh || !mesh.isMesh) return;
+  const mat = mesh.material;
+  if (mat && !(mat instanceof THREE.MeshStandardMaterial)) {
+    mesh.material = new THREE.MeshStandardMaterial({
+      map: mat.map || null,
+      metalness: 0.3,
+      roughness: 0.7,
+    });
+  }
+}
+
+export function applyFlagsToMaterial(material, flags = {}) {
+  if (!material) return;
+  const { forceOpaque, wireframe } = flags;
+  if (forceOpaque) {
+    if (material.transparent || (material.transmission && material.transmission > 0)) {
+      material.transparent = false;
+      material.opacity = 1;
+      if ('transmission' in material) material.transmission = 0;
+      material.alphaTest = 0;
+      material.needsUpdate = true;
+    }
+  }
+  if (wireframe) {
+    material.wireframe = true;
+    material.needsUpdate = true;
+  }
+}