BjornMelin/dev-skills / plugins/design-motion/skills/r3f-scene-polish
r3f-scene-polish
VerifiedArt-directs an existing three.js or React Three Fiber scene to cinematic quality with postprocessing, HDRI and PBR lighting, contact shadows, transmission materials, and camera choreography. Use for look-development once the scene renders, not for scene setup or lifecycle.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| agents/openai.yaml | config | 420 B |
| evals/evals.json | config | 4.5 KB |
| evals/trigger-queries.json | config | 2.5 KB |
| references/art-direction.md | markdown | 8.2 KB |
| references/motion-vocabulary.md | markdown | 7.2 KB |
| references/performance-accessibility.md | markdown | 1.6 KB |
| references/provenance.json | config | 2.4 KB |
| scripts/audit.mjs | script | 18.8 KB |
references/art-direction.md
View on GitHub# R3F Cinematic Art-Direction
Look-dev recipes for making an **already-working** R3F scene cinematic:
postprocessing, HDRI/PBR lighting, shadows, transmissive materials, tone mapping,
and camera work. Setup, lifecycle, disposal, and DPR belong to `web-three-r3f` —
this reference is the aesthetic layer only.
> **Verify against the repo's installed versions before editing.** APIs and props
> below were confirmed 2026-07 against the versions in the table. See
> `provenance.json` for sources.
## Version baseline (2026)
| Package | Version | Notes |
|---|---|---|
| `three` | 0.185.1 (r185) | — |
| `@react-three/fiber` | 9.6.1 | React `>=19 <19.3` |
| `@react-three/drei` | 10.7.7 | R3F v9 / React 19 |
| `@react-three/postprocessing` | 3.0.4 | — |
| `postprocessing` (core) | 6.39.2 | peer **`three >=0.168 <0.186`** |
⚠️ **Load-bearing pin:** `postprocessing` core caps at `three < 0.186`, so
`three@0.185` is the last supported release. Do not bump three to 0.186+ in a
scene that uses `@react-three/postprocessing` until pmndrs ships a new
`postprocessing`. Pin `three` to `~0.185`.
## 1. Postprocessing quality ladder
Named exports from `@react-three/postprocessing`; enums from core `postprocessing`.
Effects apply in **child order**; `EffectComposer` merges compatible effects into
one pass. Effects have no `enabled` prop — conditionally render/unmount the child.
```jsx
import { EffectComposer, N8AO, DepthOfField, Bloom, ToneMapping, SMAA, Vignette } from '@react-three/postprocessing'
import { ToneMappingMode } from 'postprocessing'
import * as THREE from 'three'
<EffectComposer
multisampling={8} // MSAA; use 0 + <SMAA/> for cheaper AA
frameBufferType={THREE.HalfFloatType} // HDR buffer — needed for correct bloom/tonemap
>
<N8AO aoRadius={6} distanceFalloff={1} intensity={2} quality="high" halfRes />
<DepthOfField focusDistance={0} focalLength={0.02} bokehScale={4} />
<Bloom mipmapBlur intensity={1.2} luminanceThreshold={0.9} luminanceSmoothing={0.025} />
<ToneMapping mode={ToneMappingMode.AGX} />
<SMAA />
<Vignette offset={0.3} darkness={0.6} />
</EffectComposer>
```
- **`N8AO`** is the current-best ambient occlusion — prefer it over legacy `SSAO`.
It computes normals from depth, so it does **not** need `enableNormalPass`
(legacy `SSAO` does). `quality`: `performance | low | medium | high | ultra`.
- **`Bloom`**: set `mipmapBlur` for the modern soft cinematic bloom;
`luminanceThreshold` gates what glows.
- **`DepthOfField`**: `focusDistance` is normalized 0–1, or use `target={[x,y,z]}`
for continuous autofocus.
- **`ToneMapping`** default mode is `AGX`. Don't double-tonemap — if you tone-map
here, set the renderer to `NoToneMapping` (`<Canvas flat>`); see §3.
- **`SMAA`** + `multisampling={0}` swaps MSAA for cheaper post-AA.
**Selective bloom (preferred, cheapest):** bloom is selective by default — lift
emissive/color out of the 0–1 range and mark it `toneMapped={false}`:
```jsx
<meshStandardMaterial emissive="cyan" emissiveIntensity={3} toneMapped={false} />
```
The explicit `<Selection>` + `<Select enabled>` + `<SelectiveBloom lights={[…]} />`
path still works but is heavier and requires a `lights` prop.
## 2. drei look-dev helpers
Named exports from `@react-three/drei`.
```jsx
import {
Environment, Lightformer, ContactShadows, AccumulativeShadows,
RandomizedLight, MeshTransmissionMaterial, CameraControls, Float, Stage,
} from '@react-three/drei'
```
- **`Environment`** — HDRI image-based lighting (+ optional background):
`<Environment preset="studio" background backgroundBlurriness={0.5} environmentIntensity={1} />`
or `files="/hdri/studio_1k.hdr"`. Presets: `city sunset dawn night warehouse
forest apartment studio park lobby`. Place `<Lightformer form="rect" .../>`
children inside for custom studio softboxes.
- **`ContactShadows`** — cheap grounded shadow: `<ContactShadows position={[0,-0.99,0]}
opacity={0.5} scale={10} blur={2} far={4} resolution={256} />` (`frames={1}` to
bake once for a static subject).
- **`AccumulativeShadows` + `RandomizedLight`** — raytraced-looking soft shadows,
free once converged (needs `shadows` on `<Canvas>`):
```jsx
<AccumulativeShadows temporal frames={100} scale={10} opacity={0.85} alphaTest={0.9}>
<RandomizedLight amount={8} radius={5} ambient={0.5} intensity={1} position={[5,5,-10]} bias={0.001} />
</AccumulativeShadows>
```
- **`MeshTransmissionMaterial`** — glass/refraction (extends `meshPhysicalMaterial`):
`<MeshTransmissionMaterial transmission={1} thickness={0.5} roughness={0}
chromaticAberration={0.03} anisotropicBlur={0.1} samples={6} resolution={256} />`.
For many glass objects, share one FBO (`transmissionSampler` / a manual
`useFBO()`) to avoid N render passes.
- **`CameraControls`** — imperative `setLookAt`/`dollyTo`/`rotateTo` via ref:
`<CameraControls makeDefault />`.
- **`Float`** — idle drift: `<Float speed={1} rotationIntensity={1} floatIntensity={1}>`.
- **`Stage`** — one-liner studio (auto-centers, frames camera, lights, grounds):
`<Stage adjustCamera={1.5} shadows="contact" environment="city" preset="rembrandt">`.
## 3. Tone mapping + color management (three r185)
Constants on `THREE`: `NoToneMapping, LinearToneMapping, ReinhardToneMapping,
CineonToneMapping, ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping`.
**Two "default" answers — state both, don't conflate:**
- three-core `WebGLRenderer.toneMapping` default = **`NoToneMapping`**.
- R3F `<Canvas>` overrides it to **`ACESFilmicToneMapping`** (and
`outputColorSpace = SRGBColorSpace`) to match Blender/Photoshop. `<Canvas flat>`
switches back to `NoToneMapping`.
```jsx
// AgX / Neutral give more accurate highlight rolloff than ACES (which crushes saturated colors).
<Canvas gl={{ toneMapping: THREE.AgXToneMapping, toneMappingExposure: 1.1 }}>…</Canvas>
```
- `THREE.ColorManagement.enabled` is **`true`** by default (since r152) — leave it
on for PBR. `outputColorSpace` defaults to `SRGBColorSpace`.
- Set `colorSpace={THREE.SRGBColorSpace}` on **color/albedo** textures; leave data
maps (normal/roughness/metalness) linear (`NoColorSpace`).
- For heaviest control, tone-map in postprocessing (`<ToneMapping>`) and set the
renderer to `flat`/`NoToneMapping` so you don't tonemap twice.
## 4. WebGPU + TSL (caveat)
`WebGPURenderer` (from `three/webgpu`) is production-usable and auto-falls back to
WebGL2 (`forceWebGL: true` to force). R3F v9's **async `gl` prop** enables it
(WebGPU needs `await renderer.init()`). **TSL** (`three/tsl`) is a
renderer-agnostic node shader language that replaces hand-written GLSL.
⚠️ **`@react-three/postprocessing` is WebGL-only** — it does not run on the WebGPU
backend. For post FX under WebGPU use three's own TSL `PostProcessing`
(`three/webgpu` + `three/tsl` passes), not `<EffectComposer>`. Choose your effect
stack around the renderer you commit to.
## 5. R3F v9 / React 19 notes
- R3F v9 targets **React 19** (v8 was React 18); drei v10 pairs with it.
- The global `JSX.IntrinsicElements` namespace for three elements is deprecated —
extend via the **`ThreeElements`** interface from `@react-three/fiber`.
- `physicallyCorrectLights` / `useLegacyLights` are **removed** — lighting is
physically correct by default.
## Deprecated / renamed (flag list)
| Old | New | Since |
|---|---|---|
| `outputEncoding` | `outputColorSpace` (`SRGBColorSpace`) | three r152 |
| `Texture.encoding` | `Texture.colorSpace` | three r152 |
| `sRGBEncoding`/`LinearEncoding` | `SRGBColorSpace`/`LinearSRGBColorSpace` | three r152 |
| `<ToneMapping adaptive middleGrey/>` | `mode={ToneMappingMode.…}` | postprocessing 6.3x |
| legacy `SSAO` | `N8AO` | current |
| `physicallyCorrectLights` | (removed; default) | three r155/165 |
| pmndrs `postprocessing` on WebGPU | three/webgpu `PostProcessing` + TSL | — |
## Reduced motion & quality ladder
Cinematic effects are the heaviest and most motion-sick-prone layer. Always:
- Gate expensive effects (N8AO, DoF, high `samples`) behind a device/DPR quality
tier; drop to a lighter stack on low-power devices.
- Provide a reduced-motion branch: cut camera travel, idle `Float`, and heavy
parallax; keep the lit, graded still. Read the preference and branch the ladder.
- Keep text/UI legible through bloom and DoF. See `performance-accessibility.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |