Open 3D Skills

---
name: threejs-scene
description: Builds real-time 3D websites in three.js from code alone, with no model files. Covers buildings and landmarks, vehicles, machines, landscapes and product studies made of procedural geometry (profile sweeps, lathes, instancing), canvas textures, shader patches, a physically based sky and sun, soft shadows, ambient occlusion and bloom, light presets, camera vantages and flights, quality tiers, and a starter that runs at 60 fps. Use when someone asks for a 3D website, a three.js scene, a WebGL hero, an interactive 3D model of a real place or object, a "3D version" of something, or when an existing three.js page looks flat, plasticky, aliased, washed out or slow.
---

# three.js scene

A convincing 3D page is mostly light and proportion, not polygon count. The White House reads as the White House because its storeys, column spacing and cornice depth are right, and because a low sun throws long shadows across it, not because every window has a frame. This skill builds scenes the way an architect's model is made: from real dimensions, in code, with lighting done properly.

## Start from the starter

`assets/starter/` is a complete, working scene (a round pavilion on a lawn) with everything below already wired. Copy it, keep `env.js`, `kit.js` and `main.js`, and replace `scene.js` with your subject.

```bash
cp -r assets/starter my-scene && cd my-scene
python3 -m http.server 8000      # any static server; ES modules need http://, not file://
```

| File | Holds |
| --- | --- |
| `index.html` | Import map pinned to three r169 (`three@0.169.0`), canvas, title, light buttons, loader |
| `main.js` | Renderer, camera, post stack, quality tiers, vantages and flights, recording hooks, frame loop |
| `env.js` | Sky, sun, image-based light, fog, clouds, night sky; three presets that blend; shadow fitting |
| `kit.js` | Seeded RNG, canvas textures, instancing kit, lathe, arc, profile sweep with mitred corners |
| `scene.js` | The example subject and every pattern worth copying |

URL parameters work out of the box: `?view=front|corner|low|aerial`, `?light=morning|golden|night`, `?quality=high|balanced|fast`, and `?record=1` for a frame-exact recording with `frame-capture`.

## Workflow

1. **Collect references and dimensions before writing geometry.** Plans, elevations, a photo from each side, the real measurements (storey heights, bay spacing, column diameter, wheelbase). Write them as constants at the top of the scene file in metres. A building built from guessed proportions looks like a toy however detailed it is.
2. **Block it out in boxes** at the right size and check from the vantages a visitor will see. Fix proportions now; detail hides nothing.
3. **Detail by kind, not by instance.** Write one column, one window, one baluster as a function, then place hundreds through the `Kit` (one draw call per part). Mouldings, kerbs, steps and rails are profiles swept along paths (`sweep`); round things are lathes.
4. **Light it** with a preset from `env.js`, then tune exposure, sun elevation and fog for the mood. Most of the realism arrives in this step.
5. **Add life:** wind in trees, water, flags, people or traffic as instanced sprites, lamps that come on at night. Drive all of it from the shared uniforms (`U.uTime`, `U.uWind`, `U.uNight`) so recording and light changes stay in sync.
6. **Measure and check** with `site-check`: frame time, draw calls, every vantage at every light, a phone. Then record with `frame-capture`.

## Rendering setup that matters

These are set in `main.js`; keep them unless you know why not.

- **Tone mapping** `ACESFilmicToneMapping` with exposure per preset (0.6 to 1.0). Without tone mapping, bright skies clip and everything looks like a game from 2009.
- **Antialiasing in the composer, not the canvas:** `antialias: false` on the renderer, and a `HalfFloatType` render target with `samples: 4` for the effect composer. Canvas MSAA does nothing once post-processing is on.
- **Post stack:** `RenderPass` → `GTAOPass` (ambient occlusion: contact shadows under cornices, between columns, where walls meet ground) → `UnrealBloomPass` (strength about 0.12 by day, 0.5 at night) → `OutputPass` (tone mapping and sRGB last). The GTAO pass is subclassed to hide anything with `userData.noAO` (sky layers, particles, glass) because AO darkens whatever it sees.
- **Image-based light from the sky itself:** `env.js` renders a private copy of the sky into a PMREM environment map, so reflections and ambient light match the sky's colour at every preset. Regenerate it while presets blend (every sixth frame is enough: PMREM is expensive).