/threejs-builder

name: threejs-builder
description: "Three.js app builder: imperative, React Three Fiber, and WebGPU in 4 phases."
agent: typescript-frontend-engineer
user-invocable: false
command: /threejs
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
routing:
  triggers:
    - threejs
    - three.js
    - 3D web
    - 3D scene
    - WebGL
    - WebGPU
    - 3D animation
    - 3D graphics
    - react three fiber
    - r3f
    - drei
    - react-three
    - "@react-three/fiber"
    - postprocessing 3D
    - TSL shader
    - three shading language
    - compute shader three
    - WebGPURenderer
    - node material three
    - game architecture three
    - gltf loading
    - glb model
    - animation state machine three
    - eventbus game
    - game state management three
    - three.js game
  pairs_with:
    - typescript-frontend-engineer
    - react-native-engineer
    - distinctive-frontend-design
  complexity: Medium
  category: frontend

Three.js Builder Skill

Overview

This skill builds complete Three.js web applications using a **Phased Construction** pattern with four phases: Design, Build, Animate, Polish. It supports three paradigms — imperative Three.js, React Three Fiber (R3F), and WebGPU — detected automatically from project context. Only the relevant paradigm's reference is loaded.

**Scope**: Use for 3D web apps, interactive scenes, WebGL/WebGPU visualizations, R3F declarative 3D, and product viewers. For game engines, 3D model creation, VR/AR experiences, or CAD workflows, use a more specialized skill.

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | `@react-three/fiber`, `r3f`, `drei`, `useFrame`, `<Canvas>`, `<mesh>`, React project with 3D | `react-three-fiber.md` | **React Three Fiber** | | `WebGPURenderer`, `TSL`, `tsl`, `compute shader`, `wgsl`, `node material`, WebGPU mentioned | `webgpu.md` | **WebGPU** | | Standalone HTML, CDN imports, `new THREE.Scene()`, no React, vanilla JS/TS | `advanced-topics.md` (load as needed)` | **Imperative** | | Game project: `EventBus`, `GameState`, player controller, enemies, scoring, multiple game systems | `game-patterns.md` (alongside paradigm reference)` | **Game architecture** | | GLTF/GLB model loading, `.glb` files, animated characters, skeletal rigs, model import | `gltf-loading.md` (alongside paradigm reference)` | **GLTF loading** | | `references/build-recipes.md` | `build-recipes.md` | Phase 2/3 build, error diagnosis | | `references/advanced-topics.md` | `advanced-topics.md` | Imperative paradigm | | `references/react-three-fiber.md` | `react-three-fiber.md` | R3F paradigm | | `references/webgpu.md` | `webgpu.md` | WebGPU paradigm | | `references/visual-polish.md` | `visual-polish.md` | Visual quality signal | | `references/gltf-loading.md` | `gltf-loading.md` | GLTF/GLB model loading signal | | `references/game-patterns.md` | `game-patterns.md` | Game project signal | | `references/game-architecture.md` | `game-architecture.md` | Game project signal | | `references/shader-patterns.md` | `shader-patterns.md` | Custom GLSL / visual effects | | `references/performance-patterns.md` | `performance-patterns.md` | Performance / many objects | | `references/advanced-animation.md` | `advanced-animation.md` | Animation systems / skeletal rigs |

Instructions

Phase 1: DESIGN

**Goal**: Detect the paradigm, understand what the user wants, and select appropriate components.

**Core Constraints**:

• **Build only what the user asked for** — no speculative features or "while I'm here" additions
• **Detect the paradigm before selecting components** — imperative, R3F, and WebGPU have fundamentally different patterns; using the wrong one is the #1 source of bugs
• **Structure through the scene graph** — use `Group` for logical groupings and maintain proper hierarchy
• **Vary style by context** — portfolio/showcase use elegant muted palettes; games use bright colors; data viz uses clean lines; backgrounds use subtle slow movement; product viewers use realistic PBR lighting
• **Read repository CLAUDE.md before building** — ensure compliance with local development standards

**Step 0: Detect paradigm**

Scan the user's request, existing project files (package.json, imports), and stated requirements to identify which paradigm applies:

| Signal | Paradigm / Context | Reference to Load | |--------|-------------------|-------------------| | `@react-three/fiber`, `r3f`, `drei`, `useFrame`, `<Canvas>`, `<mesh>`, React project with 3D | **React Three Fiber** | `references/react-three-fiber.md` | | `WebGPURenderer`, `TSL`, `tsl`, `compute shader`, `wgsl`, `node material`, WebGPU mentioned | **WebGPU** | `references/webgpu.md` | | Standalone HTML, CDN imports, `new THREE.Scene()`, no React, vanilla JS/TS | **Imperative** | `references/advanced-topics.md` (load as needed) | | Game project: `EventBus`, `GameState`, player controller, enemies, scoring, multiple game systems | **Game architecture** | `references/game-architecture.md` + `references/game-patterns.md` (alongside paradigm reference) | | GLTF/GLB model loading, `.glb` files, animated characters, skeletal rigs, model import | **GLTF loading** | `references/gltf-loading.md` (alongside paradigm reference) |

If ambiguous (e.g., user says "3D scene" with no project context), ask which paradigm — don't guess, because imperative Three.js patterns actively conflict with R3F patterns (OrbitControls setup, animation loops, component lifecycle).

Game and GLTF references load **alongside** the paradigm reference — they are complementary, not alternative. A game project using R3F loads both `react-three-fiber.md` and the relevant game references.

**After detecting paradigm**: Read the corresponding reference file. The reference contains paradigm-specific patterns, failure modes, and component selection guidance that override the generic steps below.

Additional reference loading signals (visual-polish, shader-patterns, performanc