entangled-worlds-orbiters-shared
v6.0.3
Published
Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components
Maintainers
Readme
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
- Loaders: Texture and GLB loading utilities
- Core Rendering: Lighting, Fresnel effects, and material utilities
- Configuration: Texture and configuration management system
Installation
npm install entangled-worlds-orbiters-sharedTest locally
In entangled-worlds-orbiters-shared/:
npm install
npm run build # consumers run dist/: build again after every change
npm linkIn the consuming app (entangled-worlds/ or orbiters/):
npm link entangled-worlds-orbiters-sharedUsage
// Import specific modules
import { WorldManager } from 'entangled-worlds-orbiters-shared/world';
import { MoonsManager } from 'entangled-worlds-orbiters-shared/moons';
// Or import everything
import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';Modules
World System
WorldManager- Main world orchestrationworldTexture- Textured sphere generationworldNormal- Normal material spheresworldGLB- GLB model loadingcloudShell- Cloud rendering system
Moons System
MoonsManager- Moons orchestrationmoonsGeneration- Moon generation logic
Loaders
glbLoader- GLB loading utilitiesbodyTextureLoader- Texture loading
Core
lights- Lighting setuplightFresnel- Fresnel glow effects
Utils
materials- Material utilitiesdispose- Memory management
Configuration
textureConfig- Texture configuration system
Star (entangled-worlds-orbiters-shared/star)
createStar,StarManager- The host star of a world: single, binary or trinary, emissive, shader-only glow (two draw calls for any multiplicity; lights nothing)DEFAULT_STAR_PARAMS,normalizeStarParams- Author params (temperature, radius, luminosity, activity, multiplicity, separation, seed, placement) + validator for stored paramsstarParamsFromStellarData- Catalogue host-star data (Teff, radius, mass, luminosity, spectral type, star count or a "(AB)b" name suffix) → paramsblackbodyColor,spectralClass,starLayout,starPositions- Pure colour / layout / orbit helpersgetFocus(oncreateStar/StarManager),framingDistance,defaultStarPlacement- Camera focus on the system barycentre and the default placement (over the camera's shoulder, so worlds open on their day side)- The star lights the scene:
StarManagerkey + camera-side fill lights,setLighting,lightingFromLegacy,DEFAULT_AMBIENT(pair withsetHemisphereEnabled(scene, false)from./core; moonsemissiveLift, GLBemissiveIntensityfor night sides) - Real binaries (close pair from component masses, a distant companion for wide pairs) and an optional debris disc;
mainSequenceTemperature/Radius/Luminosityhelpers - Perf + look harness:
npm run bench:star(seebench/star/results/REPORT.md)
Capabilities → moved
The capability registry (createCapabilityRegistry, validate / assertValid, the error taxonomy) moved to its own package, plantasia.space-orchidea/capabilities (removed here in 3.0.0).
Studio session (entangled-worlds-orbiters-shared/studio)
createHistory- Snapshot undo/redo with injected snapshot/restorecreateAutosaveSession- Debounced autosave state machine (dirty / in flight / queued / host ack)createPatchStore,makeHeaderBroadcast- Header mirror for a UI that mounts after the controllercreateStatusChannel- Status-line seam ("Saving…", "Saved")isTrustedHostOrigin,isEmbedded,postToHost- Host-frame transport
Note head programs (entangled-worlds-orbiters-shared/faust)
buildVoiceProgram,buildHeadPrograms- Compose a rack's note head into FAUST source, keyed by shapeexportHead- Compose, compile, shrink, size and stamp a head's programs; the compiler and the shrink tool are handed inrecipesFingerprint,readRecipes,readHeadShape,programsNamespace- The recipes file a build publishes, and the checks a release step makes on itlargestFunction,shrinkWasm- The size check and the shrink step
Keyboard shortcuts (entangled-worlds-orbiters-shared/shortcuts)
ShortcutAction- One catalogue entry:id,label(+namesby language),defaultKeys(named as a US keyboard names them,event.code; a press matches by the character it types, by its place only where it types no US character, so keys work on any keyboard),scopematchShortcut(event, bindings)- Which action a press is, ornull: modifiers, a field being typed in and surface claims decided in one place- Key strings:
Shift+KeyR,Mod+KeyZ(Ctrl or ⌘),Shift?+KeyQ(Shift may be held);parseChord,chordsOverlap resolveBindings(catalogue, overrides),findClashes- Defaults plus a person's overrides ([{ id, keys }]as their settings store them,keys: []unbinds), and the clash checkclaimKeys,isKeyClaimed- A surface (an on-screen keyboard) takes letters away from the shortcuts while it is upcreateShortcutSource({ readCatalogue, readAccount })- The catalogue (every app's actions and default keys, served by the backend: this package holds none) and a person's own keys, read at start and again when the page comes back to the front;actions(...sectionIds),bindings(actions),subscribeparseCatalogue,sectionActions,findSection,shortcutApps,localName- Reading a served catalogue and its names in a language
Uploads (entangled-worlds-orbiters-shared/uploads)
uploadViaSignedUrl- The API's signed-URL upload:/spaces/upload-init→ PUT →/spaces/upload-complete, over the app's own authenticated JSON callerputToSignedUrl- The storage PUT alone, with progress and abort
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:
- 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.
- 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_BASEvia env (Vite) or setwindow.VITE_PUBLIC_HERBARIUM_BASEbefore using the library. - Use
setPublicBasewhen 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/textureConfighelpers are absolute. - Moons generation resolves relative paths against the configured base.
- Cloud shell textures passed to
world.makeSphereare resolved to absolute URLs.
Peer Dependencies
This library requires Three.js as a peer dependency:
npm install threeLicense
MIT © Plantasia Space.
