entangled-worlds-orbiters-shared 1.0.0 → 1.0.2

package/README.md

@@ -62,6 +62,48 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 ### Configuration
 - `textureConfig` - Texture configuration system
 
+## Runtime base configuration (env)
+
+This package is built statically. At runtime, it can use a public base URL to turn relative asset paths into absolute URLs. If you don’t provide a base, it will use same-origin root-relative paths (e.g., `/default/...`).
+
+You have two ways to provide it:
+
+1) Environment variables (no code needed):
+
+If your bundler/framework defines `import.meta.env.VITE_PUBLIC_HERBARIUM_BASE` (Vite) or you set `window.VITE_PUBLIC_HERBARIUM_BASE` (before the library runs), the library will pick it up automatically.
+
+2) Programmatic override (recommended for portability):
+
+```js
+import { setPublicBase, loadTextureConfig } from 'entangled-worlds-orbiters-shared/config';
+
+// Call this early at app startup (optional if you use envs/window)
+setPublicBase(
+	(typeof import.meta !== 'undefined' && import.meta.env && import.meta.env.VITE_PUBLIC_HERBARIUM_BASE) ||
+	(typeof process !== 'undefined' && process.env && process.env.NEXT_PUBLIC_HERBARIUM_BASE)
+);
+
+// Optionally preload a remote config file
+// await loadTextureConfig('https://your-cdn/config/textures.json');
+```
+
+Is setPublicBase required?
+
+- Not required. If you don’t provide any base (via env/window/programmatic), the library will use same-origin root-relative URLs.
+- Also not required if you provide `VITE_PUBLIC_HERBARIUM_BASE` via env (Vite) or set `window.VITE_PUBLIC_HERBARIUM_BASE` before using the library.
+- Use `setPublicBase` when you want to:
+	- Override the base at runtime (e.g., switch between staging/production dynamically)
+	- Avoid build-time coupling to a specific bundler env key
+	- Ensure the base is set in environments where env injection isn’t available
+
+Defaults:
+- If nothing is provided, it falls back to same-origin root-relative paths.
+
+Effects:
+- All URLs returned by `config/textureConfig` helpers are absolute.
+- Skybox loader and moons generation resolve relative paths against the configured base.
+- Cloud shell textures passed to `world.makeSphere` are resolved to absolute URLs.
+
 ## Peer Dependencies
 
 This library requires Three.js and three-stdlib as peer dependencies:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -46,4 +46,4 @@
     "url": "https://github.com/plantasia-space-org/entangled-worlds-orbiters-shared/issues"
   },
   "homepage": "https://github.com/plantasia-space-org/entangled-worlds-orbiters-shared#readme"
-}
+}

package/src/config/env.js

@@ -0,0 +1,30 @@
+// Runtime public base URL helper for building absolute asset URLs at runtime
+
+// Mutable module-scoped variable to allow apps to override at startup
+export let __PUBLIC_BASE = null;
+
+// Set the public base (strips trailing slash) and mirror to window for convenience
+export function setPublicBase(url) {
+  __PUBLIC_BASE = (url || '').replace(/\/$/, '');
+  if (typeof window !== 'undefined') window.VITE_PUBLIC_HERBARIUM_BASE = __PUBLIC_BASE;
+}
+
+// Get the current public base from (in order): explicit set value, envs, or default
+export function getPublicBase() {
+  const envVal =
+    (typeof import.meta !== 'undefined' && import.meta.env && import.meta.env.VITE_PUBLIC_HERBARIUM_BASE) ||
+    (typeof window !== 'undefined' && window.VITE_PUBLIC_HERBARIUM_BASE) ||
+    null;
+  const base = (__PUBLIC_BASE || envVal || '').toString();
+  return base ? base.replace(/\/$/, '') : '';
+}
+
+// Resolve a possibly-relative path against the current public base
+export function resolvePublicUrl(path) {
+  if (!path) return path;
+  if (/^https?:\/\//i.test(path)) return path;
+  const base = getPublicBase();
+  const p = path.startsWith('/') ? path : `/${path}`;
+  // If base is empty, return a root-relative path (same-origin)
+  return base ? `${base}${p}` : p;
+}

package/src/config/index.js

@@ -5,4 +5,11 @@ export {
   getDefaultTexture, 
   getSkyboxOptions, 
   getDefaultSkybox 
-} from './textureConfig.js';
+} from './textureConfig.js';
+
+// runtime base helpers
+export {
+  setPublicBase,
+  getPublicBase,
+  resolvePublicUrl
+} from './env.js';

package/src/config/textureConfig.js

@@ -2,6 +2,7 @@
  * Texture Configuration Loader
  * Loads texture definitions from local config file or remote endpoint
  */
+import { resolvePublicUrl } from './env.js';
 
 const DEFAULT_CONFIG_URL = '/config/textures.json';
 const FALLBACK_CONFIG_URL = 'https://api.entangled-worlds.com/config/textures.json'; // Future endpoint
@@ -28,8 +29,10 @@ export async function loadTextureConfig(configUrl = DEFAULT_CONFIG_URL, useCache
 
   configPromise = (async () => {
     try {
-      console.log('[TextureConfig] Loading from:', configUrl);
-      const response = await fetch(configUrl);
+      // Resolve config URL against public base if it's a relative path
+      const resolvedConfigUrl = /^https?:\/\//i.test(configUrl) ? configUrl : resolvePublicUrl(configUrl);
+      console.log('[TextureConfig] Loading from:', resolvedConfigUrl);
+      const response = await fetch(resolvedConfigUrl);
       
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -96,7 +99,7 @@ export async function getTextureOptions(category, config = null) {
   categoryConfig.items.forEach(item => {
     const key = item.label || item.id;
     const relativePath = `${baseUrl}${categoryPath}/${item.filename || item.id}`;
-    options[key] = relativePath;
+    options[key] = resolvePublicUrl(relativePath);
   });
 
   return options;
@@ -121,13 +124,13 @@ export async function getDefaultTexture(category, config = null) {
   const defaultFilename = categoryConfig.defaultTexture;
   
   if (defaultFilename) {
-    return `${baseUrl}${categoryPath}/${defaultFilename}`;
+    return resolvePublicUrl(`${baseUrl}${categoryPath}/${defaultFilename}`);
   }
 
   // Fallback to first item
   if (categoryConfig.items && categoryConfig.items.length > 0) {
     const firstItem = categoryConfig.items[0];
-    return `${baseUrl}${categoryPath}/${firstItem.filename || firstItem.id}`;
+    return resolvePublicUrl(`${baseUrl}${categoryPath}/${firstItem.filename || firstItem.id}`);
   }
 
   return null;
@@ -166,8 +169,7 @@ export async function getTextureUrl(category, textureId, config = null) {
   const categoryConfig = textureConfig.textures[category];
   const baseUrl = textureConfig.baseUrl || '/default';
   const categoryPath = categoryConfig.basePath || `/${category}`;
-  
-  return `${baseUrl}${categoryPath}/${texture.filename || texture.id}`;
+  return resolvePublicUrl(`${baseUrl}${categoryPath}/${texture.filename || texture.id}`);
 }
 
 /**

package/src/loaders/cubeMapLoader.js

@@ -1,8 +1,8 @@
 import * as THREE from 'three';
 import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { getPublicBase } from '../config/env.js';
 
-// Base URL
-const PUBLIC_BASE = (import.meta?.env?.VITE_PUBLIC_HERBARIUM_BASE) || (window?.VITE_PUBLIC_HERBARIUM_BASE) || 'https://dev-herbarium.plantasia.space';
+// Base URL is resolved at runtime via helper
 
 // Shared loader + caches
 const ktx2SupportCache = new Map(); // base -> true|false
@@ -137,6 +137,7 @@ function loadFacesJPG(faceKeys) {
 
 // Resolve relative paths to full URLs
 function resolveUrls(faceKeys) {
+  const PUBLIC_BASE = getPublicBase();
   const resolved = {};
   FACE_ORDER.forEach(face => {
     const url = faceKeys[face];

package/src/moons/moonsGeneration.js

@@ -1,8 +1,9 @@
 import * as THREE from 'three';
 import { loadTexture } from '../loaders/bodyTextureLoader.js';
+import { getPublicBase } from '../config/env.js';
 
 // Resolve public herbarium base (strip trailing slash)
-const HERBARIUM_BASE = (import.meta?.env?.VITE_PUBLIC_HERBARIUM_BASE || 'https://dev-herbarium.plantasia.space').replace(/\/$/, '');
+const HERBARIUM_BASE = getPublicBase();
 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');

package/src/world/worldNormal.js

@@ -2,6 +2,9 @@
 import * as THREE from 'three';
 import { EARTH_RADIUS_UNITS } from './worldTexture.js';
 import { applyFlagsToMaterial } from '../utils/materials.js';
+import { getLightFresnel } from '../core/lightFresnel.js';
+import { createCloudShell } from './cloudShell.js';
+import { resolvePublicUrl } from '../config/env.js';
 
 /**
  * Create a simple sphere using THREE.MeshNormalMaterial.
@@ -12,6 +15,18 @@ export async function makeNormalSphere({
   sphereWidthSegments,
   sphereHeightSegments,
   flags,
+  glow,           // halo (glow) enabled
+  glowScale = 1.18,
+  glowRimHex = 0x66ccff,
+  glowFacingHex = 0x000000,
+  glowBias = 0.02,
+  glowFresnelScale = 1.0,
+  glowPower = 3.5,
+  cloudsEnabled,
+  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;
@@ -21,5 +36,36 @@ export async function makeNormalSphere({
   if (flags) applyFlagsToMaterial(material, flags);
   const mesh = new THREE.Mesh(geometry, material);
   mesh.name = 'worldNormalSphere';
+
+  // Attach halo (glow) effect if enabled
+  if (glow) {
+    const fresnelMat = getLightFresnel({ rimHex: glowRimHex, facingHex: glowFacingHex });
+    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);
+    fresnelMesh.scale.set(glowScale, glowScale, glowScale);
+    fresnelMesh.renderOrder = 999;
+    fresnelMesh.name = 'worldNormalGlow';
+    mesh.add(fresnelMesh);
+  }
+
+  // Attach clouds effect if enabled
+  if (cloudsEnabled) {
+    const cloudMesh = await createCloudShell({
+      baseGeometry: geometry,
+      baseRadius: radius,
+      widthSegments: widthSegs,
+      heightSegments: heightSegs,
+      textureUrl: resolvePublicUrl(cloudsTextureUrl),
+      color: cloudsColor,
+      opacity: cloudsOpacity,
+      speed: cloudsSpeed,
+    });
+    mesh.add(cloudMesh);
+  }
+
   return mesh;
 }

package/src/world/worldTexture.js

@@ -3,6 +3,7 @@ import { loadTexture } from '../loaders/bodyTextureLoader.js';
 import { applyFlagsToMaterial } from '../utils/materials.js';
 import { getLightFresnel } from '../core/lightFresnel.js';
 import { createCloudShell } from './cloudShell.js';
+import { resolvePublicUrl } from '../config/env.js';
 
 export const EARTH_RADIUS_UNITS = 0.5; // scene units
 
@@ -220,7 +221,7 @@ export async function makeSphere({
       baseRadius: radius,
       widthSegments: widthSegs,
       heightSegments: heightSegs,
-      textureUrl: cloudsTextureUrl,
+      textureUrl: resolvePublicUrl(cloudsTextureUrl),
       color: cloudsColor,
       opacity: cloudsOpacity,
       speed: cloudsSpeed,