ThreeDShapeElement is the primary facade for the 3D system. Each instance encapsulates a full Three.js environment and exposes the small surface the React layer needs.

Constructor

constructor(mountContainer: HTMLElement, options: ThreeDShapeElementOptions = {})

Parameter	Type	Description
mountContainer	HTMLElement	The DOM element that will receive the WebGLRenderer canvas
options.geometryType	GeometryType (optional)	Primitive type to create initially. Defaults to 'box'
options.sceneState	SceneStateSnapshot (optional)	If provided, the scene is restored from this snapshot instead of creating a new primitive

If sceneState is provided the constructor calls restoreScene(); otherwise it calls engine.addPrimitive() with the given geometry type.

Public Methods

Method	Signature	Description
getEngine()	(): ThreeDEngine	Returns the underlying engine for direct API access
resize()	(width, height): void	Resizes the renderer and updates the camera aspect ratio
setInteracting()	(active: boolean): void	Enables or disables orbit controls and marks dirty. When false, the shape acts as a static viewport
isInteracting()	(): boolean	Returns the current interaction state
getSceneSnapshot()	(): SceneStateSnapshot	Serializes the current scene for persistence
pause()	(): void	Stops the render loop, for off-screen optimization
resume()	(): void	Restarts the render loop
dispose()	(): void	Destroys the engine, releases all GPU resources and removes the canvas from the DOM. Must be called when the shape is deleted

Lifecycle

•Construction — ThreeDShapeRenderer creates the element in a useEffect and passes the container div.
•Active use — the user interacts via the properties panel or by entering 3D edit mode. Orbit, gizmo, material and geometry changes flow through getEngine().
•Visibility toggling — when element.visible becomes false, pause() is called; when it becomes true, resume() is called.
•Destruction — the useEffect cleanup calls dispose(), which cascades through ThreeDEngine.dispose() to release every resource.

Programmatic Creation

const container = document.getElementById('my-3d-host')!;
const shape = new ThreeDShapeElement(container, { geometryType: 'sphere' });

// Access the engine for advanced operations
const engine = shape.getEngine();
engine.updateMaterial('some-id', { ...DEFAULT_MATERIAL_CONFIG, color: '#ff0000' });

// When done
shape.dispose();