entangled-worlds-orbiters-shared 1.0.0

package/src/world/cloudShell.js

@@ -0,0 +1,89 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+
+// Texture-only clouds material (alpha mask + tint), UV-scrolled
+async function makeTextureMaterial({
+  color = 0xffffff,
+  opacity = 0.6,
+  textureUrl,
+  speed = 0.015,
+} = {}) {
+  const mat = new THREE.MeshStandardMaterial({
+    color,
+    transparent: true,
+    opacity: 1.0, // drive alpha via alphaMap
+    roughness: 1.0,
+    metalness: 0.0,
+    depthTest: true,
+    depthWrite: false,
+    side: THREE.FrontSide,
+    toneMapped: true,
+  });
+
+  if (textureUrl) {
+    const tex = await loadTexture(textureUrl);
+    tex.wrapS = THREE.RepeatWrapping;
+    tex.wrapT = THREE.RepeatWrapping;
+    // Use linear space for alpha masks if available
+    tex.colorSpace = THREE.LinearSRGBColorSpace || THREE.SRGBColorSpace;
+    tex.repeat.set(1, 1); // fixed tiling
+    tex.anisotropy = 2;
+    mat.alphaMap = tex;
+    mat.opacity = opacity; // material opacity multiplier
+    mat.needsUpdate = true;
+  } else {
+    // No texture -> invisible shell
+    mat.opacity = 0.0;
+  }
+
+  // Randomize wind direction per instance (0..360)
+  const dirRad = (Math.random() * 360 * Math.PI) / 180;
+  const wind = new THREE.Vector2(Math.cos(dirRad), Math.sin(dirRad)).multiplyScalar(speed);
+  mat.userData.update = (timeSec) => {
+    const t = mat.alphaMap;
+    if (t) {
+      t.offset.x = wind.x * timeSec;
+      t.offset.y = wind.y * timeSec;
+      t.needsUpdate = true;
+    }
+  };
+
+  return mat;
+}
+
+export async function createCloudShell({
+  baseGeometry,
+  baseRadius = 0.5,
+  widthSegments = 64,
+  heightSegments = 64,
+  textureUrl = '/assets/texture/2k_earth_clouds.jpg',
+  color = 0xffffff,
+  opacity = 0.6,
+  speed = 0.015,
+} = {}) {
+  const geom = baseGeometry
+    ? baseGeometry.clone()
+    : new THREE.SphereGeometry(baseRadius, widthSegments, heightSegments);
+
+  const material = await makeTextureMaterial({
+    color,
+    opacity,
+    textureUrl,
+    speed,
+  });
+
+  const mesh = new THREE.Mesh(geom, material);
+  const s = 1.001; // fixed scale
+  mesh.scale.set(s, s, s);
+  mesh.name = 'worldCloudShell';
+  mesh.renderOrder = 998; // after planet, before glow
+
+  mesh.onBeforeRender = () => {
+    const t = performance.now() * 0.001;
+    if (material.userData && typeof material.userData.update === 'function') {
+      material.userData.update(t);
+    }
+  };
+
+  return mesh;
+}

package/src/world/index.js

@@ -0,0 +1,6 @@
+// World system exports
+export { WorldManager } from './worldManager.js';
+export { makeSphere, EARTH_RADIUS_UNITS } from './worldTexture.js';
+export { makeNormalSphere } from './worldNormal.js';
+export { makeGLB } from './worldGLB.js';
+export { createCloudShell } from './cloudShell.js';

package/src/world/worldGLB.js

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

package/src/world/worldManager.js

@@ -0,0 +1,93 @@
+import { disposeObject3D } from '../utils/dispose.js';
+import { makeGLB } from './worldGLB.js';
+import { makeSphere } from './worldTexture.js';
+import { makeNormalSphere } from './worldNormal.js';
+
+export class WorldManager {
+  constructor(scene, { onLoadStart, onLoadEnd } = {}) {
+    this.scene = scene;
+    this.current = null;
+    this.flags = {};
+    this.onLoadStart = onLoadStart;
+    this.onLoadEnd = onLoadEnd;
+    this.token = 0;
+    // Registry for custom world creators
+    this.customCreators = new Map();
+  }
+
+  setFlags(flags) {
+    console.log('[WorldManager] setFlags:', flags);
+    this.flags = { ...this.flags, ...flags };
+  }
+
+  disposeCurrent() {
+    if (this.current) {
+      console.log('[WorldManager] disposeCurrent:', this.current?.name || this.current);
+      disposeObject3D(this.current);
+      this.scene.remove(this.current);
+      this.current = null;
+    }
+  }
+
+  // Register custom world creators for app-specific world types
+  registerWorldCreator(mode, creatorFunction) {
+    this.customCreators.set(mode, creatorFunction);
+  }
+
+  async setMode(mode, args = {}) {
+    const myToken = ++this.token;
+    console.log('[WorldManager] setMode request:', { mode, args });
+    this.onLoadStart?.();
+    try {
+      let obj;
+      
+      // Check for custom creators first
+      if (this.customCreators.has(mode)) {
+        console.log(`[WorldManager] -> custom creator for mode ${mode}`);
+        obj = await this.customCreators.get(mode)({ flags: this.flags, ...args });
+      } else if (mode === 2) {
+        console.log('[WorldManager] -> makeGLB');
+        obj = await makeGLB({ modelUrl: args.modelUrl, flags: this.flags });
+      } else if (mode === 3) {
+        console.log('[WorldManager] -> makeNormalSphere');
+        obj = await makeNormalSphere({ flags: this.flags, ...args });
+      } else {
+        console.log('[WorldManager] -> makeSphere (textured)');
+        obj = await makeSphere({ textureUrl: args.textureUrl, flags: this.flags, ...args });
+      }
+
+      if (this.token !== myToken) {
+        console.log('[WorldManager] setMode superseded, abandoning result');
+        return;
+      }
+      this.disposeCurrent();
+      this.scene.add(obj);
+      this.current = obj;
+      console.log('[WorldManager] setMode applied. current:', obj?.name || obj);
+
+      // If the object exposes a frame updater, run a render-time loop
+      if (obj && obj.userData && typeof obj.userData.update === 'function' && window.__EW_RENDERER) {
+        const updater = obj.userData.update;
+        console.log('[WorldManager] update loop started for', obj.name || obj);
+        const tick = () => {
+          if (this.current === obj) {
+            try {
+              updater(window.__EW_RENDERER, performance.now() * 0.001);
+            } catch (e) {
+              console.warn('[WorldManager] update loop error:', e);
+            }
+            requestAnimationFrame(tick);
+          } else {
+            console.log('[WorldManager] update loop stopped (object replaced)');
+          }
+        };
+        requestAnimationFrame(tick);
+      }
+    } catch (e) {
+      console.warn('[WorldManager] setMode error:', e);
+      throw e;
+    } finally {
+      if (this.token === myToken) this.onLoadEnd?.();
+    }
+  }
+}

package/src/world/worldNormal.js

@@ -0,0 +1,25 @@
+// Normal world (MeshNormalMaterial) implementation
+import * as THREE from 'three';
+import { EARTH_RADIUS_UNITS } from './worldTexture.js';
+import { applyFlagsToMaterial } from '../utils/materials.js';
+
+/**
+ * Create a simple sphere using THREE.MeshNormalMaterial.
+ * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
+ */
+export async function makeNormalSphere({
+  sphereRadius,
+  sphereWidthSegments,
+  sphereHeightSegments,
+  flags,
+} = {}) {
+  const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
+  const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
+  const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
+  const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
+  const material = new THREE.MeshNormalMaterial();
+  if (flags) applyFlagsToMaterial(material, flags);
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.name = 'worldNormalSphere';
+  return mesh;
+}

package/src/world/worldTexture.js

@@ -0,0 +1,239 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+import { applyFlagsToMaterial } from '../utils/materials.js';
+import { getLightFresnel } from '../core/lightFresnel.js';
+import { createCloudShell } from './cloudShell.js';
+
+export const EARTH_RADIUS_UNITS = 0.5; // scene units
+
+/**
+ * Simplified detection: width = height -> rectangular, width = 2×height -> equirectangular
+ */
+function isLikelyEquirectangular(img) {
+  const aspectRatio = img.width / img.height;
+  
+  // Check for 2:1 aspect ratio (equirectangular)
+  const is2to1 = Math.abs(aspectRatio - 2.0) < 0.1;
+  
+  // Check for 1:1 aspect ratio (square -> treat as rectangular)
+  const is1to1 = Math.abs(aspectRatio - 1.0) < 0.1;
+  
+  if (is1to1) {
+    return false; // Square images are rectangular
+  }
+  
+  if (is2to1) {
+    return true;  // 2:1 images are equirectangular
+  }
+  
+  // For other aspect ratios, default to rectangular
+  return false;
+}
+
+export async function makeSphere({
+  textureUrl,
+  flags,
+  uOffset,
+  textureOffsetDeg,
+  mirrorX,
+  mirrorDuplicateX, // optional, still supported for explicit override
+  autoDetectEquirectangular = true,
+  forceEquirectangular = false,
+  forceRectangular = false,
+  // Wrapping params
+  wrapS = 'repeat',
+  wrapT = 'clamp',
+  repeatX,
+  repeatY,
+  rotationDeg,
+  center = [0.5, 0.5],
+  flipY,
+  // NEW: sphere geometry controls (optional)
+  sphereRadius,
+  sphereWidthSegments,
+  sphereHeightSegments,
+  // PBR material tuning (optional)
+  materialRoughness,
+  materialMetalness,
+  // NEW: glow controls
+  glow = true,
+  glowRimHex = 0x66ccff,
+  glowFacingHex = 0x000000,
+  glowScale = 1.18,
+  glowBias = 0.02,
+  glowFresnelScale = 1.0,
+  glowPower = 3.5,
+  // texture clouds controls (simplified)
+  cloudsEnabled = false,
+  cloudsTextureUrl = '/assets/texture/2k_earth_clouds.jpg',
+  cloudsColor = 0xffffff,
+  cloudsOpacity = 0.6,
+  cloudsSpeed = 0.015,
+} = {}) {
+  const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
+  const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
+  const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
+  const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
+
+  const rough = (typeof materialRoughness === 'number') ? THREE.MathUtils.clamp(materialRoughness, 0, 1) : 0.7;
+  const metal = (typeof materialMetalness === 'number') ? THREE.MathUtils.clamp(materialMetalness, 0, 1) : 0.0;
+  const material = new THREE.MeshStandardMaterial({ color: 0xffffff, roughness: rough, metalness: metal });
+
+  const WRAP = {
+    clamp: THREE.ClampToEdgeWrapping,
+    repeat: THREE.RepeatWrapping,
+    mirror: THREE.MirroredRepeatWrapping,
+  };
+
+  // Attach a Fresnel glow mesh as a child of the sphere mesh
+  function createGlow(rimHex, facingHex) {
+    const fresnelMat = getLightFresnel({ rimHex, facingHex });
+    // tweak uniforms for stronger rim
+    fresnelMat.uniforms.fresnelBias.value = glowBias;
+    fresnelMat.uniforms.fresnelScale.value = glowFresnelScale;
+    fresnelMat.uniforms.fresnelPower.value = glowPower;
+
+    const glowGeom = geometry.clone();
+    const fresnelMesh = new THREE.Mesh(glowGeom, fresnelMat);
+    // Slightly larger to avoid z-fighting and create a halo
+    const s = Math.max(glowScale, 1.0);
+    fresnelMesh.scale.set(s, s, s);
+    fresnelMesh.renderOrder = 999; // render after base mesh
+    fresnelMesh.name = 'worldTextureGlow';
+    return fresnelMesh;
+  }
+
+  const chosenTexture = textureUrl; // require explicit textureUrl — no implicit default
+  if (chosenTexture) {
+    try {
+      const tex = await loadTexture(chosenTexture);
+      tex.colorSpace = THREE.SRGBColorSpace;
+      tex.generateMipmaps = true;
+      tex.anisotropy = 8;
+      if (typeof flipY === 'boolean') tex.flipY = flipY;
+
+      // Decide mapping approach
+      let shouldMirrorDuplicate = mirrorDuplicateX;
+      if (tex.image) {
+        const img = tex.image;
+        let isEquirectangular = false;
+
+        if (forceEquirectangular) {
+          isEquirectangular = true;
+        } else if (forceRectangular) {
+          isEquirectangular = false;
+        } else if (autoDetectEquirectangular && typeof mirrorDuplicateX === 'undefined') {
+          const aspectDetection = isLikelyEquirectangular(img);
+          isEquirectangular = aspectDetection && Math.abs(img.width / img.height - 2.0) < 0.05;
+        } else {
+          isEquirectangular = !shouldMirrorDuplicate;
+        }
+        shouldMirrorDuplicate = !isEquirectangular;
+      }
+
+      // Default to rectangular duplicate if still undefined
+      if (typeof shouldMirrorDuplicate === 'undefined') {
+        shouldMirrorDuplicate = true;
+      }
+
+      // Seam alignment (offset only)
+      let offsetX = 0;
+      if (typeof uOffset === 'number') {
+        offsetX = ((uOffset % 1) + 1) % 1;
+      } else if (typeof textureOffsetDeg === 'number') {
+        offsetX = (((textureOffsetDeg / 360) % 1) + 1) % 1;
+      }
+
+      const applyWrapOptions = (t) => {
+        t.wrapS = WRAP[wrapS] ?? THREE.RepeatWrapping;
+        t.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+        if (Array.isArray(center) && center.length === 2) t.center.set(center[0], center[1]);
+        if (typeof rotationDeg === 'number') t.rotation = (rotationDeg * Math.PI) / 180;
+        if (typeof repeatX === 'number' || typeof repeatY === 'number') {
+          t.repeat.set(
+            typeof repeatX === 'number' ? repeatX : t.repeat.x,
+            typeof repeatY === 'number' ? repeatY : t.repeat.y
+          );
+        }
+        t.offset.x = offsetX;
+        if (mirrorX) {
+          t.repeat.x = -Math.abs(t.repeat.x || 1);
+          t.offset.x = (t.offset.x + 1) % 1;
+        }
+        t.needsUpdate = true;
+      };
+
+      if (shouldMirrorDuplicate && tex.image && typeof document !== 'undefined') {
+        // Create a mirrored duplicate without any blending
+        const img = tex.image;
+        try {
+          const canvas = document.createElement('canvas');
+          canvas.width = img.width * 2;
+          canvas.height = img.height;
+          const ctx = canvas.getContext('2d');
+
+          // Left half: original
+          ctx.drawImage(img, 0, 0, img.width, img.height);
+          // Right half: horizontally flipped copy
+          ctx.save();
+          ctx.translate(img.width, 0);
+          ctx.scale(-1, 1);
+          ctx.drawImage(img, -img.width, 0, img.width, img.height);
+          ctx.restore();
+
+          const processedTex = new THREE.CanvasTexture(canvas);
+          processedTex.colorSpace = THREE.SRGBColorSpace;
+          processedTex.generateMipmaps = true;
+          processedTex.anisotropy = 8;
+
+          applyWrapOptions(processedTex);
+          material.map = processedTex;
+          material.needsUpdate = true;
+        } catch (e) {
+          // Fallback: use mirrored repeat directly
+          tex.wrapS = THREE.MirroredRepeatWrapping;
+          tex.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+          tex.repeat.x = Math.max(2, typeof repeatX === 'number' ? repeatX : 2);
+          applyWrapOptions(tex);
+          material.map = tex;
+          material.needsUpdate = true;
+        }
+      } else {
+        // Equirectangular or no canvas: just use original texture without any edge processing
+        applyWrapOptions(tex);
+        material.map = tex;
+        material.needsUpdate = true;
+      }
+    } catch (e) {
+      console.warn('[worldTexture] Failed to load texture:', e);
+    }
+  }
+
+  if (flags) applyFlagsToMaterial(material, flags);
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.position.set(0, 0, 0);
+
+  // NEW: add cloud shell before glow
+  if (cloudsEnabled) {
+    const cloudMesh = await createCloudShell({
+      baseGeometry: geometry,
+      baseRadius: radius,
+      widthSegments: widthSegs,
+      heightSegments: heightSegs,
+      textureUrl: cloudsTextureUrl,
+      color: cloudsColor,
+      opacity: cloudsOpacity,
+      speed: cloudsSpeed,
+    });
+    mesh.add(cloudMesh);
+  }
+
+  // Optionally add glow as a child of the mesh so it follows transforms
+  if (glow) {
+    const glowMesh = createGlow(glowRimHex, glowFacingHex);
+    mesh.add(glowMesh);
+  }
+
+  return mesh;
+}
+