entangled-worlds-orbiters-shared 1.0.0

package/src/arrow-ui/utils/getColorFormat.js

@@ -0,0 +1,75 @@
+import normalizeColorString from './normalizeColorString';
+
+const STRING = {
+	isPrimitive: true,
+	match: v => typeof v === 'string',
+	fromHexString: normalizeColorString,
+	toHexString: normalizeColorString
+};
+
+const INT = {
+	isPrimitive: true,
+	match: v => typeof v === 'number',
+	fromHexString: string => parseInt( string.substring( 1 ), 16 ),
+	toHexString: value => '#' + value.toString( 16 ).padStart( 6, 0 )
+};
+
+const ARRAY = {
+	isPrimitive: false,
+
+	// The arrow function is here to appease tree shakers like esbuild or webpack.
+	// See https://esbuild.github.io/api/#tree-shaking
+	match: v => Array.isArray( v ),
+
+	fromHexString( string, target, rgbScale = 1 ) {
+
+		const int = INT.fromHexString( string );
+
+		target[ 0 ] = ( int >> 16 & 255 ) / 255 * rgbScale;
+		target[ 1 ] = ( int >> 8 & 255 ) / 255 * rgbScale;
+		target[ 2 ] = ( int & 255 ) / 255 * rgbScale;
+
+	},
+	toHexString( [ r, g, b ], rgbScale = 1 ) {
+
+		rgbScale = 255 / rgbScale;
+
+		const int = ( r * rgbScale ) << 16 ^
+			( g * rgbScale ) << 8 ^
+			( b * rgbScale ) << 0;
+
+		return INT.toHexString( int );
+
+	}
+};
+
+const OBJECT = {
+	isPrimitive: false,
+	match: v => Object( v ) === v,
+	fromHexString( string, target, rgbScale = 1 ) {
+
+		const int = INT.fromHexString( string );
+
+		target.r = ( int >> 16 & 255 ) / 255 * rgbScale;
+		target.g = ( int >> 8 & 255 ) / 255 * rgbScale;
+		target.b = ( int & 255 ) / 255 * rgbScale;
+
+	},
+	toHexString( { r, g, b }, rgbScale = 1 ) {
+
+		rgbScale = 255 / rgbScale;
+
+		const int = ( r * rgbScale ) << 16 ^
+			( g * rgbScale ) << 8 ^
+			( b * rgbScale ) << 0;
+
+		return INT.toHexString( int );
+
+	}
+};
+
+const FORMATS = [ STRING, INT, ARRAY, OBJECT ];
+
+export default function( value ) {
+	return FORMATS.find( format => format.match( value ) );
+}

package/src/arrow-ui/utils/injectStyles.js

@@ -0,0 +1,10 @@
+export default function( cssContent ) {
+	const injected = document.createElement( 'style' );
+	injected.innerHTML = cssContent;
+	const before = document.querySelector( 'head link[rel=stylesheet], head style' );
+	if ( before ) {
+		document.head.insertBefore( injected, before );
+	} else {
+		document.head.appendChild( injected );
+	}
+}

package/src/arrow-ui/utils/normalizeColorString.js

@@ -0,0 +1,29 @@
+/* eslint-disable no-cond-assign */
+
+export default function( string ) {
+
+	let match, result;
+
+	if ( match = string.match( /(#|0x)?([a-f0-9]{6})/i ) ) {
+
+		result = match[ 2 ];
+
+	} else if ( match = string.match( /rgb\(\s*(\d*)\s*,\s*(\d*)\s*,\s*(\d*)\s*\)/ ) ) {
+
+		result = parseInt( match[ 1 ] ).toString( 16 ).padStart( 2, 0 )
+			+ parseInt( match[ 2 ] ).toString( 16 ).padStart( 2, 0 )
+			+ parseInt( match[ 3 ] ).toString( 16 ).padStart( 2, 0 );
+
+	} else if ( match = string.match( /^#?([a-f0-9])([a-f0-9])([a-f0-9])$/i ) ) {
+
+		result = match[ 1 ] + match[ 1 ] + match[ 2 ] + match[ 2 ] + match[ 3 ] + match[ 3 ];
+
+	}
+
+	if ( result ) {
+		return '#' + result;
+	}
+
+	return false;
+
+}

package/src/config/index.js

@@ -0,0 +1,8 @@
+// Configuration exports
+export { 
+  loadTextureConfig, 
+  getTextureOptions, 
+  getDefaultTexture, 
+  getSkyboxOptions, 
+  getDefaultSkybox 
+} from './textureConfig.js';

package/src/config/textureConfig.js

@@ -0,0 +1,299 @@
+/**
+ * Texture Configuration Loader
+ * Loads texture definitions from local config file or remote endpoint
+ */
+
+const DEFAULT_CONFIG_URL = '/config/textures.json';
+const FALLBACK_CONFIG_URL = 'https://api.entangled-worlds.com/config/textures.json'; // Future endpoint
+
+let cachedConfig = null;
+let configPromise = null;
+
+/**
+ * Load texture configuration from local file or remote endpoint
+ * @param {string} configUrl - Override default config URL
+ * @param {boolean} useCache - Whether to use cached config if available
+ * @returns {Promise<Object>} Texture configuration object
+ */
+export async function loadTextureConfig(configUrl = DEFAULT_CONFIG_URL, useCache = true) {
+  if (useCache && cachedConfig) {
+    console.log('[TextureConfig] Using cached config');
+    return cachedConfig;
+  }
+
+  if (configPromise) {
+    console.log('[TextureConfig] Using in-flight request');
+    return configPromise;
+  }
+
+  configPromise = (async () => {
+    try {
+      console.log('[TextureConfig] Loading from:', configUrl);
+      const response = await fetch(configUrl);
+      
+      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;
+      console.log('[TextureConfig] Loaded successfully:', {
+        version: config.version,
+        categories: Object.keys(config.textures),
+        lastUpdated: config.lastUpdated
+      });
+
+      return config;
+    } catch (error) {
+      console.error('[TextureConfig] Failed to load config:', error);
+      
+      // If primary URL fails and it's not already the fallback, try fallback
+      if (configUrl !== FALLBACK_CONFIG_URL) {
+        console.log('[TextureConfig] Trying fallback endpoint...');
+        try {
+          return await loadTextureConfig(FALLBACK_CONFIG_URL, false);
+        } catch (fallbackError) {
+          console.error('[TextureConfig] Fallback also failed:', fallbackError);
+        }
+      }
+
+      // Return minimal fallback configuration
+      console.warn('[TextureConfig] Using hardcoded fallback config');
+      return getHardcodedFallback();
+    } finally {
+      configPromise = null;
+    }
+  })();
+
+  return configPromise;
+}
+
+/**
+ * Get texture options for a specific category (clouds, moons, etc.)
+ * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object>} Options object suitable for lil-gui dropdowns
+ */
+export async function getTextureOptions(category, config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  const categoryConfig = textureConfig.textures[category];
+  
+  if (!categoryConfig) {
+    console.warn(`[TextureConfig] Category '${category}' not found`);
+    return {};
+  }
+
+  const options = {};
+  const baseUrl = textureConfig.baseUrl || '/default';
+  const categoryPath = categoryConfig.basePath || `/${category}`;
+
+  categoryConfig.items.forEach(item => {
+    const key = item.label || item.id;
+    const relativePath = `${baseUrl}${categoryPath}/${item.filename || item.id}`;
+    options[key] = relativePath;
+  });
+
+  return options;
+}
+
+/**
+ * Get default texture for a category
+ * @param {string} category - Texture category
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default texture path
+ */
+export async function getDefaultTexture(category, config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  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 `${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 null;
+}
+
+/**
+ * Get texture by ID within a category
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object|null>} Texture definition object
+ */
+export async function getTextureById(category, textureId, config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  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 {Object} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export async function getTextureUrl(category, textureId, config = null) {
+  const texture = await getTextureById(category, textureId, config);
+  if (!texture) return null;
+
+  const textureConfig = config || await loadTextureConfig();
+  const categoryConfig = textureConfig.textures[category];
+  const baseUrl = textureConfig.baseUrl || '/default';
+  const categoryPath = categoryConfig.basePath || `/${category}`;
+  
+  return `${baseUrl}${categoryPath}/${texture.filename || texture.id}`;
+}
+
+/**
+ * Search textures by tags
+ * @param {string} category - Texture category
+ * @param {string[]} tags - Tags to search for
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object[]>} Array of matching texture definitions
+ */
+export async function searchTexturesByTags(category, tags, config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  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 {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object>} Options object with labels and IDs
+ */
+export async function getSkyboxOptions(config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  const skyboxConfig = textureConfig.textures.skyboxes;
+  
+  if (!skyboxConfig) {
+    console.warn('[TextureConfig] Skyboxes category not found');
+    return {};
+  }
+
+  const options = {};
+  
+  skyboxConfig.items.forEach(item => {
+    const label = item.label || item.id;
+    const id = item.id;
+    options[label] = id;
+  });
+
+  return options;
+}
+
+/**
+ * Get default skybox ID
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export async function getDefaultSkybox(config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  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<Object>} Fresh configuration object
+ */
+export async function reloadTextureConfig(configUrl = DEFAULT_CONFIG_URL) {
+  cachedConfig = null;
+  configPromise = null;
+  return loadTextureConfig(configUrl, false);
+}
+
+/**
+ * Get configuration metadata
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object>} Configuration metadata
+ */
+export async function getConfigMetadata(config = null) {
+  const textureConfig = config || await loadTextureConfig();
+  return {
+    version: textureConfig.version,
+    lastUpdated: textureConfig.lastUpdated,
+    categories: Object.keys(textureConfig.textures),
+    totalTextures: Object.values(textureConfig.textures).reduce(
+      (sum, cat) => sum + (cat.items ? cat.items.length : 0), 0
+    )
+  };
+}

package/src/core/index.js

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

package/src/core/lightFresnel.js

@@ -0,0 +1,64 @@
+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/src/core/lights.js

@@ -0,0 +1,43 @@
+import * as THREE from 'three';
+
+let hemiRef = null;
+let ambientRef = null;
+
+export function ensureDefaultLights(scene) {
+  if (!hemiRef) {
+    hemiRef = new THREE.HemisphereLight(0xffffff, 0xffffff, 1.0);
+    hemiRef.position.set(1, 1, 1);
+    hemiRef.name = 'ew_HemisphereLight';
+    scene.add(hemiRef);
+  }
+  if (!ambientRef) {
+    ambientRef = new THREE.AmbientLight(0xffffff, 1.0);
+    ambientRef.name = 'ew_AmbientLight';
+    scene.add(ambientRef);
+  }
+  return { hemi: hemiRef, ambient: ambientRef };
+}
+
+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();
+    }
+  }
+}
+
+// Back-compat helper
+export function addDefaultLights(scene) {
+  return ensureDefaultLights(scene);
+}

package/src/index.js

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

package/src/loaders/bodyTextureLoader.js

@@ -0,0 +1,39 @@
+import * as THREE from 'three';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+
+const textureLoader = new THREE.TextureLoader();
+
+// Shared singleton accessor (align with cubeMapLoader)
+function getSharedKTX2Loader() {
+  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
+  const renderer = window.__EW_RENDERER;
+  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+  window.__EW_KTX2_LOADER = loader;
+  return loader;
+}
+
+export function loadTexture(url, { signal } = {}) {
+  return new Promise((resolve, reject) => {
+    if (url && url.endsWith('.ktx2')) {
+      const ktx2 = getSharedKTX2Loader();
+      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')));
+    }
+  });
+}