tosijs-3d 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to **tosijs-3d**. This project is pre-1.0 (`0.x`), so minor
 versions may carry breaking peer-dependency changes — each is called out in a
 **⚠️ Breaking** block in its version section below, with what a consumer must do.
 
+## 0.10.9
+
+### Added
+
+- **A compass and a watch** (`import … from 'tosijs-3d/dials'`, not in the barrel: the artwork is 36 KB). Both are drawn by Tonio, and the code only moves their named parts. The compass needle points north as you turn (`sceneCompass(b3d)` follows the active camera, flat or in a headset; north is +Z). On the watch, a dot on the ring is the time of day (noon at the top, midnight at the bottom) and a dot on the bar is how fast it passes, from still to an hour a second. Drag either: `skyWatch(skybox)` reads and writes the sky's `timeOfDay` and `realtimeScale`. Each goes on the system bar as a `<tosi-b3d-panel icon title>`. Feather's `clock` icon is added. `bun run dial-art` re-embeds the SVGs after they are redrawn.
+- **A planet and its sphere terrain are one world** (#3344). Tonio: "if you pick a point in the middle of what looks like the ocean, coast, mountain range on a planet you end up with corresponding terrain in the sphere terrain and vice versa." Either can be the source, stated by one attribute:
+  - **`<tosi-b3d-terrain planet="#p">`**: the ground takes its large shape (sea, coasts, mountain ranges) from the planet, scaled to its `radius` with the sea at 0. Its own detail layer and landforms ride on top, and it rebuilds when the planet changes (`planet.shapeKey`). Measured at 200 random places: the ground sits within the detail layer of the globe's height (mean 2.5 m, worst 3.9 m with 5 m of detail), and sea or land agrees except at the waterline.
+  - **`<tosi-b3d-planet terrain="#t">`**: the globe is drawn from the ground's own height function, and again whenever the ground's shape changes. This replaces the hand-written `planet.surface = terrain.planetSurface()` loop, and the sphere-map demo now uses it.
+
+  Linked, not automatic: a gas giant in a moon's sky, or every body of a star system, must not become the ground you stand on. `planet.relativeHeightAt(direction)` is the globe's height above its sea as a fraction of its radius. Both attributes are in the schemas.
+- **Planetary rings catch shadows** (#3320). Both are worked out in the shaders for a sphere and a flat ring lit by one star, with no shadow maps. **The planet's shadow falls across its rings** (the dark wedge behind Saturn): each ring fragment asks whether the ray toward the star passes through the planet, softened slightly at the edge. This applies to any `<tosi-b3d-planet>` with `rings`. **The rings' shadow bands a gas giant**: each fragment finds where the ray toward the star crosses the ring plane and dims by how much ring is there, so the shadow has the ring's own gaps (a lighter stripe where the Cassini gap lets light through). The ring is now one GLSL function (`RING_GLSL` in `gas-giant`) that the ring draws itself from and the planet reads, and `createGasGiantMaterial` takes `ring: () => RingShadow | null` for a planet built by hand. Not yet: the rings' shadow on a ROCKY planet's surface.
+
+Size: barrel (min, packages external) 1114.2 KB raw / 379.4 KB gz, +0.46% on 0.10.8.
+
+## 0.10.8
+
+### Added
+
+- **`planetSchema()`** (`sceneSchemas.planet`): `<tosi-b3d-planet>` described like the other scene primitives, with sections (World, Surface, Sea, Air, Clouds, Craters, Rings, Gas giant, Maps), `heightMap`/`colorMap` marked as fetched, and the `world`/`gas` lists taken from the preset tables so they cannot drift. **`x-preset-written`** names the attributes a `world` preset writes into the planet. A consumer that applies schema defaults on bind should show them but not write them back over the preset (#103, ensemble).
+- **`lat` / `lon` on `<tosi-b3d-terrain>`**: where this ground is on its planet, the latitude and longitude of the terrain's origin in degrees, so "this ground is at 12° N, 40° E" is one attribute pair, in markup and in `terrainSchema()`. `worldU`/`worldV` are now JS properties over them (`worldU = lon / 360`, `worldV = (lat + 90) / 180`). Before, they were plain properties that markup could not set and that needed a `regenerate()`. Changing `lat`/`lon` (or either view of them) rebuilds the ground. The defaults (-45, 0) are the old 0.25 / 0, so nothing moves (#103).
+- **`seamBlend` / `seamWeight`** (`sphere-map`): make a layer laid out in flat metres periodic round a world, mixed with its copy one circumference away near the far meridian and untouched elsewhere.
+
+### Fixed
+
+- **A widget bound to a tosijs box lets go of it** (#100). `toggle3d`, `slider3d` and `select3d` subscribed to a bound box and threw the unsubscribe away. Every bound row left a listener in tosijs's module-level list that held the row, its panel and its host, so ensemble's editor grew by 125 listeners and 5,360 nodes per round of panel rebuilds. Each now unsubscribes in its `dispose()`. `B3d` already disposes the widget lists it rebuilds, and **`panel3d(…)` has a `dispose()`** that disposes its rows, for a consumer that drops its own panels. Not reaped by `isConnected`: an in-scene panel's SVG is never in the document.
+- **Removing the last instance of a library model no longer turns every later one white** (#102). `disposeMeshTree` disposed a material when no mesh in the scene used it, but a library's source meshes live in its AssetContainer, out of that list, so the guard could not see that the library still needed the material. Ensemble's editor lost the colour of a whole kit on its first rebuild, and a game would see it when the last enemy of a type despawned and the next one spawned white. It now disposes only materials the scene owns (`scene.materials`); a container's are the container's.
+- **A frozen or paused scene builds its system bar** (#3342). The bar and flat panels were built only on running frames, so a scene that started frozen (Manta freezes on every menu) showed the HTML lozenge, and a `<tosi-b3d-panel icon title>` got no button until it unfroze. Stopped frames keep the scene's chrome current now, as they already did its fog.
+- **A sphere terrain joins at the far meridian** (#3318). Its noise is read on the sphere and always repeated; its profile fields (`blendProfiles`, `profileField`) and landforms (`craterField`, …) read flat metres and did not. The ground opposite the terrain's origin (longitude 180 at the default `worldU`) was two different places: a 116 m step on Manta's cratered moon, 19.5 m without the craters. Within 5% of a turn of that meridian they are now mixed with their copy one turn away, so the two sides meet. Elsewhere the ground is exactly as before, and a place one whole turn round is the same place. Spheres only: a cylinder is used as a big flat world with things placed in metres.
+- **A globe of a world with no sea is drawn at its size** (#3319). A planet drawn from a `PlanetSurface` measured every height from `seaLevel`, so a dry world that says "no sea" with a sea level far below its ground (Manta's -10000 m) gained that depth as ground. A globe meant to be 40 units across came out at 2476. The globe now measures from the higher of the sea and the lowest ground. A world with a real sea is unchanged, and on a dry world the lowest ground sits on the base radius. The convention for "no sea" is a `seaLevel` below all of the ground.
+
+Size: barrel (min, packages external) 1109.1 KB raw / 377.6 KB gz, +0.38% on 0.10.7.
+
 ## 0.10.7
 
 **What you will see on upgrading** (nothing exported in 0.10.6 is removed or renamed, but a `^0.10` range picks this up unasked):

package/dist/b3d-planet.d.ts

@@ -32,6 +32,7 @@ export declare class B3dPlanet extends B3dChild {
         ringOuter: number;
         ringOpacity: number;
         ringColor: string;
+        terrain: string;
         world: string;
         craters: number;
         seaShallow: string;
@@ -115,6 +116,35 @@ export declare class B3dPlanet extends B3dChild {
     private _builtSea;
     private _seaKey;
     private _surfaceFromMap;
+    /** The sea level of the last build, in this planet's units. */
+    private _seaAt;
+    /** Bumped by every build: what `shapeKey` reports. */
+    private _shapeGen;
+    /**
+     * Changes whenever this planet's SHAPE does (every build). A terrain that
+     * takes its shape from this planet (`planet` on the terrain) compares it to
+     * know when to rebuild.
+     */
+    get shapeKey(): string;
+    /**
+     * HOW HIGH THE GROUND IS ABOVE THE SEA in a direction from the centre, as
+     * a fraction of the planet's radius: what this globe draws there, with
+     * its sea at 0 (on a world with no sea, its lowest ground). A terrain
+     * with `planet` set multiplies it by its own radius, which is how the
+     * ground under a pin is the place the globe shows. Null before the
+     * planet is built, and for a gas giant.
+     */
+    relativeHeightAt(d: {
+        x: number;
+        y: number;
+        z: number;
+    }): number | null;
+    /** The terrain `terrain` names, when it is a sphere. */
+    private _linkedTerrain;
+    private _terrainWarned;
+    private _terrainBuilt;
+    private _surfaceFromTerrain;
+    private _followTerrain;
     /**
      * Fetch `heightMap` (once per URL and sea setting) and rebuild from it. The
      * planet shows as a smooth ball, in its colours, until the heights arrive.
@@ -138,6 +168,10 @@ export declare class B3dPlanet extends B3dChild {
      * buildPlanet). Kept as a named step so the build order still reads.
      */
     private buildOcean;
+    /** The ring's shape, for its shadow on the planet (null: no ring). */
+    private _ring;
+    /** The ring as the gas giant material's shadow needs it, now. */
+    private _ringShadow;
     private buildRings;
     /** The rocky world's look, when `world` names one (and it is not a gas giant). */
     private _look;

package/dist/b3d-planet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"b3d-planet.d.ts","sourceRoot":"","sources":["../src/b3d-planet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"b3d-planet.d.ts","sourceRoot":"","sources":["../src/b3d-planet.ts"],"names":[],"mappings":"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"}

package/dist/b3d-planet.js

@@ -167,6 +167,7 @@ tosi-b3d {
 | `seaGlint` | `1` | The sun's glint on the sea, `0…1`: a patch of sparkle, broken up by fine wave texture, that slides over the water as you move |
 | `seaIce` | `0` | Sea ice toward the poles, `0…1` |
 | `inlandWater` | `'off'` | `'on'` guesses LAKES from a `colorMap`: where the picture is blue, or nearly black (how NASA's Blue Marble paints deep lakes), it is drawn as water: the map's colour, with the glint. The height map only knows the sea, and a lake is above it. A guess: blue ice or black lava can pass for a lake |
+| `terrain` | `''` | A selector for the sphere `<tosi-b3d-terrain>` this is a GLOBE OF (`'#moon-ground'`): drawn from that ground's own height function, and again whenever its shape changes, so a place on the globe is the place on the ground. (The other way round, a terrain's `planet` gives the ground this planet's shape) |
 | `relief` | `1` | With a `heightMap` or a `surface` set: how much its true relief is exaggerated. `1` is to scale, which on a globe is flat to the eye; 20 to 60 reads as a relief map |
 | `world` | `''` | A ROCKY WORLD preset: `'moon'`, `'mercury'`, `'mars'`, `'venus'`, `'io'`, `'titan'` or `'earth'` (see [rocky-world](/rocky-world/)). Choosing one writes its sea, air, clouds, relief, craters and climate into this planet's own settings, which stay yours to tune; `worldOverrides` (a property) changes the preset for this planet |
 | `craters` | `0` | How cratered, `0…1` (see landform's `sphereCraters`) |
@@ -201,7 +202,7 @@ tosi-b3d {
 /*{ "parent": "space", "order": 40 }*/
 import { Color } from 'tosijs';
 import { isOff, B3dChild, sceneDelta, sceneSeconds } from './b3d-utils.js';
-import { GAS_GIANT_GLSL, gasGiantRgb, resolveGasGiant } from './gas-giant.js';
+import { GAS_GIANT_GLSL, RING_GLSL, gasGiantRgb, resolveGasGiant, } from './gas-giant.js';
 import { climateForGlobe } from './sphere-map.js';
 import { loadPlanetMap } from './planet-map.js';
 import { createPlanetClouds } from './planet-clouds.js';
@@ -274,6 +275,14 @@ export class B3dPlanet extends B3dChild {
         ringOuter: 0,
         ringOpacity: -1,
         ringColor: '',
+        /*
+        THE GROUND THIS IS A GLOBE OF (#3344): a selector for a sphere
+        `<tosi-b3d-terrain>` ('#moon-ground'). The planet draws from it, and
+        draws again whenever the ground's shape changes, so the globe and the
+        ground are one world. '' for none. (A terrain can take its shape from
+        a planet instead: its `planet` attribute.)
+        */
+        terrain: '',
         // A ROCKY WORLD's look (rocky-world): 'moon', 'mercury', 'mars',
         // 'venus', 'earth'. A preset: choosing one writes its sea, air, clouds,
         // relief, craters and climate into this planet's own settings, which
@@ -407,6 +416,7 @@ export class B3dPlanet extends B3dChild {
         }
     }
     update() {
+        this._followTerrain();
         this._followGroundClimate();
         if (this.rootNode == null)
             return;
@@ -444,7 +454,9 @@ export class B3dPlanet extends B3dChild {
                 turbulence: attrs.turbulence,
                 storm: attrs.storm,
                 colors: attrs.bandColors,
-            }));
+            }), 
+            // The rings' shadow on the bands (#3320).
+            { ring: () => this._ringShadow() });
             mesh.parent = this.rootNode;
             this.planetMesh = mesh;
             this.vertexHeights = null;
@@ -510,6 +522,31 @@ export class B3dPlanet extends B3dChild {
         as data (uv.x), so the shader can tell land from water per pixel and
         knows how deep the water is. There is no sea sphere.
         */
+        /*
+        A SEA BELOW ALL THE GROUND IS NO SEA (board #3319). Heights from a
+        surface are measured from its `seaLevel`, so a dry world that says "no
+        sea" with a sea far down (Manta's moon: -10000 m under ground near 320 m)
+        gained ten kilometres of ground and was drawn hundreds of times too big.
+        The datum is the higher of the sea and the lowest ground: with a real sea
+        nothing changes, and on a dry world the lowest ground sits on the base
+        radius.
+        */
+        if (this.surface != null) {
+            let lowest = Infinity;
+            for (let i = 0; i < totalVerts; i++)
+                if (heights[i] < lowest)
+                    lowest = heights[i];
+            if (lowest > 0 && Number.isFinite(lowest)) {
+                for (let i = 0; i < totalVerts; i++) {
+                    heights[i] -= lowest;
+                    const vi = i * 3;
+                    const r = radius + heights[i];
+                    positions[vi] = normals[vi] * r;
+                    positions[vi + 1] = normals[vi + 1] * r;
+                    positions[vi + 2] = normals[vi + 2] * r;
+                }
+            }
+        }
         let highest = 1e-3;
         let deepest = 1e-3;
         this.vertexHeights = heights;
@@ -517,6 +554,8 @@ export class B3dPlanet extends B3dChild {
         const seaAt = this.surface != null || !hasSea
             ? 0
             : this.heightPercentile(this._val('ocean'));
+        this._seaAt = seaAt;
+        this._shapeGen++;
         const heightData = new Float32Array(totalVerts * 2);
         for (let i = 0; i < totalVerts; i++) {
             const above = heights[i] - seaAt;
@@ -696,6 +735,97 @@ export class B3dPlanet extends B3dChild {
         return `${this._val('ocean')}|${attrs.flatSea}|${attrs.world}`;
     }
     _surfaceFromMap = false;
+    /** The sea level of the last build, in this planet's units. */
+    _seaAt = 0;
+    /** Bumped by every build: what `shapeKey` reports. */
+    _shapeGen = 0;
+    /**
+     * Changes whenever this planet's SHAPE does (every build). A terrain that
+     * takes its shape from this planet (`planet` on the terrain) compares it to
+     * know when to rebuild.
+     */
+    get shapeKey() {
+        return `${this.seed}|${this._shapeGen}`;
+    }
+    /**
+     * HOW HIGH THE GROUND IS ABOVE THE SEA in a direction from the centre, as
+     * a fraction of the planet's radius: what this globe draws there, with
+     * its sea at 0 (on a world with no sea, its lowest ground). A terrain
+     * with `planet` set multiplies it by its own radius, which is how the
+     * ground under a pin is the place the globe shows. Null before the
+     * planet is built, and for a gas giant.
+     */
+    relativeHeightAt(d) {
+        const attrs = this;
+        if (this.noise == null || attrs.gas)
+            return null;
+        const len = Math.hypot(d.x, d.y, d.z) || 1;
+        const s = this.surface;
+        if (s != null) {
+            const h = s.heightAt({ x: d.x / len, y: d.y / len, z: d.z / len });
+            return (h - s.seaLevel) / s.radius;
+        }
+        return ((this.heightAt(d.x / len, d.y / len, d.z / len) - this._seaAt) /
+            attrs.radius);
+    }
+    /** The terrain `terrain` names, when it is a sphere. */
+    _linkedTerrain() {
+        const sel = String(this.terrain ?? '').trim();
+        if (sel === '' || this.owner == null)
+            return null;
+        let el;
+        try {
+            el =
+                this.owner.querySelector(sel) ??
+                    document.querySelector(sel);
+        }
+        catch {
+            if (!this._terrainWarned) {
+                this._terrainWarned = true;
+                console.warn(`b3d-planet: terrain "${sel}" is not a valid selector`);
+            }
+            return null;
+        }
+        const t = el;
+        if (t == null || typeof t.planetSurface !== 'function')
+            return null;
+        return t;
+    }
+    _terrainWarned = false;
+    _terrainBuilt = '';
+    _surfaceFromTerrain = false;
+    /*
+    FOLLOW THE GROUND (#3344). Tonio: "if you pick a point in the middle of
+    what looks like the ocean, coast, mountain range on a planet you end up
+    with corresponding terrain in the sphere terrain and vice versa." The
+    globe is drawn from the terrain's own height function, again whenever
+    its `generationKey` changes. Not when that terrain takes ITS shape from
+    this planet: each would follow the other.
+    */
+    _followTerrain() {
+        const t = this._linkedTerrain();
+        if (t == null) {
+            if (this._surfaceFromTerrain) {
+                this._surfaceFromTerrain = false;
+                this._terrainBuilt = '';
+                this.surface = null;
+                this.regenerate();
+            }
+            return;
+        }
+        if (typeof t.planetSource === 'function' && t.planetSource() === this)
+            return;
+        const key = t.generationKey;
+        if (!key || key === this._terrainBuilt)
+            return;
+        const surface = t.planetSurface();
+        if (surface == null)
+            return;
+        this._terrainBuilt = key;
+        this._surfaceFromTerrain = true;
+        this.surface = surface;
+        this.regenerate();
+    }
     /**
      * Fetch `heightMap` (once per URL and sea setting) and rebuild from it. The
      * planet shows as a smooth ball, in its colours, until the heights arrive.
@@ -946,7 +1076,25 @@ export class B3dPlanet extends B3dChild {
     buildOcean() {
         this.oceanMesh = null;
     }
+    /** The ring's shape, for its shadow on the planet (null: no ring). */
+    _ring = null;
+    /** The ring as the gas giant material's shadow needs it, now. */
+    _ringShadow() {
+        const ring = this._ring;
+        const root = this.rootNode;
+        if (ring == null || root == null)
+            return null;
+        const c = root.getAbsolutePosition();
+        const up = BABYLON.Vector3.TransformNormal(BABYLON.Axis.Y, root.getWorldMatrix()).normalize();
+        return {
+            ...ring,
+            center: { x: c.x, y: c.y, z: c.z },
+            radius: this.radius * Math.abs(root.absoluteScaling.x),
+            normal: { x: up.x, y: up.y, z: up.z },
+        };
+    }
     buildRings() {
+        this._ring = null;
         if (this.owner == null || this.rootNode == null)
             return;
         const attrs = this;
@@ -956,27 +1104,34 @@ export class B3dPlanet extends B3dChild {
         const scene = this.owner.scene;
         const radius = attrs.radius;
         // Register ring shader once
-        if (!BABYLON.Effect.ShadersStore['planetRing6VertexShader']) {
-            BABYLON.Effect.ShadersStore['planetRing6VertexShader'] = `
+        if (!BABYLON.Effect.ShadersStore['planetRing7VertexShader']) {
+            BABYLON.Effect.ShadersStore['planetRing7VertexShader'] = `
         precision highp float;
         attribute vec3 position;
         attribute vec2 uv;
+        uniform mat4 world;
         uniform mat4 worldViewProjection;
         varying vec2 vUV;
+        varying vec3 vWorld;
         void main() {
           gl_Position = worldViewProjection * vec4(position, 1.0);
+          vWorld = (world * vec4(position, 1.0)).xyz;
           vUV = uv;
         }
       `;
-            BABYLON.Effect.ShadersStore['planetRing6FragmentShader'] = `
+            BABYLON.Effect.ShadersStore['planetRing7FragmentShader'] = `
         #extension GL_OES_standard_derivatives : enable
         precision highp float;
         varying vec2 vUV;
+        varying vec3 vWorld;
+        uniform vec4 ringLight;
+        uniform vec4 ringPlanet;
         uniform vec3 ringColor;
         uniform float ringOpacity;
         uniform float ringInner;
         uniform float seed;
 
+        ${RING_GLSL}
         float hash(float p) {
           return fract(sin(p * 127.1) * 43758.5453);
         }
@@ -986,49 +1141,13 @@ export class B3dPlanet extends B3dChild {
           vec2 uv = vUV * 2.0 - 1.0;
           float r = length(uv);
           if (r < ringInner || r > 1.0) discard;
-
-          // Normalize to ring band
           float t = (r - ringInner) / (1.0 - ringInner);
-
-          // SHARP, as rings are, and irregular: the density along the
-          // radius is 1D noise at several scales, TERRACED, so it holds
-          // plateaus of different widths and steps between them with edges
-          // about a pixel wide. Only detail finer than a pixel fades to its
-          // average (drawn, it shimmered into moire and flickered).
           float px = max(fwidth(t), 1e-5);
           float theta = atan(uv.y, uv.x);
-
-          // A shepherd moon in the narrow gap: the edges either side of it
-          // ripple round the ring, fading away from the gap. (The integer
-          // count keeps the ripple whole across atan's jump.)
-          float gapB = hash(seed + 1.0) * 0.15 + 0.8;
-          float near = abs(t - gapB);
-          t += 0.004 * sin(theta * 36.0) * exp(-near / 0.02);
-
-          float n = 0.0;
-          float a = 0.5;
-          float f = 6.0;
-          float norm = 0.0;
-          for (float i = 0.0; i < 5.0; i++) {
-            float x = t * f + seed * 13.1 + i * 7.3;
-            float c = floor(x);
-            float k = fract(x);
-            float vn = mix(hash(c), hash(c + 1.0), k * k * (3.0 - 2.0 * k));
-            float fade = 1.0 - smoothstep(0.3, 0.6, f * px);
-            n += a * fade * (vn - 0.5);
-            norm += a;
-            a *= 0.55;
-            f *= 2.7;
-          }
-          n = clamp(n / norm * 1.6 + 0.5, 0.0, 1.0);
-          float steps = n * 6.0;
-          float sw = max(fwidth(steps), 1e-4);
-          float terrace = (floor(steps) + smoothstep(1.0 - sw, 1.0, fract(steps))) / 6.0;
-          float density = mix(n, terrace, 0.75);
-
-          // The broad profile: faint inside, brightest a little out.
-          float profile = 0.35 + 0.65 * sin(3.1416 * pow(t, 0.75));
-          float bands = profile * (0.3 + 1.1 * density) * 1.3;
+          // The ring itself is one function, shared with the planet that
+          // reads its shadow (gas-giant RING_GLSL).
+          vec2 ring = b3dRing(t, theta, seed, px);
+          float bands = ring.x;
 
           // Imperfect round the ring: a faint clumping by angle and radius.
           vec2 cq = uv * 9.0 + seed;
@@ -1040,18 +1159,22 @@ export class B3dPlanet extends B3dChild {
           float h01 = hash(ci.x + (ci.y + 1.0) * 57.0);
           float h11 = hash(ci.x + 1.0 + (ci.y + 1.0) * 57.0);
           float clump = mix(mix(h00, h10, cf.x), mix(h01, h11, cf.x), cf.y);
-          bands *= 0.95 + 0.1 * clump;
-
-          // Gaps: the wide one (Cassini's) and the moon's narrow one,
-          // cut clean, a pixel soft.
-          float g1 = abs(t - hash(seed) * 0.4 - 0.45);
-          float gap1 = smoothstep(0.022 - px, 0.022 + px, g1);
-          float gap2 = smoothstep(0.005 - px, 0.005 + px, abs(t - gapB));
-          bands *= mix(0.04, 1.0, gap1) * mix(0.06, 1.0, gap2);
+          float k = 0.95 + 0.1 * clump;
+          bands *= k;
+          float alpha = clamp(ring.y * k, 0.0, 1.0) * ringOpacity;
 
-          // Edges: crisp, a few pixels at most.
-          float edgeFade = smoothstep(0.0, max(0.015, px * 2.0), t) * smoothstep(1.0, 1.0 - max(0.01, px * 2.0), t);
-          float alpha = clamp(bands, 0.0, 1.0) * edgeFade * ringOpacity;
+          /*
+          THE PLANET'S SHADOW ON THE RING (#3320): the dark wedge behind
+          the planet. From this point toward the star, does the ray pass
+          through the planet? A sphere, so it is exact, softened over a
+          couple of percent of the radius for the penumbra.
+          */
+          vec3 toL = ringLight.w > 0.5 ? normalize(ringLight.xyz - vWorld) : normalize(ringLight.xyz);
+          vec3 oc = ringPlanet.xyz - vWorld;
+          float along = dot(oc, toL);
+          float miss = length(oc - toL * along);
+          float lit = along > 0.0 ? smoothstep(ringPlanet.w * 0.97, ringPlanet.w * 1.03, miss) : 1.0;
+          bands *= mix(0.03, 1.0, lit);
 
           gl_FragColor = vec4(ringColor * bands, alpha);
         }
@@ -1080,10 +1203,13 @@ export class B3dPlanet extends B3dChild {
         mesh.rotation.x = Math.PI / 2; // Flat in XZ plane
         // In the equator, as rings are. It used to be tipped off it, and as
         // the planet turned (the ring is its child) the ring precessed.
-        const mat = new BABYLON.ShaderMaterial('planet-ring-mat', scene, { vertex: 'planetRing6', fragment: 'planetRing6' }, {
+        const mat = new BABYLON.ShaderMaterial('planet-ring-mat', scene, { vertex: 'planetRing7', fragment: 'planetRing7' }, {
             attributes: ['position', 'uv'],
             uniforms: [
+                'world',
                 'worldViewProjection',
+                'ringLight',
+                'ringPlanet',
                 'ringColor',
                 'ringOpacity',
                 'ringInner',
@@ -1095,8 +1221,27 @@ export class B3dPlanet extends B3dChild {
         mat.setFloat('ringOpacity', Math.max(0, Math.min(1, opacity)));
         mat.setFloat('ringInner', innerRadii / outerRadii);
         mat.setFloat('seed', attrs.seed % 100);
+        this._ring = {
+            inner: innerRadii,
+            outer: outerRadii,
+            opacity: Math.max(0, Math.min(1, opacity)),
+            seed: attrs.seed % 100,
+        };
         mat.backFaceCulling = false;
         mat.alphaMode = BABYLON.Constants.ALPHA_COMBINE;
+        // Where the star and the planet are, each frame, for the shadow.
+        const light = new BABYLON.Vector4(0, 1, 0, 0);
+        const planet = new BABYLON.Vector4();
+        mat.onBind = () => {
+            sceneLight(scene, light);
+            mat.setVector4('ringLight', light);
+            const root = this.rootNode;
+            if (root != null) {
+                const c = root.getAbsolutePosition();
+                planet.set(c.x, c.y, c.z, radius * Math.abs(root.absoluteScaling.x));
+            }
+            mat.setVector4('ringPlanet', planet);
+        };
         mesh.material = mat;
         mesh.parent = this.rootNode;
         this.ringMesh = mesh;