Skip to content

feat(clouds): takram's clouds draw in our scene through their WebGPU port, behind ?clouds=takram - #212

Open
jonjaques wants to merge 4 commits into
the-weatherfrom
spike/takram-clouds
Open

jonjaques wants to merge 4 commits into
the-weatherfrom
spike/takram-clouds

Conversation

@jonjaques

Copy link
Copy Markdown
Owner

What changed

A spike, and it answers one question: takram's volumetric clouds draw in our scene through the unofficial WebGPU port as it ships. three-clouds-webgpu 0.1.0-alpha.6 runs unmodified on our three 0.185.1, behind ?clouds=takram, beside ?clouds=1 and under the same engine.clouds levers. alpha.8 on three 0.187 was not tried, because alpha.6 drew.

The base is the-weather, not main: the branch was cut from it, because main has no cloud renderer and no cornerstones.

The port is not forked. The adapter is four modules under apps/game/src/render/ and holds no cloud shader:

  • takramFrame.ts puts our eye in the port's world. The port draws over a WGS84 ellipsoid in ECEF and takes the scene through one matrix; a point of the body's datum stands on Earth's equator, and the eye keeps its true height, heading and sun. Float64, no Three.
  • takramDepth.ts copies the scene's depth to one sample. The port samples depth by uv, and the default picture is 4× MSAA, which can only be loaded by texel.
  • takramClouds.ts builds the port's pass and takram's atmosphere, and draws the port's resolved layer as the first opaque of the scene pass over the clouds (ADR-0063), with the native composite's blend. The planet, the ground and the sea are ours.
  • takramTunables.ts is the port's 174 tunables and five presets as a table, written through engine.takram.

Four things the port needed that its recipe does not say:

  • Its composite assumes three's QuadMesh, whose v is 0 at the top. A plane's is 1 there, and the first frame drew the sky's clouds on the ground.
  • low, medium and lowEnd do not compile on a first frame. They turn accurateSunSkyLight off, and on r185 that graph fails with Member "bottomRadius" not found in struct "AtmosphereParameters". Rebuilt on the frame after one the port drew, it compiles. Nothing fails in the picture: the march's pipeline is refused and the frame costs less. A setting is written only after a frame the port drew. The cause is not found.
  • Its shadow maps are fitted to the camera's far plane, and ours is 10¹⁰ m. As shipped the clouds barely shadow themselves, and the pass is more than half of high. shadow.maxFar 200,000 draws a better-shadowed cloud for 9.10 ms in place of 19.82. The adapter leaves the preset as shipped.
  • pnpm refuses the geospatial fork build as a tarball URL (ERR_PNPM_EXOTIC_SUBDEP). It is vendored as a file, one of the policy's trusted sources, with its MIT text beside it. The policy stays on.

The sensor's chain and the engine hold CloudChainSystem, the cloud system less the native march's field and resources, so either renderer's factory fits. CONTEXT.md has the entry.

Cost

The whole frame with the clouds on less the same page with them off. G1 (weather-g1-fair, on P222_3_2_k IV), Mac mini (M6), production build 28903d80, one fresh page a row, ir.gpu(135) three times and the least kept, three pairs and their median, thermal pressure 0 before and after every row. The frame without clouds is 5.2 ms at 1920 × 1080 and 11.9 ms at 2880 × 1800.

Row 1920 × 1080, DPR 1 2880 × 1800
The native renderer 7.87 ms 8.86 ms
Takram lowEnd 2.49 5.63
Takram low 4.50 7.10
Takram medium 10.22 16.39
Takram high 19.82 26.60
Takram ultra 54.89 70.12
high, no layer casting a shadow 8.82 15.72
high, shadow.maxFar 200 km 9.10 16.61
high, lightShafts off 19.46 not taken
high, temporalUpscale off 55.11 not taken

The native row agrees with the weather's own ground row, 7.82 ms. ultra reads 60.1 ms right after the clouds go off and on and 64.1 ms held on; the table's is the first.

Invariants

  • Rule 60. The adapter imports three/webgpu and three/tsl. The port's own build imports three, which shares three.core.js; one copy of three resolves.
  • Rule 61. The adapter warms its composite through render/warmup.ts. The port's march and shadow pipelines have no compile-ahead and build on the first frame drawn. See Left out.
  • Rule 69. The composite stands where the native one stands, and the marks are unchanged, so an object marked over the clouds draws over these too.
  • Rule 68. Every still, cast and figure went through scripts/drive.mjs on one rig, under the GPU lock.
  • Rules 1 and 52. The frame placement is float64 on the CPU. The port's shaders work in its own ECEF in float32 and take length(position) − bottomRadius, which steps by half a meter at Earth's radius. That is inside the dependency and is not held to rule 52; no artifact showed on a still camera.
  • No new invariant.

Screenshots

G1, same camera and sun, 2880 × 1800, shown at half size. The native renderer:

The native renderer on G1: smooth lumps with stepped edges over the plain

Takram, high as shipped:

Takram's high preset on G1: cumulus with small cells and a far field to the horizon

Takram, high with shadow.maxFar 200,000:

Takram's high preset with the shadow range capped at 200 km: darker, shadowed bases

One cloud edge against sky at 2×, nearest-neighbor. The native renderer, then takram:

The native renderer's edge at 2×: steps of four device pixels

Takram's edge at 2×: detail to the pixel, with grain

Takram's presets on G1 at 1920 × 1080: low and medium above, high and ultra below.

Takram's four presets on G1

G3 (weather-g3-underlit-dusk), 2880 × 1800 at half size. The native renderer, then takram. Takram draws its stock layers, not our dusk-altocumulus regime, so these are two skies.

The native renderer on G3: an altocumulus deck lit orange from below

Takram on G3: purple cumulus under salmon cirrus

E1 (weather-e1-cumulus-orbit, Earth from 400 km), 1920 × 1080: takram on the left, the native renderer on the right. The port's march ends at 200 km.

Earth from 400 km: takram draws almost nothing, the native renderer draws the field

Takram on G1 at 1920 × 1080, a slow turn of 2.4° a second, then a held camera:

https://agentic-media-dumpster.jonjaques.com/2026/11/7y8m56ebdz/takram-high-slow-turn-1080p.mp4

https://agentic-media-dumpster.jonjaques.com/2026/11/hk5zca53b2/takram-high-held-1080p.mp4

Verification

  • pnpm check green at 28903d80: 21 stages, 139.3 s. Its sim stage passed; I did not read the capability count. The commit after it, 6274b60c, is CONTEXT.md alone, and spelling, format and docs passed on it; the full check was not run again.
  • pnpm vitest run takramFrame: four properties on the frame placement pass. With the east axis flipped, one fails.
  • CONTEXT.md updated. No ADR: a spike, and the choice between the renderers is not made.
  • The rig round-tripped all 174 tunables and applied each of the five presets with no mismatched field.
  • The held cast: 420 frames at 41.6 fps, no isolated frame. The slow-turn cast: 600 frames at 38.4 fps, under the rig's 40 fps all-clear.
  • pnpm test:gpu: not run.
  • pnpm presets:compare: not run. Without the flag the takram chunk is never loaded, and check-site-chunks holds that, but no plate was compared.
  • No regression test holds the first-frame compile failure. It needs a *.gpu.test.ts, which is not written.
  • The branch was never pushed and the-weather has not moved from c34cd9f7, so nothing was replayed.
  • invariant-auditor was not launched. The diff would warrant it: a dependency in the render layer and a second system in the sensor's chain.

Left out

Each is a fork point, sized in the build log's entry and in the thread, and none is started:

  • The air. The light on a cloud and the haze in front of it are takram's Earth's, not ADR-0056's.
  • The weather. The port's stock 512² map, tiled a hundred times round the globe, not our field. At G1 its texels show as square-footprint cells.
  • Shadows on the ground and the sea. cloudShadowAt answers the sun's transmittance at any point; no material of ours reads it.
  • Orbit. The native far atlas stays; no handover.
  • Motion. A cloud writes no motion vector, and nothing reads the cloud in front of a transparent object.
  • Boot. With high drawing during boot the cover lifts 34 s after the page attaches at 1920 × 1080, and not within 90 s at ultra.
  • Two causes not found: the first-frame compile failure, and a stale shadow program when a setting changes after back-to-back ir.gpu frames. Both are worked round, in the adapter and in how the rows were taken.
  • An intermittent console error, renderPipeline_MeshBasicNodeMaterial_39 refused, in two boots at lowEnd. The picture drew.
  • Measured on the Mac mini alone.

🤖 Generated with Claude Code

jonjaques and others added 4 commits November 14, 2026 15:41
…port, behind ?clouds=takram

A spike. `three-clouds-webgpu` 0.1.0-alpha.6, the unofficial WebGPU port of
@takram/three-clouds, runs unmodified on our three 0.185.1 and draws on the
G1 cornerstone in the slot the native composite uses. One build shows either
renderer: `?clouds=1` is ours, `?clouds=takram` is theirs, under the same
`engine.clouds` levers. `engine.takram` holds the port's presets and tunables.

The adapter is four modules and holds no cloud shader:

- `takramFrame.ts` puts our eye into the port's Earth frame. The port draws
  over a WGS84 ellipsoid in ECEF and takes the scene through one matrix; a
  point of the body's datum is stood on Earth's equator and the eye keeps
  its true height, heading and sun. Float64, no Three, with a property test.
- `takramDepth.ts` copies the scene's depth to one sample. The port samples
  depth by uv and the default picture is 4× MSAA, which can only be loaded
  by texel. R32F, because a reversed depth in a half float steps by 12% of
  itself at 100 km.
- `takramClouds.ts` builds the port's pass and takram's atmosphere, and
  draws the port's resolved layer as the first opaque of the scene pass over
  the clouds (ADR-0063), with the native composite's blend. Its luminance is
  scaled to scene units by arithmetic: an albedo-one surface under the
  port's sun is its illuminance over π, which is one unit (ADR-0065).
- `takramTunables.ts` is every preset and tunable as a table, and the
  page's settings, which outlive a chain.

Three things the port needed that its recipe does not say:

- Its composite samples at the mesh's uv and is written for three's
  `QuadMesh`, whose v is 0 at the top. A plane's is 1 there and drew the
  clouds on the ground.
- Its pass updates once per three frame, a counter only three's own loop
  advances. Here it is once per render call, as the scene pass is, or a rig
  submitting frames back to back times one march and forty quads.
- pnpm refuses the geospatial fork build as a tarball URL
  (ERR_PNPM_EXOTIC_SUBDEP), because it is the atmosphere's dependency and
  not ours. It is vendored as a file, one of the policy's trusted sources
  and the port's own install; the policy stays on. Its MIT text is beside it.

The sensor's chain and the engine now hold `CloudChainSystem`, the cloud
system less the native march's field and resources, so either renderer's
factory fits.

Not done, and each a fork point for the report: the air between eye and
cloud is takram's Earth's, the weather is the port's tiled map, no cloud
shadows our ground, a cloud writes no motion vector, and nothing reads the
cloud in front of a transparent object.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
… so the page loads no chunk more

`pnpm check` failed at `bundle`: `index.html` loaded 59 chunks where
`GAME_PAGE_CHUNKS` says 58. Built with and without the takram import, the
closure differs by one chunk, `profile` (`procedural/hash.ts` and
`profile.ts`, 950 bytes).

The takram chunk imported `cloudsServed` from `@inertialref/rendering`. That
put the weather's modules in a second lazy chunk's reach while the hash
beside them stayed the page's alone, so the bundler split the hash out and
every visit fetched it. `App` already holds `cloudsServed` through the
engine and now hands it to `loadTakramClouds`. The report carries no lever
hash for the same reason: `cloudLeversHash` reaches the same module.

The port's own modules were never the problem. They sit behind the flag in a
398 kB chunk, minified, which holds the port, takram's atmosphere and
geospatial packages, and `postprocessing`, a WebGL library the atmosphere's
root entry imports and the port reads two helpers through.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
…?clouds=takram:low builds a preset

Three of the port's five presets did not survive how the page applied them,
and the first cost table was taken in the broken state.

`low`, `medium` and `lowEnd` turn `accurateSunSkyLight` off. On three 0.185
that graph does not compile on a first frame: TSL reports
`Member "bottomRadius" not found in struct "AtmosphereParameters"`, then
`topRadius`, `minCosLight` and the scattering table's sizes, and Dawn refuses
`renderPipeline_CloudsPass` for an invalid fragment module. It fails the same
way built at boot and rebuilt on the first frame after the clouds were off.
Rebuilt on the frame after one the port drew, it compiles. `high` and
`ultra` build either way.

Nothing fails loudly. The march's pipeline is refused, the composite draws
the last good layer or none, and the frame gets cheaper: `low` read 9.7 ms a
frame with errors in the console and 12.4 ms without, and neither was the
preset. So the settings are now written by `flush`, which the system calls
after a frame the port drew, and by nothing else; a context is always built
at the port's own `high`. Both routes to `low` then draw one picture, 1.0%
RMSE apart, at 9.7 ms, with a clean console.

The write also restores `temporalUpscale` and `lightShaftsHalfResolution`
first. Only `lowEnd` names them, so after a full-resolution march the next
preset kept it.

`?clouds=takram:low` builds the port at a preset, so a cost row can be a
fresh page rather than a switch. The frame state reports how often the
port's pass ran against the frames drawn: one to one, under the page's loop
and under back-to-back frames.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
…n the build log

The three commits before this each say what one change did. None holds the
table the spike exists to produce, and the evidence behind it is in the
worktree's ignored `.data/takram/`, which goes when the worktree does.

The entry carries what a later run would otherwise measure again: the cost
of each of the port's presets on G1 at 1920 × 1080 and 2880 × 1800 beside
the native renderer's, the far-plane fit that makes `high` cost 19.82 ms
where 9.10 ms draws a better-shadowed cloud, and the five things that cost
the time: the composite's uv, the presets that do not compile on a first
frame and get cheaper for it, the stale shadow program after back-to-back
frames, the chunk split, and pnpm's refusal of a tarball URL.

It records no decision between the renderers. That is the owner's, and no
ADR is written for a spike.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://spike-takram-clouds-inertialrefd.jaquers.workers.dev (commit 6274b60)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://0e1da490-inertialrefd.jaquers.workers.dev 6274b60 2026-11-15T00:12:35.710Z Visit the dashboard ↗

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant