Log inGet started
World

Painted Valley

Branchmain
Branchesmain
Commit12ad3f264b

README.md

paintedValley/sky — the sky, its clouds, the far country, and the light of the hour

Port of Painted Valley's valley/sky.js, valley/clouds.js, valley/backdrop.js and the sky's part of valley/main.js (blendi/painted-valley on Patch, MIT). Numbers, names and comments are the original's.

Files

filewhat it is
sky.modulethe part's entry, require("paintedValley.sky.sky"): KEYS / blend / sunAt / SUNSET, createSkyParts + light(hour), setHour, build / update / destroy, bindTo
clouds.moduleclouds.js: mulberry32, the hand-made layout (14 cumulus, 210 puffs), the billow numbers, the cube's strips, setLight / drawAll / update
backdrop.modulebackdrop.js: the height map and the painted strip, as strips of dispatches
skyDome.shaderthe dome (// @domain: sky), sky.js's fragment line for line
skyCommon.shaderModuleshared WGSL: cloudsAt (the cube atlas), skyGradient, skyAt (water.js), backdropUv, backdropDone
cloudBillow.computeShaderbillowTexture(64) on the GPU, from the original's own random numbers, rounded to half as three.js rounds
cloudMarch.computeShaderthe cloud ray marcher (map / paint / main), one strip of one cube face a dispatch
backdropHeight.computeShaderbackdrop.js heightFragment
backdropPaint.computeShaderbackdrop.js paintFragment (three RGBA8 outputs)
dev/skyTest.scenethe sky porter's own empty test scene (not the valley's)

Module API (require("paintedValley.sky.sky"))

  • build(v): makes the clouds (2048² faces, 240 steps, live at v.quality == "high"), the far country (12288-wide strip, 4096² height map), the dome material pv_sky_dome on a Skybox, and the sky's own sun and ambient light; paints the strip, then the clouds for v.hour (default 15.5). Yields until painted when called from a task (about 0.2–0.3 s), else update() finishes the painting. The driver's setHour(v, hour, quick) is setHour(v, hour, soft) here.
  • update(v, dt): every frame (play and edit): what a bake still owes, else clouds.js update (one strip of one face a frame while live).
  • setHour(v, hour, soft?): 12..SUNSET (clamped). Pushes core.setMany{ uSunDir, uSunColor, uSkyColor, uBounceColor, uFogColor, uFogSunColor, uFogDensity, uCloudShade = 0.15 } when v.core is given (the values sky.js hands field.setLight), sets the dome's uniforms, relights the clouds (soft: a strip a frame, as time passing does; otherwise drawAll, laid over the next ~10 frames), sets the engine sun/ambient, and exposure. main.js's keys call it with soft = nil; its drift calls setHour(v, min(SUNSET, hour + dt * drift * DRIFT), true).
  • destroy(v).
  • State on the table: hour, exposure (the frame reads it), elevation, sunDir (.x .y .z and [1..3], towards the sun), light (the field light as pushed), uniforms (uZenith, uMid, uHorizon, uGlow, uBankLit, uBankShade as they stand), textures (compute names: tClouds = "pv_sky_clouds", tBack0..2 = "pv_sky_back0..2"), parts (clouds, backdrop; backdrop.el and backdrop.width/height), SUNSET, TIMES and DRIFT (main.js), KEYS, blend(e), sunAt(hour) -> (dir, e), ready().
  • bindTo(materialKey) / unbind(materialKey): for water.js. The sky binds tClouds and keeps uZenith, uMid, uHorizon, uGlow (float3) and uCloudFace (float) up to date on that material on every setHour. Its shader declares those after its own block and #include "paintedValley.sky.skyCommon", then calls skyAt(tClouds, tClouds_sampler, d, material.uCloudFace, material.uHorizon, material.uMid, material.uZenith) where water.js calls skyAt(d). (Checked beside valleyShade in one surface shader: compiles, 4 texture slots.)

Port decisions and differences

  • The cube map is an atlas. Five faces (+X, -X, +Y, +Z, -Z; -Y is never drawn) side by side in one 10240×2048 RGBA16F storage texture. Texel ↔ direction is the original's faceDir both ways; the lookup clamps half a texel inside each face where WebGL's seamless cube filters across the edge (a half-texel difference at face edges).
  • Strips. drawAll draws every face at once in the original (a ~75 ms GPU hitch on an RTX 5090 at 2048/240); here it is 4 strips a frame (~7.5 ms) over ~10 frames, 8 a frame while building. Live mode is the original's, 1 strip (~1.9 ms) a frame. The backdrop's height map and strip each measured under a frame and are spread over ~4 frames. (GPU times from a fence counter in a headless sub-client on a shared GPU: approximate.)
  • Per-dispatch params don't reach dispatchEx on this build, so each strip's job sits in its own tiny buffer.
  • Billows. The 64³ volume is filled on the GPU from the original's mulberry(90210) numbers (generated in Luau, same order) and truncated to half precision as three.js's toHalfFloat does. Spot texels match the original exactly; a whole-volume checksum differs by a handful of one-ulp half roundings (f32 GPU vs f64 JS arithmetic).
  • The far country's hash is evaluated as the original's compile does it. backdrop.js's hash keeps only a few bits in its last fract, so float rounding decides the mountains. ANGLE/D3D11 (the original on Windows) fuses the multiply-add and takes the 50 out of the sum (50 * (fx + fy)); our compiler fused and refolded differently, which lowered and blunted the great peak by about 0.5 km. The WGSL hash now does each rounded step explicitly (fma, then every step pinned through an opaque zero from the job buffer). Checked against the original rendered in Chrome on the same GPU: hash, noise and ridged bit-exact on 256 probe points, height within 0.07 m.
  • Hour table, sunAt, layout: identical to the original (checked against the original's JS under node to 1e-16).
  • Sky alpha. The dome returns 1 - 0.75 * done as the original does, but the deferred frame drops fragment alpha. In the original only the far country is "done" (skips the paint finish); open sky and clouds get the r = 1 brush. skyCommon.backdropDone(...) gives the frame that mask from a sky pixel's view ray.
  • Engine light. setHour sets the engine's sun and ambient light to the hour's light: colour × intensity = uSunColor / uSkyColor, direction = −uSunDir. The lights are the sky's own unsynced, temporary entities (paintedValley.sky.sun / .ambient), so a scene's authored sun and ambient stay as their author saved them. A light is written when its value differs from what it was last given: the same hour writes nothing. v.sceneLights = true (the Valley component's sceneLights) makes the scene's own sun (directional) and ambient Light entities, found by name, the lights instead; v.engineLight = false (engineLight) leaves the engine's light alone.
  • Uniform time stays 0, as the original's (the clouds hold their shape).
  • The height map is freed once the strip is painted (the original keeps it; nothing reads it after).