startRig puts one element per lit card, farthest first, at its rows with transform-origin on the horizon centre, animated by +-scale_i x heading with scale(scale_i); the still draws the same cards at heading 0. index.ts lights in prepare, so a sky-change rebuild lights again and any failure (no WebGL2 included) is planesFail and the sky alone. ridgeAssets.test gates the committed v2 bake. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
11 KiB
Background scene
Default: the ridge scene (ridge/): no per-frame WebGL (the baked cards are lit once per scene build, in a WebGL2 context that is released after). startBackgroundScene runs it unless the client
config says backgroundScene.style: 'raymarch'; the tier flag still defaults to off, and null still
means "keep the CSS ground". Everything below this section describes the opt-in ray-march scene.
ridge/Ridge.tscreateRidgeScene({ canvas, tier, probe?, onProbe?, sky?, backdrop? })returns{ login, dispose }or null (tieroff, no 2D context). It paints the sky (ridge/physicalSky.ts, from theSkyColoursthe host passes) on the host canvas at the viewport's size in canvas pixels, then the stars baked into it, a twinkle overlay canvas for the swinging ones (ridge/stars.ts), the lit ridge cards (below) and, when it rains, tiled rain streaks slid down on the compositor (ridge/rain.ts). With no cards (the load failed) the scene shows sky, stars and weather only. No script runs per frame except the twinkle, at most every 50 ms. The host canvas and its parent must be positioned and the canvas should fill the parent. A resize rebuilds it; so does a sky change (index.ts).- Paused when the tab is hidden; under
prefers-reduced-motionthe rain is paused and the stars stay at base brightness.tier: 'still'paints the sky and stars and adds no overlay, no rain and no loop. - Cadence guard: for the first 2 s after start (after 5 warm-up frames) rAF intervals are sampled; if their p95 is over
33 ms the scene settles to a still image (
ridge/probe.ts) and stops.?probe=1(orprobe: true) keeps sampling and showsn / median / p95in a corner readout. ridge/skyColour.tsskyColours()is the fallback three-stop palette (top, mid, horizon) a scene gets with noskyoption; the host passesridgeSkyFor(skyForState.ts) instead.- Ridge cards:
ridge/manifest.tsloadManifestreads${BASE_URL}public/ridge/index.json(configbackgroundScene.placepicks the entry, unknown or absent: the index default), then the place'smanifest.json(schema 2, written byscripts/ridge-bake/export.py; it is the one JSON the backdrop reads): K G-buffer cards, nearest first, each a colour WebP (albedo, straight alpha) and a geometry WebP (the normal as 'rt8', the log-distance, and the wall code R = G = 255 for the extruded face under a ridge).index.tsprepare()loads the manifest and, with the scene chunk,ridge/Backdrop.tsloadBackdrop: every card's two files fetched and decoded straight (no premultiply, no colour management), thenridge/lightCards.tslights each card once in WebGL2 for the sky of this build (sun and ambient from the atmosphere, aerial perspective from the geometry's distance, ink on occluding edges and creases, the sky's own display so terrain and sky share an exposure) into a 2D canvas, and releases the context. A sky change is a rebuild, so it lights again; nothing is lit per frame, and the host canvas is only ever asked for 2d.createRidgeScene({ backdrop })stays synchronous, and a rebuild keeps the old scene up until the new one's cards are lit, then swaps. The rig is one div of K card elements (farthest first; DOM order is paint order; no z-index, no fixed position, nothing outside the scene's parent), each placed at its rows of the plane and moved byview.tscardMotion: the camera turns through the baker's heading range (capped so every card still covers the viewport) and card i pansscale_ix heading and is drawnscale_itimes its bake, about the horizon centre, as a camera pushed forward on a circle round the bake centre sees it (ruling ridge-camera-on-circle); the scales come from the manifest. It drifts onElement.animate(transform only, 150 s loop, paused when the tab is hidden, motion is reduced or the scene is still); a still draws the same cards at heading 0 into the host canvas. A failure anywhere (404, a manifest that is not schema 2, a card that will not decode, no WebGL2, a lighting pass that throws) is the sky-only scene onFALLBACK_VIEW, told to the host by the live scene alone, throughonPlanesFailwhen the live scene has no cards andonPlanesOkwhen a later one has them (never from a stale or disposed build); it is neveronCompileFail.vite.config.jscopiespublic/ridgeintodist/public/. harness/scene/bundle.cjs <out> ridgebuilds a standalone page (?tier=,?probe=1).- Not yet measured on a phone: see the PR description.
Ray-march scene
A two-pass WebGL2 scene for the client's background canvas: an infinite terrain of CultMath
noise with a world tree at its centre, dusk atmosphere and clouds, and a camera that pulls back
from the tree on login. It is a self-contained module; nothing in the client imports it yet.
Integration (a canvas under the app, startBackgroundScene, login() when the session starts,
dispose()) is Void's cut terrain-background; the personas (orbiting-personas) and the squirrel
are later cuts. This PR is the render core plus the contract the host needs: flag, tier, failure
callbacks and the creature sizing rule. Nothing has drawn a creature.
Ridge scene: Vienna and the weather
The ridge sky is the physical atmosphere (ridge/earthAtmosphere.ts) lit by the real sun over the viewpoint, 48.1929826 N, 16.3534237 E
(ridge/vienna.ts).
The weather is one number (ridge/weather.ts), from the page URL's ?weather=, else weather.json beside config.json, else clear.
The browser never calls a weather service. weather.json is written by Eureka's refresher (gamecult-ops docs/weather-feed.md, a 5-minute timer; the only writer) from GeoSphere Austria's TAWES station 11035 (Wien Hohe Warte), credit
"Datenquelle: GeoSphere Austria - https://data.hub.geosphere.at". Shape: {fetched_at, observed_at, station, precip_mm_10min, humidity_pct, glow_wm2, sunshine_s_10min, attribution}, null for a missing measurement. A file fetched more than 30 minutes ago, or holding an observation more than 40 minutes old, or from another station, is a clear
sky. Rain is the gauge; cloud is an estimate from the global radiation against Haurwitz's clear-sky value, cross-checked by the sunshine
duration, with the humidity as the fallback when the sun is low (ridge/weatherFeed.ts). The weather draws a cloud deck in the sky
(ridge/clouds.ts) and lays tiled rain streaks over the sky (ridge/rain.ts, compositor-driven, none in a still).
Entry points
index.tsstartBackgroundScene(config.backgroundScene, capabilities, options)is the host's door. The client config'sbackgroundScene.tier(offdefault,still,low,full) is the feature flag and the ceiling;tier.tslowers it forsaveData, low memory or few cores. Atoffnothing is imported and no canvas context is requested; otherwiseScene.tsloads on demand, so it stays out of the main chunk; if that chunk fails to load the error goes toonCompileFailand the door returns null, it does not throw.Scene.tscreateScene({ canvas, tier, onCompileFail, onContextLost, ... })returns{ login, dispose }, ornull(keep the CSS ground then) when the tier isoff, WebGL2 is missing, neitherEXT_color_buffer_floatnorEXT_color_buffer_half_floatexists (onUnavailablesays which; with only the half extension the prepass start target is RGBA16F, written rounded down), or a shader fails to compile (onCompileFailgets theShaderCompileError; programs already linked are freed).stillis a live rendered frame, not a baked image: it runs the full pipeline once at the top level and stops;lowstarts the ladder at level 2;fullat level 0. A lost WebGL context stops the scene for good and callsonContextLost; the scene never rebuilds itself.host.tsdisposes it, dropsdata-sceneso the CSS ground shows, and starts a fresh scene onwebglcontextrestored. It caps at 30 fps, pauses when the tab is hidden, renders 32 frames and stops underprefers-reduced-motion(a change of the preference while it runs freezes or thaws it), and steps down a quality ladder (budget.ts) against a 4 ms GPU budget when timer queries exist.creatures.tsthe creature record andcreatureScale: a neutral creature is one fixed size and overridessizeBucket. The bucket names and scales are placeholders until the persona cut owns them.camera.tsthe pull-back path as pure functions (pullProgress,cameraPose).world.tsevery world number, and the Lipschitz bounds the sphere trace steps by. The GLSL#defines are generated from it; no number is written twice.shaders/sdf.glsl(the distance bound pass 0 and pass 1 share), pass 0prepass.frag.glsl, pass 1terrain.frag.glsl, pass 2atmosphere.frag.glsl,resolve.frag.glsl(TAA),composite.frag.glsl, plus CultLib's vendored GLSL (shaders/README.md).
How it renders
- Cone prepass (
prepass.frag.glsl, one texel per 8x8 tile of pass 1): marches one ray per tile, shrinking each step by the widest any ray of the tile strays from it, so every step is free for the whole tile. It stores the distance no ray of the tile can have hit before, orW_FARwhen the whole tile climbs out above the highest geometry. Pass 1 starts its rays there.createScene({ prepass: false })skips it (the measurement baseline). - Solid pass (
terrain.frag.glsl, 0.4-0.75 of canvas resolution): sphere trace ofmin(terrain, tree). Terrain height ismask(r) * (A * fbm + E * phacelle), withcultmath_fbm_grad(...).wandcultmath_phacelle(...).cos.w. It writes lit colour with coverage and the hit distance (second render target). - Atmosphere pass (0.25-0.5 of canvas): closed-form exponential height fog plus a cloud slab marched with a few jittered steps, both only up to the hit distance from pass 1.
- Resolve: TAA on the atmosphere (Halton jitter, history reprojected by the pass-1 depth, 3x3 neighbourhood clamp, 1/8 blend; reset on resize, level change and wake).
- Composite at canvas resolution: solid over analytic sky, then the atmosphere, ACES tonemap, dither.
createScene({ onTraceStats }) measures the trace: pass 1 gets a step-count output and an extra
render target, read back every 8th frame through a pixel-pack buffer and a fence (never waited
on), and reports mean steps per pixel. Unset, neither the output nor the target exists.
The step bound, and what is not proven
The trace steps by (y - h(x, z)) / sqrt(1 + G^2), G the Lipschitz bound of the height field,
computed from SNOISE_LIPSCHITZ (CultMath's constant for snoise) in world.ts. Above the
envelope (fbm plus the erosion amplitude) the step uses the envelope's bound alone and Phacelle is
not evaluated.
- The Phacelle gradient bound
phacelleGradBound(7.0) is Libby's measured sup (6.63 at |side| = 1.5, n = 0, CultLib PR #1 head 990521b3) plus margin: a measurement, not a proof. The shader fixes roughness n = 0; a nonzero n needs the bound divided by (1 - n). - The bound makes grazing rays crawl. A ray that exhausts its steps while still below the highest terrain is ended as a distant surface (fog hides it). That is a visible approximation, not a hit proven by the march.
- The low-resolution atmosphere samples pass-1 depth nearest, so silhouettes of near objects carry a thin fog halo.
Measured and not measured
See the pull request or harness/scene/README.md for the numbers and how they were taken. They
come from a software rasterizer, not a GPU, and nothing has been run on a phone.