entangled-worlds-orbiters-shared 3.1.0 → 3.3.0

package/src/star/framing.ts

@@ -1,8 +1,7 @@
 // Camera framing helpers (pure, no three): how far a camera must sit to fit a focus sphere, and a
-// host-camera-aware default placement for the star so it reads beside the planet, not behind it.
+// default placement for the star that lights the planet's side facing the camera.
 
-import { FOCUS_GLOW_RADII } from './layout.js';
-import { DEFAULT_STAR_PARAMS, STAR_PARAM_RANGES } from './params.js';
+import { DEFAULT_STAR_PARAMS } from './params.js';
 
 const DEG = Math.PI / 180;
 
@@ -35,62 +34,25 @@ export interface StarPlacementInput {
 export interface StarPlacement {
   azimuth: number;
   elevation: number;
-  /** False when no in-frame spot clears the planet (it fills the frame); the star is then just above it. */
+  /** Always true (kept for older hosts): the spot is behind any camera closer than ~0.79 × the star's distance (≥ 15.8 units). */
   fits: boolean;
 }
 
 /**
- * Azimuth / elevation that put the primary's disc (plus its bright glow) just outside the planet's
- * angular disc and inside the frame of a camera on +Z looking at the origin — upper-right when there
- * is room, swinging towards straight up as the frame narrows (portrait). Hosts use it only when the
- * author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the host-agnostic fallback.
+ * The opening light: the star over the camera's right shoulder (behind it, a little up and to the
+ * right), so the planet opens on its day side — about 90% of the face the camera sees is lit, the
+ * night edge on the left — and the star itself shows when the viewer orbits round. 145° / 15° is
+ * ~38° off the view axis. It is `DEFAULT_STAR_PARAMS`' direction, so a host with no camera gets it too.
  */
-export function defaultStarPlacement(input: StarPlacementInput): StarPlacement {
-  const fov = Number.isFinite(input.fovDeg) && input.fovDeg > 0 ? input.fovDeg : 45;
-  const aspect = Number.isFinite(input.aspect) && input.aspect > 0 ? input.aspect : 1;
-  const cd = Number.isFinite(input.cameraDistance) && input.cameraDistance > 0 ? input.cameraDistance : 4;
-  const pr = Math.max(0, Number.isFinite(input.planetRadius) ? input.planetRadius : 1);
-  const starRadius = input.starRadius ?? DEFAULT_STAR_PARAMS.radius;
-  const [dLo, dHi] = STAR_PARAM_RANGES.distance;
-  const D = Math.min(dHi, Math.max(dLo, input.distance ?? DEFAULT_STAR_PARAMS.distance));
+export const OVER_THE_SHOULDER = { azimuth: DEFAULT_STAR_PARAMS.azimuth, elevation: DEFAULT_STAR_PARAMS.elevation } as const;
 
-  // Work on the image plane at unit distance (tangent units): positions and radii both scale by tan.
-  const tanV = Math.tan((fov * DEG) / 2);
-  const tanH = tanV * aspect;
-  const planetTan = cd > pr ? pr / Math.sqrt(cd * cd - pr * pr) : Infinity;
-  const starTan = (starRadius * FOCUS_GLOW_RADII) / Math.sqrt(D * D + cd * cd);
-  const rho = planetTan + starTan * 1.35; // centre distance from the view axis: disc + glow clear the planet
-  const maxX = tanH * 0.97 - starTan * 0.5; // centre in frame, disc mostly in frame
-  const maxY = tanV * 0.97 - starTan * 0.5;
-
-  let x = 0;
-  let y = Number.isFinite(rho) ? rho : maxY;
-  let fits = false;
-  for (let phiDeg = 30; phiDeg <= 90; phiDeg += 2) {
-    const px = rho * Math.cos(phiDeg * DEG);
-    const py = rho * Math.sin(phiDeg * DEG);
-    if (px <= maxX && py <= maxY) {
-      x = px;
-      y = py;
-      fits = true;
-      break;
-    }
-  }
-
-  // Ray from the camera through (x, y) on the image plane, hit on the sphere |P| = D.
-  const len = Math.hypot(x, y, 1);
-  const ux = x / len;
-  const uy = y / len;
-  const uz = -1 / len;
-  const cu = cd * uz; // C · u with C = (0, 0, cd)
-  const t = -cu + Math.sqrt(Math.max(0, cu * cu - cd * cd + D * D));
-  const px = ux * t;
-  const py = uy * t;
-  const pz = cd + uz * t;
-  const round = (v: number) => Math.round(v * 10) / 10;
-  return {
-    azimuth: round(Math.atan2(px, -pz) / DEG),
-    elevation: round(Math.asin(Math.max(-1, Math.min(1, py / D))) / DEG),
-    fits,
-  };
+/**
+ * Azimuth / elevation of the default star for a camera on +Z looking at the origin: over the
+ * camera's shoulder (`OVER_THE_SHOULDER`), so the world opens lit. The star sits ≥ 0.79 × its
+ * distance (≥ 15.8 units) out on +Z, behind any host camera, so the frame never changes it. Hosts
+ * use it only when the author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the
+ * host-agnostic fallback.
+ */
+export function defaultStarPlacement(_input?: StarPlacementInput): StarPlacement {
+  return { azimuth: OVER_THE_SHOULDER.azimuth, elevation: OVER_THE_SHOULDER.elevation, fits: true };
 }

package/src/star/index.ts

@@ -19,7 +19,7 @@ export type { StarParams, StarMultiplicity, SpectralClass } from './params.js';
 export { blackbodyColor } from './blackbody.js';
 export type { RGB } from './blackbody.js';
 export { starLayout, starPositions, starSystemPosition, starFocusRadius, flareAt } from './layout.js';
-export { framingDistance, defaultStarPlacement } from './framing.js';
+export { framingDistance, defaultStarPlacement, OVER_THE_SHOULDER } from './framing.js';
 export type { StarPlacement, StarPlacementInput } from './framing.js';
 export type { StarLayout, LaidOutStar, StarOrbit, StarRole, FlareState } from './layout.js';
 export {

package/src/star/layout.ts

@@ -203,8 +203,7 @@ export function starsReach(layout: Pick<StarLayout, 'stars' | 'pairOrbit'>): num
 function distantFor(p: StarParams, reach: number): StarLayout['distant'] {
   if (!p.distantCompanion) return null;
   const r = createLcg(`${p.seed}|distant`);
-  // Default: up and back towards the frame's centre from the host — above the planet rather than
-  // behind it, and inside a typical frame when the host itself is placed beside the planet.
+  // Default: a little above the host and swung towards the scene's −Z axis — never on top of it.
   const inward = p.azimuth >= 0 ? -1 : 1;
   let azimuth = p.distantAzimuth ?? wrapDeg(p.azimuth + inward * lerp(12, 22, r()));
   let elevation = p.distantElevation ?? Math.min(60, p.elevation + lerp(6, 11, r()));

package/src/star/params.ts

@@ -55,8 +55,9 @@ export const DEFAULT_STAR_PARAMS: Readonly<StarParams> = Object.freeze({
   separation: 2,
   seed: 1,
   distance: 20,
-  azimuth: 16,
-  elevation: 10,
+  // Over the camera's shoulder (`OVER_THE_SHOULDER` in framing.ts): worlds open on their day side.
+  azimuth: 145,
+  elevation: 15,
   companionTemperatureK: 0,
   companionRadius: 0,
   distantCompanion: false,

package/src/world/cloudShell.js

@@ -53,6 +53,19 @@ async function makeTextureMaterial({
   return mat;
 }
 
+/**
+ * @param {object} [opts]
+ * @param {import('three').BufferGeometry} [opts.baseGeometry] cloned for the shell; when absent a
+ *   sphere is built from `baseRadius` and the segment counts.
+ * @param {number} [opts.baseRadius=0.5]
+ * @param {number} [opts.widthSegments=64]
+ * @param {number} [opts.heightSegments=64]
+ * @param {string} [opts.textureUrl]
+ * @param {number} [opts.color=0xffffff]
+ * @param {number} [opts.opacity=0.6]
+ * @param {number} [opts.speed=0.015]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer]
+ */
 export async function createCloudShell({
   baseGeometry,
   baseRadius = 0.5,

package/src/world/index.js

@@ -3,4 +3,6 @@ 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';
+export { createCloudShell } from './cloudShell.js';
+
+/** @typedef {import('./worldManager.js').WorldCreator} WorldCreator */

package/src/world/worldGLB.js

@@ -1,6 +1,17 @@
 import { loadGLB } from '../loaders/glbLoader.js';
 
-/** `emissiveIntensity`: textured self-glow (1 = old flat-lit look; ≈0.15 under a star light). */
+/**
+ * `emissiveIntensity`: textured self-glow (1 = old flat-lit look; ≈0.15 under a star light).
+ *
+ * @param {object} [opts]
+ * @param {string} opts.modelUrl REQUIRED; throws without it.
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {number} [opts.retries=3]
+ * @param {boolean} [opts.withCredentials=false]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED at runtime (`loadGLB` throws
+ *   without one); nullable here because `WorldManager` threads its own, which may be null.
+ * @param {number} [opts.emissiveIntensity]
+ */
 export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false, renderer, emissiveIntensity } = {}) {
   if (!modelUrl) throw new Error('modelUrl is required');
   const obj = await loadGLB(modelUrl, { retries, applyFlags: flags, withCredentials, renderer, emissiveIntensity });

package/src/world/worldManager.js

@@ -3,7 +3,22 @@ import { makeGLB } from './worldGLB.js';
 import { makeSphere } from './worldTexture.js';
 import { makeNormalSphere } from './worldNormal.js';
 
+/**
+ * Builds a world object for a mode registered with `registerWorldCreator`. It receives the manager's
+ * flags, the `setMode` args and the renderer, and may return the object or a promise of it (the
+ * manager awaits either).
+ * @typedef {(args: { flags: object, renderer: import('three').WebGLRenderer | null, [key: string]: unknown }) => import('three').Object3D | Promise<import('three').Object3D>} WorldCreator
+ */
+
 export class WorldManager {
+  /**
+   * @param {import('three').Scene} scene
+   * @param {object} [opts]
+   * @param {() => void} [opts.onLoadStart]
+   * @param {() => void} [opts.onLoadEnd]
+   * @param {import('three').WebGLRenderer | null} [opts.renderer]
+   * @param {boolean} [opts.externalTick=false]
+   */
   constructor(scene, { onLoadStart, onLoadEnd, renderer, externalTick = false } = {}) {
     this.scene = scene;
     // The renderer this world belongs to — threaded to the texture loaders so each view's textures
@@ -16,6 +31,7 @@ export class WorldManager {
     // defeating the one-loop compositor.
     this.externalTick = Boolean(externalTick);
     this.current = null;
+    /** @type {Record<string, any>} */
     this.flags = {};
     this.onLoadStart = onLoadStart;
     this.onLoadEnd = onLoadEnd;
@@ -24,7 +40,10 @@ export class WorldManager {
     this.customCreators = new Map();
   }
 
-  /** Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise). */
+  /**
+   * Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise).
+   * @param {number} timeSec
+   */
   tick(timeSec) {
     if (!this.externalTick || !this.current) return;
     const updater = this.current.userData?.update;
@@ -38,6 +57,7 @@ export class WorldManager {
     }
   }
 
+  /** @param {object} flags merged over the current flags */
   setFlags(flags) {
     this.flags = { ...this.flags, ...flags };
   }
@@ -51,10 +71,21 @@ export class WorldManager {
   }
 
   // Register custom world creators for app-specific world types
+  /**
+   * @param {number} mode
+   * @param {WorldCreator} creatorFunction
+   */
   registerWorldCreator(mode, creatorFunction) {
     this.customCreators.set(mode, creatorFunction);
   }
 
+  /**
+   * Build and show the world for `mode` (a registered creator, 2 = GLB, 3 = normal sphere, else the
+   * textured sphere), replacing the current one. A newer call supersedes one still loading.
+   * @param {number} mode
+   * @param {Record<string, any>} [args]
+   * @returns {Promise<void>}
+   */
   async setMode(mode, args = {}) {
     const myToken = ++this.token;
     this.onLoadStart?.();

package/src/world/worldNormal.js

@@ -9,6 +9,25 @@ import { resolvePublicUrl } from '../config/env.js';
 /**
  * Create a simple sphere using THREE.MeshNormalMaterial.
  * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.sphereRadius]
+ * @param {number} [opts.sphereWidthSegments]
+ * @param {number} [opts.sphereHeightSegments]
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {boolean} [opts.glow] add the fresnel halo.
+ * @param {number} [opts.glowScale=1.18]
+ * @param {number} [opts.glowRimHex=0x66ccff]
+ * @param {number} [opts.glowFacingHex=0x000000]
+ * @param {number} [opts.glowBias=0.02]
+ * @param {number} [opts.glowFresnelScale=1]
+ * @param {number} [opts.glowPower=3.5]
+ * @param {boolean} [opts.cloudsEnabled]
+ * @param {string} [opts.cloudsTextureUrl]
+ * @param {number} [opts.cloudsColor=0xffffff]
+ * @param {number} [opts.cloudsOpacity=0.6]
+ * @param {number} [opts.cloudsSpeed=0.015]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer]
  */
 export async function makeNormalSphere({
   sphereRadius,

package/src/world/worldTexture.js

@@ -50,6 +50,47 @@ function isLikelyEquirectangular(img) {
   return false;
 }
 
+/**
+ * The textured world sphere. Every option is optional. The offset, repeat, rotation, flip and sphere
+ * geometry options are read only when they have their type; the rest are used as given (`glow`,
+ * `cloudsEnabled` and `mirrorX` by truthiness).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.textureUrl]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED for a KTX2 texture.
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {number} [opts.uOffset] horizontal texture offset, 0..1 (wins over `textureOffsetDeg`).
+ * @param {number} [opts.textureOffsetDeg] horizontal texture offset in degrees.
+ * @param {boolean} [opts.mirrorX]
+ * @param {boolean} [opts.mirrorDuplicateX] explicit override of the equirectangular detection.
+ * @param {boolean} [opts.autoDetectEquirectangular=true]
+ * @param {boolean} [opts.forceEquirectangular=false]
+ * @param {boolean} [opts.forceRectangular=false]
+ * @param {string} [opts.wrapS='repeat'] `'clamp'`, `'repeat'` or `'mirror'`.
+ * @param {string} [opts.wrapT='clamp'] `'clamp'`, `'repeat'` or `'mirror'`.
+ * @param {number} [opts.repeatX]
+ * @param {number} [opts.repeatY]
+ * @param {number} [opts.rotationDeg]
+ * @param {number[]} [opts.center=[0.5, 0.5]] texture rotation centre, `[u, v]`.
+ * @param {boolean} [opts.flipY]
+ * @param {number} [opts.sphereRadius]
+ * @param {number} [opts.sphereWidthSegments]
+ * @param {number} [opts.sphereHeightSegments]
+ * @param {number} [opts.materialRoughness] accepted from saved worlds; no longer changes the look.
+ * @param {number} [opts.materialMetalness] accepted from saved worlds; no longer changes the look.
+ * @param {boolean} [opts.glow=true]
+ * @param {number} [opts.glowRimHex=0x66ccff]
+ * @param {number} [opts.glowFacingHex=0x000000]
+ * @param {number} [opts.glowScale=1.18]
+ * @param {number} [opts.glowBias=0.02]
+ * @param {number} [opts.glowFresnelScale=1]
+ * @param {number} [opts.glowPower=3.5]
+ * @param {boolean} [opts.cloudsEnabled=false]
+ * @param {string} [opts.cloudsTextureUrl]
+ * @param {number} [opts.cloudsColor=0xffffff]
+ * @param {number} [opts.cloudsOpacity=0.6]
+ * @param {number} [opts.cloudsSpeed=0.015]
+ */
 export async function makeSphere({
   textureUrl,
   renderer,