Entangled Worlds Orbiters Shared Library

A shared library containing core components for 3D world rendering, moons system, and UI components used across Entangled Worlds applications.

Features

• World System: Core world rendering with textured spheres, normal materials, GLB models, and cloud shells
• Moons System: Orbital moon generation and management
• Arrow UI: Reusable UI component system based on lil-gui
• Loaders: Texture, GLB, and cubemap loading utilities
• Core Rendering: Lighting, Fresnel effects, and material utilities
• Configuration: Texture and configuration management system

Installation

npm install entangled-worlds-orbiters-shared

Test locally

In /entangled-worlds-orbiters-shared: npm install npm link

In /entangled-worlds-preview or /orbiters:

npm link entangled-worlds-orbiters-shared

Usage

// Import specific modules
import { WorldManager } from 'entangled-worlds-orbiters-shared/world';
import { MoonsManager } from 'entangled-worlds-orbiters-shared/moons';
import { GUI } from 'entangled-worlds-orbiters-shared/arrow-ui';

// Or import everything
import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';

Modules

World System

• WorldManager - Main world orchestration
• worldTexture - Textured sphere generation
• worldNormal - Normal material spheres
• worldGLB - GLB model loading
• cloudShell - Cloud rendering system

Moons System

• MoonsManager - Moons orchestration
• moonsGeneration - Moon generation logic

Arrow UI

• Complete UI component system based on lil-gui
• Controllers for boolean, color, function, number, option, and string inputs

Loaders

• cubeMapLoader - Skybox loading
• glbLoader - GLB loading utilities
• bodyTextureLoader - Texture loading

Core

• lights - Lighting setup
• lightFresnel - Fresnel glow effects

Utils

• materials - Material utilities
• dispose - Memory management

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):

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:

npm install three three-stdlib

License

MIT