---
name: threejs-procedural-geometry
description: Procedural geometry compilation for Three.js WebGPU/TSL. Use when a task needs an indexed mesh writer, contour-derived terrain or terraces, profile or branch sweeps, or a BatchedMesh, InstancedMesh, or dynamic-update decision.
---

# Procedural Geometry

Treat geometry generation as a compiler: select the representation, freeze
semantic regions and error bounds, compute exact capacity, emit topology and
render attributes, then validate both. Meaning belongs to generator inputs;
allocation, topology, groups, updates, and disposal belong to the writer.

For multi-system work, `$threejs-choose-skills` is an optional coordinator.
Fields own continuous causes, materials own PBR response, motion owns
deformation state, and this skill owns rendered topology. When geometry supplies
another system, publish stable units, coordinate/frame convention, producer and
consumer owners, revision, support, validity domain, error bound, and update
phase independently of render LOD and draw indices.

## 1. Select the representation before allocation

Choose from the observable and update pattern:

| Contract | Representation |
| --- | --- |
| one unique authored surface with material regions | indexed `BufferGeometry` with groups |
| many same-material objects with varied topology | `BatchedMesh` |
| many repeats with identical topology | `InstancedMesh` |
| GPU-owned transforms or visibility with identical topology | matrix-free instanced geometry plus storage-backed state |
| hot visibility compaction with stable buckets | storage data plus indirect draw commands |
| continuous single-valued relief | indexed adaptive grid, quadtree, or clipmap with a seam policy |
| hard terraces, cliffs, or topology-bearing bands | contour-derived caps plus explicit walls/band meshes |
| visible overhangs or caves | bounded volumetric meshing after memory/topology gates pass |

In r185 WebGPU, `BatchedMesh` manages geometry and culling but the backend still
iterates visible multi-draw entries; it is not evidence of one native draw.
`InstancedMesh` is valid only for identical topology.

This step is complete when one representation owns each surface/object class,
its culling and update unit is named, and no triangle or buffer has been emitted.

## 2. Freeze semantics and error contracts

Record coordinate frames, semantic dimensions, named regions, material slots,
smoothing groups, UV charts, hard boundaries, topology identities, LOD view
envelope, and resource owner. Gate each LOD with a conservative error bound in
physical render-target pixels at the actual target size and an unjittered view.
Include the complete support and error of geometry, active displacement or
deformation, filtering, and reconstruction. Use the exact camera projection or,
for a perspective approximation, the nearest valid positive view depth; accept
the LOD only when the projected bound is at or below that view's declared
threshold. Give each view separate enter/exit thresholds with hysteresis and a
minimum dwell, and keep both transition levels resident until the transition
finishes. Triangle ratios are supporting counts, not an error bound.

For contour-driven work, consume one versioned field source. Read
[contour topology and terrain compilation](references/profile-sweeps-and-mesh-writers.md#contour-topology-and-terrain-compilation)
before extracting a shoreline, terrace, band, cliff, or region with holes.

When placement, picking, or measurement anchors must survive LOD or rebuilds,
read [semantic anchors and LOD bindings](references/profile-sweeps-and-mesh-writers.md#semantic-anchors-and-lod-bindings)
before decimation.

This step is complete when every intended face belongs to a semantic region,
material slot, smoothing group, UV chart, topology identity, and projected-error
gate, and every required anchor has a stable source/topology identity and LOD
binding policy.

## 3. Compute exact capacity, then emit

Count render vertices after all required duplication and count indices before
allocation:

```text
vertexCount = smooth vertices + hard-edge duplicates + UV seams
            + material-boundary duplicates + caps and explicit boundaries
indexCount = 3 * triangleCount
```

Allocate typed arrays once. Use `Uint16Array` only when the highest referenced
vertex is at most `65535`; otherwise use `Uint32Array`. Emit through a small
writer surface such as:

```text
addVertex, addTriangle, addQuad
duplicateForBoundary
startSmoothingGroup, startUvChart, addGroup
finishGeometry
```

Every index belongs to exactly one nonoverlapping group with a stable material
index. `finishGeometry` asserts the planned and written counts match.

This step is complete when allocation equals the planned capacity exactly,
every emitted index is owned by one group, and overflow or unfilled capacity is
an explicit error.

## 4. Close topology, normals, UVs, and frames

Keep topological identity separate from render-vertex identity. Render vertices
duplicate at hard normals, material boundaries, UV seams, and mirrored tangent
spaces while topological edges still prove adjacency and closure.

Use analytic normals/tangents where the generator owns a parameterization.
`computeVertexNormals()` is for deliberately smooth shared-vertex regions. For
normal-map parity, await `MikkTSpace.ready` before
`computeMikkTSpaceTangents(...)`; r185 de-indexes indexed geometry, so recompute
counts, groups, bounds, and bytes for that distinct representation.

Production UVs express physical distance or declared repeats; normalized local
parameters belong in a separate debug attribute. Profile and branch sweeps use
a rotation-minimizing parallel-transport frame with an explicit antiparallel
fallback and closed-loop holonomy correction.

Read
[profile sweeps and transported frames](references/profile-sweeps-and-mesh-writers.md#profile-sweeps-and-transported-frames)
when emitting along a curve.

This step is complete when topology closes at every undeclared boundary,
normals/tangents match semantic boundaries, UV density is stable across LOD,
and transported frames remain continuous through zero curvature and inflections.

## 5. Wire batching and updates

Initialize and gate the renderer before allocating GPU-owned storage or
indirect commands:

```js
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for geometry storage and indirect draws.');
}
```

Check the selected storage bindings and buffer usage against the initialized
device limits before compilation.

Set attribute `usage` before first render. Static geometry uploads once and may
release CPU arrays only when no rebuild requires them. Dynamic sections use
`addUpdateRange()` in component units, `needsUpdate`, and targeted bounds
recomputation. Capacity, item size, or usage-model changes rebuild the owning
attribute/geometry rather than mutating its contract.

When compute owns instance state, submit compute before the consuming render
and keep one transform owner. In r185, `computeAsync()` is not a GPU-completion
fence. Indirect commands use CPU-known byte offsets and stable homogeneous
buckets; shader masking is not visibility compaction.

Read
[batching, dynamic updates, and indirect draws](references/profile-sweeps-and-mesh-writers.md#batching-dynamic-updates-and-indirect-draws)
before adding a batch container, per-frame mutation, storage state, or indirect
draw.

This step is complete when each mutable byte range, dispatch, draw entry,
bounding volume, and disposal point has one owner and hidden work is absent from
the claimed culling result.

## 6. Validate topology and render geometry

Validate topological identities before render duplication, then the final
`BufferGeometry`:

- closed/simple/nested contour loops and declared open boundaries;
- two oppositely oriented incident faces per interior topological edge;
- no T-junctions, duplicate faces, bow-ties, or unintended non-manifold edges;
- finite attributes, in-range indices, nondegenerate triangles, and winding;
- unit normals, tangent handedness, physical UV density, group coverage, and
  bounds containing every vertex;
- protected features and topology through every LOD and mixed-LOD seam;
- stable anchor source/topology IDs, per-LOD bindings, exclusion revisions, and
  bounded position/frame error through rebuild and LOD changes;
- exact resident/upload bytes, draw/backend entries, update ranges, and
  sustained target timing where performance is claimed.

Diagnostics expose topological versus render IDs, boundaries, winding, normals,
tangents, UV density, material groups, LOD/seam error, batch identity, and dirty
ranges.

This step is complete when every semantic region passes topology, attribute,
LOD, group, bounds, byte, lifecycle, and claimed performance gates, including
adversarial contour and frame cases selected by the active branches.

## Completion

The geometry system is complete when representation precedes allocation; exact
capacity equals emitted data; semantic topology survives render duplication,
batching, updates, and LOD; every index and mutable byte has one owner; and the
final mesh passes topology, attribute, projected-error, resource, and lifecycle
checks.