git:20260716.2ce13bc to git:20260716.62a9bc5

---

name: threejs-procedural-planets

description: Scale procedural planetary bodies in Three.js r185 WebGPU/TSL. Use when global curvature needs a cube-sphere quadtree, a sustained ground view needs a tangent clipmap, an orbit-to-ground transition needs both, or a gas-giant cloud deck needs body-scale band fields.

---

# Procedural Planets

Choose the body-scale representation first. One set of planet-space causes must

drive geometry, normals, material identity, queries, diagnostics, water/coast

handoffs, and atmosphere inputs.

## Process

1. **Gate body scale.** Test whether curvature, horizon, global geodesy,

orbit-to-ground transition, or atmosphere coupling is observable. A bounded

local site belongs to procedural fields and geometry when tangent-plane

sagitta, normal rotation, geodesic, horizon, and projected errors all pass.

Read

when deriving the body-scale gate.

**Complete when:** the accepted camera and data domain either proves a local

approximation or names at least one body-scale observable that requires this

skill.

2. **Freeze the body model and units.** Declare center, sphere radius or

ellipsoid axes in meters, `metersPerWorldUnit`, height and sea-level datum,

body/world transform, origin policy, surface-coordinate meaning, and

atmosphere bottom/top geometry. When a sphere approximates an ellipsoid,

**Complete when:** every length and vector has units and a frame, surface

altitude has one definition, render-origin changes leave physical field

identity unchanged, and the spherical branch either passes every declared

approximation gate or is rejected in favor of the ellipsoid.

3. **Select mapping and spatial representation.** Choose normalized,

spherified, or verified equal-area cube mapping from distortion and inverse

requirements. Choose a cube-face quadtree for arbitrary globe views, a

tangent clipmap for sustained local views, or a hybrid with an explicit

near/far handoff. A gas/cloud-deck body uses continuous wrapped band fields

**Complete when:** mapping Jacobian, seams, inverse/domain validity, camera

domain, and near/far ownership all have falsifiable gates.

4. **Build error-bounded LOD and submission.** For the global branch, maintain

six 2:1-balanced face quadtrees, continuous parent morph, and one of the 16

four-edge transition masks. Reuse a shared indexed grid and submit compact

patch records in instanced or indirect mask bins. For clipmaps, bound ring

error, recentering, and far-field ownership. Evaluate physical-pixel error

over the complete displaced support for every active view.

Before allocating compute, storage, or indirect resources, run

`await renderer.init()` and require

`renderer.backend.isWebGPUBackend === true`. Otherwise keep planning on the

CPU or report the native-WebGPU branch unavailable.

**Complete when:** projected error, hysteresis, and submission bounds pass,

plus every selected branch satisfies its own criterion:

- **global:** 2:1 balance holds across face edges/corners, all 16 masks are

crack-free, and production submission has no per-patch draw loop;

- **clipmap:** rings cover the local domain, recentering preserves field

coordinates, curvature/reconstruction error passes, and one far-body owner

covers beyond the outer ring;

- **hybrid:** near/far coverage has no gap and one composite owner in the

overlap, composite position and normal remain continuous through the

handoff, and overlap residency is bounded;

- **gas/cloud deck:** wrapped-longitude seams, advection continuity, stable

storm identity, and conservative advected bounds pass.

5. **Build shared causal fields.** Define common field functions for reference

direction, displacement, tangent gradient, geology, craters, climate,

hydrology, snow/ice, material causes, queries, and diagnostics. Direct,

compute-cached, and CPU-visible paths use the same schema and identity

constants. Cache only dirty patch causes, include cross-face filter support,

GPU patch min/max bounds use workgroup reduction plus deterministic merging,

or a proven monotonic ordered-integer encoding with explicit sign, NaN, and

decode-error rules. Do not rely on unsupported float atomics.

**Complete when:** geometry and shading use the same height function, cache

invalidation follows causes rather than cameras, parity covers every

published channel, min/max reduction is legal and conservative, and metric

value and normal errors pass their own gates.

6. **Publish narrow handoffs.** A field handoff states producer, consumer,

owner, units, frame/origin, sample time or interval, represented support and

filter, validity/staleness, version, and error. A planetary coast additionally

publishes mean surface, seabed height, metric coast distance/frame, source

resolution, and uncertainty. Atmosphere receives the same reference surface,

transform, `metersPerWorldUnit`, altitude convention, shell geometry, sun

**Complete when:** each consumer names one authoritative producer, rejects

invalid or stale data, and performs no frame-critical GPU readback.

7. **Bind materials and presentation.** Use `MeshStandardNodeMaterial` or

`MeshPhysicalNodeMaterial` from shared field causes. Keep data textures

linear, preserve declared color encodings, and hand HDR scene color to the

one `RenderPipeline` output transform. Rebuild only dirty field tiles or LOD

frontier state, keep in-flight cache resources immutable, and dispose retired

buffers, textures, passes, and indirect state.

**Complete when:** output conversion has one owner, direct and cached paths

agree, origin rebases preserve the body, and repeated resize/replacement

reaches a stable resource plateau.

8. **Verify the selected branches.** Capture orbit, horizon, and close views;

unlit silhouette; flat albedo without atmosphere; grazing light; mapping,

patch-error, transition-mask, normal, material, coast, and atmosphere

diagnostics. Sweep split/merge boundaries and use multiple fixed seeds.

**Complete when:** the scale and sphere/ellipsoid gates, mapping distortion,

every selected branch criterion above, shared-field parity, derivative

accuracy, atmosphere units, triangle/draw counts, cache bytes, timing, and

zero runtime readbacks all have direct evidence.

## Ownership Boundary

- Use `$threejs-procedural-fields` and `$threejs-procedural-geometry` for local

terrain whose accepted domain does not expose body curvature or global LOD.

- Use `$threejs-water-optics` for the time-varying free surface, currents,

breaking, foam, and water optics; this skill owns the reference surface,

seabed, and planetary coast analysis.

- Use `$threejs-sky-atmosphere-and-haze` for scattering and aerial perspective;

this skill owns the surface-side geometry and units handoff.

- Use `$threejs-image-pipeline`, `$threejs-scalable-real-time-shadows`, and

`$threejs-visual-validation` for shared output, shadows, and evidence.

This skill owns the body-scale surface representation, coupled planetary

fields, patch LOD/submission, query parity, and surface-side handoffs.