git:20260713.f0e8d5c to git:20260716.2ce13bc

+ ---

+ 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

+ [planet-field-and-atmosphere-systems.md](references/planet-field-and-atmosphere-systems.md)

+ 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,

+ apply the reference's position, normal, area, geodesic, horizon, atmosphere-

+ altitude, and optical-depth error gate. Give each changing field one owner

+ and one version.

+

+ **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

+ rather than solid-terrain displacement. Read the reference when selecting a

+ mapping, ellipsoid convention, quadtree, clipmap, or hybrid.

+

+ **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,

+ and validate gradients independently before using analytic normals. Read the

+ reference when implementing caches, crater fields, detail filtering,

+ CPU/TSL parity, normals, materials, or gas-band fields.

+

+ 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

+ frame, and scene-linear radiometric basis. Read the coast and atmosphere

+ sections of the reference when either consumer is active.

+

+ **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.

+