Claude Skill

threejs-ops

Application/game-scale three.js: ES modules, GLTF pipeline (DRACO/KTX2/meshopt), AnimationMixer, physics (rapier/cannon-es), react-three-fiber, and performance at scale (InstancedMesh, LOD, draw calls). Triggers on: three.js, GLTFLoader, r3f, game loop, WebGL memory leak, boids.

LLM Mart · 0 points · 4 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_threejs-ops-6aef525.zip · 90 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/threejs-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Three.js — application & game scale

Patterns for building three.js applications and games: module setup, asset pipelines, animation, simulation loops, physics, the React ecosystem, and staying fast (and leak-free) as scene complexity grows.

Scope split with sibling skills — do not duplicate them:

Concern Owner
Creative/generative three.js — sketches, generative art, shader toys, art-piece particles and post genart-ops
three.js inside a Mapbox GL custom layer (CustomLayerInterface, threebox) mapbox-ops
App/game-scale three.js — modules, assets, animation, loops, physics, R3F, scale, and the game-grade render pipeline, procedural materials and worlds (§9) this skill

1. ES-module reality (read this before writing any <script> tag)

three.js is ES-modules only. The legacy patterns are dead and will 404 or silently break on any modern release:

Dead pattern Removed Use instead
examples/js/* non-module loaders (js/loaders/GLTFLoader.js, THREE.OrbitControls globals) r148 three/addons/ module imports
build/three.js + build/three.min.js UMD builds (<script src=…> + global THREE) r160 build/three.module.js via import map or bundler

Versioning: npm publishes 0.<release>.<patch> — three@0.185.1 is r185. Releases land monthly; pin exact versions.

No-bundler setup (import map)

Copy assets/importmap-starter.html — a complete, runnable starter (import map + addons + resize + setAnimationLoop). The core:

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.185.1/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.185.1/examples/jsm/"
  }
}
</script>
<script type="module">
  import * as THREE from 'three';
  import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
</script>

Gotchas: both entries MUST pin the same version (mixed versions = instanceof failures across module copies); the three/addons/ key needs the trailing slash; import maps must appear before the first type="module" script.

Bundler vs no-bundler

Situation Choice
Real app/game, npm deps, physics WASM, R3F Vite (npm create vite@latest) — default answer
Demo, CodePen, teaching, drop-in page on an existing site Import map — zero build
@dimforge/rapier3d (WASM-bindgen) Needs a bundler; use rapier3d-compat without one (§5)

With a bundler, import { X } from 'three/addons/…' resolves via the package's exports map — same specifier both worlds.

WebGPU (know it exists; default to WebGL)

Since r167 three ships a parallel build: import { WebGPURenderer } from 'three/webgpu' plus the TSL node-shader language from three/tsl (import-map users: point the "three" key at build/three.webgpu.js instead of three.module.js — it re-exports core; never load both). WebGPURenderer falls back to WebGL2 automatically and initializes async (await renderer.init(), or let setAnimationLoop defer for you). Default for app/game work remains WebGLRenderer — reach for WebGPU when you need compute (GPU crowds, particle sims) or TSL materials. Shader-level TSL/GLSL work is genart-ops territory.


2. GLTF asset pipeline

glTF (.glb) is the format. Wire all three decoders once at startup so any optimized asset loads; full setup, optimization CLI recipes (gltf-transform, gltfpack), and CC0 model sources (Quaternius, Kenney, Poly Pizza) in references/asset-pipeline.md.

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

const draco = new DRACOLoader().setDecoderPath(
  'https://www.gstatic.com/draco/versioned/decoders/1.5.7/');
const ktx2 = new KTX2Loader()
  .setTranscoderPath('https://cdn.jsdelivr.net/npm/three@0.185.1/examples/jsm/libs/basis/')
  .detectSupport(renderer);              // MUST pass the live renderer

const loader = new GLTFLoader()
  .setDRACOLoader(draco).setKTX2Loader(ktx2).setMeshoptDecoder(MeshoptDecoder);

const { scene: model, animations } = await loader.loadAsync('hero.glb');

Cloning a skinned character for multiple instances needs SkeletonUtils.clone() — a plain .clone() shares (and corrupts) the skeleton.


3. Animation system

AnimationMixer drives everything (skeletal + morph targets). One mixer per model root; mixer.update(dt) every frame. Crossfades, blending weights, one-shot clips, additive layers, and morph-target patterns in references/animation.md.

const mixer = new THREE.AnimationMixer(model);
const idle = mixer.clipAction(THREE.AnimationClip.findByName(animations, 'Idle'));
const run  = mixer.clipAction(THREE.AnimationClip.findByName(animations, 'Run'));
idle.play();
// smooth transition — never .stop() + .play()
run.reset().play();
idle.crossFadeTo(run, 0.3, /*warp*/ true);

4. Game loops

Render on rAF; simulate on a fixed timestep when gameplay/physics needs determinism. Full accumulator pattern (with render interpolation), dt clamping, tab-hidden handling, input sampling, and frame-rate-independent damping (MathUtils.damp, follow cameras) in references/game-loop.md.

const FIXED = 1 / 60;
let acc = 0, last = performance.now();
renderer.setAnimationLoop((now) => {
  acc += Math.min((now - last) / 1000, 0.1);  // clamp: tab-switch dt spike
  last = now;
  while (acc >= FIXED) { simulate(FIXED); acc -= FIXED; }
  render(acc / FIXED);                         // interpolation alpha
});

Rules: use renderer.setAnimationLoop (not raw rAF — required for WebXR, and it pauses cleanly); clamp dt or the first frame after a background tab teleports everything; pause simulation on document.hidden (visibilitychange); determinism = fixed step + seeded RNG + no per-frame Math.random() in sim code.


5. Physics

Default: @dimforge/rapier3d (Rust/WASM — fast, deterministic, actively developed, built-in kinematic character controller). cannon-es remains the pure-JS fallback for zero-WASM constraints. Decision table, init patterns, body/mesh sync, and character controllers in references/physics.md.

The package-name trap:

Package When
@dimforge/rapier3d Bundler with WASM support (Vite: works out of the box)
@dimforge/rapier3d-compat No bundler / import map — WASM inlined as base64; await RAPIER.init() first
import RAPIER from '@dimforge/rapier3d-compat';
await RAPIER.init();
const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
// step inside the FIXED loop (§4), then copy body → mesh:
world.timestep = FIXED; world.step();
mesh.position.copy(body.translation());
mesh.quaternion.copy(body.rotation());

6. react-three-fiber + drei

R3F v9 (React 19) renders the three.js scene graph declaratively; drei is its helper library. When: React app, UI-heavy, want the pmndrs ecosystem (@react-three/rapier, postprocessing). When not: no React on the page, engine-style tight control, minimal bundle. Hooks, pitfalls (per-frame setState kills you — mutate refs in useFrame), and the drei shortlist in references/r3f-drei.md.


7. Scale patterns — staying fast, staying leak-free

Draw calls are the budget; GPU memory leaks are the debt. renderer.info is the meter for both. InstancedMesh at count, LOD, culling, and the full disposal discipline in references/scale-and-disposal.md.

Quick rules:

  • Same mesh × N ≥ ~50 → InstancedMesh (one draw call). Set matrices via setMatrixAt(i, m), then instanceMatrix.needsUpdate = true.
  • Watch renderer.info.render.calls per frame — hundreds is fine, thousands is the problem. renderer.info.memory.{geometries,textures} must return to baseline after teardown.
  • Removing from the scene frees nothing. GPU memory needs explicit geometry.dispose(), material.dispose(), every texture .dispose(), and renderer.dispose() on full teardown (SPA route change = the classic leak).
function disposeObject(root) {
  root.traverse((o) => {
    o.geometry?.dispose();
    for (const m of Array.isArray(o.material) ? o.material : [o.material]) {
      if (!m) continue;
      for (const v of Object.values(m)) v?.isTexture && v.dispose();
      m.dispose();
    }
  });
  root.removeFromParent();
}

8. Ambient life — boids, steering, waypoints

Crowd/wildlife/NPC motion is steering forces + a spatial hash, driven from the fixed loop and rendered via InstancedMesh. Seek/arrive/wander, the three boids rules, waypoint drivers, and library options in references/actors-and-steering.md. For structured game-state building blocks (actor motion controllers, waypoint drivers, camera rigs) see xt4d/GameBlocks — agent-oriented, self-explanatory reference implementations.


9. High-fidelity games built from code

Distilled from a reference build: a rain-soaked port FPS that Claude made in one shot as a single-file artifact on plain WebGLRenderer r180, with zero downloaded assets. Its look comes from discipline, not features:

Lever Rule of thumb Reference
Light One art-directed sun + procedural sky PMREM-baked (sun removed) as the only ambient render-pipeline.md
Atmosphere Shadow-mapped volumetric fog; far haze uses the sky's horizon colour so nothing seams render-pipeline.md
Finishing Own HDR chain (RGBA16F, no EffectComposer): AO on ambient only, bloom, auto-exposure, ACES/AgX + grade, FXAA + grain render-pipeline.md
Surfaces GPU-bake layered PBR sets from periodic noise once; add world-space variation + weather at runtime procedural-materials.md
Density Merge statics by material, bake weathering into vertex colours, one-draw backdrops; ~100-150 calls procedural-world.md
Robustness Module stubs, per-module try/catch, self-test + tiered fallback, test hooks an agent can drive game-architecture.md

Shadow version gate: since r182 PCF shadow maps are hardware-compare samplers with no raw depth, so the PCSS patch moves to BasicShadowMap; render-pipeline.md section 3 has both splices.

Where a quick human pass paid off most on top of the one-shot build: hero assets the player stares at (weapon + hands), weapon sound, and gameplay variety. Spend review time there first.


10. Stylised looks, characters, outdoor worlds, self-testing

Reference build: Oil paint (blendi on patch.gg, MIT), a painterly third-person walk through an autumn wood in which every element is a world-pinned brush dab: ~1.5M instances in 18 draws.

Need Rule of thumb Reference
A stylised look that holds still Build the style into one primitive the whole scene shares; size clamps in pixels; per-cell ownership so LOD never swaps things stylised-rendering.md
Character feel In-place clips + distance-synced blends + pose-matched transitions + foot IK; tune the controller, not the clips character-locomotion.md
A big outdoor world One heightmap with a CPU twin, one path spline driving everything, a leash instead of streaming terrain-and-foliage.md
Proving it works An in-game test API + headless tools that measure stills, frame time, PSNR stability and cold start verification-harness.md

Bundled resources

Resource Load when
references/asset-pipeline.md Loading/optimizing GLTF, decoder wiring, sourcing CC0 models
references/animation.md Crossfades, blend weights, one-shots, morph targets
references/game-loop.md Fixed timestep, interpolation, pause/visibility, input sampling, damping/follow-cam, determinism
references/physics.md rapier vs cannon-es, init, sync, character controllers
references/r3f-drei.md React Three Fiber apps, drei helpers, R3F pitfalls
references/scale-and-disposal.md Instancing, LOD, culling, draw-call budgets, disposal/leaks
references/actors-and-steering.md Boids, steering, waypoint actors, ambient life
references/render-pipeline.md HDR post chain, sky/PMREM, PCSS, SSAO, volumetric fog, exposure/tonemap, dynamic resolution
references/procedural-materials.md Texture-free PBR: GPU bake, noise kit, wear layers, chunk patching, procedural AA
references/procedural-world.md Code-built levels, merge-by-material, authored LOD, sea, rain, flocks, particles, AABB collision
references/game-architecture.md Module contract + stubs, fault isolation, test hooks, input fallbacks, HUD, procedural audio
references/stylised-rendering.md Painterly/NPR looks that never shimmer: dab primitive, pixel clamps, A2C, snapped ground rings, palette lighting
references/character-locomotion.md Third-person feel: in-place clips, synced blend spaces, pose-matched states, foot IK, Rapier KCC, orbit camera, cloak
references/terrain-and-foliage.md Outdoor worlds: heightmap CPU/GPU twin, Rapier heightfield, path spline, leash, crowns, wind, falling leaves
references/verification-harness.md Headless self-tests: in-game test API, GPU fence, Playwright stills, frame time, PSNR stability, cold start, film
assets/importmap-starter.html Starting a no-bundler project — copy and edit
assets/three-facts.json Canonical version gates + package facts (verifier input)

Staleness verifier — this skill encodes fast-moving facts (three version gates, npm package names/versions). Check internal consistency (CI) or live drift against the npm registry:

python3 skills/threejs-ops/scripts/check-three-facts.py --offline   # structural, no network — PR CI
python3 skills/threejs-ops/scripts/check-three-facts.py --live      # npm registry probe — exit 10 drift, 7 unreachable
python3 skills/threejs-ops/scripts/check-three-facts.py --offline --json | jq '.data[] | select(.status!="ok")'
Files (claude-mods)
  • assets
    • importmap-starter.html 3.1 KB · in bundle
    • three-facts.json 2.5 KB
      Loading…
  • references
    • actors-and-steering.md 5.4 KB
      Loading…
    • animation.md 5.7 KB
      Loading…
    • asset-pipeline.md 6.2 KB
      Loading…
    • character-locomotion.md 14.3 KB
      Loading…
    • game-architecture.md 12.5 KB
      Loading…
    • game-loop.md 7 KB
      Loading…
    • physics.md 6 KB
      Loading…
    • procedural-materials.md 14.5 KB
      Loading…
    • procedural-world.md 13.1 KB
      Loading…
    • r3f-drei.md 5.4 KB
      Loading…
    • render-pipeline.md 14.7 KB
      Loading…
    • scale-and-disposal.md 7.1 KB
      Loading…
    • stylised-rendering.md 13.5 KB
      Loading…
    • terrain-and-foliage.md 12.6 KB
      Loading…
    • verification-harness.md 13.6 KB
      Loading…
  • scripts
    • check-three-facts.py 13.9 KB
      Loading…
  • tests
    • run.sh 5.6 KB
      Loading…
  • SKILL.md 16 KB
    ---
    name: threejs-ops
    description: "Application/game-scale three.js: ES modules, GLTF pipeline (DRACO/KTX2/meshopt), AnimationMixer, physics (rapier/cannon-es), react-three-fiber, performance at scale (InstancedMesh, LOD, draw calls), and high-fidelity games built entirely from code: HDR post stack, PCSS shadows, volumetric fog, GPU-baked procedural PBR materials, procedural worlds and audio. Triggers on: three.js, GLTFLoader, r3f, game loop, WebGL memory leak, boids, browser FPS, AAA look, procedural textures, no-asset game, stylised rendering, NPR, painterly, third-person character, foot IK, terrain, foliage, headless game testing."
    license: MIT
    compatibility: "Web three.js r150+ (ES modules only — UMD builds removed in r160). check-three-facts.py is stdlib-only Python 3.10+."
    metadata:
      author: claude-mods
      related-skills: "genart-ops, mapbox-ops, react-ops, javascript-ops, perf-ops"
    ---
    
    # Three.js — application & game scale
    
    Patterns for building three.js **applications and games**: module setup, asset
    pipelines, animation, simulation loops, physics, the React ecosystem, and staying
    fast (and leak-free) as scene complexity grows.
    
    **Scope split with sibling skills** — do not duplicate them:
    
    | Concern | Owner |
    |---|---|
    | Creative/generative three.js — sketches, generative art, shader toys, art-piece particles and post | [genart-ops](../genart-ops/SKILL.md) |
    | three.js inside a Mapbox GL custom layer (`CustomLayerInterface`, threebox) | [mapbox-ops](../mapbox-ops/SKILL.md) |
    | App/game-scale three.js — modules, assets, animation, loops, physics, R3F, scale, and the game-grade render pipeline, procedural materials and worlds (§9) | **this skill** |
    
    ---
    
    ## 1. ES-module reality (read this before writing any `<script>` tag)
    
    three.js is **ES-modules only**. The legacy patterns are dead and will 404 or
    silently break on any modern release:
    
    | Dead pattern | Removed | Use instead |
    |---|---|---|
    | `examples/js/*` non-module loaders (`js/loaders/GLTFLoader.js`, `THREE.OrbitControls` globals) | **r148** | `three/addons/` module imports |
    | `build/three.js` + `build/three.min.js` UMD builds (`<script src=…>` + global `THREE`) | **r160** | `build/three.module.js` via import map or bundler |
    
    Versioning: npm publishes `0.<release>.<patch>` — `three@0.185.1` **is** r185.
    Releases land monthly; pin exact versions.
    
    ### No-bundler setup (import map)
    
    Copy [assets/importmap-starter.html](assets/importmap-starter.html) — a complete,
    runnable starter (import map + addons + resize + `setAnimationLoop`). The core:
    
    ```html
    <script type="importmap">
    {
      "imports": {
        "three": "https://cdn.jsdelivr.net/npm/three@0.185.1/build/three.module.js",
        "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.185.1/examples/jsm/"
      }
    }
    </script>
    <script type="module">
      import * as THREE from 'three';
      import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
    </script>
    ```
    
    Gotchas: both entries MUST pin the **same version** (mixed versions =
    `instanceof` failures across module copies); the `three/addons/` key needs the
    trailing slash; import maps must appear **before** the first `type="module"`
    script.
    
    ### Bundler vs no-bundler
    
    | Situation | Choice |
    |---|---|
    | Real app/game, npm deps, physics WASM, R3F | **Vite** (`npm create vite@latest`) — default answer |
    | Demo, CodePen, teaching, drop-in page on an existing site | **Import map** — zero build |
    | `@dimforge/rapier3d` (WASM-bindgen) | Needs a bundler; use `rapier3d-compat` without one (§5) |
    
    With a bundler, `import { X } from 'three/addons/…'` resolves via the package's
    `exports` map — same specifier both worlds.
    
    ### WebGPU (know it exists; default to WebGL)
    
    Since **r167** three ships a parallel build: `import { WebGPURenderer } from
    'three/webgpu'` plus the TSL node-shader language from `three/tsl` (import-map
    users: point the `"three"` key at `build/three.webgpu.js` **instead of**
    `three.module.js` — it re-exports core; never load both). `WebGPURenderer`
    falls back to WebGL2 automatically and initializes async (`await
    renderer.init()`, or let `setAnimationLoop` defer for you). Default for
    app/game work remains `WebGLRenderer` — reach for WebGPU when you need compute
    (GPU crowds, particle sims) or TSL materials. Shader-level TSL/GLSL work is
    [genart-ops](../genart-ops/SKILL.md) territory.
    
    ---
    
    ## 2. GLTF asset pipeline
    
    glTF (`.glb`) is the format. Wire **all three decoders** once at startup so any
    optimized asset loads; full setup, optimization CLI recipes (`gltf-transform`,
    `gltfpack`), and CC0 model sources (Quaternius, Kenney, Poly Pizza) in
    [references/asset-pipeline.md](references/asset-pipeline.md).
    
    ```javascript
    import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
    import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
    import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
    import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
    
    const draco = new DRACOLoader().setDecoderPath(
      'https://www.gstatic.com/draco/versioned/decoders/1.5.7/');
    const ktx2 = new KTX2Loader()
      .setTranscoderPath('https://cdn.jsdelivr.net/npm/three@0.185.1/examples/jsm/libs/basis/')
      .detectSupport(renderer);              // MUST pass the live renderer
    
    const loader = new GLTFLoader()
      .setDRACOLoader(draco).setKTX2Loader(ktx2).setMeshoptDecoder(MeshoptDecoder);
    
    const { scene: model, animations } = await loader.loadAsync('hero.glb');
    ```
    
    Cloning a skinned character for multiple instances needs
    `SkeletonUtils.clone()` — a plain `.clone()` shares (and corrupts) the skeleton.
    
    ---
    
    ## 3. Animation system
    
    `AnimationMixer` drives everything (skeletal + morph targets). One mixer per
    model root; `mixer.update(dt)` every frame. Crossfades, blending weights,
    one-shot clips, additive layers, and morph-target patterns in
    [references/animation.md](references/animation.md).
    
    ```javascript
    const mixer = new THREE.AnimationMixer(model);
    const idle = mixer.clipAction(THREE.AnimationClip.findByName(animations, 'Idle'));
    const run  = mixer.clipAction(THREE.AnimationClip.findByName(animations, 'Run'));
    idle.play();
    // smooth transition — never .stop() + .play()
    run.reset().play();
    idle.crossFadeTo(run, 0.3, /*warp*/ true);
    ```
    
    ---
    
    ## 4. Game loops
    
    Render on rAF; simulate on a **fixed timestep** when gameplay/physics needs
    determinism. Full accumulator pattern (with render interpolation), dt clamping,
    tab-hidden handling, input sampling, and frame-rate-independent damping
    (`MathUtils.damp`, follow cameras) in
    [references/game-loop.md](references/game-loop.md).
    
    ```javascript
    const FIXED = 1 / 60;
    let acc = 0, last = performance.now();
    renderer.setAnimationLoop((now) => {
      acc += Math.min((now - last) / 1000, 0.1);  // clamp: tab-switch dt spike
      last = now;
      while (acc >= FIXED) { simulate(FIXED); acc -= FIXED; }
      render(acc / FIXED);                         // interpolation alpha
    });
    ```
    
    Rules: use `renderer.setAnimationLoop` (not raw rAF — required for WebXR, and
    it pauses cleanly); **clamp dt** or the first frame after a background tab
    teleports everything; pause simulation on `document.hidden`
    (`visibilitychange`); determinism = fixed step + seeded RNG + no per-frame
    `Math.random()` in sim code.
    
    ---
    
    ## 5. Physics
    
    **Default: `@dimforge/rapier3d`** (Rust/WASM — fast, deterministic, actively
    developed, built-in kinematic character controller). `cannon-es` remains the
    pure-JS fallback for zero-WASM constraints. Decision table, init patterns,
    body/mesh sync, and character controllers in
    [references/physics.md](references/physics.md).
    
    The package-name trap:
    
    | Package | When |
    |---|---|
    | `@dimforge/rapier3d` | Bundler with WASM support (Vite: works out of the box) |
    | `@dimforge/rapier3d-compat` | No bundler / import map — WASM inlined as base64; `await RAPIER.init()` first |
    
    ```javascript
    import RAPIER from '@dimforge/rapier3d-compat';
    await RAPIER.init();
    const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
    // step inside the FIXED loop (§4), then copy body → mesh:
    world.timestep = FIXED; world.step();
    mesh.position.copy(body.translation());
    mesh.quaternion.copy(body.rotation());
    ```
    
    ---
    
    ## 6. react-three-fiber + drei
    
    R3F v9 (React 19) renders the three.js scene graph declaratively;
    [drei](https://github.com/pmndrs/drei) is its helper library. **When**: React
    app, UI-heavy, want the pmndrs ecosystem (`@react-three/rapier`,
    postprocessing). **When not**: no React on the page, engine-style tight control,
    minimal bundle. Hooks, pitfalls (per-frame `setState` kills you — mutate refs in
    `useFrame`), and the drei shortlist in
    [references/r3f-drei.md](references/r3f-drei.md).
    
    ---
    
    ## 7. Scale patterns — staying fast, staying leak-free
    
    Draw calls are the budget; GPU memory leaks are the debt. `renderer.info` is the
    meter for both. InstancedMesh at count, LOD, culling, and the **full disposal
    discipline** in [references/scale-and-disposal.md](references/scale-and-disposal.md).
    
    Quick rules:
    
    - **Same mesh × N ≥ ~50 → `InstancedMesh`** (one draw call). Set matrices via
      `setMatrixAt(i, m)`, then `instanceMatrix.needsUpdate = true`.
    - Watch `renderer.info.render.calls` per frame — hundreds is fine, thousands is
      the problem. `renderer.info.memory.{geometries,textures}` must return to
      baseline after teardown.
    - **Removing from the scene frees nothing.** GPU memory needs explicit
      `geometry.dispose()`, `material.dispose()`, **every texture** `.dispose()`,
      and `renderer.dispose()` on full teardown (SPA route change = the classic leak).
    
    ```javascript
    function disposeObject(root) {
      root.traverse((o) => {
        o.geometry?.dispose();
        for (const m of Array.isArray(o.material) ? o.material : [o.material]) {
          if (!m) continue;
          for (const v of Object.values(m)) v?.isTexture && v.dispose();
          m.dispose();
        }
      });
      root.removeFromParent();
    }
    ```
    
    ---
    
    ## 8. Ambient life — boids, steering, waypoints
    
    Crowd/wildlife/NPC motion is steering forces + a spatial hash, driven from the
    fixed loop and rendered via InstancedMesh. Seek/arrive/wander, the three boids
    rules, waypoint drivers, and library options in
    [references/actors-and-steering.md](references/actors-and-steering.md). For
    structured game-state building blocks (actor motion controllers, waypoint
    drivers, camera rigs) see
    [xt4d/GameBlocks](https://github.com/xt4d/GameBlocks) — agent-oriented,
    self-explanatory reference implementations.
    
    ---
    
    ## 9. High-fidelity games built from code
    
    Distilled from a reference build: a rain-soaked port FPS that Claude made in one shot as a
    single-file artifact on plain `WebGLRenderer` r180, with zero downloaded assets. Its
    look comes from discipline, not features:
    
    | Lever | Rule of thumb | Reference |
    |---|---|---|
    | Light | One art-directed sun + procedural sky PMREM-baked (sun removed) as the only ambient | [render-pipeline.md](references/render-pipeline.md) |
    | Atmosphere | Shadow-mapped volumetric fog; far haze uses the sky's horizon colour so nothing seams | [render-pipeline.md](references/render-pipeline.md) |
    | Finishing | Own HDR chain (RGBA16F, no EffectComposer): AO on ambient only, bloom, auto-exposure, ACES/AgX + grade, FXAA + grain | [render-pipeline.md](references/render-pipeline.md) |
    | Surfaces | GPU-bake layered PBR sets from periodic noise once; add world-space variation + weather at runtime | [procedural-materials.md](references/procedural-materials.md) |
    | Density | Merge statics by material, bake weathering into vertex colours, one-draw backdrops; ~100-150 calls | [procedural-world.md](references/procedural-world.md) |
    | Robustness | Module stubs, per-module try/catch, self-test + tiered fallback, test hooks an agent can drive | [game-architecture.md](references/game-architecture.md) |
    
    **Shadow version gate:** since **r182** PCF shadow maps are hardware-compare samplers with no
    raw depth, so the PCSS patch moves to `BasicShadowMap`; render-pipeline.md section 3 has both splices.
    
    Where a quick human pass paid off most on top of the one-shot build: hero
    assets the player stares at (weapon + hands), weapon sound, and gameplay variety. Spend review
    time there first.
    
    ---
    
    ## 10. Stylised looks, characters, outdoor worlds, self-testing
    
    Reference build: **Oil paint** (blendi on patch.gg, MIT), a painterly third-person walk through
    an autumn wood in which every element is a world-pinned brush dab: ~1.5M instances in 18 draws.
    
    | Need | Rule of thumb | Reference |
    |---|---|---|
    | A stylised look that holds still | Build the style into one primitive the whole scene shares; size clamps in pixels; per-cell ownership so LOD never swaps things | [stylised-rendering.md](references/stylised-rendering.md) |
    | Character feel | In-place clips + distance-synced blends + pose-matched transitions + foot IK; tune the controller, not the clips | [character-locomotion.md](references/character-locomotion.md) |
    | A big outdoor world | One heightmap with a CPU twin, one path spline driving everything, a leash instead of streaming | [terrain-and-foliage.md](references/terrain-and-foliage.md) |
    | Proving it works | An in-game test API + headless tools that measure stills, frame time, PSNR stability and cold start | [verification-harness.md](references/verification-harness.md) |
    
    ---
    
    ## Bundled resources
    
    | Resource | Load when |
    |---|---|
    | [references/asset-pipeline.md](references/asset-pipeline.md) | Loading/optimizing GLTF, decoder wiring, sourcing CC0 models |
    | [references/animation.md](references/animation.md) | Crossfades, blend weights, one-shots, morph targets |
    | [references/game-loop.md](references/game-loop.md) | Fixed timestep, interpolation, pause/visibility, input sampling, damping/follow-cam, determinism |
    | [references/physics.md](references/physics.md) | rapier vs cannon-es, init, sync, character controllers |
    | [references/r3f-drei.md](references/r3f-drei.md) | React Three Fiber apps, drei helpers, R3F pitfalls |
    | [references/scale-and-disposal.md](references/scale-and-disposal.md) | Instancing, LOD, culling, draw-call budgets, disposal/leaks |
    | [references/actors-and-steering.md](references/actors-and-steering.md) | Boids, steering, waypoint actors, ambient life |
    | [references/render-pipeline.md](references/render-pipeline.md) | HDR post chain, sky/PMREM, PCSS, SSAO, volumetric fog, exposure/tonemap, dynamic resolution |
    | [references/procedural-materials.md](references/procedural-materials.md) | Texture-free PBR: GPU bake, noise kit, wear layers, chunk patching, procedural AA |
    | [references/procedural-world.md](references/procedural-world.md) | Code-built levels, merge-by-material, authored LOD, sea, rain, flocks, particles, AABB collision |
    | [references/game-architecture.md](references/game-architecture.md) | Module contract + stubs, fault isolation, test hooks, input fallbacks, HUD, procedural audio |
    | [references/stylised-rendering.md](references/stylised-rendering.md) | Painterly/NPR looks that never shimmer: dab primitive, pixel clamps, A2C, snapped ground rings, palette lighting |
    | [references/character-locomotion.md](references/character-locomotion.md) | Third-person feel: in-place clips, synced blend spaces, pose-matched states, foot IK, Rapier KCC, orbit camera, cloak |
    | [references/terrain-and-foliage.md](references/terrain-and-foliage.md) | Outdoor worlds: heightmap CPU/GPU twin, Rapier heightfield, path spline, leash, crowns, wind, falling leaves |
    | [references/verification-harness.md](references/verification-harness.md) | Headless self-tests: in-game test API, GPU fence, Playwright stills, frame time, PSNR stability, cold start, film |
    | [assets/importmap-starter.html](assets/importmap-starter.html) | Starting a no-bundler project — copy and edit |
    | [assets/three-facts.json](assets/three-facts.json) | Canonical version gates + package facts (verifier input) |
    
    **Staleness verifier** — this skill encodes fast-moving facts (three version
    gates, npm package names/versions). Check internal consistency (CI) or live
    drift against the npm registry:
    
    ```bash
    python3 skills/threejs-ops/scripts/check-three-facts.py --offline   # structural, no network — PR CI
    python3 skills/threejs-ops/scripts/check-three-facts.py --live      # npm registry probe — exit 10 drift, 7 unreachable
    python3 skills/threejs-ops/scripts/check-three-facts.py --offline --json | jq '.data[] | select(.status!="ok")'
    ```
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.