} ``` For a loop with no Canvas at all, register with the scheduler directly. Its callbacks receive timing-only state (`{ time, delta, elapsed, frame }`): ```tsx import { getScheduler } from '@react-three/fiber' const unregister = getScheduler().register((state, delta) => updateGame(delta)) ``` > The scheduler itself lives in [`@pmndrs/scheduler`](https://www.npmjs.com/package/@pmndrs/scheduler) and is consumed by R3F; you still reach it through `getScheduler()` / `useThree().scheduler`. ## Scheduler API reference `getScheduler()` (or `useThree().scheduler`) returns the singleton. Key members: **Phases:** `addPhase(name, { before?, after?, timestep?, maxSubsteps? })`, `hasPhase(name)`, `phases` (getter), `setPhaseTimestep(name, timestep | undefined, { maxSubsteps? })`, `getPhaseTimestep(name)`, `getOverstep(phase?, rootId?)`. **Roots:** `registerRoot(id, options?)`, `unregisterRoot(id)`, `generateRootId()`, `getRootCount()`, `getRootIds()`, `getRootFrameloop(id)`, `setRootFrameloop(id, mode)`, `setRootOrder(id, order)`, `setRootConstraints(id, { before?, after? })`, `isReady` (getter), `onRootReady(cb)`. Canvas manages these automatically. Each root gets its own `onError` (a Canvas reports to its error boundary), so a job that throws on one canvas never reaches another canvas's handler. **Jobs:** `register(callback, options?)`, `unregister(id, rootId?)`, `updateJob(id, partialOptions)`, `getJobCount()`, `getJobIds()`, `hasUserJobsInPhase(phase, rootId?)`. **Job state:** `pauseJob(id)`, `resumeJob(id)`, `isJobPaused(id)`, `subscribeJobState(id, listener)`. **Loop control:** `start()`, `stop()`, `isRunning` (getter), `frameloop` (legacy bulk/default getter/setter), `defaultFrameloop`, `invalidate(frames?, stackFrames?)`, `invalidateRoot(rootId, frames?, stackFrames?)`, `resetTiming()`. **Manual stepping:** `step(timestamp?)` (run one frame for all roots), `stepRoot(rootId, timestamp?)` (run one root), `stepJob(id, timestamp?)` (run one job in isolation). `register` accepts the full job options: ```ts interface JobOptions { id?: string // unique id (auto-generated if omitted) rootId?: string // target root (defaults to the first root) phase?: string // execution phase (default: 'update') before?: string | string[] // run before this phase or job id after?: string | string[] // run after this phase or job id priority?: number // loose tie-breaker within a phase (higher = earlier, default 0); prefer before/after fps?: number // throttle limit (at most one call per RAF) drop?: boolean // timestamp catch-up behavior when throttled (default true) enabled?: boolean // skip without unregistering (default true) } ``` `updateJob` can mutate `priority`, `fps`, `drop`, and `enabled` without a rebuild; changing `phase`, `before`, or `after` triggers a rebuild of the sorted job list. ## Example: a full game loop ```tsx function GameLoop() { const { scheduler } = useThree() useEffect(() => { scheduler.addPhase('ai', { after: 'physics', before: 'update' }) }, [scheduler]) // Input first useFrame(processInput, { phase: 'input', id: 'input-handler' }) // Physics on the fixed 1/60 s step (0..8 steps per frame) useFrame((_, delta) => physicsWorld.step(delta), { phase: 'physics' }) // AI at 20fps, dropping missed intervals useFrame(aiSystemUpdate, { phase: 'ai', fps: 20, drop: true }) // Game state every frame useFrame(updateGameState, { phase: 'update', id: 'game-state' }) // VFX after game state useFrame(updateVFX, { after: 'game-state' }) // HUD overlay after the default render (does not take over rendering) useFrame( ({ gl }) => { gl.autoClear = false gl.render(hudScene, hudCamera) gl.autoClear = true }, { after: 'render' }, ) // Stats last useFrame(collectStats, { phase: 'finish' }) return null } ``` ]]> **v10+ only.** The WebGPU hooks require React 19 and a WebGPU renderer. The TSL hooks ship in their own package, `@react-three/tsl`, next to `@react-three/fiber`: ```bash npm install @react-three/fiber@alpha @react-three/tsl@alpha three ``` ## Enabling WebGPU There is nothing to enable: `

{ const fogNode = fog(uniforms.scope('fog').uColor, uniforms.scope('fog').uDensity) return () => { scene.fogNode = fogNode return () => void (scene.fogNode = null) } }, []) ``` ## useUniform Single-uniform hook with create/get/update semantics. ```tsx // Create uniform (or get existing + update value) const uName = useUniform(name, value) // Get existing uniform (throws if not found) const uName = useUniform(name) ``` ### Parameters | Parameter | Type | Description | | --------- | -------------- | ---------------------------------------------- | | `name` | `string` | Unique identifier for the uniform | | `value` | `UniformValue` | Optional. Initial value, or value to update to | ### Return Value Returns a `UniformNode` - a Three.js TSL uniform node. Reading by name alone (`useUniform('uTime')`) returns it typed by name when your uniforms are [registered](./typed-resources), exactly when you pass its type (`useUniform('uTint')`), and as a [loose](#reading-by-name) `LooseUniformNode` otherwise, which TSL accepts as is. | Property | Type | Description | | -------- | -------- | ---------------------------------------------- | | `value` | `T` | Current uniform value (get/set) | | `uuid` | `string` | Three.js UUID | | `name` | `string` | Debug name (set automatically from `name` arg) | ### Supported Types ```typescript type UniformValue = | number | boolean | string // string colors auto-convert to THREE.Color | Vector2 | Vector3 | Vector4 | Color | Matrix3 | Matrix4 | Node // TSL nodes like color(), vec3(), float() for type casting | UniformNode // existing uniform nodes ``` ### Usage ```tsx import { useUniform } from '@react-three/tsl' import { positionLocal, normalLocal } from 'three/tsl' function DisplacedSphere() { const uDisplacement = useUniform('uDisplacement', 0.5) useFrame((state) => { uDisplacement.value = Math.sin(state.elapsed) * 0.5 }) return ( ) } ``` - **Create mode** (`useUniform('uTime', 0)`): creates if missing; if it exists, returns the existing uniform and updates its value. When a later render passes a different value, the uniform's `.value` is updated in place (the node is not recreated). An equal value in a new object, such as an inline `new Color('red')`, is not a change, so an imperative `.value` write survives the re-render. - **Get mode** (`useUniform('uTime')`): returns the existing uniform; throws if it does not exist. Uniforms are shared across components - one component can create a uniform and another can read it by name. ## useUniforms Batch uniform management with scoping and the create-if-not-exists pattern. ```tsx // Create/update uniforms at root level const uniforms = useUniforms({ uTime: 0, uColor: '#ff0000' }) // Create/update uniforms in a scope const uniforms = useUniforms({ uHealth: 100 }, 'player') // Function syntax for RootState access const uniforms = useUniforms((state) => ({ uAspect: state.size.width / state.size.height, })) // Read all uniforms / read a scope const all = useUniforms() const playerUniforms = useUniforms('player') // A reader cannot infer types from the store. Name what was registered and the // uniforms come back fully typed: uHealth is a UniformNode<'float', number> const { uHealth } = useUniforms<{ uHealth: number; uSpeed: number }>('player') ``` A reader sees what was declared above it in the same render: a child calling `useUniforms()` gets the uniforms its parent creates on its very first render, before the parent's registration has landed on the store, so a render pipeline or material it builds right away closes over the real node. The same holds for the reader forms of `useNodes`, `useBuffers` and `useGPUStorage`, and for `useUniform(name)`. A reader rendered _before_ the component that declares an entry (a sibling earlier in the tree) gets it once that registration commits, and re-renders then; `useUniform(name)` there throws, since the uniform does not exist yet. ### Parameters | Parameter | Type | Description | | --------- | ------------------------------------ | -------------------------------------------- | | `creator` | `UniformCreator \| object \| string` | Uniform definitions, function, or scope name | | `scope` | `string` | Optional scope name for organization | When using the function form, the creator receives a [`CreatorState`](#scopedstore) (RootState with ScopedStore wrappers on `uniforms`, `nodes`, `buffers`, `gpuStorage`). ### Return Value Returns `UniformsWithUtils` - your uniforms by name, **plus three util functions**: ```typescript { // ...your uniforms uTime: UniformNode uColor: UniformNode // utils removeUniforms: (names: string | string[], scope?: string) => void clearUniforms: (scope?: string) => void rebuildUniforms: (scope?: string) => void } ``` - **`removeUniforms`** - remove specific uniforms by name from root or a scope. - **`clearUniforms`** - clear a scope, `'root'` for root only, or no argument to clear everything. - **`rebuildUniforms`** - invalidate the cache and bump the HMR version to force re-creation of the creators (all, `'root'`, or a named scope). ### Input Types ```tsx const uniforms = useUniforms({ uNumber: 5.0, // primitive uBool: true, uColor: '#ff0000', // string -> THREE.Color uVec2: { x: 1, y: 2 }, // plain object -> THREE.Vector2 (great for Leva) uVec3: new THREE.Vector3(1, 2, 3), // Three.js types uColorNode: color('#ff0000'), // TSL node -> typed uniform }) ``` ### Leva Integration Leva controls work directly. The component re-renders on change, plain objects auto-convert to vectors, and function syntax deep-compares output so the GPU only updates when a value actually changes: ```tsx const { color, intensity } = useControls({ color: { x: 1, y: 0.5, z: 0 }, intensity: { value: 1.0, min: 0, max: 2 }, }) const { uColor, uIntensity } = useUniforms({ uColor: color, uIntensity: intensity }) ``` ### Updating Values Always update uniform values imperatively in `useFrame` (no React re-render): ```tsx const { uTime } = useUniforms({ uTime: 0 }) useFrame(({ elapsed }) => { uTime.value = elapsed }) // Also available from state useFrame(({ elapsed, uniforms }) => { uniforms.uTime.value = elapsed }) ``` ### Scoped Uniforms Scopes prevent naming conflicts across features. The same name lives independently in each scope: ```tsx useUniforms({ uHealth: 100, uSpeed: 1.0 }, 'player') useUniforms({ uHealth: 75, uSpeed: 0.8 }, 'enemy') // Read elsewhere, with the schema the creator registered const playerUniforms = useUniforms<{ uHealth: number; uSpeed: number }>('player') // or without one: each uniform is loose, still usable in TSL as is const enemy = useUniforms('enemy') enemy.uHealth.mul(2) ``` The same schema form exists on `useNodes`, `useBuffers` and `useGPUStorage`: `useNodes<{ wobble: Node }>('fx')`. ## useNodes Global TSL node management with the create-if-not-exists pattern and optional scoping. Use it to share expensive TSL expressions, functions, and varyings across components. ```tsx const nodes = useNodes(() => ({ wobbleFn: Fn(() => vec3(sin(time), cos(time), sin(time.mul(2)))), })) // Scoped const nodes = useNodes(() => ({ effectFn: Fn(() => /* ... */) }), 'effects') // Read all / read a scope const all = useNodes() const effectNodes = useNodes('effects') ``` The creator's job is registration: whatever it returns is stored, so other components can read it with `useNodes('scope')`, `state.nodes` or a creator's `nodes`. Keeping the return value is optional - `useNodes(registerEffects)` on its own registers them. A creator must return the nodes it registers; to put a node onto a Three object instead (`scene.fogNode`), use `useLocalNodes` and [return an install function](#installing-nodes-on-three-objects). ### When the creator runs Once per generation. The first component to register a name wins, and later renders - including renders with different props - reuse the registered node: the creator does **not** re-run when a value it captured changes. This is deliberate. Other components build their own graphs from a shared node, and replacing it would not reach all of them; every replacement would also recompile each material that uses it. So: - A value that changes goes into a uniform (`useUniforms`), and the node reads the uniform. - A structural change goes through `rebuildNodes(scope)` (or a hot update), which starts a new generation: every creator re-runs together and every consumer sees the new nodes. Because of that, a creator that reads an entry before it exists keeps `undefined` until the next rebuild. Register what a creator reads above it (earlier in the same component, or higher in the tree). In development a warning names such a read; use `.has()` when probing for an optional entry on purpose. The same holds for `useUniforms`, `useBuffers` and `useGPUStorage` creators. ### Parameters | Parameter | Type | Description | | --------- | ----------------------- | ---------------------------------------------- | | `creator` | `NodeCreator \| string` | Function that returns TSL nodes, or scope name | | `scope` | `string` | Optional scope name for organization | The creator receives a [`CreatorState`](#scopedstore). ### Return Value Returns `NodesWithUtils` - your nodes by name, **plus three util functions**. A creator's nodes keep the types it inferred; a reader's (`useNodes()`, `useNodes('fx')`) are typed by name once you [register your nodes](./typed-resources#register-your-nodes), and [loose](#reading-by-name) otherwise: TSL accepts them and they can be called (`nodes.rimLightFn()`) without a cast. ```typescript { // ...your nodes // utils removeNodes: (names: string | string[], scope?: string) => void clearNodes: (scope?: string) => void rebuildNodes: (scope?: string) => void } ``` - **`removeNodes`** - remove specific nodes by name from root or a scope. - **`clearNodes`** - clear a scope, `'root'` for root only, or no argument to clear everything. - **`rebuildNodes`** - invalidate the cache and bump the HMR version to force re-creation of node creators (all, `'root'`, or a named scope). > The `rebuild*` utils are returned by the hook directly; you do not need the standalone `rebuildAllNodes`/`rebuildAllUniforms` exports for in-component use. ### What to Store Store expensive, reusable work - complex noise/effect functions, shared varyings: ```tsx useNodes(() => ({ noiseFn: Fn(() => fbm(positionWorld.mul(scale))), glowFn: Fn(([color, intensity]) => color.mul(pow(fresnel, intensity))), vWorldPos: varying(vec3()), })) ``` Don't store trivial expressions or constants - use them directly instead. ### Usage ```tsx import { useNodes, useLocalNodes } from '@react-three/tsl' import { Fn, vec3, sin, cos, time } from 'three/tsl' // Define shared nodes once, usually near the root function GlobalNodes() { useNodes(() => ({ wobbleFn: Fn(() => vec3(sin(time), cos(time.mul(1.3)), sin(time.mul(2)))), })) return null } function WobblyMesh() { const { colorNode } = useLocalNodes(({ nodes }) => ({ colorNode: nodes.wobbleFn.mul(0.5).add(0.5) }), []) return ( ) } ``` ## useLocalNodes Creates component-local values from the rendering context and the shared TSL resources. Unlike `useNodes`, this does **not** register to the global store - the result is local to the component, and nothing is published during render or commit. ```tsx const localNodes = useLocalNodes( ({ uniforms, nodes }) => ({ colorNode: nodes.noiseFn.mul(uniforms.intensity), positionNode: positionLocal.add(vec3(0, uniforms.height, 0)), }), [], ) ``` ### Signature ```typescript function useLocalNodes>(creator: LocalNodeCreator, deps?: React.DependencyList): T type LocalNodeCreator = (state: CreatorState) => T ``` The creator receives a [`CreatorState`](#scopedstore) - **not** a raw `RootState`. `uniforms`, `nodes`, `buffers`, and `gpuStorage` are wrapped in a ScopedStore (property access returns the leaf node; use `.scope(name)` for nested scopes). All other RootState properties (`size`, `viewport`, `camera`, etc.) pass through unchanged. Returns any object, not limited to TSL nodes; the exact keys and types of the creator's return are preserved. `deps` accepts a readonly list. ### Dependency Array The second argument works like `useMemo`'s: it declares the **JavaScript construction inputs** the creator reads while building the graph. Whether the array is present selects the mode; its length is up to you. **`[]` is the normal case.** A value that changes over time - a color from a prop, a slider, a strength - belongs in a uniform (`useUniforms`), whose `.value` updates on the GPU with no rebuild and no shader recompile. Declare a dependency only for an input that decides the graph's **structure** and cannot be a uniform: which node to use, how many octaves a JavaScript loop unrolls, whether a branch exists at all. | Call | Ordinary component renders | | -------------------------------- | --------------------------------------------------------------------- | | `useLocalNodes(creator)` | Re-evaluate on every render, even when the creator is a `useCallback` | | `useLocalNodes(creator, [])` | Reuse the result - the creator has no JavaScript construction inputs | | `useLocalNodes(creator, [a, b])` | Reuse until a declared dependency changes by `Object.is` | Whichever form you use, three triggers rebuild independently of `deps` (see [Rebuild Triggers](#rebuild-triggers)), and every rebuild runs the creator **from the current render** - so `[]` means "no JS inputs", not "never rebuild". Creator identity is never a trigger once an array is supplied, which is what makes the inline form cheap: ```tsx // Resource-driven composition: everything comes from the shared resources. const local = useLocalNodes(({ uniforms }) => ({ result: uniforms.strength.mul(2) }), []) // `pattern` picks which node the graph is built from: a structural input, so declare it. const local = useLocalNodes(({ nodes }) => ({ result: pattern === 'noise' ? nodes.noise : nodes.stripes }), [pattern]) ``` #### Live TSL values vs JS construction inputs The array is about what the **graph is built from**, not about what it reads at run-time: - A `UniformNode`, a `texture()`, `time`, `cameraPosition` - these are **live TSL values**. The graph references the node; updating `uTime.value` in `useFrame` reaches the GPU without a rebuild and must not be a dependency. - A prop, a piece of state, a number you multiply by, a string you branch on in JavaScript - these are **construction inputs**. Reading them while building the graph bakes them in, so a change needs a rebuild: declare them. ```tsx const { uStrength } = useUniforms({ uStrength: 1 }) const { colorNode } = useLocalNodes( ({ uniforms }) => ({ // uniforms.uStrength is live: read on the GPU every frame // `octaves` is baked in by the JavaScript loop: declared below colorNode: fbm(positionWorld, octaves).mul(uniforms.uStrength), }), [octaves], ) useFrame(() => { uStrength.value = 5 // value-only change -> no rebuild, no dependency }) ``` #### Stale-closure caveat An omitted construction input does not trigger a rebuild, and until one happens the result reflects the value from the render that built it. When a legitimate rebuild happens later (resource replacement, HMR, a declared dependency changing) the current render's creator runs, so the omitted input's **latest** value shows up then - the usual `useMemo` model. If you find yourself adding a prop or a piece of state to `deps`, first ask whether it should be a uniform instead. Declaring it rebuilds the graph - and recompiles every material using it - each time it changes; a uniform does neither. For the same reason, don't enable `react-hooks/exhaustive-deps` for `useLocalNodes` through `additionalHooks`: it asks for every captured value to be declared, which steers towards rebuilding on every prop change. Use [`@react-three/eslint-plugin`](https://github.com/pmndrs/react-three-fiber/blob/v10/packages/eslint-plugin/docs/rules/prefer-local-nodes-deps.md)'s `prefer-local-nodes-deps` instead (in its `recommended` config): it flags an inline creator with no array, and when the creator reads values from the component it points you to a uniform first. #### Behavior change for stable callbacks Before this contract existed, `useLocalNodes` memoized against creator identity, so a `useCallback` creator was reused across renders while an inline creator reran every render. Now the **absence of the array** means "re-evaluate every render" regardless of how stable the function is. Callers who passed a `useCallback` creator for that effect should pass `[]` (or their inputs) instead - the `useCallback` is no longer needed. ### Rebuild Triggers Independently of `deps`, the creator re-runs when: - A shared resource the creator **read** changes: it is replaced, removed, or appears where the creator read nothing. This covers `uniforms`, `nodes`, `buffers`, `gpuStorage` and `textures`. Registrations the creator did not read change nothing, so a model finishing loading or a panel registering its own uniforms neither re-renders this component nor rebuilds its graph. - The owning store changes (multi-canvas `primaryStore` resolution). - The HMR version is bumped, by a hot update or a manual `rebuild*` call (see [TSL HMR](./hmr)). Value changes do **not** trigger a rebuild - TSL nodes reference uniforms, they do not capture values: ```tsx const { uTime } = useUniforms({ uTime: 0 }) const { colorNode } = useLocalNodes(({ uniforms }) => ({ colorNode: sin(uniforms.uTime) }), []) useFrame(() => { uTime.value = performance.now() // value-only change -> no rebuild }) ``` #### Textures in a creator `textures` is the canvas's texture registry, a `Map` keyed by URL. A texture that `useTexture` loads earlier in the same render is already there, before its registration lands, so a creator right after it builds with the texture on the first try: ```tsx const TEXTURES = { day: '/earth-day.jpg', night: '/earth-night.jpg' } function Globe() { useTexture(TEXTURES) const { dayNode } = useLocalNodes(({ textures }) => ({ dayNode: texture(textures.get(TEXTURES.day)) }), []) // ... } ``` A texture loaded somewhere else later rebuilds a creator that read its URL as missing. #### What counts as a read | In the creator | Rebuilds when | | --------------------------------------------------------- | ------------------------------------------------------- | | `uniforms.uTime`, `nodes.noise`, `buffers.positions` | that entry is replaced, removed, or appears | | `uniforms.scope('fog').uDensity`, `uniforms.fog.uDensity` | that leaf changes; other leaves in `fog` don't count | | `uniforms.has('uTime')`, `'uTime' in uniforms` | the entry appears or disappears | | `uniforms.keys()`, `Object.keys(...)`, spreading a scope | an entry is added to or removed from that scope | | `textures.get(url)`, `textures.has(url)` | the texture at that URL is replaced, loads or goes | | iterating `textures`, `textures.size` | a URL is added or removed, or an entry iterated changes | Only reads made **before the creator returns** are tracked. The body of a `Fn(() => ...)` runs later, while three builds the shader, so a lookup there is not seen - and you get a development warning. Read the resource in the creator and close over it: ```tsx // Tracked: the uniform is read while the creator runs useLocalNodes(({ uniforms }) => { const strength = uniforms.uStrength return { effect: Fn(() => strength.mul(2)) } }, []) // Not tracked: the lookup happens inside Fn, after the creator returned useLocalNodes(({ uniforms }) => ({ effect: Fn(() => uniforms.uStrength.mul(2)) }), []) ``` The same applies to a value captured from **outside** the creator, such as a node returned by `useUniform`: the creator did not read it through its `state`, so declare it in `deps` if a replacement should rebuild the graph. Neither this hook nor React guarantees exactly one creator invocation: StrictMode, an initial suspension, or a discarded render can run it again. Keep creators pure apart from node construction. ### Installing Nodes on Three Objects Some nodes are not returned to anyone: they go straight onto a Three object, like `scene.fogNode` or `scene.backgroundNode`. For those, return a **function** instead of a record. The creator still builds the nodes during render; the function you return runs after commit, and whatever **it** returns is the cleanup: ```tsx useLocalNodes(({ scene, uniforms }) => { // render: build only const fogNode = fog(uniforms.fogColor, rangeFogFactor(uniforms.near, uniforms.far)) // after commit: install, and say how to undo it return () => { scene.fogNode = fogNode return () => { scene.fogNode = null } } }, []) ``` - The install step runs as a layout effect, so the node is in place before the first frame. - Everything that rebuilds a record (`deps`, a resource the creator read, a hot update or `rebuild*`) rebuilds here too: the previous cleanup runs, then the new install. - The cleanup also runs on unmount, and StrictMode's mount, cleanup, mount leaves the last install in place. - Resources read inside the install step are tracked like reads in the creator. - The hook returns nothing in this form. Don't assign inside the creator itself (`useLocalNodes(({ scene }) => { scene.fogNode = ... })`): that runs during render, which React can discard or repeat, and nothing would ever undo it. A creator that returns nothing is a type error and warns in development. ### Use For - Component-specific compositions of shared nodes - Graphs whose structure depends on props (which node, how many octaves) - values from props go into uniforms - Combining global uniforms/nodes with local logic Do not use it for expensive nodes shared across many components (use `useNodes`) or for static nodes that never change (use `useMemo` or direct creation). ### GPU-Side Branching Use TSL conditionals so branches react to uniform changes at run-time: ```tsx import { If, select } from 'three/tsl' const { colorNode } = useLocalNodes(({ uniforms, nodes }) => { const result = vec3(0).toVar() If(uniforms.uVariant.equal(0), () => result.assign(nodes.noisePattern)) .ElseIf(uniforms.uVariant.equal(1), () => result.assign(nodes.stripesPattern)) .Else(() => result.assign(nodes.dotsPattern)) return { colorNode: result } }, []) // Or select() for two-way branching const { colorNode } = useLocalNodes( ({ uniforms, nodes }) => ({ colorNode: select(uniforms.uUseNoise.equal(1), nodes.noisePattern, nodes.stripesPattern), }), [], ) ``` ### useNodes vs useLocalNodes | Feature | useNodes | useLocalNodes | | --------------- | ------------------------- | ----------------------------------------------- | | Storage | Global store | Component-local | | Sharing | Shared across components | Component-specific | | Best for | Expensive, reusable nodes | Component compositions | | Rebuild trigger | HMR / `rebuildNodes` only | Declared deps, resource replacement, store, HMR | ## ScopedStore Creator functions for `useUniforms`, `useNodes`, `useLocalNodes`, `useBuffers`, and `useGPUStorage` receive a `CreatorState`, not the raw `RootState`. `CreatorState` wraps the nested stores in a **ScopedStore** for type-safe access: ```typescript type CreatorState = RootState & { uniforms: CreatorUniforms // typed by name once you register your uniforms nodes: CreatorNodes // typed by name once you register your nodes buffers: CreatorBuffers // BufferLike reads, typed by name once registered gpuStorage: CreatorGPUStorage // StorageLike reads, typed by name once registered } ``` The runtime structure of these stores is `Record>` (a leaf node, or a nested scope). The ScopedStore wrapper lets you: 1. Access a leaf directly by property - `uniforms.uTime`, or `uniforms.player.uHealth` inside a scope. 2. Access a nested scope explicitly with `.scope(key)` - returns an empty wrapper if the scope does not exist, so it is safe. 3. Iterate with `has(key)`, `keys()`, `Object.keys()`, spread, and `for...in`. ### Reading by name TSL operators work on every uniform and node read, registered or not: ```tsx useLocalNodes( ({ uniforms, nodes }) => ({ wobble: sin(uniforms.uTime.mul(2)), playerHealth: uniforms.scope('player').uHealth, // or uniforms.player.uHealth glow: nodes.scope('effects').rimLightFn(), }), [], ) ``` How exactly they are typed depends on [registration](./typed-resources). Registered, a read is typed by name: `uniforms.uTime` is a float uniform, and `uniforms.uTiem` is an error. Unregistered, a uniform read is a `LooseUniformNode` and a node read a `LooseNode`. A string name can't tell TypeScript what the entry holds, and three's types only give operator methods to a node whose type (float, vec3, color, ...) is known, so these loose types have every member of three's nodes, typed `any` (a `LooseNode` can also be called, as an `Fn()` can). Every operator, TSL function and material slot accepts them; a misspelt member is still an error. That is a deliberate simplification: what their own methods return is `any`, and an operation that needs a specific type (`cross()` wants vec3s) isn't checked. When you want the exact type, cast once or give the scope its schema: ```tsx import type { UniformNode, Vector3 } from 'three/webgpu' useLocalNodes(({ uniforms }) => { const uDir = uniforms.uDir as UniformNode<'vec3', Vector3> // one `as` is enough const player = uniforms.scope<{ uHealth: UniformNode<'float', number> }>('player') return { facing: cross(uDir, normalView), damage: player.uHealth.mul(2) } }, []) ``` The same holds outside creators: `useUniforms()`, `useUniforms('scope')`, `useUniform('name')`, `useNodes()`, `useNodes('scope')`, and `state.uniforms` / `state.nodes` in `useFrame` and `useThree`. See [What stays loose](./typed-resources#what-stays-loose). Buffers and GPU storage are not loose: an unregistered read is the broad `BufferLike` or `StorageLike` union (a typed array is nothing like a buffer node), which one `as` or a schema (`useBuffers<{ positions: StorageBufferNode<'vec3'> }>('particles')`) narrows. [Registered](./typed-resources#register-buffers-and-gpu-storage), they are typed by name like uniforms and nodes. The wrappers are created lazily - the underlying Proxy is only built when you actually access `uniforms`, `nodes`, `buffers`, or `gpuStorage`, so creators that don't touch them pay no cost. ## Related - [WebGPU Overview](./overview) - concepts and architecture - [Render Pipeline](./render-pipeline) - post-processing and passes - [TSL HMR](./hmr) - what rebuilds on hot reload ]]> Three.js renamed `PostProcessing` to `RenderPipeline` in r183. The hook builds a `THREE.RenderPipeline`. ## API ```tsx // Basic - configure the output useRenderPipeline(({ renderPipeline, passes }) => { renderPipeline.outputNode = bloom(passes.scenePass.getTextureNode()) }) // With MRT setup useRenderPipeline( // mainCB - configure output ({ renderPipeline, passes }) => { const beauty = passes.scenePass.getTextureNode() const velocity = passes.scenePass.getTextureNode('velocity') renderPipeline.outputNode = motionBlur(beauty, velocity) }, // setupCB - configure MRT (runs first) ({ passes }) => { passes.scenePass.setMRT(mrt({ output, velocity })) }, ) // Read-only access const { renderPipeline, passes } = useRenderPipeline() ``` ### Parameters | Parameter | Type | Description | | --------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `mainCB` | `RenderPipelineMainCallback` | Configure `outputNode` and create effect passes | | `setupCB` | `RenderPipelineSetupCallback` | Optional. Configure MRT on the scene pass | | `options` | `RenderPipelineOptions` | Optional. `{ persist: true }` keeps the pipeline rendering after unmount, see [Ownership](#ownership-and-cleanup) | Both callbacks receive the same state as [`useNodes`](./tsl-hooks) creators (scene, camera, size, the wrapped `uniforms`, `nodes`, `buffers`, `gpuStorage` and `textures`) plus the pipeline and its passes. Returning an object from either callback registers those passes into `state.passes`. The `scenePass` key is reserved for the hook's own pass and cannot be returned. ```typescript type RegisteredPasses = Record & { scenePass?: never } type RenderPipelineMainCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void type RenderPipelineSetupCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void ``` ### Return Value ```typescript type UseRenderPipelineReturn = { passes: PassRecord // All registered passes clearPasses: () => void // Clear the passes record reset: () => void // Free the pipeline now rebuild: () => void // Re-run the callbacks against a fresh scene pass } & ({ isReady: true; renderPipeline: RenderPipeline } | { isReady: false; renderPipeline: null }) ``` The return is discriminated on `isReady`, so checking it narrows `renderPipeline` to non-null: ```tsx const { isReady, renderPipeline } = useRenderPipeline() if (isReady) renderPipeline.needsUpdate = true // RenderPipeline, not RenderPipeline | null ``` ## You must set outputNode If you change away from the default scene pass, you **must** set `renderPipeline.outputNode` yourself. This is deliberate - changing the pipeline output is not inferred automatically, so you stay in control of what gets rendered. ## Usage ### Simple Bloom ```tsx import { useRenderPipeline } from '@react-three/tsl' import { bloom } from 'three/tsl' function Scene() { useRenderPipeline(({ renderPipeline, passes }) => { const sceneTexture = passes.scenePass.getTextureNode() renderPipeline.outputNode = bloom(sceneTexture, 1.5, 0.1, 0.9) }) return ( ) } ``` ### Read-Only Access Called without callbacks, the hook only reads. It never creates the pipeline, and mounting or unmounting it has no effect on the one that is rendering: ```tsx function DebugPanel() { const { renderPipeline, passes, isReady } = useRenderPipeline() if (!isReady) return

No render pipeline

return

Passes: {Object.keys(passes).join(', ')}

} ``` ## What the Hook Does Automatically When called with a callback: 1. Creates a RenderPipeline for this component. 2. Creates a default scene pass (no MRT by default). 3. Sets a default `outputNode` to the scene pass (passthrough). 4. Recreates the scene pass only when the scene or camera actually changes, or on `rebuild()`. 5. Frees the pipeline and scene pass when the component unmounts, and the canvas goes back to rendering without post-processing. ## Ownership and Cleanup The component that configures the pipeline owns it. Conditionally rendering it turns the effect on and off: ```tsx function Bloom() { useRenderPipeline(({ renderPipeline, passes }) => { renderPipeline.outputNode = bloom(passes.scenePass.getTextureNode()) }) return null } // Unmounting frees its pipeline; the scene renders without bloom {showBloom && } ``` - **Readers don't count.** `useRenderPipeline()` without callbacks reads whatever pipeline is rendering, and never creates, keeps alive or frees one. - **Swapping effects works.** Replacing `` with `` in one render frees Bloom's pipeline and renders through Blur's. - **The latest owner renders.** If two mounted components configure the pipeline at the same time, the most recently mounted one renders and the hook warns once in development. When it unmounts, the other takes over again with the graph it already built. - **Remounts keep the pipeline.** Cleanup is deferred by one task, so StrictMode's double mount, and a Fast Refresh that keeps the component's state, reuse the pipeline and scene pass instead of building new ones. A remount that resets the component (Fast Refresh after you add or remove a hook, or `// @refresh reset`) is a new instance: it builds a new pipeline and the old one is freed. - **Canvas unmount frees everything** on that canvas, including persisted pipelines. Every mounted instance owns its own pipeline, so remounting the same effect component, on another route for example, always builds a new one. `persist` is for a different case: keeping an effect on screen after the component that configured it unmounts, when nothing replaces it. ```tsx useRenderPipeline(mainCB, setupCB, { persist: true }) ``` A persisted pipeline keeps rendering until another component configures the canvas's pipeline, `reset()` is called (a reader can call it), or the canvas unmounts. It cannot `rebuild()` once its component has unmounted, since its callbacks are gone. Passes your callbacks return are not disposed by the hook; see [#3864](https://github.com/pmndrs/react-three-fiber/issues/3864). ## MRT (Multiple Render Targets) For effects like motion blur, velocity buffers, or G-buffers, configure MRT in `setupCB`, which runs before `mainCB`. ```tsx import { mrt, output, velocity } from 'three/tsl' import { motionBlur } from 'three/addons/tsl/display/MotionBlur.js' function RenderPipelineManager() { useRenderPipeline( // mainCB - configure effect (MRT already set) ({ renderPipeline, passes }) => { const beauty = passes.scenePass.getTextureNode() const vel = passes.scenePass.getTextureNode('velocity') renderPipeline.outputNode = motionBlur(beauty, vel.mul(1.0)) }, // setupCB - configure MRT BEFORE mainCB runs ({ passes }) => { passes.scenePass.setMRT(mrt({ output, velocity })) }, ) return null } ``` ## Callback Execution Order: `setupCB` runs **first** (MRT must be configured before rendering), then `mainCB`. Callbacks run when: - The RenderPipeline is created: on mount, and after `reset()` the next time the hook's effect runs (`rebuild()`, a hot update, or a scene or camera change) - The scene or camera changes (the scene pass needs recreation) - Any hot update in the app, or a `rebuild*()` from another TSL hook, bumps the TSL resource generation - A resource the callbacks read appears, is replaced or is removed (see [Reading Resources](#reading-resources)) - `rebuild()` is called explicitly Callbacks do **not** re-run on: - Component re-renders - StrictMode's double mount ### HMR On a hot update the TSL hooks register a fresh generation of uniforms and nodes, and `useRenderPipeline` re-runs its callbacks once they have, so the graph picks up both your edits and the new uniforms. This happens on every hot update in the app, not only on edits to the component that owns the pipeline: the pipeline and scene pass are kept, and only the graph built on them is replaced and recompiled. A hot update that resets the owning component builds a new pipeline instead (see [Ownership](#ownership-and-cleanup)). `

**Experimental.** `useBuffers` and `useGPUStorage` cover GPU compute workflows that are still evolving. APIs may change between releases. Pin your version and expect churn. `useBuffers` and `useGPUStorage` manage GPU storage for compute operations. They follow the same create-if-not-exists pattern and scoping model as [`useNodes` and `useUniforms`](./tsl-hooks), and their creators receive a [`CreatorState`](./tsl-hooks#scopedstore) with ScopedStore wrappers. ```tsx import { useBuffers, useGPUStorage } from '@react-three/tsl' ``` ## useBuffers Manages buffer data: CPU TypedArrays, GPU buffer attributes, and TSL buffer nodes. ```tsx // Root level const buffers = useBuffers(() => ({ positions: instancedArray(count, 'vec3'), velocities: new Float32Array(count * 3), })) // Scoped const buffers = useBuffers(() => ({ particlePos: new StorageBufferAttribute(count, 4) }), 'particles') // Read all / read a scope const all = useBuffers() const particleBuffers = useBuffers('particles') ``` ### Parameters | Parameter | Type | Description | | --------- | ------------------------- | -------------------------------------------- | | `creator` | `BufferCreator \| string` | Function that returns buffers, or scope name | | `scope` | `string` | Optional scope name for organization | ### Return Value Returns `BuffersWithUtils` - your buffers by name, **plus four util functions**: ```typescript { // ...your buffers removeBuffers: (names: string | string[], scope?: string) => void clearBuffers: (scope?: string) => void rebuildBuffers: (scope?: string) => void disposeBuffers: (names: string | string[], scope?: string) => void } ``` - **`removeBuffers`** - remove buffers by name from root or a scope (store only). - **`clearBuffers`** - clear a scope, `'root'` for root only, or no argument for everything. - **`rebuildBuffers`** - invalidate the cache and bump the HMR version to force re-creation (all, `'root'`, or a scope). See [TSL HMR](./hmr) for the rebuild guarantees. - **`disposeBuffers`** - releases GPU resources (`.dispose()`) **and** removes from the store. ### What Can Be Stored ```tsx useBuffers(() => ({ // TypedArrays (CPU-side data) cpuData: new Float32Array(count * 3), indices: new Uint32Array(count), // Three.js buffer attributes storageAttr: new StorageBufferAttribute(count, 4), instancedAttr: new StorageInstancedBufferAttribute(count, 4), indirectAttr: new IndirectStorageBufferAttribute(data, 1), // TSL buffer nodes positions: instancedArray(count, 'vec3'), custom: storage(bufferAttribute, 'vec4', count), })) ``` ## useGPUStorage Manages GPU storage textures for compute operations. ```tsx // Root level const storage = useGPUStorage(() => ({ heightMap: new StorageTexture(512, 512) })) // Scoped const storage = useGPUStorage(() => ({ normalMap: new StorageTexture(1024, 1024) }), 'terrain') // Read all / read a scope const all = useGPUStorage() const terrainStorage = useGPUStorage('terrain') ``` ### Parameters | Parameter | Type | Description | | --------- | -------------------------- | -------------------------------------------- | | `creator` | `StorageCreator \| string` | Function that returns storage, or scope name | | `scope` | `string` | Optional scope name for organization | ### Return Value Returns `StorageWithUtils` - your storage by name, **plus four util functions**: ```typescript { // ...your storage removeStorage: (names: string | string[], scope?: string) => void clearStorage: (scope?: string) => void rebuildStorage: (scope?: string) => void disposeStorage: (names: string | string[], scope?: string) => void } ``` These mirror the `useBuffers` utils. `disposeStorage` releases GPU texture memory and removes the entry from the store. ### What Can Be Stored ```tsx useGPUStorage(() => ({ // Three.js storage textures heightMap: new StorageTexture(512, 512), voxelData: new Storage3DTexture(64, 64, 64), // TSL storage texture nodes storageNode: storageTexture(texture, uvNode, storeNode), })) ``` ## Accessing in Node Creators Both hooks expose their data to `useNodes` and `useLocalNodes` through the creator state's ScopedStore wrappers: ```tsx const { positions } = useBuffers(() => ({ positions: instancedArray(count, 'vec3') }), 'particles') const { heightMap } = useGPUStorage(() => ({ heightMap: new StorageTexture(512, 512) }), 'terrain') const { positionNode, heightNode } = useNodes(({ buffers, gpuStorage }) => ({ positionNode: buffers.scope('particles').positions.element(instanceIndex), heightNode: texture(gpuStorage.scope('terrain').heightMap), })) ``` ## Example: Particle System ```tsx import { useBuffers, useGPUStorage, useNodes, useLocalNodes } from '@react-three/tsl' import { instancedArray, Fn, vec3, instanceIndex, texture } from 'three/tsl' import { StorageTexture } from 'three/webgpu' const PARTICLE_COUNT = 10000 function ParticleSystem() { const { positions, velocities } = useBuffers( () => ({ positions: instancedArray(PARTICLE_COUNT, 'vec3'), velocities: instancedArray(PARTICLE_COUNT, 'vec3'), }), 'particles', ) const { forceField } = useGPUStorage(() => ({ forceField: new StorageTexture(256, 256) }), 'particles') const { updateParticles } = useNodes( ({ buffers, gpuStorage }) => ({ updateParticles: Fn(() => { const pos = buffers.scope('particles').positions.element(instanceIndex) const vel = buffers.scope('particles').velocities.element(instanceIndex) const uv = pos.xz.div(100).add(0.5) const force = texture(gpuStorage.scope('particles').forceField, uv).xyz vel.addAssign(force.mul(0.01)) pos.addAssign(vel) })(), }), 'compute', ) const { positionNode } = useLocalNodes( ({ buffers }) => ({ positionNode: buffers.particles.positions.element(instanceIndex), }), [], ) return ( ) } ``` ## Best Practices - Use scopes to group buffers/storage by system (`'particles'`, `'terrain'`). - Call `disposeBuffers` / `disposeStorage` in cleanup to free GPU resources. - Use `.scope('name')` for safe access (returns an empty wrapper if the scope is missing); direct `buffers.name` access works when you know the scope exists. ## Related - [TSL Hooks](./tsl-hooks) - nodes and uniforms, plus the ScopedStore wrapper - [WebGPU Overview](./overview) - concepts and architecture - [TSL HMR](./hmr) - rebuild behavior for buffers and storage ]]> **Experimental (A5).** The `useTextures` API may change before it's stabilized. ## useTexture ```tsx import { useTexture } from '@react-three/fiber' // Single const diffuse = useTexture('/diffuse.png') // Array const [diffuse, normal] = useTexture(['/diffuse.png', '/normal.png']) // Record - the most convenient form, since it spreads into a material const props = useTexture({ map: '/diffuse.png', normalMap: '/normal.png' }) return ``` ### Parameters | Parameter | Type | Description | | ---------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- | | `input` | `string \| string[] \| Record` | URL, list of URLs, or a name to URL map. The return value mirrors the input shape. | | `options.onLoad` | `(texture) => void` | Called once when the texture(s) finish loading. Not called on a registry hit. | | `options.cache` | `boolean` | Enroll the result in the registry. Defaults to `true`. | Passing a bare function instead of `options` still works and is treated as `onLoad`: ```tsx const floor = useTexture('/floor.jpg', (t) => { t.wrapS = t.wrapT = THREE.RepeatWrapping }) ``` ### Registry enrollment `cache` defaults to `true`, so loading enrolls into the registry automatically. The same URL then returns the **same** `Texture` object everywhere, and that object outlives its last consumer. ```tsx const diffuse = useTexture('/diffuse.png') diffuse.colorSpace = THREE.SRGBColorSpace // Elsewhere: the same object, with colorSpace already set const same = useTexture('/diffuse.png') ``` Pass `{ cache: false }` to skip registry enrollment for a texture: ```tsx const scratch = useTexture('/scratch.png', { cache: false }) ``` Registry reads in `useTexture` happen **once at mount**. A mounted `useTexture` does not re-render when the registry changes, so loading texture A never re-renders a component using texture B. To react to registry changes, use the selector form of `useTextures`. ## useTextures `useTextures` returns a handle onto the registry, a `Map` of plain `Texture` objects keyed by URL (or by any key you choose for textures you register yourself). Calling `useTextures()` with no selector subscribes to the whole registry, so the component re-renders whenever a key is added or disposed. Pass a selector to narrow that to a single key. Reading with `get()` inside `useFrame` is live either way and needs no subscription. ### Return value | Member | Type | Description | | ------------------------ | -------------------------------------------- | ---------------------------------------------------------- | | `all` | `Map` | The live registry. Treat as read-only. | | `get(input)` | `Texture \| undefined` (mirrors input shape) | Read one key, an array of keys, or a name to key map. | | `has(key)` | `boolean` | Whether a key exists. | | `add(key, texture)` | `void` | Register a texture that has no URL. Also accepts a record. | | `dispose(key, options?)` | `boolean` | Free GPU resources and remove the key. Refcount-aware. | | `disposeAll()` | `void` | Dispose everything and clear the registry. | ### Reading textures ```tsx import { useTexture, useTextures } from '@react-three/fiber' function Floor() { // Load once, anywhere in the tree — registered by default useTexture({ map: '/PavingStones092_1K_Color.jpg', normalMap: '/PavingStones092_1K_Normal.jpg', }) return null } function Wall() { // Reach the same textures from a different component — the record form // mirrors its input, so it drops straight into a material const { map, normalMap } = useTextures().get({ map: '/PavingStones092_1K_Color.jpg', normalMap: '/PavingStones092_1K_Normal.jpg', }) return ( ) } ``` ### Registering textures without a URL Render targets and procedural textures have no URL to key off, so register them yourself: ```tsx const textures = useTextures() textures.add('rt-main', renderTarget.texture) ``` ## Lifecycle and disposal Each mounted `useTexture` consumer (with `cache` on, the default) holds a reference on the keys it uses, and releases it on unmount. `dispose(key)` is refcount-aware. If the key is still referenced by a mounted consumer, it **warns to the console, skips the disposal, and returns `false`**: ```tsx const textures = useTextures() textures.dispose('/diffuse.png') // false if still in use, and nothing is freed textures.dispose('/diffuse.png', { force: true }) // disposes regardless textures.disposeAll() // scene teardown ``` > **A reference count of zero does not free anything.** Unmounting the last consumer only releases the reference. The texture stays in the registry and keeps its GPU memory until `dispose` or `disposeAll` is called. That is deliberate: leaving a scene and coming back should not re-upload its textures. It does mean a long-lived app has to dispose the keys it is finished with. ## When is the registry reactive? (and the flip-flop pattern) There are three distinct situations, and only one of them wants React reactivity: | Use case | Tool | Reactive? | | ------------------------------------------------------- | ------------------------------------- | ----------------------------- | | Load an asset by URL | `useTexture(url)` | No — the object never changes | | **Swap** which texture lives under a key (occasionally) | `useTextures(s => s.get(key))` | Yes — scoped to that one key | | Swap a texture **every frame** (ping-pong) | `registry.get(key)` inside `useFrame` | No — read it imperatively | Loading a URL never needs reactivity (the texture instance is stable), and a render target being drawn into updates _inside_ three.js (`needsUpdate`) without changing the JS object — so neither involves React. The one case that does is a **flip-flop / ping-pong**: you keep two textures and swap which one a material reads. For an _occasional_ swap (e.g. toggling an output on some event), subscribe to just that key with the selector form — only this component re-renders, and only when the slot actually changes: ```tsx function Output() { // Re-renders only when the texture under 'finalOutput' is swapped const tex = useTextures((s) => s.get('finalOutput')) return ( ) } // Elsewhere, from an event handler or effect (never during render, // since add() sets store state) — the Output component picks up texB useTextures().add('finalOutput', texB) ``` For a **per-frame** ping-pong, don't make React re-render every frame — read the current texture imperatively in the loop instead: ```tsx function PingPong({ material }) { const textures = useTextures() useFrame((state) => { const even = Math.floor(state.elapsed * 60) % 2 === 0 material.map = textures.get(even ? 'a' : 'b') }) return null } ``` ## Related - [Loading Textures](/next/tutorials/loading-textures) - tutorial introduction to texture loading - [Render Targets](/next/scene/render-targets) - creating the render targets you can register here ]]> `. From then on: ```tsx const all = useUniforms() all.uTime.value // number all.player.uHealth.value // number all.uTiem // ❌ type error: not registered const player = useUniforms('player') // 'player' autocompletes useUniform('uTime').value // number, no generic needed useFrame(({ uniforms }, delta) => { uniforms.uTime.value += delta // state.uniforms is typed too }) useThree((s) => s.uniforms.uColor) // and in useThree useNodes(({ uniforms }) => ({ tinted: mix(uniforms.uColor, uniforms.player.uTint, uniforms.uTime), // and in creators })) ``` Creators are checked against what you registered. New keys are always allowed: ```tsx useUniforms(() => ({ uTime: 0, uWind: new Vector3() })) // ✅ useUniforms(() => ({ uTime: 'fast' })) // ❌ uTime is registered as a number useUniforms({ uHealth: new Color() }, 'player') // ❌ uHealth is a number in 'player' ``` ## What stays loose Registration never makes existing code stricter than it has to: | Call | Not registered | Registered | | ----------------------------------------------------------- | ---------------------------- | ----------------------------------------- | | `useUniforms(() => ({...}))` | Inferred from the creator | Inferred; registered keys keep their type | | `useUniforms()` / `state.uniforms` / a creator's `uniforms` | Loose | Typed; unknown root keys are errors | | `useUniforms('player')` (registered scope) | Loose | Typed | | `useUniforms('enemy')` (other scope) | Loose | Loose | | `useUniforms<{ blur: number }>('fx')` | Typed by the explicit schema | Same | | `useUniform('uTime')` | Loose unless you pass a type | Typed by name | A loose read is a `LooseUniformNode`, and it works in TSL as is: ```tsx const { uTime, uColor } = useUniforms() material.colorNode = mix(color('red'), uColor, sin(uTime.mul(2))) useFrame((_, delta) => (uTime.value += delta)) ``` Why it is typed that way: a read by name can't know what the uniform under that name holds, and three's types only give the operator methods (`.mul`, `.add`, swizzles, `.toVar()`) to a node whose type is known: a float, a vec3, a color. A plain "some uniform" type has none of them, which is why these reads used to need a cast. So an unregistered read is typed as a node that has every member that any of three's uniform nodes has, each typed `any`. Every operator, TSL function and material slot accepts it, and a misspelt member (`uTime.valeu`) is still an error. It's a deliberate simplification, and it gives up two things. What its own methods return is `any` (TSL functions such as `sin()` or `mix()` still return typed nodes), and nothing checks that an operation fits the uniform's real type: `cross()` wants two vec3s and will take it. Cast once when you want the exact type; a single `as` works, since every member is `any`: ```tsx import type { Color, UniformNode, Vector3 } from 'three/webgpu' const uDir = uniforms.uDir as UniformNode<'vec3', Vector3> const facing = cross(uDir, normalView) // checked as vec3 const uTint = uniforms.uTint as UniformNode<'color', Color> uTint.value.set('red') // .value is a Color ``` > **Feedback wanted.** This loose default is new in the v10 alpha. If it gets in your way, or lets through a mistake you'd want TypeScript to catch, please [open or comment on a GitHub issue](https://github.com/pmndrs/react-three-fiber/issues). `UniformNode` here is three's (``). A schema does the same without a cast: `useUniforms<{ blur: number }>('fx')`, `useUniform('uTint')`, or `uniforms.scope<{ uHealth: UniformNode<'float', number> }>('player')` in a creator. Registering gives exact types everywhere and also catches a misspelt name, which no loose read can. A root read (`useUniforms().x`, `state.uniforms.x`, a creator's `uniforms.x`) may name a scope as well as a uniform, so `state.uniforms.player.uHealth` is loose the same way. Cast the uniform, not the scope. ## Strict or loose By default, reading an unregistered key from the root (`useUniforms()`, `state.uniforms`, a creator's `uniforms`) is a type error. That is what catches typos. If your app creates many uniforms on the fly and reads them from the root elsewhere, opt out: ```ts declare module '@react-three/tsl' { interface Register { uniforms: typeof globalUniforms strict: false } } ``` Registered keys stay fully typed. Unregistered root keys are allowed and read [loose](#what-stays-loose), so a typo compiles. `strict` covers registered [nodes](#register-your-nodes), [buffers and GPU storage](#register-buffers-and-gpu-storage) the same way. ## Register your nodes Nodes register the same way, by their node types. `nodes` holds root-level nodes, `nodeScopes` named scopes: ```ts import type { Node } from 'three/webgpu' import { Fn, sin, vec3 } from 'three/tsl' import type { CreatorState } from '@react-three/tsl' export const rimLightFn = Fn(() => vec3(1, 0.5, 0)) export const sharedNodes = ({ uniforms }: CreatorState) => ({ wobble: sin(uniforms.uTime.mul(2)).toVar(), rimLight: rimLightFn, }) declare module '@react-three/tsl' { interface Register { nodes: ReturnType // or spelled out: { wobble: Node<'float'>; rimLight: typeof rimLightFn } nodeScopes: { fx: { blur: Node<'vec4'> } } } } ``` Then `useNodes().wobble`, `useNodes('fx').blur`, `state.nodes.wobble` and a creator's `nodes.rimLight()` are typed by name, typos on the root are errors (unless `strict: false`), and creators are checked: `useNodes(() => ({ wobble: vec3(1) }))` is an error once `wobble` is registered as a float node. A scope only known at runtime (`useNodes(creator, props.scope)`) is not checked. Unlike uniforms there is no `configureTSL` for nodes: a registered node exists once the component that creates it (`useNodes(sharedNodes)`) has rendered. A component rendered before that reads `undefined`, whatever the type says. Without registration a node read is a loose `LooseNode`, for the same reason a uniform read is a `LooseUniformNode`: it has every member of three's nodes and of an `Fn()`, typed `any`, and can be called, so `nodes.wobble.mul(2)`, `material.colorNode = nodes.wobble` and `nodes.rimLightFn()` compile. One `as` makes it exact: `nodes.blur as Node<'vec4'>`, `nodes.rimLight as typeof rimLightFn`. ## Register buffers and GPU storage `useBuffers` and `useGPUStorage` register the same way: `buffers` / `bufferScopes` and `gpuStorage` / `gpuStorageScopes`, each by the type the hook stores. ```ts import type { StorageBufferNode, StorageTexture } from 'three/webgpu' declare module '@react-three/tsl' { interface Register { buffers: { positions: StorageBufferNode<'vec3'>; seeds: Float32Array } bufferScopes: { particles: { colors: StorageBufferNode<'vec4'> } } gpuStorage: { heightMap: StorageTexture } gpuStorageScopes: { terrain: { normals: StorageTexture } } } } ``` Then `useBuffers().positions.element(instanceIndex)`, `useBuffers('particles').colors` (the scope name autocompletes), `state.buffers.seeds[0]`, `texture(useGPUStorage().heightMap)` and a creator's `buffers` / `gpuStorage` are typed by name, root typos are errors (unless `strict: false`), and creators are checked: `useBuffers(() => ({ positions: new Float32Array(12) }))` is an error once `positions` is registered as a buffer node. A scope only known at runtime is not checked. As with nodes, a registered entry exists only once the component that creates it has rendered. Unregistered reads are not loose here. A read is the union of what the hook stores (`BufferLike`: typed arrays, buffer attributes and buffer nodes; `StorageLike`: storage textures and nodes), since a CPU array and a GPU buffer node have little in common to make loose. Narrow it with one `as` (`buffers.positions as StorageBufferNode<'vec3'>`) or a schema (`useBuffers<{ positions: StorageBufferNode<'vec3'> }>('particles')`). With `strict: false`, an unregistered root key reads as that union too. ## configureTSL `Register` only describes types. `configureTSL` makes them true at runtime: it creates the uniforms on every primary canvas's `RootState`, including canvases already mounted, before any component runs. Secondaries and portals see them like any shared uniform. - A hook that declares the same name later gets the configured node, not a new one. - Calling it again adds to the configuration. Uniforms that already exist are never replaced. - It is optional. Without it, a registered uniform only exists once some component creates it, so a read before that returns `undefined` even though its type says otherwise. Pass the same objects you registered, so the types and the runtime come from one place. ## Notes - `Register` is global to your TypeScript program, like any module augmentation. Declare it once, with every resource family you register in the same interface. - Each family is independent: registering nodes leaves uniforms loose, and so on. `strict` applies to every family you register. ]]>

``` The primary creates the `WebGPURenderer`; each other canvas borrows it and draws into its own `

({ wobble: sin(time.mul(2)), // change to mul(5), save, see the update })) const { uColor } = useUniforms({ uColor: '#ff0000', // change the color, save, see the update }) ``` ## What Rebuilds on HMR Every TSL hook re-runs when the HMR version is bumped: | Hook | Rebuilds on HMR | How | | ---------------------------- | --------------- | ----------------------------------- | | `useNodes` / `useLocalNodes` | Yes | Re-runs creator | | `useUniforms` / `useUniform` | Yes | Re-runs creator | | `useBuffers` | Yes | Re-runs creator | | `useGPUStorage` | Yes | Re-runs creator | | `useRenderPipeline` | Yes | Re-runs callbacks, keeps scene pass | `useLocalNodes` also rebuilds because it subscribes to the HMR version directly, alongside its `uniforms`/`nodes`/`textures` triggers - in every mode, including `useLocalNodes(creator, [])`. The dependency array only governs ordinary component renders (see [TSL Hooks](./tsl-hooks#dependency-array)). ## Rebuild Guarantees A rebuild — whether from a hot update or a manual `rebuild*` call — is **atomic** from a reader's point of view: - The shared maps are never emptied. Readers keep the previous generation of nodes/uniforms until the re-run creators commit the new one, then see a single swap from old-complete to new-complete. A reader can never observe an empty or half-rebuilt scope (which would strip `*Node` props off materials mid-reload). - Creators never write to the store during render. New entries are registered in React's commit phase, so a rebuild can't interrupt other components mid-render. - Reuse is generation-aware. After an invalidation, previously cached entries can't be re-adopted into the new generation — every creator produces fresh resources, no matter how re-runs interleave (StrictMode double-invokes, multiple canvases sharing a `primaryStore`, and so on). Two consequences worth knowing: - **Removed creators leave their last generation in place.** If an edit deletes a creator component (or a whole scope), the old entries stay visible to readers until something re-registers the scope or you call `clearNodes`/`removeNodes`. During a hot reload, last-good data beats an empty scene. - **Captured references go stale across rebuilds.** A rebuild replaces uniform/node objects. Code that reads through the hooks each render picks up the new generation automatically, but a long-lived closure that captured a uniform object directly (for example a `useFrame` callback or an external library callback holding `uTime` from an old generation) keeps writing to the replaced object. Prefer reading through the hook, or re-capture inside the component so the closure refreshes with the rebuild. ## Effects Must Be Re-Run Safe Fast Refresh re-runs your components' effects on every hot update, while R3F's reconciler correctly keeps the underlying three.js objects alive. An effect that mutates a reconciler-managed object must therefore be idempotent: ```tsx // ❌ accumulates 90° per hot update — after one edit the plane faces away useEffect(() => { geometryRef.current?.rotateX(-Math.PI / 2) }, []) // ✅ guard per instance, safe to re-run useEffect(() => { const geometry = geometryRef.current if (geometry && !geometry.userData.rotated) { geometry.userData.rotated = true geometry.rotateX(-Math.PI / 2) } }, []) ``` Where possible, prefer declarative props (`rotation` on the mesh) or bake transforms at creation time instead of mutating in effects. ## useRenderPipeline on HMR `useRenderPipeline` re-runs its `setupCB`/`mainCB` after every hot update in the app, once the other TSL hooks have registered their fresh generation, so the graph picks up both your edits and the new uniform objects. It keeps the pipeline and scene pass and replaces only the graph built on them. The remount Fast Refresh does on the owning component keeps the pipeline too; a reset of that component (after adding or removing a hook, or `// @refresh reset`) builds a new pipeline and frees the old one. To re-run the callbacks yourself, against a fresh scene pass, call `rebuild()`: ```tsx function RebuildButton() { const { rebuild } = useRenderPipeline() return } ``` For values that change at runtime, drive them through uniforms rather than closure values. See [Render Pipeline](./render-pipeline#hmr). ## Disabling HMR If you need to turn off automatic refresh (rare), use the `hmr` prop: ```tsx

``` ## Manual Rebuild Each creator hook returns a `rebuild*` util that invalidates its cache and bumps the HMR version to force re-creation (with the same atomic-swap guarantees as automatic HMR). Pass a scope name to rebuild a single scope, `'root'` for root only, or no argument for everything. Other scopes are untouched — their entries keep their identity. ```tsx const { rebuildNodes } = useNodes(() => ({ wobble: sin(time.mul(2)) })) const { rebuildUniforms } = useUniforms({ uColor: '#ff0000' }) const { rebuildBuffers } = useBuffers(() => ({ positions: instancedArray(count, 'vec3') })) const { rebuildStorage } = useGPUStorage(() => ({ heightMap: new StorageTexture(512, 512) })) rebuildNodes() // all nodes rebuildNodes('player') // only the 'player' scope rebuildUniforms() rebuildBuffers('particles') rebuildStorage() ``` ## Global Rebuild Functions For custom HMR handlers or dev tooling, standalone rebuild functions are exported. They require the R3F store reference: ```tsx import { rebuildAllNodes, rebuildAllUniforms, rebuildAllBuffers, rebuildAllStorage } from '@react-three/tsl' rebuildAllNodes(store) rebuildAllUniforms(store) rebuildAllBuffers(store) rebuildAllStorage(store) ``` ## Reader Reactivity Reader-mode hooks subscribe to store changes, so they update reactively when nodes/uniforms change elsewhere (including after an HMR-triggered rebuild): ```tsx const allNodes = useNodes() const playerNodes = useNodes('player') const allUniforms = useUniforms() const playerUniforms = useUniforms('player') ``` ## Related - [TSL Hooks](./tsl-hooks) - the `rebuild*` utils on each hook - [Render Pipeline](./render-pipeline) - why pipeline callbacks skip HMR - [Compute (Buffers & Storage)](./compute) - rebuild for buffers and storage ]]> { console.log(inView ? 'Object entered view' : 'Object left view') }}> ) } ``` Useful for pausing animations off-screen, lazy-loading heavy resources, or analytics on what users actually see. ### onOccluded — occlusion queries (WebGPU only) Fires when the object becomes occluded or revealed, based on GPU occlusion queries. This only works with the WebGPU renderer. ```tsx function OcclusionAwareObject() { return ( { console.log(occluded ? 'Object is hidden behind something' : 'Object is visible') }}> ) } ``` When you attach `onOccluded` (or `onVisible`), R3F automatically sets `occlusionTest = true` on the object and enables the occlusion system for the canvas. On a WebGL renderer a one-time warning is logged and the occlusion events simply never fire. ### onVisible — combined visibility Fires when the _combined_ visibility state changes. An object is considered visible when **all** of the following are true: - it is within the camera frustum, **and** - it is not occluded (WebGPU only — on WebGL it is always treated as not occluded), **and** - its `visible` property is `true`. ```tsx function FullyVisibleObject() { return ( { if (visible) { // start expensive animations, load high-res textures, etc. } else { // pause animations, reduce quality, etc. } }}> ) } ``` ## The camera frustum R3F keeps a `THREE.Frustum` on the root state, synchronized with the default camera. The visibility events above use it internally, but you can read it directly from `useThree` for custom logic. ```tsx import { useThree } from '@react-three/fiber' function VisibilityCheck() { const frustum = useThree((state) => state.frustum) // point test if (frustum.containsPoint(new THREE.Vector3(0, 5, 0))) { // point is in view } // object test (bounding sphere) if (frustum.intersectsObject(mesh)) { // object is at least partially visible } // sphere test if (frustum.intersectsSphere(boundingSphere)) { // sphere intersects frustum } } ``` ### In the frame loop The frustum is updated automatically each frame — after all `update`-phase callbacks and before `render` — so it is safe to read inside `useFrame`: ```tsx useFrame(({ frustum }) => { for (const object of objects) { object.visible = frustum.intersectsObject(object) } }) ``` ## autoUpdateFrustum By default R3F refreshes the frustum every frame. If you don't need it, or want to drive updates yourself, disable it on the `Canvas`: ```tsx

``` | Canvas prop | Type | Default | Description | | ------------------- | --------- | ------- | ---------------------------------------- | | `autoUpdateFrustum` | `boolean` | `true` | Enable/disable automatic frustum updates | The matching `autoUpdateFrustum` and `frustum` values are also available on the root state via `useThree`. ### Manual frustum updates The `updateFrustum` utility is exported for manual control. Passing an existing frustum updates it in place (no allocation); omitting it returns a new one. ```tsx import { updateFrustum } from '@react-three/fiber' // signature: updateFrustum(camera, frustum?) => THREE.Frustum // update an existing frustum in place updateFrustum(camera, existingFrustum) // create a new frustum from a camera const newFrustum = updateFrustum(camera) // works with any camera — e.g. a shadow or portal camera updateFrustum(light.shadow.camera, shadowFrustum) ``` ## Performance & implementation notes - Events fire on state changes only, not every frame. - Frustum checks rely on bounding spheres; geometry without a computed `boundingSphere` is computed on first check. - The visibility scan runs in the `preRender` phase, after frustum updates. - Objects are unregistered automatically when they unmount. - When occlusion is enabled, R3F adds an invisible internal helper group named `__r3fInternal` to the scene, containing a tiny observer mesh that caches `isOccluded()` results during the render pass (WebGPU's `isOccluded()` only returns valid results while rendering). Both are invisible, carry a `__r3fInternal` flag, and are cleaned up on unmount — relevant only if you are counting scene children. ]]> { const cam = new THREE.PerspectiveCamera() someGroup.add(cam) // you parented it yourself return cam }, []) // camera stays parented to someGroup — R3F won't move it return

} ``` ## Parenting objects under the camera You can imperatively add to the camera, but remember to clean up: ```tsx function HUD() { const { camera } = useThree() const hudRef = useRef(null) useEffect(() => { const hud = hudRef.current if (!hud) return camera.add(hud) return () => void camera.remove(hud) }, [camera]) return ( ) } ``` The declarative `Portal` component below is usually cleaner. ## The Portal component `Portal` renders its children into any `Object3D` container — the camera, a group, or any other scene object — and handles mounting and cleanup for you. ```tsx import { Portal, useThree } from '@react-three/fiber' function CameraHeadlights() { const { camera } = useThree() return ( ) } ``` `container` accepts an `Object3D` directly or a ref to one. Children are added on mount and disposed on unmount, including internal subscriptions. ## injectScene — how children attach to the container This is the important detail to get right. By default `Portal` does **not** add your children directly to the container. It inserts a fresh `THREE.Scene` _under_ the container and renders the children into that scene. So when you ``, your objects become **grand-children** of the camera: ``` camera → (injected THREE.Scene) → your children ``` This default exists so that `state.scene` inside the portal is always a real `THREE.Scene`, which means scene-only properties like `background`, `environment`, and `fog` keep working inside the portal ([#2725](https://github.com/pmndrs/react-three-fiber/issues/2725)). The injection is controlled by `injectScene`, which defaults to `true` and is passed through the Portal's `state` prop: ```tsx // default — injectScene is true {/* rendered into an injected THREE.Scene that is a child of the camera */} ``` > Note: if the `container` you pass is itself already a `THREE.Scene`, no extra scene is injected — the container is used directly. ### injectScene= — direct camera children When you specifically need your objects to be _direct_ children of the camera (for example a light whose transform must be exactly the camera's, with no intermediate node), set `injectScene: false` in the portal `state`: ```tsx {/* rendered directly as children of the camera — no injected scene */} ``` With `injectScene={false}` the hierarchy is simply: ``` camera → your children ``` This is treated as an edge-case "anti-pattern" in the source because the portal's `state.scene` is then the container itself rather than a real `THREE.Scene` (so scene-level properties like `background`/`environment`/`fog` won't apply). Use it only when you genuinely need direct parenting. > In practice the default `injectScene={true}` is what you want for HUDs and overlays — the extra scene node is harmless for transforms since it sits at the camera's origin. Reach for `injectScene={false}` only when the intermediate scene is a problem. ]]> { renderer.setRenderTarget(fbo) renderer.render(scene, camera) renderer.setRenderTarget(null) }) return ( ) } ``` ## Argument forms The hook accepts several patterns. With no size, it uses the canvas dimensions (and resizes with the canvas). ```tsx // canvas size (resizes with canvas) const fbo = useRenderTarget() // canvas size with options const fbo = useRenderTarget({ samples: 4 }) // square render target (512×512) const fbo = useRenderTarget(512) // square render target with options const fbo = useRenderTarget(512, { depthBuffer: true }) // explicit dimensions const fbo = useRenderTarget(512, 256) // explicit dimensions with options const fbo = useRenderTarget(512, 256, { samples: 4 }) ``` ### Signatures ```ts // canvas size (defaults to canvas dimensions) useRenderTarget(options?: RenderTargetOptions): R3FRenderTarget // square render target useRenderTarget(size: number, options?: RenderTargetOptions): R3FRenderTarget // explicit dimensions useRenderTarget(width: number, height: number, options?: RenderTargetOptions): R3FRenderTarget ``` The return type `R3FRenderTarget` is `WebGLRenderTarget | RenderTarget` on `@react-three/fiber`, and narrows to the one class once the app registers its renderer or imports from a single-renderer entry (see [Per-renderer type](#per-renderer-type) below). ## Options | Option | Type | Default | Description | | ----------------- | --------- | ------------------ | ------------------------- | | `depthBuffer` | `boolean` | `true` | Create depth buffer | | `stencilBuffer` | `boolean` | `false` | Create stencil buffer | | `samples` | `number` | `0` | MSAA sample count | | `count` | `number` | `1` | MRT target count (WebGPU) | | `format` | `number` | `RGBAFormat` | Texture format | | `type` | `number` | `UnsignedByteType` | Data type | | `minFilter` | `number` | `LinearFilter` | Minification filter | | `magFilter` | `number` | `LinearFilter` | Magnification filter | | `generateMipmaps` | `boolean` | `false` | Generate mipmaps | ## Per-renderer type The class you get back follows the renderer the Canvas loaded: a `WebGLRenderTarget` on WebGL, a `RenderTarget` on WebGPU. The hook constructs the target class carried by the root's renderer support (`state.internal.support.RenderTarget`), so it is always valid for the renderer in use without branching yourself. Only the declared type differs: - **`@react-three/fiber`**: `WebGLRenderTarget | RenderTarget` (either renderer can be running). Register the renderer once and it narrows, with no cast, along with `state.renderer` and the rest (see [Typing the renderer](../API/typescript#typing-the-renderer)): ```ts declare module '@react-three/fiber' { interface Register { renderer: 'webgpu' // or 'webgl' } } ``` - **`@react-three/fiber/legacy`**: `WebGLRenderTarget`. - **`@react-three/fiber/webgpu`** (deprecated): `RenderTarget`. ]]> ``` ### Triggering manual frames One major caveat is that if anything in the tree _mutates_ props, then React cannot be aware of it and the display would be stale. For instance, camera controls just grab into the camera and mutate its values. Here you can use React Three Fiber's `invalidate` function to trigger frames manually. ```jsx function Controls() { const orbitControlsRef = useRef() const { invalidate, camera, renderer } = useThree() useEffect(() => { orbitControlsRef.current.addEventListener('change', invalidate) return () => orbitControlsRef.current.removeEventListener('change', invalidate) }, []) return ``` > \[!NOTE] Drei's controls do this automatically for you. Generally you can call invalidate whenever you need to render: ```jsx invalidate() ``` > \[!IMPORTANT] Calling `invalidate()` will not render immediately, it merely requests a new frame to be rendered out. Calling invalidate multiple times will not render multiple times. Think of it as a flag to tell the system that something has changed. ### Sync animations with on-demand-rendering and invalidate Since `invalidate()` is only a flag that schedules render, you might bump into syncing issues when you run animations that are synchronous (as in, they start immediately). By the time fiber renders the first frame the animation has already progressed which leads to a visible jump. In such cases you should pre-emptively schedule a render and then start the animation in the next frame. ```jsx { // Pre-emptively schedule a render invalidate() // Wait for the next frame to start the animation requestAnimationFrame(() => controls.dolly(1, true)) }} ``` ## Re-using geometries and materials Each geometry and material means additional overhead for the GPU. You should try to re-use resources if you know they will repeat. You could do this globally: ```jsx const red = new THREE.MeshLambertMaterial({ color: "red" }) const sphere = new THREE.SphereGeometry(1, 28, 28) function Scene() { return ( <> ``` If you create a material or color in global space - outside of React Three Fiber's `Canvas` context - you should enable [ColorManagement](https://threejs.org/docs/#manual/en/introduction/Color-management) in three.js. This will allow certain conversions (for hexadecimal and CSS colors in sRGB) to be made automatically, producing correct colors in all cases. ```jsx import * as THREE from 'three' // r150 THREE.ColorManagement.enabled = true // r139-r149 THREE.ColorManagement.legacyMode = false ``` ### Caching with `useLoader` > \[!NOTE] Every resource that is loaded with useLoader is cached automatically! If you access a resource via useLoader with the same URL, throughout the component tree, then you will always refer to the same asset and thereby re-use it. This is especially useful if you run your GLTF assets through [GLTFJSX](https://github.com/pmndrs/gltfjsx) because it links up geometries and materials and thereby creates re-usable models. [CodeSandbox dix1y](https://codesandbox.io/s/dix1y) ```jsx function Shoe(props) { const { nodes, materials } = useLoader(GLTFLoader, "/shoe.glb") return ( ) } ``` ## Instancing Each mesh is a draw call, you should be mindful of how many of these you employ: no more than 1000 as the very maximum, and optimally a few hundred or less. You can win performance back by reducing draw calls, for example by instancing repeating objects. This way you can have hundreds of thousands of objects in a single draw call. [CodeSandbox h873k](https://codesandbox.io/s/h873k) Setting up instancing is not so hard, consult [the three.js docs](https://threejs.org/docs/#api/en/objects/InstancedMesh) if you need help. ```jsx function Instances({ count = 100000, temp = new THREE.Object3D() }) { const instancedMeshRef = useRef() useEffect(() => { // Set positions for (let i = 0; i < count; i++) { temp.position.set(Math.random(), Math.random(), Math.random()) temp.updateMatrix() instancedMeshRef.current.setMatrixAt(i, temp.matrix) } // Update the instance instancedMeshRef.current.instanceMatrix.needsUpdate = true }, []) return ( ) } ``` ## Level of detail Sometimes it can be beneficial to reduce the quality of an object the further it is away from the camera. Why would you display it full resolution if it is barely visible. This can be a good strategy to reduce the overall vertex-count which means less work for the GPU. Scroll in and out to see the effect: [CodeSandbox 12nmp](https://codesandbox.io/s/12nmp) There is a small component in Drei called `` which sets up LOD without boilerplate. You load or prepare a couple of resolution stages, as many as you like, and then give them the same amount of distances from the camera, starting from highest quality to lowest. ```jsx import { Detailed, useGLTF } from '@react-three/drei' function Model() { const [low, mid, high] = useGLTF(["/low.glb", "/mid.glb", "/high.glb"]) return ( ) } ``` ## Nested loading Nested loading means that lesser textures and models are loaded first, higher-resolution later. The following sandbox goes through three loading stages: - A loading indicator - Low quality - High quality [CodeSandbox 7duy8](https://codesandbox.io/s/7duy8) And this is how easy it is to achieve it, you can nest suspense and even use it as a fallback: ```jsx function App() { return ( loading...}>

) } function Model({ url }) { const { scene } = useGLTF(url) return } ``` ## Performance monitoring Drei has a new component [PerformanceMonitor](https://github.com/pmndrs/drei#performancemonitor) that allows you to monitor, and adapt to, device performance. This component will collect the average fps (frames per second) over time. If after a couple of iterations the averages are below or above a threshold it will trigger onIncline and onDecline callbacks that allow you to respond. Typically you would reduce the quality of your scene, the resolution, effects, the amount of stuff to render, or, increase it if you have enough framerate to fill. Since this would normally cause ping-ponging between the two callbacks you define upper and lower framerate bounds, as long as you stay within that margin nothing will trigger. Ideally your app should find its way into that margin by gradually altering quality. A simple example for regulating the resolution. It starts out with 1.5, if the system falls below the bounds it goes to 1, if it's fast enough it goes to 2. ```jsx function App() { const [dpr, setDpr] = useState(1.5) return (

The most important gotcha in three.js is that creating objects can be expensive, think twice before you mount/unmount things! Every material or light that you put into the scene has to compile, every geometry you create will be processed. Share materials and geometries if you can, either in global scope or locally: ```jsx const geom = useMemo(() => new BoxGeometry(), []) const mat = useMemo(() => new MeshBasicMaterial(), []) return items.map(i => { const interval = setInterval(() => setX((x) => x + 0.1), 1) return () => clearInterval(interval) }, []) ``` ### ❌ `setState` in useFrame is bad ```jsx const [x, setX] = useState(0) useFrame(() => setX((x) => x + 0.1)) return ``` ### ❌ `setState` in fast events is bad ```jsx setX((x) => e.point.x)} /> ``` ### ✅ Instead, just mutate, use deltas In general you should prefer useFrame. Consider mutating props safe as long as the component is the only entity that mutates. Use deltas instead of fixed values so that your app is refresh-rate independent and runs at the same speed everywhere! ```jsx const meshRef = useRef() useFrame((state, delta) => (meshRef.current.position.x += delta)) return ``` Same goes for events, use references. ```jsx (ref.current.position.x = e.point.x)} /> ``` If you must use intervals, use references as well, but keep in mind that this is not refresh-rate independent. ```jsx useEffect(() => { const interval = setInterval(() => ref.current.position.x += 0.1, 1) return () => clearInterval(interval) }, []) ``` ## Handle animations in loops The frame loop is where you should place your animations. For instance using lerp, or damp. ### ✅ Use `lerp` + `useFrame` ```jsx function Signal({ active }) { const meshRef = useRef() useFrame((state, delta) => { meshRef.current.position.x = THREE.MathUtils.lerp(meshRef.current.position.x, active ? 100 : 0, 0.1) }) return ``` ### ✅ Or react-spring Or, use animation libraries. React-spring has its own frame-loop and animates outside of React. Framer-motion is another popular alternative. ```jsx import { a, useSpring } from '@react-spring/three' function Signal({ active }) { const { x } = useSpring({ x: active ? 100 : 0 }) return ``` ## Do not bind to fast state reactively Using state-managers and selective state is fine, but not for updates that happen rapidly for the same reason as above. ### ❌ Don't bind reactive fast-state ```jsx import { useSelector } from 'react-redux' // Assuming that x gets animated inside the store 60fps const x = useSelector((state) => state.x) return ``` ### ✅ Fetch state directly For instance using [Zustand](https://github.com/pmndrs/zustand) (same in Redux et al). ```jsx useFrame(() => (ref.current.position.x = api.getState().x)) return ``` ## Don't mount indiscriminately In threejs it is very common to not re-mount at all, see the ["disposing of things"](https://discoverthreejs.com/tips-and-tricks/) section in discover-three. This is because buffers and materials get re-initialized/compiled, which can be expensive. ### ❌ Avoid mounting runtime ```jsx { stage === 1 && } { stage === 2 && } { stage === 3 && } ``` ### ✅ Consider using visibility instead ```jsx function Stage1(props) { return ( ... ``` ### ✅ Use `startTransition` for expensive ops React 18 introduces the `startTransition` and `useTransition` APIs to defer and schedule work and state updates. Use these to de-prioritize expensive operations. Since version 8 of Fiber canvases use concurrent mode by default, which means React will schedule and defer expensive operations. You don't need to do anything, but you can play around with the [experimental scheduler](https://github.com/drcmda/scheduler-test) and see if marking ops with a lesser priority makes a difference. ```jsx import { useTransition } from 'react' import { Points } from '@react-three/drei' const [isPending, startTransition] = useTransition() const [radius, setRadius] = useState(1) const positions = calculatePositions(radius) const colors = calculateColors(radius) const sizes = calculateSizes(radius) { startTransition(() => { setRadius(prev => prev + 1) }) }} > ``` ## Don't re-create objects in loops Try to avoid creating too much effort for the garbage collector, re-pool objects when you can! ### ❌ Bad news for the GC This creates a new vector 60 times a second, which allocates memory and forces the GC to eventually kick in. ```jsx useFrame(() => { ref.current.position.lerp(new THREE.Vector3(x, y, z), 0.1) }) ``` ### ✅ Better re-use object Set up re-used objects in global or local space, now the GC will be silent. ```jsx function Foo(props) const vec = new THREE.Vector() useFrame(() => { ref.current.position.lerp(vec.set(x, y, z), 0.1) }) ``` ## `useLoader` instead of plain loaders Threejs loaders give you the ability to load async assets (models, textures, etc), but if you do not re-use assets it can quickly become problematic. ### ❌ No re-use is bad for perf This re-fetches, re-parses for every component instance. ```jsx function Component() { const [texture, set] = useState() useEffect(() => void new TextureLoader().load(url, set), []) return texture ? ( ) : null } ``` Instead use useLoader, which caches assets and makes them available throughout the scene. ### ✅ Cache and re-use objects ```jsx function Component() { const texture = useLoader(TextureLoader, url) return ( ) } ``` Regarding GLTF's try to use [GLTFJSX](https://github.com/pmndrs/gltfjsx) as much as you can, this will create immutable JSX graphs which allow you to even re-use full models. ]]> \[!TIP] Looking to upgrade to the latest version? See the [v10 Migration Guide](/next/migration/v10) for WebGPU support and the new scheduler. This is a compatibility release for React 19, which brings further performance, stability, and type improvements. You can check out the React 19 changelog [here](https://react.dev/blog/2024/04/25/react-19). We would like to express our gratitude to the community for their continued support, as well as to all our contributors, including the React team at Meta and Vercel, for ensuring this upgrade went smoothly. 🎉 > \[!WARNING]\ > This release contains breaking changes when using Strict Mode, which can highlight bugs during development. See [StrictMode](#strictmode). ## Features ### useLoader Accepts Loader Instance `useLoader` now supports re-use of external loader instances for more controlled pooling and setup. ```jsx import { GLTFLoader } from 'three/addons' import { useLoader } from '@react-three/fiber' function Model() { const gltf = useLoader(GLTFLoader, '/path/to/model.glb') // ... } // or, const loader = new GLTFLoader() function Model() { const gltf = useLoader(loader, '/path/to/model.glb') // ... } ``` ### Factory extend Signature `extend` can now produce a component when a three.js class is passed to it individually instead of a catalog of named classes. This is backwards compatible and reduces TypeScript boilerplate and JSX collisions. We recommend libraries migrate to this signature so internal components don't clash with user-land declarations. ```tsx import { OrbitControls } from 'three/addons' import { type ThreeElement, type ThreeElements } from '@react-three/fiber' declare module '@react-three/fiber' { interface ThreeElements { orbitControls: ThreeElement } } extend({ OrbitControls }) // or, const Controls = extend(OrbitControls) ``` ### Async GL prop The Canvas GL prop accepts constructor parameters, properties, or a renderer instance via a callback. The callback now passes constructor parameters instead of just a canvas reference. ```diff

console.log('click')} onContextMenu={(e) => console.log('context menu')} onDoubleClick={(e) => console.log('double click')} onWheel={(e) => console.log('wheel spins')} onPointerUp={(e) => console.log('up')} onPointerDown={(e) => console.log('down')} onPointerOver={(e) => console.log('over')} onPointerOut={(e) => console.log('out')} onPointerEnter={(e) => console.log('enter')} onPointerLeave={(e) => console.log('leave')} onPointerMove={(e) => console.log('move')} onPointerMissed={() => console.log('missed')} /> ``` From this we can see that what we need to do is use the old `onClick` event we use on any DOM element to react to a user clicking the mesh. Let's add it then: ```jsx alert('Hellooo')}> ``` We did it! We created the most boring interaction in the story of 3D and we made an alert show up. Now let's make it actually animate our mesh. Let's start by setting some state to check if the mesh is active: ```jsx const [active, setActive] = useState(false) ``` After we have this we can set the scale with a ternary operator like so: ```jsx setActive(!active)}> ``` If you try to click on your mesh now, it scales up and down. We just made our first interactive 3D mesh! What we did in this chapter was: - Attached a click handler to our mesh - Added some state to track if the mesh is currently active - Changed the scale based on that state [CodeSandbox 98ppy](https://codesandbox.io/s/98ppy) **Exercises** - Change other props of the mesh like the `position` or even the `color` of the material. - Use `onPointerOver` and `onPointerOut` to change the props of the mesh on hover events. ## Next steps We just made our mesh react to user interaction but it looks pretty bland without any transition, right? In the next chapter let's integrate `react-spring` into our project to make this into an actual animation. ]]> All the models in this page were created by Sara Vieira and are freely available to download from any of the sandboxes. There are many types of 3D model extensions, in this page we will focus on loading the three most common ones: `GLTF`, `FBX` and `OBJ`. All of these will use the `useLoader` function but in slightly different ways. This whole section will assume you have placed your models in the public folder or in a place in your application where you can import them easily. ## Loading GLTF models Starting with the open standard and the one that has more support in React Three Fiber we will load a `.gltf` model. Let's start by importing the two things we need: ```js import { useLoader } from '@react-three/fiber' import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js' ``` With this we can create a Model component and place it in our scene like so: ```jsx function Scene() { const gltf = useLoader(GLTFLoader, '/Poimandres.gltf') return } ``` You can play with the sandbox and see how it looks here after I added an HDRI background: [CodeSandbox 6etx1](https://codesandbox.io/s/6etx1) ### Loading GLTF models as JSX Components Here comes the really fancy part, you can transform these models into React components and then use them as you would any React component. To do this, grab your `GLTF` model and head over to and drop your `GLTF`, after that you should see something like: ![gltfjsx](https://github.com/pmndrs/react-three-fiber/raw/v10/docs/tutorials/gltfjsx.png) Let's now copy the code and move it over to `Model.js`: ```jsx /* Auto-generated by: https://github.com/pmndrs/gltfjsx */ import React, { useRef } from 'react' import { useGLTF } from '@react-three/drei' export default function Model(props) { const groupRef = useRef() const { nodes, materials } = useGLTF('/Poimandres.gltf') return ( ) } useGLTF.preload('/Poimandres.gltf') ``` Now we can import our model like we would import any React component and use it in our app: ```jsx import { Suspense } from 'react' import { Canvas } from '@react-three/fiber' import { Environment } from '@react-three/drei' import Model from './Model' export default function App() { return (

) } ``` You can play with the sandbox here: [CodeSandbox vbnbf](https://codesandbox.io/s/vbnbf) ## Loading OBJ models In this case, we will use the trusted `useLoader` hook but in combination with `three.js` `OBJLoader`. ```js import { OBJLoader } from 'three/addons/loaders/OBJLoader.js' import { useLoader } from '@react-three/fiber' ``` With these imported let's get the mesh into our scene: ```jsx function Scene() { const obj = useLoader(OBJLoader, '/Poimandres.obj') return } ``` And here we go, we have an OBJ model showing on the web! Pretty cool ah? You can play with the sandbox here: [CodeSandbox 51zks](https://codesandbox.io/s/51zks) ## Loading FBX models Let's again use the trusted `useLoader` but this time with the `FBXLoader` that comes from `three.js` ```js import { useLoader } from '@react-three/fiber' import { FBXLoader } from 'three/addons/loaders/FBXLoader.js' ``` To create our scene we can get the FBX as a return value of `useLoader` by passing `FBXLoader` and the location of our file like so: ```jsx function Scene() { const fbx = useLoader(FBXLoader, '/Poimandres.fbx') return } ``` You can play with the sandbox here: [CodeSandbox ssrfg](https://codesandbox.io/s/ssrfg) ### Loading FBX models using `useFBX` [@react-three/drei](https://github.com/pmndrs/drei) exports a very useful helper when it comes to loading FBX models and it's called `useFBX`, in this case there is no need to import anything from `three.js` as it is all done behind the scenes and we can just pass the location of the file to `useFBX` like so: ```jsx function Scene() { const fbx = useFBX('/Poimandres.fbx') return } ``` You can play with the sandbox here: [CodeSandbox m6p73](https://codesandbox.io/s/m6p73) ## Showing a loader If your model is big and takes a while to load, it's always good to show a small loader of how much is already is loaded and again [@react-three/drei](https://github.com/pmndrs/drei) is here to help with `Html` and `useProgress`. - `Html` allows you place plain ol' HTML in your canvas and render it like you would a normal DOM element. - `useProgress` is a hook that gives you a bunch of information about the loading status of your model. With these two things, we can create a very bare-bones loading component like so: ```jsx import { Html, useProgress } from '@react-three/drei' function Loader() { const { progress } = useProgress() return {progress} % loaded } ``` We can then wrap our model in it using `Suspense` like so: ```jsx export default function App() { return (

) } ``` The hook returns much more than just the progress so there is a lot you can do there to give the user more information about the loading status of the application. You can play with all of them in this sandbox: [CodeSandbox nn2m7](https://codesandbox.io/s/nn2m7) ]]> All textures used in this chapter were downloaded from [ambientCG](https://ambientcg.com/) (formerly cc0textures). ## Using `TextureLoader` and `useLoader` To load the textures we will use the `TextureLoader` from three.js in combination with `useLoader` that will allow us to pass the location of the texture and get the map back. It's better to explain with code, let's say you downloaded [this texture](https://ambientcg.com/view?id=PavingStones092) and placed it in the public folder of your site, to get the color map from it you could do: ```js const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg') ``` Let's then with this information create a small scene where we can use this texture: ```jsx import { Suspense } from 'react' import { Canvas, useLoader } from '@react-three/fiber' import { TextureLoader } from 'three' function Scene() { const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg') return ( <> ) } export default function App() { return (

) } ``` If everything went according to plan, you should now be able to apply this texture to the sphere like so: ```jsx ``` Awesome! That works but we have a lot more textures to import and do we have to create a different useLoader for each of them? That's the great part! You don't, the second argument is an array where you can pass all the textures you have and the maps will be returned and ready to use: ```js const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [ 'PavingStones092_1K_Color.jpg', 'PavingStones092_1K_Displacement.jpg', 'PavingStones092_1K_Normal.jpg', 'PavingStones092_1K_Roughness.jpg', 'PavingStones092_1K_AmbientOcclusion.jpg', ]) ``` Now we can place them in our mesh like so: ```jsx ``` The displacement will probably be too much, usually setting it to 0.2 will make it look good. Our final code would look something like: ```jsx function Scene() { const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [ 'PavingStones092_1K_Color.jpg', 'PavingStones092_1K_Displacement.jpg', 'PavingStones092_1K_Normal.jpg', 'PavingStones092_1K_Roughness.jpg', 'PavingStones092_1K_AmbientOcclusion.jpg', ]) return ( {/* Width and height segments for displacementMap */} ) } ``` ## Using `useTexture` In v10, `useTexture` is built into `@react-three/fiber`, so there is no need to import `TextureLoader` or install drei for this hook. The same textures can be loaded with: ```js import { useTexture } from '@react-three/fiber' ... const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useTexture([ 'PavingStones092_1K_Color.jpg', 'PavingStones092_1K_Displacement.jpg', 'PavingStones092_1K_Normal.jpg', 'PavingStones092_1K_Roughness.jpg', 'PavingStones092_1K_AmbientOcclusion.jpg', ]) ``` The `useTexture` hook from [`@react-three/drei`](https://github.com/pmndrs/drei) still works, but is not required for v10. You can also use object-notation which is the most convenient: ```jsx const props = useTexture({ map: 'PavingStones092_1K_Color.jpg', displacementMap: 'PavingStones092_1K_Displacement.jpg', normalMap: 'PavingStones092_1K_Normal.jpg', roughnessMap: 'PavingStones092_1K_Roughness.jpg', aoMap: 'PavingStones092_1K_AmbientOcclusion.jpg', }) return ( ) ``` You can play with the sandbox and see how it looks: [CodeSandbox rusfd](https://codesandbox.io/s/rusfd) ## The texture registry with `useTextures` In v10, `useTexture` is built into `@react-three/fiber` and, by default, enrolls what it loads into a global texture registry. `useTextures()` lets you reach those textures from anywhere and manage their GPU lifetime, without threading refs through your component tree. See [Textures](/next/webgpu/textures) for the registry API, the `cache` option, refcounted disposal, and when the registry is reactive. ]]> ` parent**! ```jsx import { useFrame } from '@react-three/fiber' function MyAnimatedBox() { useFrame(() => { console.log("Hey, I'm executing every frame!") }) return ( ) } ``` This loop is the basic building block of our animation, the callback we pass to `useFrame` will be executed every frame and it will be passed an object containing the state of our Fiber scene: For example, we can read timing information directly off the state to know how much time has elapsed in our application, and use that to animate a value: ```jsx useFrame((state) => { const a = state.elapsed console.log(a) // the value will be ~0 at scene initialization and grow each frame }) ``` `state.elapsed` is the number of seconds since the first frame. The frame state also gives you `state.delta` (seconds since the previous frame), `state.time` (the RAF timestamp), and `state.frame` (frame count) — these replace the old `state.clock` from v9. ## Animating with Refs It would be tempting to just update the state of our component via `setState` and let it change the `mesh` via props, but going through state isn't ideal, when dealing with continuous updates, commonly known as [transient updates](https://zustand.docs.pmnd.rs/guides/updating-state#transient-updates-\(for-often-occurring-state-changes\)). Instead, we want to **directly mutate our mesh each frame**. First, we'll have to get a `reference` to it, via the `useRef` React hook: ```jsx import React from 'react' function MyAnimatedBox() { const myMesh = React.useRef() return ( ) } ``` `myMesh` will now hold a reference to the actual three.js object, which we can now freely mutate in `useFrame`, without having to worry about React: ```jsx useFrame((state) => { myMesh.current.rotation.x = state.elapsed }) ``` Let's have a closer look: - We are reading `elapsed` from the `state` passed to `useFrame`, which we know is the state of our Fiber scene. - We are accessing the `rotation.x` property of `myMesh.current` object, which is a reference to our mesh object - We are assigning our time-dependent value to the `rotation` on the `x` axis, meaning our object will now infinitely rotate around the x axis! [CodeSandbox 29gxw](https://codesandbox.io/s/29gxw) **Exercises** - Try `Math.sin(state.elapsed)` and see how your animation changes ## Next steps Now that you understand the basic technique for animating in Fiber, [learn how event works](/next/tutorials/events-and-interaction)! If you want to go deeper into animations, check these out: - [Animating with React Spring](https://react-spring.dev/docs/getting-started) ]]> ) } ``` In three.js, this is equivalent to: ```js import * as THREE from 'three' const scene = new THREE.Scene() //

**Alpha Release** - v10 is currently in alpha. We'd love your feedback! > > - [Report an issue](https://github.com/pmndrs/react-three-fiber/issues/new?labels=v10) - Found a bug? Let us know > - [Join the discussion](https://github.com/pmndrs/react-three-fiber/discussions) - Questions or ideas > - [Track progress](https://github.com/pmndrs/react-three-fiber/milestones) - See what's coming ## The Short Version **`@react-three/fiber` now renders with WebGPU.** Every `

\[!TIP] `@react-three/eslint-plugin`'s `migration` config finds most of these in your code and fixes many of them with `--fix`: the `gl` and `clock` reads, numeric `useFrame` priorities, removed Canvas props and imports, `onUpdate` and ``. Add `configs.migration` to your `eslint.config.js` (eslintrc: `plugin:@react-three/legacy-migration`) while you upgrade; see the [plugin readme](https://github.com/pmndrs/react-three-fiber/tree/v10/packages/eslint-plugin#migration). ## Renderer and entries | Change | What to do | Since | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | **`@react-three/fiber` renders with WebGPU.** `