threejs-director git:20261028.62f2e2fA

Immutable. This exact content never changes and is served at /api/v1/blob/7a998339f42c83d0.

---
name: threejs-director
description: The entry point for any Three.js scene, game or simulation request. Use first when a task spans more than one area (geometry, materials, environments, a playable character, sky, weather, grass, water, terrain shade, vehicles) or when it is not obvious which specialist skill applies. Reads the request, picks the skills, fixes their order and hands over; writes no code of its own.
---

# Three.js director

Target: Three.js 0.186.1, WebGPU renderer (`three/webgpu`) and TSL (`three/tsl`); WebGPU
only, no WebGL fallback, no GLSL strings. Everything is generated by code; no model files
are loaded. Physics, where needed, is Jolt (`jolt-physics` WASM).

This skill routes. It does not build anything. Read the request, decide which skills
apply, load them in the order below, then follow them. If exactly one skill applies and
the request says so, skip this one and load that skill directly.

## Routing table

Match the request against the left column. Load every row that matches, not only the
first. A parent skill is loaded before its children.

| The request mentions | Load | Then |
| --- | --- | --- |
| any surface, shader, material, how something looks up close | `tsl-materials` | the matching child below |
| glass, windows, windscreens, canopies, portholes, transparent panels | `glass` | |
| metal, steel, aluminium, brushed, galvanised, cast, machinery | `metal` | `rust` if aged |
| painted surfaces, livery, coatings, wear, chipped paint | `paint` | `rust` if aged |
| rust, oxidation, corrosion, weathering of steel | `rust` | `metal` or `paint` underneath |
| lake, river, canal, puddle, fountain, wet ground, what water should look like | `water` | `ocean-water` if it is open sea or needs a mirror |
| one object with several different surfaces (a vehicle, a machine) | `material-composition` | the children for each surface |
| rooms behind windows, lit windows at night, facades seen from outside | `interior-mapping` | `glass` for the pane itself |
| any built geometry: trains, tracks, buildings, bridges, stairs, containers, LOD, polygon budget | `procedural-geometry` | |
| pipes, ducts, conduits, cable trays, plant rooms | `pipes` | `metal`, `paint` |
| signs, markings, labels, decals, road paint, platform edges | `signage` | |
| a station, platform, guideway, maglev, rail infrastructure | `station-maglev` | `procedural-geometry`, `engineered-environments` |
| a dense city, towers, podiums, districts, elevated streets | `megacity` | `procedural-geometry`, `engineered-environments`, `interior-mapping` |
| any large place that must read as working infrastructure | `engineered-environments` | the geometry skills for its parts |
| a player, first or third person, walking, WASD, jump, crouch | `character-kit` | its four children |
| moving on a capsule, stairs, slopes, moving platforms | `character-walking` | |
| the player camera, orbit, pointer lock, follow | `character-camera` | |
| a visible figure for the player without model files | `character-model` | |
| key bindings, mouse look, input handling | `character-input` | |
| sky, sun, time of day, clouds, dusk, night | `photo-sky` | |
| snow, blizzard, rain, weather changing over time, wet roads, spray | `snow-weather` | `photo-sky` for the overcast pools |
| grass, meadow, ground cover, fields seen from a road | `card-grass` | |
| open sea, coast, big water that follows the camera, planar mirror, ice | `ocean-water` | `water` first for the principles |
| hills and trees shading terrain in the distance, cheap AO, far shadows | `far-shade` | |
| a car, truck, trailer, driving, wheels, suspension, towing | `jolt-driving` | `snow-weather` for spray, `card-grass` for the verge |

## Order of work

When several skills apply, work in this order. Each stage leaves something the next can
stand on, and the measurements of one stage fix the scale of the next.

1. **Place and scale.** `engineered-environments` for what the place is and how it
   works; the character kit's ruler (1.8 m standing, 2.1 m door, 0.17 m step) even if
   there is no character, so everything is built at a size a person would read.
2. **Ground and sky.** Terrain or floor first, then `photo-sky`, then `far-shade` if the
   terrain is large. Everything after this is lit by them.
3. **Geometry.** `procedural-geometry` and its specialists (`station-maglev`,
   `megacity`, `pipes`). Build the big masses before the details; decide LOD and
   instancing now, not after.
4. **Materials.** `tsl-materials` and its children on the geometry just built.
   `material-composition` when one object has several surfaces. `signage` last, on top.
5. **Facades and cover.** `interior-mapping` on building windows, `card-grass` on open
   ground, `ocean-water` where there is sea.
6. **Weather.** `snow-weather`, which reads the sky's cloud state and writes wetness
   back into materials.
7. **Player and vehicles.** `character-kit` or `jolt-driving`, last, so the physics
   colliders are built from finished geometry.

A request for a single thing (one material, one object) uses only the stage it belongs
to. Do not pull in the whole order for a material swatch.

## Conflicts and overlaps

- `water` and `ocean-water`: `water` is the principles, `ocean-water` is the
  implementation for large or reflective water. Lakes and puddles can use either; the
  planar mirror in `ocean-water` is the right tool for a reflective lake.
- `character-kit` and `jolt-driving` both initialise Jolt. One world, two users: build
  the world once with `jolt-driving`'s `createJoltWorld` and pass it to the character
  adapter. The two kits were written against different Jolt releases (1.1.0 and 1.0.0
  wasm-compat); use one build and check both against it in the first run.
- `megacity` and `station-maglev` both produce infrastructure. `engineered-environments`
  decides the hierarchy before either is loaded.
- `glass` and `interior-mapping` both touch building windows. The pane is `glass`; what
  is seen through it is `interior-mapping`. On a distant facade, `interior-mapping`
  alone is enough.

## What to say back

Before building, state in one short list which skills were chosen and in what order.
Then follow them. Do not restate their content; they are read in full by whoever builds.

## Pipelines

Worked orders for common requests. Each arrow is a skill handed the previous one's
output.

- **A maglev station at dusk**: `engineered-environments` → `station-maglev` →
  `procedural-geometry` → `metal` + `glass` + `paint` → `signage` → `interior-mapping`
  → `photo-sky` → `character-kit`
- **A drivable winter road**: `photo-sky` → `far-shade` → `card-grass` (winter palette)
  → `procedural-geometry` (road, barriers) → `jolt-driving` → `snow-weather`
- **A coastal city**: `engineered-environments` → `megacity` → `procedural-geometry` →
  `tsl-materials` + `material-composition` → `interior-mapping` → `ocean-water` →
  `photo-sky` → `character-kit`
- **An industrial plant walkthrough**: `engineered-environments` → `procedural-geometry`
  → `pipes` → `metal` + `paint` + `rust` → `signage` → `character-kit`
- **One weathered vehicle**: `material-composition` → `paint` → `metal` → `rust` →
  `glass`