threejs-procedural-creatures

name	threejs-procedural-creatures
description	Compile procedural creatures for Three.js WebGPU/TSL. Use for generated body surfaces, semantic rigs or creature locomotion, or repeated procedural populations.

Procedural Creatures

Build a creature as a compiler: a dimensioned spec produces stable body, rig, pose, and population identities; runtime work advances only selected state. The canonical path uses Three.js r185 WebGPURenderer, TSL, NodeMaterial, and workload-selected storage. Imported skinned animation assets are a separate pipeline rather than an extension of this skill.

1. Define the body contract

Name the requested observable, closest/farthest projected extent, morphology envelope, pose/topology update frequency, visible population, target adapter, world units/frame, final-output owner, and any habitat/support/water/weather providers.

Classify the request into one or more branches:

Branch	Creature owns
generated body	spec, field or segment compiler, shipping surface, materials
rig/locomotion	semantic slots, local pose, fixed-step or analytic motion, support-relative targets
repeated population	compatible geometry/material identities, pose pages, bounds, culling, LOD

This step is complete when every requested observable has one owner, every external input names its producer and sampling contract, and the topology, pose, and population change regimes are explicit.

2. Select the shipping representation

Choose from connectivity, deformation, reuse, and projected error:

Workload	Representation	Required proof
fixed connectivity with changing pose	one extracted reference mesh plus validated skinning	topology, weights, deformation, bidirectional surface error
fixed connectivity with bounded morphology change	reference mesh, skinning, optional bounded local field correction	full-envelope Jacobian, inversion, correction and surface error
components may merge, split, open, or close	budgeted dynamic extraction or explicit unsupported result	topology events, cadence, transition and complete mesh validity
body is visibly separate rigid plates/links	closed articulated segment hierarchy	closed geometry, joint gaps/limits, transform parity
many bodies share topology	shared geometry/material plus fixed pose pages	compatible identity, dirty traffic, bounds and visible submission
small projected body	simplified mesh or orientation-aware impostor	view-cone silhouette error and transition hysteresis

A concatenated capsule/primitive shell is a field diagnostic, not proof of a manifold body. Choose one primary representation per range and state which features or topology changes it cannot represent.

This step is complete when each range has one shipping representation, its geometry/cache identity is defined, and every transition has a physical-pixel error gate, hysteresis/dwell, simultaneous-memory budget, and reset action.

3. Compile the generated body

When a selected branch needs a field-derived body, extracted skin, skinning, correction, semantic rig, creature locomotion, or repeated pose storage, open only its applicable sections of creature-body-systems.md:

• every selected branch reads Spaces and state ownership and Spec and compiler;
• generated-body work reads Field and blend contract and Reference surface and correction;
• rig or locomotion work reads Pose and locomotion;
• repeated-population work reads Repeated populations and rendering;
• verification reads Completion evidence for the selected branches.

When the body is a hierarchy of rigid shells or plates, read articulated-hard-shell-creatures.md. Keep stable semantic segment/joint IDs, closed surfaces, parent-local pivots, and one transform path for visible, shadow/depth, bounds, and motion vectors.

Compile heavy work before visibility: spec validation, topology, reference surface or closed segments, weights, candidates, frames, geometry identities, materials, and fixed page layouts. Spawning validates and writes active slots; it does not construct geometry or compile pipelines.

This step is complete when all graph references and slots resolve, CPU/TSL parity passes where applicable, emitted surfaces are valid over the declared pose/morphology envelope, and every cached artifact resolves the complete identity that affects it.

4. Build pose and locomotion only where requested

Pose remains creature-local; root motion is applied exactly once by the instance transform. Use stable seeded variation and injected simulation time. Closed-form motion samples time directly. Gait, springs, ropes, buoyancy, and contact response advance at a fixed step owned locally or by the routed simulation stage, with immutable previous/current states for presentation.

For support-relative limbs:

1. batch required probes at one sample instant/version;
2. retain stable support/feature identity and the planted point in support-local coordinates;
3. form gait homes and swing arcs in the support tangent frame;
4. predict targets from body velocity relative to represented support-point velocity;
5. transform targets through the inverse root into body space;
6. solve IK, write local slots, then update posed bounds.

When support, water, air, gravity, weather, or physical contacts participate, define a handoff with units, frame/origin, interval or sample instant, cadence/sample phase, producer/consumer/version, footprint/filter, validity/staleness/error, and rate-versus-integrated meaning. Water-surface motion and material current are distinct channels; missing represented data is absence rather than a physical zero. Frame-critical decisions use an analytic mirror, deterministic shared field, or batched provider with declared latency/error rather than GPU readback.

One-way visual coupling returns no physical reaction. A two-way route sends source/reaction quantities through the authoritative solver named by the handoff. This skill owns creature pose and structural response, not private terrain, water, wind, gravity, or contact state.

This step is complete when equal seed/tick/inputs reproduce pose, render cadence cannot alter recurrent state, support-relative drift and limb-length residuals pass, required provider channels are present with bounded error, and every pose writer has a deterministic order.

5. Scale the population and present once

Initialize the canonical renderer before allocating resources:

import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer({ antialias: false });
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('WebGPU backend unavailable for the canonical creature path.');
}

• Share geometry only across compatible compiler/topology/geometry/tier identities. A species label alone is not a batch key.
• Store creature-local pose, root transform, bound, stable identity, representation, and history generation in fixed-capacity pages. Upload only coalesced dirty ranges.
• Use posed primitive/segment bounds or a proven conservative animation envelope. Cull pages and instances before submission.
• Bound shader loops by actual part/candidate count. Candidate evaluation keeps the authored blend ancestry and its omission certificates.
• Use one population ID/normal/depth edge pass for repeated outlines; reserve a duplicate iso-offset body for a measured hero branch.
• Reuse the same deformed local position in visible and cast-shadow paths; derive received-shadow lookup in world space.
• Decode authored sRGB once before linear uniform/storage use. One scene pipeline owns tone mapping and output conversion.
• Precompile every shipping display, depth/shadow, outline, and configured output variant before first visibility.

This step is complete when population pages have bounded capacity/lifetime, static or unchanged poses cause no redundant recurrent work, bounds cull correctly, visible/depth/shadow/motion consume one accepted pose generation, and exactly one component owns final output conversion.

6. Verify representation, state, and lifecycle

Inspect final/no-post output plus the selected diagnostics:

body: field/normal/candidate views, topology, skin weights, segment IDs,
      correction residual, inversions/intersections, silhouette
rig: slot/parent IDs, joint limits, radial frames, planted support and IK,
     previous/current pose and history generation
population: page occupancy, dirty ranges, posed bounds, culling, LOD/impostor,
            visible/shadow/depth/motion parity

Exercise fixed-seed replay; tick seek versus stepping; complete pose and morphology envelopes; render hitches; sloped/moving support; missing, stale, or discontinuous provider data; spawn/death/teleport/reparent/slot reuse; topology/LOD change; resize; and disposal.

Report compiler/surface counts, field parity and surface error, locomotion drift and convergence, visible/submitted pages and instances, dirty upload bytes, field/correction evaluations, CPU fixed-step cost, whole-frame and paired- marginal CPU/GPU p50/p95, peak live bytes, first-visible pipeline events, and sustained target behaviour.

Failure signatures include primitive sheets shipped as a manifold body, renaming parts changing a blend field, skin weights crossing touching limbs, helper-axis frame flips, root transforms applied twice, render-dt gait, support drift, water channels conflated, one mutable global population buffer, unbounded shader loops, disabled culling, pose generations disagreeing across passes, and resources/state surviving disposal.

Verification is complete when every selected representation, rig/locomotion, population, output, reset, budget, and disposal gate passes; unselected branches carry no required payload or evidence.

Routing boundary

Use $threejs-procedural-motion-systems for general transform timelines and springs, $threejs-procedural-geometry for generic mesh writers, $threejs-procedural-fields for reusable fields/material coordinates, $threejs-procedural-vegetation for plants, and $threejs-visual-validation for target-scene visual contracts. This skill owns procedural creature bodies, semantic rigs, creature locomotion, pose storage, and repeated-population representation. Imported glTF clips, retargeting, and VAT animation belong to an imported-asset character pipeline.