entangled-worlds-orbiters-shared 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.js",
     "./world": "./src/world/index.js",
+    "./minimal": "./src/minimal/index.js",
     "./moons": "./src/moons/index.js",
     "./loaders": "./src/loaders/index.js",
     "./render": "./src/render/index.js",
@@ -42,6 +43,7 @@
   "files": [
     "src/**/*",
     "!src/**/*.test.ts",
+    "!src/**/*.test.js",
     "dist/**/*",
     "public/**/*",
     "README.md",
@@ -90,6 +92,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:render"
+    "test:minimal": "node --test src/minimal/*.test.js",
+    "test": "npm run test:clock && npm run test:render && npm run test:minimal && npm run test:moons",
+    "test:moons": "node --test src/moons/*.test.js"
   }
 }

package/src/minimal/index.js

@@ -0,0 +1,26 @@
+/**
+ * The minimal ("performance mode") look: one cheap lit sphere, one key light, a weak ambient fill,
+ * and nothing else — no texture, no halo, no cloud shell, no skybox.
+ *
+ * Its own entry point rather than a few more names on `./world`, because both consumers want exactly
+ * this and nothing around it: the Orbiters renderer and the Entangled Worlds editor's performance
+ * preview. Keeping it separate means importing the look never drags in the texture/GLB/cloud loaders
+ * that the look exists to avoid.
+ */
+export {
+  createMinimalWorld,
+  resolvePlanetColor,
+  MINIMAL_WORLD_MODE,
+  MINIMAL_MATERIAL_KINDS,
+  MINIMAL_PLANET_COLOR_HEX,
+} from './minimalWorld.js';
+
+export {
+  applyMinimalLighting,
+  removeMinimalLighting,
+  updateMinimalKeyLight,
+  takeSceneLights,
+  DEFAULT_LIGHT_NAMES,
+  MINIMAL_LIGHT_NAME,
+  MINIMAL_FILL_NAME,
+} from './minimalLighting.js';

package/src/minimal/minimalLighting.js

@@ -0,0 +1,137 @@
+/**
+ * @file src/minimal/minimalLighting.js
+ * @description The one light the minimal look keeps.
+ *
+ * Shared for the same reason as `minimalWorld.js`, and more sharply: lighting is what makes two
+ * renders of the same world look like the same world. The editor's performance preview and the
+ * Orbiters render MUST take their key light, their fill and their restore behaviour from this one
+ * module, or an author would tune a world against lighting the public never sees.
+ *
+ * Minimal is not an unlit scene. The moons are a lit material, so a scene with no lights renders them
+ * as black discs, and the planet needs a light for its shape to be legible at all. What it does not
+ * need is the world's usual pair — a hemisphere and an ambient, both white-on-white at full strength,
+ * which light every surface identically and are themselves part of why a sphere reads as a flat disc.
+ *
+ * So: exactly one directional light, no shadows. Its colour and direction come from the world's own
+ * authored lighting where the world provides them, which is how a minimal scene still carries some of
+ * the world's identity without loading anything.
+ */
+import * as THREE from 'three';
+
+/** The shared default lights, by the names the shared package gives them. */
+export const DEFAULT_LIGHT_NAMES = Object.freeze(['ew_HemisphereLight', 'ew_AmbientLight']);
+/** The single light the minimal look keeps. */
+export const MINIMAL_LIGHT_NAME = 'orb_MinimalKeyLight';
+/** The weak ambient that keeps the unlit side from going pure black. */
+export const MINIMAL_FILL_NAME = 'orb_MinimalFillLight';
+
+const DEFAULT_INTENSITY = 1.8;
+const DEFAULT_DIRECTION = Object.freeze({ x: 1, y: 0.6, z: 1 });
+/**
+ * The fill. A single directional light alone puts the unlit side at pure black, which cuts the
+ * silhouette in half instead of rounding it — the terminator reads as a hard edge rather than a
+ * curve. A weak ambient lifts that side just enough for the shape to close.
+ *
+ * Ambient is the cheapest light there is: a constant added per fragment, no direction, no attenuation,
+ * no extra pass, and no shadow map. It is the right way to soften this and the only one worth its cost.
+ */
+const FILL_INTENSITY = 0.55;
+
+function removeLightByName(scene, name) {
+  const light = scene.getObjectByName(name);
+  if (!light) return;
+  scene.remove(light);
+  // Lights hold no geometry or texture, but they do hold a shadow map + camera once shadows have
+  // been on, and `dispose` is what releases it.
+  light.dispose?.();
+}
+
+/**
+ * Detach the world's default lights and hand them back — WITHOUT disposing them.
+ *
+ * They carry the world's authored colour, direction and intensities, and nothing re-applies those
+ * when the mode is switched off inside Studio. Keeping the objects means leaving minimal restores
+ * exactly what the world had, rather than a generic pair at 1.0/1.0.
+ *
+ * @param {THREE.Scene} scene
+ * @returns {THREE.Light[]} the detached lights, in the order they were found
+ */
+export function takeSceneLights(scene) {
+  if (!scene) return [];
+  const taken = [];
+  DEFAULT_LIGHT_NAMES.forEach((name) => {
+    const light = scene.getObjectByName(name);
+    if (!light) return;
+    scene.remove(light);
+    taken.push(light);
+  });
+  return taken;
+}
+
+/**
+ * Add the key light plus a weak ambient fill. Idempotent. Two lights, both of the cheapest kinds,
+ * and neither casting a shadow.
+ *
+ * The world's own lights are NOT removed here — that is `takeSceneLights`, so the caller decides
+ * whether it is keeping them to put back.
+ */
+export function applyMinimalLighting(scene) {
+  if (!scene) return null;
+
+  if (!scene.getObjectByName(MINIMAL_FILL_NAME)) {
+    const fill = new THREE.AmbientLight(0xffffff, FILL_INTENSITY);
+    fill.name = MINIMAL_FILL_NAME;
+    scene.add(fill);
+  }
+
+  const existing = scene.getObjectByName(MINIMAL_LIGHT_NAME);
+  if (existing) return existing;
+  const key = new THREE.DirectionalLight(0xffffff, DEFAULT_INTENSITY);
+  key.position.set(DEFAULT_DIRECTION.x, DEFAULT_DIRECTION.y, DEFAULT_DIRECTION.z);
+  key.castShadow = false;
+  key.name = MINIMAL_LIGHT_NAME;
+  scene.add(key);
+  return key;
+}
+
+export function removeMinimalLighting(scene) {
+  if (!scene) return;
+  removeLightByName(scene, MINIMAL_LIGHT_NAME);
+  removeLightByName(scene, MINIMAL_FILL_NAME);
+}
+
+/**
+ * Point the key light the way the world says its light points.
+ *
+ * DIRECTION only — the world's light COLOUR is deliberately not applied. Minimal is a monochrome
+ * look, and a world that authored a strongly tinted light would drag the whole scene into that hue
+ * and break the consistency the mode is for. Direction gives the shape somewhere to be lit from,
+ * which is what actually varies usefully between worlds.
+ *
+ * A no-op when the key light is not in the scene, so a full-profile world load never has to check
+ * which mode it is in.
+ *
+ * @param {THREE.Scene} scene
+ * @param {{ lightDirection?: object, direction?: object,
+ *           diffuseIntensity?: number, diffuse?: number }} lighting
+ */
+export function updateMinimalKeyLight(scene, lighting = {}) {
+  const key = scene?.getObjectByName(MINIMAL_LIGHT_NAME);
+  if (!key) return;
+
+  const direction = lighting.lightDirection ?? lighting.direction;
+  if (direction && typeof direction === 'object') {
+    const x = Number.isFinite(direction.x) ? direction.x : DEFAULT_DIRECTION.x;
+    const y = Number.isFinite(direction.y) ? direction.y : DEFAULT_DIRECTION.y;
+    const z = Number.isFinite(direction.z) ? direction.z : DEFAULT_DIRECTION.z;
+    // A direction of all zeros would put the light inside the planet and black the scene out.
+    if (x !== 0 || y !== 0 || z !== 0) key.position.set(x, y, z);
+  }
+
+  const intensity = lighting.diffuseIntensity ?? lighting.diffuse;
+  if (Number.isFinite(intensity) && intensity > 0) {
+    // The world's intensities are authored against TWO lights at full strength; this is one, so it
+    // keeps the default as a floor rather than dimming the only light in the scene.
+    key.intensity = Math.max(DEFAULT_INTENSITY, intensity);
+  }
+}

package/src/minimal/minimalWorld.js

@@ -0,0 +1,179 @@
+/**
+ * @file src/minimal/minimalWorld.js
+ * @description The planet as performance mode draws it: one sphere, one cheap lit material, no
+ * texture, no halo, no cloud shell.
+ *
+ * Shared, not Orbiters-local, because TWO surfaces draw this look: Orbiters renders it in
+ * performance mode, and the Entangled Worlds editor previews it so an author can see what they are
+ * authoring. If each kept its own copy the preview would drift from the render and start lying about
+ * what the public will see — the one failure this module exists to prevent.
+ *
+ * Why this exists rather than reusing the shared normal-material sphere: `MeshNormalMaterial` colours
+ * each pixel by the direction the surface faces, which is a gradient, not shading. It cannot respond
+ * to a light at all — so however many lights the scene has, the planet reads as a flat disc while the
+ * moons beside it (a lit material) read as spheres. A lit material is what makes the shape legible.
+ *
+ * The cost of that is close to nothing. Lambert is one dot product per fragment against a single
+ * directional light — no specular, no roughness, no environment lookup, no texture fetch. What it
+ * costs over the normal material is far less than what a texture, a halo or a cloud shell cost, all
+ * of which this mode drops.
+ *
+ * `kind` exists so the options can be compared on real hardware without a rebuild
+ * (`?minimalMaterial=lambert|phong|normal`), and so the choice is one line if a cheaper one wins.
+ */
+import * as THREE from 'three';
+
+export const MINIMAL_WORLD_MODE = 90;
+
+/**
+ * The minimal planet's colour when the world names none.
+ *
+ * Deliberately neutral, and deliberately NOT read from the `--color*` theme variables: those are the
+ * app chrome's palette (white, black, the UI accent), not the world's, so reading them would paint
+ * every planet the same interface colour. A world that DOES name a colour is honoured — see
+ * `resolvePlanetColor` — and what carries the identity of one that does not is its own authored
+ * light (`minimalLighting.js`).
+ */
+const DEFAULT_PLANET_COLOR = 0xb8c2cc;
+
+/**
+ * The same neutral as a CSS hex, for surfaces that have to SHOW it rather than render it — the
+ * editor's colour swatch displays this when a world has authored nothing, so the control never
+ * claims a colour the renderer is not actually using. Exported so there is one constant, not an
+ * editor copy that has to be kept equal to this one.
+ */
+export const MINIMAL_PLANET_COLOR_HEX = `#${DEFAULT_PLANET_COLOR.toString(16).padStart(6, '0')}`;
+
+/**
+ * The floor an authored colour is lifted to, as HSL lightness in the sRGB the author picked in.
+ *
+ * Minimal drops the skybox, so the planet is drawn against black (`SceneSpace` sets the background to
+ * BLACK when there is no cubemap). The scene's whole light budget is one key at 1.8 plus a 0.55
+ * ambient fill, so a near-black body reflects almost nothing and disappears into that background
+ * entirely — not a dark planet, no planet. Lifting the lightness while keeping hue and saturation
+ * means a world that authored near-black still reads as its own hue, just at the darkest level that
+ * is still a visible sphere.
+ *
+ * 0.10 sits below anything an author would recognise as a colour rather than as black: `#101030`, a
+ * genuinely dark navy, measures 0.125 and passes through untouched.
+ */
+const MIN_PLANET_LIGHTNESS = 0.1;
+
+export const MINIMAL_MATERIAL_KINDS = Object.freeze(['lambert', 'phong', 'normal']);
+
+/**
+ * Segment counts used only when the world names none.
+ *
+ * The world's OWN resolution is never overridden, including when it is very low. A low-segment world
+ * is a faceted world on purpose — that faceting is the world's shape, not a defect to be smoothed
+ * away — and performance mode changes what is DRAWN, never the world's configuration.
+ */
+const FALLBACK_WIDTH_SEGMENTS = 48;
+const FALLBACK_HEIGHT_SEGMENTS = 32;
+
+function resolveSegments(value, fallback) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+  return Math.round(numeric);
+}
+
+/**
+ * Parse a colour, or report that it could not be parsed.
+ *
+ * `new THREE.Color(x)` does NOT throw on a value it cannot read: `Color.set` ignores anything that is
+ * not a Color, a number or a string, and `setStyle` warns and leaves the colour untouched. Either way
+ * the object keeps whatever it was constructed with, so a `try/catch` around it catches nothing and
+ * the caller silently gets that starting value — white, by default.
+ *
+ * That matters here because the colour arrives from world metadata, which is `Schema.Types.Mixed` and
+ * validated nowhere: any non-empty string persists, so `'blueish'` would paint a WHITE planet rather
+ * than falling back to the neutral one.
+ *
+ * So: probe from black. If the result is black the value was either genuinely black or not read at
+ * all — probe again from white to tell those apart. The common case parses on the first probe and
+ * costs one object.
+ *
+ * @returns {THREE.Color|null} null when the value could not be read as a colour
+ */
+function parseColor(value) {
+  const fromBlack = new THREE.Color(0x000000).set(value);
+  if (fromBlack.getHex() !== 0x000000) return fromBlack;
+  const fromWhite = new THREE.Color(0xffffff).set(value);
+  return fromWhite.getHex() === 0x000000 ? fromBlack : null;
+}
+
+/**
+ * The planet colour to use, given the colour the world authored (if any).
+ *
+ * The only thing done to an authored colour is the legibility floor above. Hue and saturation are
+ * never touched: the point of the control is that the world picks its own colour, so anything that
+ * moved it toward a house palette would defeat it.
+ *
+ * @param {THREE.Color|number|string|null|undefined} override
+ * @returns {THREE.Color}
+ */
+export function resolvePlanetColor(override) {
+  if (override === undefined || override === null) return new THREE.Color(DEFAULT_PLANET_COLOR);
+  // An unreadable colour is never worth failing a world load over — the world just keeps the neutral.
+  const color = parseColor(override);
+  if (!color) return new THREE.Color(DEFAULT_PLANET_COLOR);
+  // Read and write HSL in sRGB — the space the author picked the colour in. The working space is
+  // linear, where the same swatch measures several times darker, so a floor applied there would
+  // lift colours the author would not call dark at all.
+  const hsl = { h: 0, s: 0, l: 0 };
+  color.getHSL(hsl, THREE.SRGBColorSpace);
+  if (hsl.l < MIN_PLANET_LIGHTNESS) {
+    color.setHSL(hsl.h, hsl.s, MIN_PLANET_LIGHTNESS, THREE.SRGBColorSpace);
+  }
+  return color;
+}
+
+function createMaterial(kind, color) {
+  switch (kind) {
+    case 'normal':
+      // The previous look, kept so it can be compared directly rather than from memory.
+      return new THREE.MeshNormalMaterial();
+    case 'phong':
+      // One specular highlight on top of Lambert. Reads glossier; costs a little more.
+      return new THREE.MeshPhongMaterial({ color, shininess: 12, specular: 0x222222 });
+    default:
+      return new THREE.MeshLambertMaterial({ color });
+  }
+}
+
+/**
+ * Build the minimal planet. Signature matches what `WorldManager.setMode` hands a custom creator.
+ *
+ * @param {{
+ *   sphereRadius?: number,
+ *   sphereWidthSegments?: number,
+ *   sphereHeightSegments?: number,
+ *   materialKind?: 'lambert'|'phong'|'normal',
+ *   planetColor?: THREE.Color|number|string,
+ * }} args
+ * @returns {Promise<THREE.Mesh>}
+ */
+export async function createMinimalWorld({
+  sphereRadius = 1,
+  sphereWidthSegments,
+  sphereHeightSegments,
+  materialKind = 'lambert',
+  planetColor,
+} = {}) {
+  const kind = MINIMAL_MATERIAL_KINDS.includes(materialKind) ? materialKind : 'lambert';
+  const color = resolvePlanetColor(planetColor);
+
+  // The world's own radius and segment counts, as authored. Same shape as the full look — this mode
+  // changes the material and what surrounds the planet, never the geometry the world describes.
+  const geometry = new THREE.SphereGeometry(
+    sphereRadius,
+    resolveSegments(sphereWidthSegments, FALLBACK_WIDTH_SEGMENTS),
+    resolveSegments(sphereHeightSegments, FALLBACK_HEIGHT_SEGMENTS),
+  );
+  const material = createMaterial(kind, color);
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.name = 'orb_MinimalWorld';
+  mesh.castShadow = false;
+  mesh.receiveShadow = false;
+  return mesh;
+}

package/src/moons/moonsGeneration.js

@@ -38,7 +38,6 @@ export async function generateMoons({
   debugShowReferenceMoon = false, // changed from true to prevent extra moon
   referenceMoonScale = 0.25,
   // behavior flags
-  preserveInstanceTint = false,      // keep per-instance color even when textured
   useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
   // The renderer whose KTX2 transcoder decodes the moon texture. Required on any page with more than
   // one renderer; falls back to the standalone app's global inside the loader.
@@ -118,10 +117,20 @@ export async function generateMoons({
     }
   }
 
-  const enableVertexColors = !sharedTexture || preserveInstanceTint;
+  // `vertexColors` is deliberately NOT set, and setting it here was a bug worth spelling out.
+  //
+  // The per-moon tint rides on `instanceColor` (set by `setColorAt` below). Three defines
+  // USE_INSTANCING_COLOR for that on its own and multiplies it into `vColor` — no material flag
+  // needed. `vertexColors` is a DIFFERENT feature: it multiplies by the geometry's `color`
+  // ATTRIBUTE. This geometry is a plain SphereGeometry and has no such attribute, so enabling it
+  // made the shader multiply by an absent attribute — zero — and every moon rendered BLACK, with the
+  // tint annihilated along with it.
+  //
+  // It only bit the untextured path (`!sharedTexture`), which is the one the performance look uses:
+  // moons there carry no texture, so their colour IS the moon, and it was the one case where the
+  // colour silently could not work.
   const moonMaterial = new THREE.MeshStandardMaterial({
     map: sharedTexture || null,
-    vertexColors: enableVertexColors,
     roughness,
     metalness,
     emissive: new THREE.Color(emissiveColor),

package/src/render/frameBudget.test.js

@@ -1,62 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { createFrameBudget, CAPPED_FPS } from './frameBudget.js';
-
-test('the first frame is always allowed', () => {
-  const budget = createFrameBudget();
-  assert.equal(budget.shouldRender(0), true);
-});
-
-test('a 60Hz display yields 30fps, not 20', () => {
-  // The whole reason the tolerance exists. rAF on a 60Hz display delivers at ~16.7ms intervals; a
-  // strict >= 33.3 test rejects the frame at 33.3 and waits for 50, which is 20fps.
-  const budget = createFrameBudget();
-  const accepted = [];
-  for (let i = 0; i < 12; i += 1) {
-    const now = i * (1000 / 60);
-    if (budget.shouldRender(now)) accepted.push(i);
-  }
-  // Every other frame: 0, 2, 4, ... — half of 60 is the 30 that was asked for.
-  assert.deepEqual(accepted, [0, 2, 4, 6, 8, 10]);
-});
-
-test('a 120Hz display is capped to the same rate', () => {
-  const budget = createFrameBudget();
-  let accepted = 0;
-  for (let i = 0; i < 120; i += 1) {
-    if (budget.shouldRender(i * (1000 / 120))) accepted += 1;
-  }
-  // One second of 120Hz ticks, capped at 30 — allow the boundary frame either way.
-  assert.ok(accepted >= CAPPED_FPS && accepted <= CAPPED_FPS + 1, `accepted ${accepted}`);
-});
-
-test('a rejected frame does not move the clock forward', () => {
-  // Otherwise a burst of rejected frames would keep pushing the next allowed one further out.
-  const budget = createFrameBudget();
-  budget.shouldRender(0);
-  assert.equal(budget.shouldRender(10), false);
-  assert.equal(budget.shouldRender(20), false);
-  assert.equal(budget.shouldRender(30), true);
-});
-
-test('reset makes the next frame the first one again', () => {
-  const budget = createFrameBudget();
-  budget.shouldRender(0);
-  assert.equal(budget.shouldRender(5), false);
-  budget.reset();
-  assert.equal(budget.shouldRender(5), true);
-});
-
-test('a missing timestamp never blocks a frame', () => {
-  // rAF always supplies one, but `renderOnce` can be driven by tooling that does not.
-  const budget = createFrameBudget();
-  assert.equal(budget.shouldRender(undefined), true);
-  assert.equal(budget.shouldRender(Number.NaN), true);
-});
-
-test('a custom rate is honoured', () => {
-  const budget = createFrameBudget({ fps: 10, toleranceMs: 0 });
-  assert.equal(budget.shouldRender(0), true);
-  assert.equal(budget.shouldRender(99), false);
-  assert.equal(budget.shouldRender(100), true);
-});