Painted Valley
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
| file | what it is |
|---|---|
sky.module | the part's entry, require("paintedValley.sky.sky"): KEYS / blend / sunAt / SUNSET, createSkyParts + light(hour), setHour, build / update / destroy, bindTo |
clouds.module | clouds.js: mulberry32, the hand-made layout (14 cumulus, 210 puffs), the billow numbers, the cube's strips, setLight / drawAll / update |
backdrop.module | backdrop.js: the height map and the painted strip, as strips of dispatches |
skyDome.shader | the dome (// @domain: sky), sky.js's fragment line for line |
skyCommon.shaderModule | shared WGSL: cloudsAt (the cube atlas), skyGradient, skyAt (water.js), backdropUv, backdropDone |
cloudBillow.computeShader | billowTexture(64) on the GPU, from the original's own random numbers, rounded to half as three.js rounds |
cloudMarch.computeShader | the cloud ray marcher (map / paint / main), one strip of one cube face a dispatch |
backdropHeight.computeShader | backdrop.js heightFragment |
backdropPaint.computeShader | backdrop.js paintFragment (three RGBA8 outputs) |
dev/skyTest.scene | the 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 atv.quality == "high"), the far country (12288-wide strip, 4096² height map), the dome materialpv_sky_domeon a Skybox, and the sky's own sun and ambient light; paints the strip, then the clouds forv.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'ssetHour(v, hour, quick)issetHour(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). Pushescore.setMany{ uSunDir, uSunColor, uSkyColor, uBounceColor, uFogColor, uFogSunColor, uFogDensity, uCloudShade = 0.15 }whenv.coreis 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, andexposure. main.js's keys call it with soft = nil; its drift callssetHour(v, min(SUNSET, hour + dt * drift * DRIFT), true).destroy(v).- State on the table:
hour,exposure(the frame reads it),elevation,sunDir(.x .y .zand[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.elandbackdrop.width/height),SUNSET,TIMESandDRIFT(main.js),KEYS,blend(e),sunAt(hour) -> (dir, e),ready(). bindTo(materialKey)/unbind(materialKey): for water.js. The sky bindstCloudsand keepsuZenith, uMid, uHorizon, uGlow(float3) anduCloudFace(float) up to date on that material on every setHour. Its shader declares those after its own block and#include "paintedValley.sky.skyCommon", then callsskyAt(tClouds, tClouds_sampler, d, material.uCloudFace, material.uHorizon, material.uMid, material.uZenith)where water.js callsskyAt(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
dispatchExon 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
hashkeeps 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 * doneas 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'ssceneLights) makes the scene's ownsun(directional) andambientLight 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).