Skip to main content

Class: ThreeDScene

Defined in: core/ThreeDScene.ts:74

Scene configured for 3D content. Provides a 3D camera, orbit controls, and lighting setup by default. Compatible with the Timeline system for animations.

Extends​

Constructors​

Constructor​

new ThreeDScene(container, options): ThreeDScene

Defined in: core/ThreeDScene.ts:116

Create a new 3D scene.

Parameters​

container​

HTMLElement

DOM element to render into, or null for headless mode

options​

ThreeDSceneOptions = {}

Scene configuration options

Returns​

ThreeDScene

Overrides​

Scene.constructor

Properties​

_autoRender​

protected _autoRender: boolean = true

Defined in: core/Scene.ts:115

Inherited from​

Scene._autoRender

_disposed​

protected _disposed: boolean = false

Defined in: core/Scene.ts:99

Inherited from​

Scene._disposed

_waitCleanups​

protected _waitCleanups: () => void[] = []

Defined in: core/Scene.ts:100

Returns​

void

Inherited from​

Scene._waitCleanups

Accessors​

_hasActiveLoop​

Get Signature​

get protected _hasActiveLoop(): boolean

Defined in: core/Scene.ts:325

Whether a render loop is active (play() or wait()). Used by ThreeDScene to avoid duplicate orbit rAF loops.

Returns​

boolean

Inherited from​

Scene._hasActiveLoop

audioManager​

Get Signature​

get audioManager(): AudioManager

Defined in: core/Scene.ts:362

Get the audio manager (lazily created on first access). Use this to access lower-level audio controls.

Returns​

AudioManager

Inherited from​

Scene.audioManager

backgroundOpacity​

Get Signature​

get backgroundOpacity(): number

Defined in: core/Scene.ts:1402

Get the background opacity (0 = fully transparent, 1 = fully opaque).

Returns​

number

Set Signature​

set backgroundOpacity(value): void

Defined in: core/Scene.ts:1410

Set the background opacity (0 = fully transparent, 1 = fully opaque). Only effective if the scene was created with backgroundOpacity < 1.

Parameters​
value​

number

Returns​

void

Inherited from​

Scene.backgroundOpacity

camera​

Get Signature​

get camera(): Camera2D

Defined in: core/Scene.ts:245

Get the camera.

Returns​

Camera2D

Inherited from​

Scene.camera

camera3D​

Get Signature​

get camera3D(): Camera3D

Defined in: core/ThreeDScene.ts:279

Get the 3D camera.

Returns​

Camera3D

currentTime​

Get Signature​

get currentTime(): number

Defined in: core/Scene.ts:343

Get the current playback time.

Returns​

number

Inherited from​

Scene.currentTime

isHeadless​

Get Signature​

get isHeadless(): boolean

Defined in: core/Scene.ts:285

Whether this scene is running in headless mode (no WebGL renderer).

Returns​

boolean

Inherited from​

Scene.isHeadless

isPlaying​

Get Signature​

get isPlaying(): boolean

Defined in: core/Scene.ts:317

Get whether animations are currently playing.

Returns​

boolean

Inherited from​

Scene.isPlaying

isRenderLoopActive​

Get Signature​

get isRenderLoopActive(): boolean

Defined in: core/ThreeDScene.ts:821

The orbit-controls rAF loop also renders every frame while it runs, so count it as an active render loop (e.g. so Draggable doesn't issue redundant renders while orbiting/dragging).

Returns​

boolean

Overrides​

Scene.isRenderLoopActive

lighting​

Get Signature​

get lighting(): Lighting

Defined in: core/ThreeDScene.ts:286

Get the lighting system.

Returns​

Lighting

mobjects​

Get Signature​

get mobjects(): ReadonlySet<Mobject>

Defined in: core/Scene.ts:350

Get all mobjects in the scene.

Returns​

ReadonlySet<Mobject>

Inherited from​

Scene.mobjects

multiCamera​

Get Signature​

get multiCamera(): MultiCamera

Defined in: core/Scene.ts:259

Get the active MultiCamera, or null if single-camera rendering is in use.

Returns​

MultiCamera

Inherited from​

Scene.multiCamera

orbitControls​

Get Signature​

get orbitControls(): OrbitControls

Defined in: core/ThreeDScene.ts:293

Get the orbit controls (if enabled).

Returns​

OrbitControls

renderer​

Get Signature​

get renderer(): IRenderer

Defined in: core/Scene.ts:252

Get the renderer.

Returns​

IRenderer

Inherited from​

Scene.renderer

stateManager​

Get Signature​

get stateManager(): SceneStateManager

Defined in: core/Scene.ts:1429

Get the scene's state manager for advanced undo/redo control.

Returns​

SceneStateManager

Inherited from​

Scene.stateManager

threeScene​

Get Signature​

get threeScene(): Scene

Defined in: core/Scene.ts:238

Get the Three.js scene.

Returns​

Scene

Inherited from​

Scene.threeScene

timeline​

Get Signature​

get timeline(): Timeline

Defined in: core/Scene.ts:301

Get the current timeline.

Returns​

Timeline

Inherited from​

Scene.timeline

Methods​

_cancelPendingRender()​

protected _cancelPendingRender(): void

Defined in: core/Scene.ts:981

Returns​

void

Inherited from​

Scene._cancelPendingRender

_isInSceneGraph()​

protected _isInSceneGraph(obj): boolean

Defined in: core/ThreeDScene.ts:196

Extend the base "already placed" check to also recognize objects parked in the HUD scene. Without this, Scene.add() treats a fixed-in-frame mobject as not-yet-placed and reparents it out of _hudScene into the main 3D scene root — silently undoing addFixedInFrameMobjects() the moment the mobject is (re-)added, e.g. via Scene.play()'s own "add if not yet tracked" step for an animation target (#505).

Parameters​

obj​

Object3D

Returns​

boolean

Overrides​

Scene._isInSceneGraph

_needsPerFrameRendering()​

protected _needsPerFrameRendering(): boolean

Defined in: core/ThreeDScene.ts:614

Override: also needs per-frame rendering when camera is animating.

Returns​

boolean

Overrides​

Scene._needsPerFrameRendering

_render()​

protected _render(): void

Defined in: core/ThreeDScene.ts:624

Override _render to use the 3D camera with two-pass rendering for HUD. This is called by the animation loop internally.

Returns​

void

Overrides​

Scene._render

_renderMultiCamera()​

protected _renderMultiCamera(): void

Defined in: core/Scene.ts:1014

Render via the attached MultiCamera. Clears the full canvas first so arbitrary viewport layouts (e.g. picture-in-picture) don't leak stale pixels, and restores renderer state via try/finally even if a camera render throws.

Returns​

void

Inherited from​

Scene._renderMultiCamera

_scheduleRender()​

protected _scheduleRender(): void

Defined in: core/Scene.ts:969

Queue a render to run on the next microtask. Multiple calls within the same tick coalesce. If _cancelPendingRender() is called or _suppressAutoRender is set before the microtask fires, the render is skipped. Used by add() so a chained play() can suppress the pre-animation flash described in issue #317.

Returns​

void

Inherited from​

Scene._scheduleRender

add()​

add(...mobjects): this

Defined in: core/ThreeDScene.ts:226

Override add for 3D-correct material/render setup (issue #255):

  • depthTest=true on every material (base Scene disables it for 2D layering)
  • depthWrite=!transparent (transparent meshes must not occlude later transparent fragments behind them)
  • renderOrder reset to 0 so Three.js sorts transparent objects by camera distance instead of add order (base Scene stamps an incrementing renderOrder for 2D z-ordering, which defeats 3D depth sort)

Auto-render is suppressed inside super.add() and scheduled once at the end, after settings are applied, so the first visible frame is correct. Render is deferred via the scheduler (issue #317) so a chained play() can suppress it and avoid a pre-animation flash.

Also resolves any pending fixed-in-frame request recorded by addFixedInFrameMobjects() while the mobject wasn't yet tracked: the mobject lands here (via super.add()) only after begin() has already run for whatever animation introduces it, so moving it into the HUD scene at this point carries no risk of flashing its pre-animation state (#505).

Parameters​

mobjects​

...Mobject[]

Returns​

this

Overrides​

Scene.add

addFixedInFrameMobjects()​

addFixedInFrameMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:522

Pin mobjects to the screen (HUD) so they don't move with the 3D camera. Equivalent to Python Manim's add_fixed_in_frame_mobjects.

If a mobject isn't tracked by the scene yet (i.e. it hasn't been added via add()), this only records the intent — it does NOT reparent into the HUD scene or render. Real Manim's add_fixed_in_frame_mobjects is inert metadata with zero scene-graph side effects, callable any time before self.play(...) regardless of whether the mobject is on stage yet; committing the reparent eagerly here instead would risk rendering the mobject's already-finalized state in the HUD before its own intro animation's begin() has reset it for the reveal (#505). The deferred placement happens in add() once the mobject actually lands.

Parameters​

mobjects​

...Mobject[]

Mobjects to fix in screen space

Returns​

this

this for chaining

addFixedOrientationMobjects()​

addFixedOrientationMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:579

Add mobjects that always face the camera regardless of camera orientation. Unlike addFixedInFrameMobjects (which pins to screen/HUD), these stay in the 3D world at their world position but rotate to always face the camera. Equivalent to Python Manim's add_fixed_orientation_mobjects.

Parameters​

mobjects​

...Mobject[]

Mobjects to give fixed orientation

Returns​

this

this for chaining

addForegroundMobject()​

addForegroundMobject(...mobjects): this

Defined in: core/Scene.ts:415

Add mobjects as foreground objects that render on top of everything. Matches Manim Python's add_foreground_mobject().

Parameters​

mobjects​

...Mobject[]

Mobjects to add in the foreground

Returns​

this

Inherited from​

Scene.addForegroundMobject

addSound()​

addSound(url, options?): Promise<AudioTrack>

Defined in: core/Scene.ts:383

Add a sound to play at a specific time on the timeline. Mirrors Python manim's self.add_sound("file.wav", time_offset=0.5).

Parameters​

url​

string

URL of the audio file

options?​

AddSoundOptions

Scheduling and playback options

Returns​

Promise<AudioTrack>

Promise resolving to the created AudioTrack

Example​

await scene.addSound('/sounds/click.wav', { time: 0.5 });
await scene.addSound('/sounds/whoosh.wav');  // plays at time 0

Inherited from​

Scene.addSound

addSoundAtAnimation()​

addSoundAtAnimation(animation, url, options?): Promise<AudioTrack>

Defined in: core/Scene.ts:402

Add a sound that starts when a given animation begins.

Parameters​

animation​

Animation

The animation to sync with

url​

string

URL of the audio file

options?​

Omit<AddSoundOptions, "time"> & object

Additional options (timeOffset shifts relative to animation start)

Returns​

Promise<AudioTrack>

Promise resolving to the created AudioTrack

Example​

const fadeIn = new FadeIn(circle);
await scene.addSoundAtAnimation(fadeIn, '/sounds/appear.wav');
await scene.play(fadeIn);

Inherited from​

Scene.addSoundAtAnimation

batch()​

batch(callback): void

Defined in: core/Scene.ts:1245

Batch multiple mobject updates without re-rendering between each. Useful for performance when making many changes at once.

Parameters​

callback​

() => void

Function containing multiple mobject operations

Returns​

void

Example​

scene.batch(() => {
  circle.setColor('red');
  circle.shift([1, 0, 0]);
  square.setStrokeOpacity(0.5);
});

Inherited from​

Scene.batch

begin3DIllusionCameraRotation()​

begin3DIllusionCameraRotation(rate): this

Defined in: core/ThreeDScene.ts:365

Begin 3D illusion camera rotation. Unlike ambient rotation (which only rotates theta), this also oscillates phi sinusoidally, creating a wobbling 3D illusion as if the viewer walks around the scene. Equivalent to Python Manim's begin_3dillusion_camera_rotation(rate).

Parameters​

rate​

number = 2

Rotation rate in radians per second. Defaults to 2.

Returns​

this

this for chaining

beginAmbientCameraRotation()​

beginAmbientCameraRotation(rate): this

Defined in: core/ThreeDScene.ts:340

Begin continuous ambient rotation of the camera around the scene. Rotates the camera's theta angle at the given rate (radians per second) during wait() calls and play() calls. Equivalent to Python Manim's begin_ambient_camera_rotation(rate).

Parameters​

rate​

number = 0.1

Rotation rate in radians per second. Defaults to 0.1.

Returns​

this

this for chaining

clear()​

clear(options): this

Defined in: core/ThreeDScene.ts:750

Override clear to also clear the HUD scene and fixed mobjects.

Parameters​

options​
render?​

boolean

Returns​

this

Overrides​

Scene.clear

dispose()​

dispose(): void

Defined in: core/ThreeDScene.ts:870

Clean up all resources.

Returns​

void

Overrides​

Scene.dispose

export()​

export(filename, options?): Promise<Blob>

Defined in: core/Scene.ts:1537

Export the scene animation as a file (GIF or video). Format is inferred from the filename extension.

Supported extensions:

  • .gif - Animated GIF
  • .webm - WebM video (VP9)
  • .mp4 - MP4 video (browser codec support varies)
  • .mov - QuickTime video (browser codec support varies)

Parameters​

filename​

string

Output filename (e.g. 'animation.gif', 'scene.webm')

options?​

SceneExportOptions

Export options (fps, quality, dimensions, etc.)

Returns​

Promise<Blob>

The exported Blob

Example​

// Export as GIF
const blob = await scene.export('animation.gif');

// Export as WebM with custom options
const blob = await scene.export('scene.webm', {
  fps: 30,
  quality: 0.8,
  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
});

Inherited from​

Scene.export

getCameraOrientation()​

getCameraOrientation(): object

Defined in: core/ThreeDScene.ts:328

Get the current camera orientation angles.

Returns​

object

Object with phi, theta, and distance

distance​

distance: number

phi​

phi: number

theta​

theta: number

getCanvas()​

getCanvas(): HTMLCanvasElement

Defined in: core/Scene.ts:1361

Get the canvas element.

Returns​

HTMLCanvasElement

The HTMLCanvasElement used for rendering

Inherited from​

Scene.getCanvas

getContainer()​

getContainer(): HTMLElement

Defined in: core/Scene.ts:1370

Get the container element the scene is rendered into. Returns the parent element of the canvas.

Returns​

HTMLElement

The container HTMLElement

Inherited from​

Scene.getContainer

getHeight()​

getHeight(): number

Defined in: core/Scene.ts:1395

Get the height of the canvas in pixels.

Returns​

number

Canvas height in pixels

Inherited from​

Scene.getHeight

getState()​

getState(label?): SceneSnapshot

Defined in: core/Scene.ts:1483

Get a snapshot of the current scene state without modifying stacks.

Parameters​

label?​

string

Returns​

SceneSnapshot

Inherited from​

Scene.getState

getTargetFps()​

getTargetFps(): number

Defined in: core/Scene.ts:1271

Get the current target frame rate.

Returns​

number

Target fps

Inherited from​

Scene.getTargetFps

getTimelineDuration()​

getTimelineDuration(): number

Defined in: core/Scene.ts:1418

Get the total duration of the current timeline.

Returns​

number

Duration in seconds, or 0 if no timeline

Inherited from​

Scene.getTimelineDuration

getWidth()​

getWidth(): number

Defined in: core/Scene.ts:1387

Get the width of the canvas in pixels.

Returns​

number

Canvas width in pixels

Inherited from​

Scene.getWidth

isInView()​

isInView(object): boolean

Defined in: core/Scene.ts:1068

Check if an object is within the camera's view frustum. Useful for manual culling checks or debugging.

Parameters​

object​

Object3D

Three.js object to check

Returns​

boolean

true if object is in view or if culling is disabled

Inherited from​

Scene.isInView

moveCamera()​

moveCamera(options): Promise<void>

Defined in: core/ThreeDScene.ts:395

Animate the camera to a new orientation over a given duration. Equivalent to Python Manim's move_camera(phi, theta, distance). If no duration is given, snaps instantly.

Parameters​

options​

Target orientation and duration

distance?​

number

duration?​

number

phi?​

number

theta?​

number

Returns​

Promise<void>

Promise that resolves when the animation completes

pause()​

pause(): this

Defined in: core/Scene.ts:868

Pause playback (video and audio).

Returns​

this

Inherited from​

Scene.pause

play()​

play(...animations): Promise<void>

Defined in: core/Scene.ts:675

Play animations in parallel (all at once). Matches Manim's scene.play() behavior where multiple animations run simultaneously. Automatically adds mobjects to the scene if not already present.

Parameters​

animations​

...Animation[]

Animations to play

Returns​

Promise<void>

Promise that resolves when all animations complete

Inherited from​

Scene.play

playAll()​

playAll(...animations): Promise<void>

Defined in: core/Scene.ts:742

Play multiple animations in parallel (all at once). Alias for play() - delegates to play() to avoid duplicated logic.

Parameters​

animations​

...Animation[]

Animations to play simultaneously

Returns​

Promise<void>

Promise that resolves when all animations complete

Inherited from​

Scene.playAll

playWithTimestamps()​

playWithTimestamps(entries): Promise<void>

Defined in: core/Scene.ts:695

Play animations with explicit per-animation start/end times (seconds).

NOTE: this is a manim-widget wire-format feature — Python manim has no equivalent per-animation timing API. It is used by the player when deserializing AnimationGroup descriptors that carry start/end fields.

Each entry's end - start overrides the animation's own duration so the Timeline schedules it for the correct window. WARNING: this permanently mutates the Animation object's duration property. Reusing the same animation instance in multiple calls will use the last set duration.

Parameters​

entries​

object[]

Returns​

Promise<void>

Inherited from​

Scene.playWithTimestamps

redo()​

redo(): boolean

Defined in: core/Scene.ts:1472

Redo the last undone change. The current state is pushed to the undo stack.

Returns​

boolean

true if redo was applied, false if nothing to redo

Inherited from​

Scene.redo

remove()​

remove(...mobjects): this

Defined in: core/ThreeDScene.ts:785

Override remove to also handle fixed mobjects.

Parameters​

mobjects​

...Mobject[]

Returns​

this

Overrides​

Scene.remove

removeFixedInFrameMobjects()​

removeFixedInFrameMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:559

Remove mobjects from the fixed-in-frame HUD.

Parameters​

mobjects​

...Mobject[]

Mobjects to unpin from screen space

Returns​

this

this for chaining

removeFixedOrientationMobjects()​

removeFixedOrientationMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:598

Remove mobjects from fixed-orientation tracking. The mobject's rotation will be reset to identity.

Parameters​

mobjects​

...Mobject[]

Mobjects to remove from fixed orientation

Returns​

this

this for chaining

render()​

render(): void

Defined in: core/ThreeDScene.ts:737

Public render - delegates to _render.

Returns​

void

Overrides​

Scene.render

resize()​

resize(width, height): this

Defined in: core/ThreeDScene.ts:808

Handle window resize.

Parameters​

width​

number

New width in pixels

height​

number

New height in pixels

Returns​

this

Overrides​

Scene.resize

resume()​

resume(): this

Defined in: core/Scene.ts:882

Resume playback (video and audio).

Returns​

this

Inherited from​

Scene.resume

saveState()​

saveState(label?): SceneSnapshot

Defined in: core/Scene.ts:1448

Save the current state of all scene mobjects. Pushes onto the undo stack and clears the redo stack.

Parameters​

label?​

string

Optional human-readable label

Returns​

SceneSnapshot

The captured SceneSnapshot

Example​

scene.add(circle, square);
scene.saveState();
circle.shift([2, 0, 0]);
scene.undo(); // circle returns to original position

Inherited from​

Scene.saveState

seek()​

seek(time): this

Defined in: core/Scene.ts:853

Seek to a specific time in the timeline. Also seeks the audio manager if audio has been used.

Parameters​

time​

number

Time in seconds

Returns​

this

Inherited from​

Scene.seek

setCameraOrientation()​

setCameraOrientation(phi, theta, distance?): this

Defined in: core/ThreeDScene.ts:304

Set the camera orientation using spherical coordinates.

Parameters​

phi​

number

Polar angle from Y axis (0 = top, PI = bottom)

theta​

number

Azimuthal angle in XZ plane

distance?​

number

Optional distance from the look-at point

Returns​

this

this for chaining

setFrustumCulling()​

setFrustumCulling(enabled): this

Defined in: core/Scene.ts:1279

Enable or disable frustum culling.

Parameters​

enabled​

boolean

Whether frustum culling should be enabled

Returns​

this

Inherited from​

Scene.setFrustumCulling

setLookAt()​

setLookAt(target): this

Defined in: core/ThreeDScene.ts:315

Set the camera's look-at target.

Parameters​

target​

Vector3Tuple

Target position [x, y, z]

Returns​

this

this for chaining

setOrbitControlsEnabled()​

setOrbitControlsEnabled(enabled): this

Defined in: core/ThreeDScene.ts:494

Enable or disable orbit controls.

Parameters​

enabled​

boolean

Whether orbit controls should be enabled

Returns​

this

this for chaining

setState()​

setState(snapshot): void

Defined in: core/Scene.ts:1491

Apply a previously captured snapshot, overwriting all mobject states. Does NOT modify undo/redo stacks. Call saveState() first to preserve.

Parameters​

snapshot​

SceneSnapshot

Returns​

void

Inherited from​

Scene.setState

setTargetFps()​

setTargetFps(fps): this

Defined in: core/Scene.ts:1261

Set the target frame rate.

Parameters​

fps​

number

Target frames per second (1-120)

Returns​

this

Inherited from​

Scene.setTargetFps

stop()​

stop(): this

Defined in: core/Scene.ts:897

Stop playback and reset timeline (video and audio).

Returns​

this

Inherited from​

Scene.stop

stop3DIllusionCameraRotation()​

stop3DIllusionCameraRotation(): this

Defined in: core/ThreeDScene.ts:382

Stop the 3D illusion camera rotation. Equivalent to Python Manim's stop_3dillusion_camera_rotation().

Returns​

this

this for chaining

stopAmbientCameraRotation()​

stopAmbientCameraRotation(): this

Defined in: core/ThreeDScene.ts:351

Stop the ambient camera rotation. Equivalent to Python Manim's stop_ambient_camera_rotation().

Returns​

this

this for chaining

undo()​

undo(): boolean

Defined in: core/Scene.ts:1458

Undo the last change (restore the most recently saved state). The current state is pushed to the redo stack.

Returns​

boolean

true if undo was applied, false if nothing to undo

Inherited from​

Scene.undo

useMultiCamera()​

useMultiCamera(mc): this

Defined in: core/Scene.ts:270

Attach (or detach) a MultiCamera for split-screen, picture-in-picture, or quad-view rendering. Pass null to revert to single-camera rendering. Has no effect in headless mode (the NullRenderer cannot scissor viewports).

Parameters​

mc​

MultiCamera

MultiCamera instance, or null to restore the default render path

Returns​

this

this for chaining

Inherited from​

Scene.useMultiCamera

wait()​

wait(duration): Promise<void>

Defined in: core/Scene.ts:752

Wait for a duration (pause between animations). Runs a render loop during the wait so that updaters keep ticking.

Parameters​

duration​

number = 1

Duration in seconds

Returns​

Promise<void>

Promise that resolves after the duration

Inherited from​

Scene.wait

createHeadless()​

static createHeadless(options): ThreeDScene

Defined in: core/ThreeDScene.ts:885

Create a headless ThreeDScene for testing without a DOM container.

Parameters​

options​

ThreeDSceneOptions = {}

Returns​

ThreeDScene

Overrides​

Scene.createHeadless