Class: ThreeDScene
Defined in: src/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
Extended by
Constructors
Constructor
new ThreeDScene(
container,options):ThreeDScene
Defined in: src/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
Properties
_autoRender
protected_autoRender:boolean=true
Defined in: src/core/Scene.ts:117
Inherited from
_disposed
protected_disposed:boolean=false
Defined in: src/core/Scene.ts:101
Inherited from
_waitCleanups
protected_waitCleanups: () =>void[] =[]
Defined in: src/core/Scene.ts:102
Returns
void
Inherited from
Accessors
_hasActiveLoop
Get Signature
get
protected_hasActiveLoop():boolean
Defined in: src/core/Scene.ts:363
Whether a render loop is active (play() or wait()). Used by ThreeDScene to avoid duplicate orbit rAF loops.
Returns
boolean
Inherited from
audioManager
Get Signature
get audioManager():
AudioManager
Defined in: src/core/Scene.ts:422
Get the audio manager (lazily created on first access). Use this to access lower-level audio controls.
Returns
Inherited from
backgroundColor
Get Signature
get backgroundColor():
Color
Defined in: src/core/Scene.ts:1510
Get the scene background color, as a THREE.Color.
Returns
Set Signature
set backgroundColor(
color):void
Defined in: src/core/Scene.ts:1519
Set the scene background color. Accepts a THREE.Color or a CSS color string. Used by setTheme to re-skin an existing scene.
Parameters
color
string | Color
Returns
void
Inherited from
backgroundOpacity
Get Signature
get backgroundOpacity():
number
Defined in: src/core/Scene.ts:1526
Get the background opacity (0 = fully transparent, 1 = fully opaque).
Returns
number
Set Signature
set backgroundOpacity(
value):void
Defined in: src/core/Scene.ts:1534
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
camera
Get Signature
get camera():
Camera2D
Defined in: src/core/Scene.ts:253
Get the camera.
Returns
Inherited from
camera3D
Get Signature
get camera3D():
Camera3D
Defined in: src/core/ThreeDScene.ts:279
Get the 3D camera.
Returns
currentTime
Get Signature
get currentTime():
number
Defined in: src/core/Scene.ts:381
Get the current playback time.
Returns
number
Inherited from
isHeadless
Get Signature
get isHeadless():
boolean
Defined in: src/core/Scene.ts:323
Whether this scene is running in headless mode (no WebGL renderer).
Returns
boolean
Inherited from
isPlaying
Get Signature
get isPlaying():
boolean
Defined in: src/core/Scene.ts:355
Get whether animations are currently playing.
Returns
boolean
Inherited from
isRenderLoopActive
Get Signature
get isRenderLoopActive():
boolean
Defined in: src/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
lighting
Get Signature
get lighting():
Lighting
Defined in: src/core/ThreeDScene.ts:286
Get the lighting system.
Returns
mobjects
Get Signature
get mobjects():
ReadonlySet<Mobject>
Defined in: src/core/Scene.ts:388
Get all mobjects in the scene.
Returns
ReadonlySet<Mobject>
Inherited from
multiCamera
Get Signature
get multiCamera():
MultiCamera
Defined in: src/core/Scene.ts:267
Get the active MultiCamera, or null if single-camera rendering is in use.
Returns
Inherited from
orbitControls
Get Signature
get orbitControls():
OrbitControls
Defined in: src/core/ThreeDScene.ts:293
Get the orbit controls (if enabled).
Returns
postProcessing
Get Signature
get postProcessing():
PostProcessingPipeline
Defined in: src/core/Scene.ts:294
Get the attached post-processing pipeline, or null when the default direct render path is in use.
Returns
Inherited from
renderer
Get Signature
get renderer():
IRenderer
Defined in: src/core/Scene.ts:260
Get the renderer.
Returns
Inherited from
stateManager
Get Signature
get stateManager():
SceneStateManager
Defined in: src/core/Scene.ts:1553
Get the scene's state manager for advanced undo/redo control.
Returns
Inherited from
threeScene
Get Signature
get threeScene():
Scene
Defined in: src/core/Scene.ts:246
Get the Three.js scene.
Returns
Inherited from
timeline
Get Signature
get timeline():
Timeline
Defined in: src/core/Scene.ts:339
Get the current timeline.
Returns
Inherited from
Methods
_cancelPendingRender()
protected_cancelPendingRender():void
Defined in: src/core/Scene.ts:1055
Returns
void
Inherited from
_isInSceneGraph()
protected_isInSceneGraph(obj):boolean
Defined in: src/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
Returns
boolean
Overrides
_needsPerFrameRendering()
protected_needsPerFrameRendering():boolean
Defined in: src/core/ThreeDScene.ts:614
Override: also needs per-frame rendering when camera is animating.
Returns
boolean
Overrides
_render()
protected_render():void
Defined in: src/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
_renderMultiCamera()
protected_renderMultiCamera():void
Defined in: src/core/Scene.ts:1119
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
_renderPostProcessing()
protected_renderPostProcessing():boolean
Defined in: src/core/Scene.ts:1099
Render through the attached post-processing pipeline. Guards for a lost WebGL context the same way _renderMultiCamera does.
Returns
boolean
true if the composer drew the frame, false to fall back
Inherited from
_scheduleRender()
protected_scheduleRender():void
Defined in: src/core/Scene.ts:1043
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
add()
add(...
mobjects):this
Defined in: src/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
addFixedInFrameMobjects()
addFixedInFrameMobjects(...
mobjects):this
Defined in: src/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: src/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: src/core/Scene.ts:475
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
addSound()
addSound(
url,options?):Promise<AudioTrack>
Defined in: src/core/Scene.ts:443
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?
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
addSoundAtAnimation()
addSoundAtAnimation(
animation,url,options?):Promise<AudioTrack>
Defined in: src/core/Scene.ts:462
Add a sound that starts when a given animation begins.
Parameters
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
batch()
batch(
callback):void
Defined in: src/core/Scene.ts:1350
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
begin3DIllusionCameraRotation()
begin3DIllusionCameraRotation(
rate):this
Defined in: src/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: src/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: src/core/ThreeDScene.ts:750
Override clear to also clear the HUD scene and fixed mobjects.
Parameters
options
render?
boolean
Returns
this
Overrides
dispose()
dispose():
void
Defined in: src/core/ThreeDScene.ts:870
Clean up all resources.
Returns
void
Overrides
export()
export(
filename,options?):Promise<Blob>
Defined in: src/core/Scene.ts:1661
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?
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
getCameraOrientation()
getCameraOrientation():
object
Defined in: src/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: src/core/Scene.ts:1469
Get the canvas element.
Returns
HTMLCanvasElement
The HTMLCanvasElement used for rendering
Inherited from
getContainer()
getContainer():
HTMLElement
Defined in: src/core/Scene.ts:1478
Get the container element the scene is rendered into. Returns the parent element of the canvas.
Returns
HTMLElement
The container HTMLElement
Inherited from
getHeight()
getHeight():
number
Defined in: src/core/Scene.ts:1503
Get the height of the canvas in pixels.
Returns
number
Canvas height in pixels
Inherited from
getMobject()
getMobject(
id):Mobject
Defined in: src/core/Scene.ts:405
Find a mobject by its user-defined identifier (see Mobject.setUserId).
Searches every added mobject and its descendants (the family tree), so a
mobject nested inside a VGroup or Group is found as long as its container
was added to the scene. This mirrors how add() tracks a mobject together
with its children.
Parameters
id
string
The user id to match against each mobject's userId
Returns
The first mobject whose userId equals id, or undefined if
none matches. When several mobjects share the same id, the first one
found in scene-insertion then depth-first family order is returned.
Inherited from
getState()
getState(
label?):SceneSnapshot
Defined in: src/core/Scene.ts:1607
Get a snapshot of the current scene state without modifying stacks.
Parameters
label?
string
Returns
Inherited from
getTargetFps()
getTargetFps():
number
Defined in: src/core/Scene.ts:1376
Get the current target frame rate.
Returns
number
Target fps
Inherited from
getTimelineDuration()
getTimelineDuration():
number
Defined in: src/core/Scene.ts:1542
Get the total duration of the current timeline.
Returns
number
Duration in seconds, or 0 if no timeline
Inherited from
getWidth()
getWidth():
number
Defined in: src/core/Scene.ts:1495
Get the width of the canvas in pixels.
Returns
number
Canvas width in pixels
Inherited from
isInView()
isInView(
object):boolean
Defined in: src/core/Scene.ts:1173
Check if an object is within the camera's view frustum. Useful for manual culling checks or debugging.
Parameters
object
Three.js object to check
Returns
boolean
true if object is in view or if culling is disabled
Inherited from
moveCamera()
moveCamera(
options):Promise<void>
Defined in: src/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: src/core/Scene.ts:942
Pause playback (video and audio).
Returns
this
Inherited from
play()
play(...
animations):Promise<void>
Defined in: src/core/Scene.ts:744
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
playAll()
playAll(...
animations):Promise<void>
Defined in: src/core/Scene.ts:816
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
playWithTimestamps()
playWithTimestamps(
entries):Promise<void>
Defined in: src/core/Scene.ts:769
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
redo()
redo():
boolean
Defined in: src/core/Scene.ts:1596
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
remove()
remove(...
mobjects):this
Defined in: src/core/ThreeDScene.ts:785
Override remove to also handle fixed mobjects.
Parameters
mobjects
...Mobject[]
Returns
this
Overrides
removeFixedInFrameMobjects()
removeFixedInFrameMobjects(...
mobjects):this
Defined in: src/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: src/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: src/core/ThreeDScene.ts:737
Public render - delegates to _render.
Returns
void
Overrides
resize()
resize(
width,height):this
Defined in: src/core/ThreeDScene.ts:808
Handle window resize.
Parameters
width
number
New width in pixels
height
number
New height in pixels
Returns
this
Overrides
resume()
resume():
this
Defined in: src/core/Scene.ts:956
Resume playback (video and audio).
Returns
this
Inherited from
saveState()
saveState(
label?):SceneSnapshot
Defined in: src/core/Scene.ts:1572
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
The captured SceneSnapshot
Example
scene.add(circle, square);
scene.saveState();
circle.shift([2, 0, 0]);
scene.undo(); // circle returns to original position
Inherited from
seek()
seek(
time):this
Defined in: src/core/Scene.ts:927
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
setCameraOrientation()
setCameraOrientation(
phi,theta,distance?):this
Defined in: src/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: src/core/Scene.ts:1384
Enable or disable frustum culling.
Parameters
enabled
boolean
Whether frustum culling should be enabled
Returns
this
Inherited from
setLookAt()
setLookAt(
target):this
Defined in: src/core/ThreeDScene.ts:315
Set the camera's look-at target.
Parameters
target
Target position [x, y, z]
Returns
this
this for chaining
setOrbitControlsEnabled()
setOrbitControlsEnabled(
enabled):this
Defined in: src/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: src/core/Scene.ts:1615
Apply a previously captured snapshot, overwriting all mobject states. Does NOT modify undo/redo stacks. Call saveState() first to preserve.
Parameters
snapshot
Returns
void
Inherited from
setTargetFps()
setTargetFps(
fps):this
Defined in: src/core/Scene.ts:1366
Set the target frame rate.
Parameters
fps
number
Target frames per second (1-120)
Returns
this
Inherited from
stop()
stop():
this
Defined in: src/core/Scene.ts:971
Stop playback and reset timeline (video and audio).
Returns
this
Inherited from
stop3DIllusionCameraRotation()
stop3DIllusionCameraRotation():
this
Defined in: src/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: src/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: src/core/Scene.ts:1582
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
useMultiCamera()
useMultiCamera(
mc):this
Defined in: src/core/Scene.ts:278
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 instance, or null to restore the default render path
Returns
this
this for chaining
Inherited from
usePostProcessing()
usePostProcessing(
pipeline):this
Defined in: src/core/Scene.ts:307
Attach (or detach) an opt-in GPU post-processing pipeline (bloom, vignette,
depth of field). Pass null to revert to the direct render path. Has no
effect in headless mode (the NullRenderer has no WebGL context). The
pipeline preloads its modules so later frames can route through the
composer; until they load, the direct path is used.
Parameters
pipeline
PostProcessingPipeline instance, or null to detach
Returns
this
this for chaining
Inherited from
wait()
wait(
duration):Promise<void>
Defined in: src/core/Scene.ts:826
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
createHeadless()
staticcreateHeadless(options):ThreeDScene
Defined in: src/core/ThreeDScene.ts:885
Create a headless ThreeDScene for testing without a DOM container.
Parameters
options
ThreeDSceneOptions = {}
Returns
ThreeDScene