Procedural Geometry

Procedural Geometry

Generate geometry from semantic dimensions and explicit coordinate frames. The fast path is not "make triangles"; it is a reusable mesh compiler that writes indexed BufferGeometry directly into preallocated typed arrays, owns smoothing groups and material slots, and chooses BatchedMesh, InstancedMesh, or static geometry from topology and update behavior before any vertex is emitted.

Use $threejs-choose-skills for preflight when geometry, materials, shadows, and post processing all matter. This skill owns reusable mesh emission. Use $threejs-procedural-buildings-and-cities for building grammars, $threejs-procedural-vegetation for growth hierarchies, and then apply these mesh-writer mechanisms inside those subject skills.

When geometry supplies collision or support, apply the shared physics-domain and interaction contract. Publish stable ColliderProxy records and a static SupportSurfaceSample adapter from authoritative geometry/field topology. Its canonical PhysicsSignalDescriptor and each batched PhysicsSampleRequest/ SupportSurfaceSample preserve contextId, requested/actual footprint and filter, frame/origin/transform revision, state/resource version, validity, per-channel error, residency, cadence/latency, and explicit absence. A request uses its exact PhysicsInstant or PhysicsTimeInterval; the returned support record uses sampleInstant: PhysicsInstant. Convert world geometry once through PhysicsContext.worldToPhysicsTransform and its sole metersPerWorldUnit; the proxy/provider serializes no reciprocal or second scale. IDs, material bindings, frames, source versions, validity, and error bounds are independent of render LOD, batching, and runtime triangle/ instance indices. Moving or deforming support remains owned by motion/site/domain solvers through a DeformingSupportProxy; this mesh compiler must not infer its velocity from render-frame differences.

API Baseline

• Renderer: WebGPURenderer from three/webgpu; call await renderer.init().
• Shading: TSL from three/tsl with MeshStandardNodeMaterial, MeshPhysicalNodeMaterial, MeshBasicNodeMaterial, or other NodeMaterial family classes.
• Post and diagnostics: RenderPipeline, pass(), mrt(), PassNode.setResolutionScale(), built-in GTAONode, BloomNode, TRAANode, CSMShadowNode, and TileShadowNode when those effects are needed by the inspection scene.
• GPU-generated or hot dynamic fields: TSL Fn().compute(count) through renderer.compute() / renderer.computeAsync(), with StorageBufferAttribute, StorageInstancedBufferAttribute, storage() nodes, and indirect draw buffers where culling or compaction is compute-owned.
• Color: LDR color assets encoded as sRGB use SRGBColorSpace; HDR/EXR radiance remains loader-declared linear. Geometry data, normals, masks, LUTs, and procedural lookup textures use NoColorSpace/linear. Keep HDR buffers as HalfFloatType until the single tone-map and output conversion owner in the node pipeline via outputColorTransform or renderOutput().

After initialization, use renderer.compute() for ordinary submission. r185 computeAsync() only initializes on demand before enqueueing and is not a GPU-completion fence.

Capability Gate

Use one native renderer path and degrade geometry quality, not backend:

await renderer.init();

if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error(
    'WebGPU is required for the canonical procedural-geometry path; explicit fallback teaching belongs to threejs-compatibility-fallbacks.'
  );
}

Legacy WebGL implementation (deprecated, do not extend): examples/sculpted-gallery-frame/frame-geometry.js

Canonical implementation contract: examples/semantic-mesh-writer/. Run node examples/semantic-mesh-writer/validate-geometry.js --fixture frame-hero --json after edits.

Space Contract

Local Terrain And Coast Representation Gate

For local islands, archipelagos, reservoirs, river margins, and coastal sites, consume one versioned field contract from $threejs-procedural-fields: positive-inside shoreline distance, coast frame, raw elevation, bathymetry, terrace levels, cliff top/toe, material identities, and placement exclusions. Do not independently regenerate a shoreline in the terrain, seabed, material, and placement paths.

Choose the mesh class from the observable:

The terraced compiler operates on superlevel regions Omega_k={p:zRaw(p)>=L_k}. The horizontal cap at level L_k is the polygonal region Omega_k minus Omega_(k+1); the boundary of Omega_(k+1) owns the wall from L_k to L_(k+1). This handles split/merge topology without attempting to pair unrelated contour vertices. Extract contours with marching squares and an asymptotic decider for ambiguous cells; key intersections by global grid edge plus iso-level so adjacent cells and chunks reuse the same result.

Use constrained triangulation for polygons with holes and robust predicates. Ear clipping is eligible only for validated simple loops. Duplicate render vertices across cap/wall, material, UV, and hard-normal boundaries, but retain a separate topological edge/vertex identity so manifold validation still knows the surfaces meet. A closed land body requires every topological edge to have two incident faces; explicitly declared waterline or chunk boundaries are the only exceptions.

Emit semantic slots such as terrain-cap, cliff-wall, dry-beach, wet-beach, and visible-seabed. Caps use world-distance XZ UVs; walls use coast arc length and physical height. Export stable shoreline/terrace boundary IDs plus placement anchors carrying position, surface frame, coast distance, slope, terrace ID, clearance, and seed. Buildings, docks, paths, vegetation, and rocks consume those records and an explicit exclusion field; they must not re-sample an approximate display mesh and invent new identities.

wet-beach is a static substrate/capacity identity and visible-seabed is a geometry/visibility identity. Neither stores dynamic liquid, inundation, foam, or precipitation state. Their materials consume the route-selected receiver owner's immutable wetness/inundation snapshot and the water owner's completed signals.

Read the full compiler, LOD, seam, and adversarial-validation contract in profile-sweeps-and-mesh-writers.md.

Static physics support output

When requested by the route, compile a physics proxy package beside render geometry. It references the active PhysicsContext, canonical physicsFrameId/physicsOriginEpoch/transformRevision, source field/topology revision, stable proxy and semantic IDs, PhysicsMaterialId, support domain, sidedness, sample footprint policy, and maximum position/support-height/normal error. A SupportSurfaceSample adapter queries this package or its authoritative field, never the current display LOD or camera depth.

SupportSurfaceSample is kinematic only. Its optional nearest-surface signed separation is not a contact penetration/manifold. It does not own contact lifecycle, impulses, or reactions. The collision solver owns the canonical ContactManifoldRecord plus dimensional InteractionRecord ABI and resolves impulses; geometry supplies stable generation-bearing shape/support/feature identity and bounded surface data only.

A view-independent geometry/deformation state publishes one leased PresentedStatePair per stable binding/provider in PhysicsPresentationCandidate; each previous/current arm carries independent provenance, PhysicsInstant, state handle, and spatial binding. Per-view render LOD, visibility, picking acceleration, shadow representation, cache state, and reset actions belong to ViewPreparationPublication, after CameraViewPublication owns the render mapping. The sealed snapshot references candidate binding IDs and lease refs rather than copying pairs or transforms; the multi-target FrameExecutionRecord owns completion and lease disposition. A representation/topology change emits the scoped motion/history invalidation reason. Static geometry is an explicit hold pair, not an unleased mutable buffer, and a view-specific LOD is never baked into the shared candidate.

Graphics LOD may change vertices, groups, and draw representation while the physics proxy identity remains fixed. A distinct physics proxy quality change requires an explicit QualityTransition and new declared errors; it cannot be triggered as a side effect of render LOD. This skill emits only static support. Moving platforms, flexible structures, animated hulls, and edited deforming surfaces require a versioned DeformingSupportProxy and transform/deformation provider owned by the motion, site, or external solver adapter.

Build Order

1. Choose the algorithm class and batch model: semantic indexed BufferGeometry writer for unique authored surfaces, BatchedMesh for many same-material objects with varied topology, InstancedMesh for repeated topology with per-instance transforms or attributes, and storage/indirect buffers only when visibility or deformation is hot enough to justify GPU-side generation.
2. Define semantic dimensions, named regions, material slots, smoothing groups, UV charts, and LOD tiers before allocating buffers. Each LOD declares a projected geometric-error threshold using the shared physical-pixel contract; triangle-count ratios alone do not bound silhouette or shading error.
3. Precompute exact vertex/index capacity per tier; allocate typed arrays once; select Uint16Array indices only when every referenced vertex fits, otherwise use Uint32Array.
4. Emit through a writer API: addVertex, addTriangle, addQuad, addGroup, startSmoothingGroup, startUvChart, and finishGeometry.
5. Duplicate vertices intentionally at hard edges, caps, UV seams, material boundaries, mirrored tangent spaces, and any place that needs independent normals or tangents.
6. Generate UVs from real distance for production materials. Reserve normalized (s,t) coordinates for local debug views or analytic node masks.
7. Sweep curves with a rotation-minimizing parallel-transport frame: project an authored initial normal off the first tangent, apply the minimal tangent-to- tangent rotation with an explicit antiparallel fallback, re-orthonormalize, and apply authored twist separately. Closed loops distribute residual holonomy by arc length. Frenet frames are invalid at zero curvature and inflections.
8. Prefer analytic normals and tangents from the generator. Use computeVertexNormals() only for intentionally smooth shared-vertex regions; for Mikk parity, await MikkTSpace.ready and call computeMikkTSpaceTangents(geometry,MikkTSpace,negateSign). r185 de-indexes indexed input, so treat it as a separate representation and recompute counts/groups/bounds/bytes; prefer analytic tangents when valid.
9. Assign BufferGeometry groups exactly: every index belongs to one group, no group overlaps, and material index order is stable across LODs.
10. Set attribute usage before first render. Static meshes can release CPU arrays with onUpload() when no rebuild is needed; dynamic sections use addUpdateRange(), needsUpdate, and targeted bounds recomputation.
11. Validate finite attributes, index bounds, degenerate triangles, winding, normal length, tangent handedness, UV density, bounding box/sphere, group coverage, byte cost, draw calls, and renderer stats.
12. For large sets, partition by the smallest useful culling/streaming unit. Compare CPU chunk submission, BatchedMesh, and compute-filled indirect visibility using submitted-work measurements. A shader mask that still executes every hidden vertex is not culling.

Read references/profile-sweeps-and-mesh-writers.md for the profile sweep, rail emission, branch-ring, semantic writer, batching decision table, quality tiers, and validation budgets.

Performance Contract

• Static profile: record V, T, index width, attribute stride, material groups, projected geometric error, and compile bytes/time. It performs no per-frame allocation or mutation and rebuilds only when geometry inputs change.
• Repeated unique modules: BatchedMesh can reduce scene objects/state churn while preserving per-object culling/replacement, but r185 WebGPU emits one backend draw item per visible multi-draw entry. Measure renderer.info and GPU submission; merge static compatible geometry when draw collapse is the actual requirement.
• Repeated identical topology with CPU-owned matrices: InstancedMesh and its instanceMatrix. When storage owns the complete transform, use a matrix-free Mesh with InstancedBufferGeometry plus storage-backed position/quaternion/ scale (or required affine state); otherwise r185 still allocates/applies the redundant [Derived] 64-byte mat4<f32> instanceMatrix.
• Dynamic edits: update only changed component ranges; target zero full-buffer uploads during interaction and zero geometry object churn per frame.
• Dynamic updates report changed ranges and bytes, CPU encode/submission p50/p95, GPU consumption p50/p95, and allocation count. Rebuilds are a separate cold/interaction class and must report vertices, indices, groups, peak transient bytes, and time to first correct frame.

The scene router allocates the actual ceiling. Accept with target-device whole-frame and paired-marginal p50/p95, update/submission timing, peak upload bytes, and sustained behavior. Static scenes have no per-frame geometry mutation. Choose tessellation from projected error; no universal triangle cap separates mobile from desktop.

Failure Conditions

• triangle emission starts before the batch model and material slots are known;
• profile orientation flips along a curve;
• caps reuse side vertices and create averaged edge normals;
• UV scale changes with segment count or LOD tier;
• arbitrary vertex merging destroys hard edges, UV seams, tangent spaces, or material boundaries;
• generated dimensions are hidden in magic multipliers;
• InstancedMesh is used despite per-instance topology differences;
• BatchedMesh is claimed to collapse r185 WebGPU GPU draws without inspecting visible multi-draw entries/backend commands;
• attribute usage is changed after upload instead of rebuilding the attribute;
• dynamic geometry uploads whole buffers when only subranges changed;
• triangle count is the only reported complexity metric.
• collision/support is sampled from the active render LOD, camera depth, or runtime triangle index, or a graphics LOD change mutates proxy identity;