# ThreeContext (/docs/api/three-context)





`ThreeContext` is the single runtime object for a scene. It holds the renderer, scene, camera, animation loop, timer, and event bus.

You don't construct `ThreeContext` directly — it's created automatically inside [`ThreeStart`](/docs/api/three-start) and exposed via its [`ctx`](/docs/api/three-start#properties) field.

<Callout type="info">
  Every [`Object3DBehaviour`](/docs/api/object3d-behaviour) and [`ContextModule`](/docs/api/context-module) instance has access to the same context via `this.ctx`.
</Callout>

Properties [#properties]

| Name | Type | Description |
|---|---|---|
| `camera` | `THREE.PerspectiveCamera` | The active camera. Reassigning it swaps the camera used by the scene pass and fires `CameraChanged`. |
| `canvasContainer` | `HTMLDivElement | null` | The HTML element the renderer canvas is currently mounted into, or `null` if not mounted. |
| `isMounted` | `boolean` | `true` while the renderer canvas is attached to a container (between `mount()` and `unmount()`). |
| `isLoopRunning` | `boolean` | `true` while the animation loop is running (between `runLoop()` and `stopLoop()`). |
| `renderer` | `THREE.Renderer` | The Three.js renderer owned by this context. Sealed at construction. |
| `scene` | `THREE.Scene` | The root `Scene` that components and the camera live in. Sealed at construction. |
| `renderPipeline` | `THREE.RenderPipeline` | The render pipeline used by the default render function. Sealed at construction. |
| `scenePass` | `THREE.PassNode` | The scene pass node fed into `renderPipeline`. Attach post-processing effects to it via TSL. |
| `modules` | `ThreeStartModules` | Registered [`ContextModule`](/docs/api/context-module) instances, keyed by name. Read-only at runtime — mutations throw. Populate via `starter.addModules()` before `start()`. |

Methods [#methods]

| Name | Type | Description |
|---|---|---|
| `render` | `() => void` | Render once using the current render function. Fires `RenderBefore` / `RenderAfter`. |
| `overrideRender` | `(fn: () => void) => this` | Replace the render function with a custom implementation. Restore via `resetRender()`. |
| `resetRender` | `() => this` | Restore the default render function (undoes `overrideRender`). |
| `getDeltaTime` | `() => number` | Seconds elapsed since the previous tick, scaled by `timescale`. Use inside per-frame methods. |
| `getTime` | `() => number` | Total elapsed time in seconds since the loop started, scaled by `timescale`. |
| `getTimescale` | `() => number` | Current time-scaling factor. `1` = realtime, `0` = paused, `2` = 2× speed. |
| `setTimescale` | `(value: number) => this` | Change the time-scaling factor applied to `getDeltaTime` / `getTime`. `1` = realtime, `0` = paused. |
| `requestRender` | `() => void` | Schedule a single render on the next animation frame. Coalesces multiple calls within the same frame. |

Events [#events]

`ThreeContext` extends [`TypedEmitter`](/docs/api/typed-emitter) and acts as the central **event bus** of the runtime — subscribe via `ctx.on(...)`, unsubscribe via `ctx.off(...)`. Events are typed by `ThreeContextEventMap` below.

**Emitter methods**

| Name | Type | Description |
|---|---|---|
| `on` | `<K extends ThreeContextEvents>(event: K, fn: (...args: ThreeContextEventMap[K]) => void, context?: any) => this` | Subscribe to an event. See the Events table for available keys and payloads. |
| `once` | `<K extends ThreeContextEvents>(event: K, fn: (...args: ThreeContextEventMap[K]) => void, context?: any) => this` | Subscribe to an event, automatically unsubscribing after it fires once. |
| `off` | `<K extends ThreeContextEvents>(event: K, fn?: (...args: ThreeContextEventMap[K]) => void, context?: any, once?: boolean) => this` | Remove a previously registered listener. Omit `fn` to remove all listeners for the event. |

**Events**

| Event | String key | Args | Description |
|---|---|---|---|
| `ThreeContextEvents.Update` | `"update"` | — | Fired once per animation frame, before `RenderBefore` and rendering. Driver of all per-frame logic. |
| `ThreeContextEvents.RenderBefore` | `"renderbefore"` | — | Fired once per animation frame, just before the scene is rendered. Use to mutate state right before draw. |
| `ThreeContextEvents.RenderAfter` | `"renderafter"` | — | Fired once per animation frame, immediately after the scene is rendered. |
| `ThreeContextEvents.Mount` | `"mount"` | `root: HTMLDivElement` | Fired when `starter.mount(container)` succeeds. Carries the container element. |
| `ThreeContextEvents.Unmount` | `"unmount"` | — | Fired when `starter.unmount()` runs. |
| `ThreeContextEvents.Resized` | `"resized"` | `width: number`, `height: number` | Fired when the canvas container resizes (and once on first mount). Carries the new pixel dimensions. |
| `ThreeContextEvents.CameraChanged` | `"camerachanged"` | `newCamera: THREE.PerspectiveCamera`, `prevCamera: THREE.PerspectiveCamera` | Fired when `ctx.camera` is reassigned. Carries the new and previous cameras. |
| `ThreeContextEvents.LoopRun` | `"looprun"` | — | Fired when `starter.runLoop()` starts the animation loop. |
| `ThreeContextEvents.LoopStop` | `"loopstop"` | — | Fired when `starter.stopLoop()` halts the animation loop. |