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:108

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:99

Inherited from​

Scene._autoRender

_disposed​

protected _disposed: boolean = false

Defined in: core/Scene.ts:83

Inherited from​

Scene._disposed

_waitCleanups​

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

Defined in: core/Scene.ts:84

Returns​

void

Inherited from​

Scene._waitCleanups

Accessors​

_hasActiveLoop​

Get Signature​

get protected _hasActiveLoop(): boolean

Defined in: core/Scene.ts:261

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:287

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:1165

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

Returns​

number

Set Signature​

set backgroundOpacity(value): void

Defined in: core/Scene.ts:1173

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:207

Get the camera.

Returns​

Camera2D

Inherited from​

Scene.camera

camera3D​

Get Signature​

get camera3D(): Camera3D

Defined in: core/ThreeDScene.ts:230

Get the 3D camera.

Returns​

Camera3D

currentTime​

Get Signature​

get currentTime(): number

Defined in: core/Scene.ts:268

Get the current playback time.

Returns​

number

Inherited from​

Scene.currentTime

isHeadless​

Get Signature​

get isHeadless(): boolean

Defined in: core/Scene.ts:221

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:253

Get whether animations are currently playing.

Returns​

boolean

Inherited from​

Scene.isPlaying

lighting​

Get Signature​

get lighting(): Lighting

Defined in: core/ThreeDScene.ts:237

Get the lighting system.

Returns​

Lighting

mobjects​

Get Signature​

get mobjects(): ReadonlySet<Mobject>

Defined in: core/Scene.ts:275

Get all mobjects in the scene.

Returns​

ReadonlySet<Mobject>

Inherited from​

Scene.mobjects

orbitControls​

Get Signature​

get orbitControls(): OrbitControls

Defined in: core/ThreeDScene.ts:244

Get the orbit controls (if enabled).

Returns​

OrbitControls

renderer​

Get Signature​

get renderer(): IRenderer

Defined in: core/Scene.ts:214

Get the renderer.

Returns​

IRenderer

Inherited from​

Scene.renderer

stateManager​

Get Signature​

get stateManager(): SceneStateManager

Defined in: core/Scene.ts:1192

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:200

Get the Three.js scene.

Returns​

Scene

Inherited from​

Scene.threeScene

timeline​

Get Signature​

get timeline(): Timeline

Defined in: core/Scene.ts:237

Get the current timeline.

Returns​

Timeline

Inherited from​

Scene.timeline

Methods​

_cancelPendingRender()​

protected _cancelPendingRender(): void

Defined in: core/Scene.ts:841

Returns​

void

Inherited from​

Scene._cancelPendingRender

_needsPerFrameRendering()​

protected _needsPerFrameRendering(): boolean

Defined in: core/ThreeDScene.ts:541

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

Returns​

boolean

Overrides​

Scene._needsPerFrameRendering

_render()​

protected _render(): void

Defined in: core/ThreeDScene.ts:552

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

_scheduleRender()​

protected _scheduleRender(): void

Defined in: core/Scene.ts:829

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:194

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.

Parameters​

mobjects​

...Mobject[]

Returns​

this

Overrides​

Scene.add

addFixedInFrameMobjects()​

addFixedInFrameMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:463

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.

Parameters​

mobjects​

...Mobject[]

Mobjects to fix in screen space

Returns​

this

this for chaining

addFixedOrientationMobjects()​

addFixedOrientationMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:506

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:340

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:308

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:327

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:1062

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:316

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:291

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:670

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:779

Clean up all resources.

Returns​

void

Overrides​

Scene.dispose

export()​

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

Defined in: core/Scene.ts:1301

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:279

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:1124

Get the canvas element.

Returns​

HTMLCanvasElement

The HTMLCanvasElement used for rendering

Inherited from​

Scene.getCanvas

getContainer()​

getContainer(): HTMLElement

Defined in: core/Scene.ts:1133

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:1158

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:1246

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:1088

Get the current target frame rate.

Returns​

number

Target fps

Inherited from​

Scene.getTargetFps

getTimelineDuration()​

getTimelineDuration(): number

Defined in: core/Scene.ts:1181

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:1150

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:891

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:346

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:730

Pause playback (video and audio).

Returns​

this

Inherited from​

Scene.pause

play()​

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

Defined in: core/Scene.ts:503

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:604

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

redo()​

redo(): boolean

Defined in: core/Scene.ts:1235

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:704

Override remove to also handle fixed mobjects.

Parameters​

mobjects​

...Mobject[]

Returns​

this

Overrides​

Scene.remove

removeFixedInFrameMobjects()​

removeFixedInFrameMobjects(...mobjects): this

Defined in: core/ThreeDScene.ts:487

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:525

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:657

Public render - delegates to _render.

Returns​

void

Overrides​

Scene.render

resize()​

resize(width, height): this

Defined in: core/ThreeDScene.ts:726

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:744

Resume playback (video and audio).

Returns​

this

Inherited from​

Scene.resume

saveState()​

saveState(label?): SceneSnapshot

Defined in: core/Scene.ts:1211

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:715

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:255

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:1096

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:266

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:445

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:1254

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:1078

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:759

Stop playback and reset timeline (video and audio).

Returns​

this

Inherited from​

Scene.stop

stop3DIllusionCameraRotation()​

stop3DIllusionCameraRotation(): this

Defined in: core/ThreeDScene.ts:333

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:302

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:1221

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

wait()​

wait(duration): Promise<void>

Defined in: core/Scene.ts:614

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:794

Create a headless ThreeDScene for testing without a DOM container.

Parameters​

options​

ThreeDSceneOptions = {}

Returns​

ThreeDScene

Overrides​

Scene.createHeadless