DevtoolProbe Class

The DevtoolProbe class is the central API for 3Lens. It manages renderer observation, scene tracking, object selection, performance monitoring, and communication with the overlay/extension.

Import

import { DevtoolProbe, createProbe } from '@3lens/core';

Recommended

Use createProbe() to create instances instead of new DevtoolProbe() directly. The factory handles auto-connection to the browser extension.

Class Overview

class DevtoolProbe {
  // Configuration
  readonly config: ProbeConfig;
  
  // Properties
  get threeVersion(): string | null;
  get entityCount(): number;
  get moduleCount(): number;
  get pluginCount(): number;
  get activePluginCount(): number;
  
  // Renderer Management
  observeRenderer(renderer: THREE.WebGLRenderer | THREE.Renderer): void;
  isWebGL(): boolean;
  isWebGPU(): boolean;
  getRendererKind(): 'webgl' | 'webgpu' | null;
  getRendererAdapter(): RendererAdapter | null;
  
  // Scene Management
  observeScene(scene: THREE.Scene): void;
  unobserveScene(scene: THREE.Scene): void;
  getObservedScenes(): THREE.Scene[];
  
  // Selection
  selectObject(obj: THREE.Object3D | null): void;
  selectByDebugId(debugId: string | null): boolean;
  getSelectedObject(): THREE.Object3D | null;
  onSelectionChanged(callback): Unsubscribe;
  
  // Inspect Mode
  initializeInspectMode(canvas, camera, three): void;
  setInspectModeEnabled(enabled: boolean): void;
  isInspectModeEnabled(): boolean;
  
  // Frame Stats
  getLatestFrameStats(): FrameStats | null;
  getFrameStatsHistory(count?: number): FrameStats[];
  onFrameStats(callback): Unsubscribe;
  
  // Snapshots
  takeSnapshot(): SceneSnapshot;
  onSnapshot(callback): Unsubscribe;
  
  // Lifecycle
  connect(transport: Transport): void;
  disconnect(): void;
  isConnected(): boolean;
  dispose(): void;
  
  // ...and many more methods
}

Constructor

constructor(config: ProbeConfig)

Creates a new probe instance. Prefer using createProbe() instead.

Parameter	Type	Description
config	ProbeConfig	Probe configuration

Properties

config

readonly config: ProbeConfig

The probe's configuration object (read-only after construction).

threeVersion

get threeVersion(): string | null

The detected three.js version from the observed renderer. Returns null if no renderer is observed.

const probe = createProbe({ appName: 'My App' });
probe.observeRenderer(renderer);
console.log(probe.threeVersion); // "0.160.0"

entityCount

get entityCount(): number

The number of registered logical entities.

moduleCount

get moduleCount(): number

The number of registered modules.

pluginCount

get pluginCount(): number

The number of registered plugins.

activePluginCount

get activePluginCount(): number

The number of currently active plugins.

Renderer Management

observeRenderer()

observeRenderer(renderer: THREE.WebGLRenderer | THREE.Renderer): void

Start observing a three.js renderer. Auto-detects WebGL vs WebGPU.

// WebGL Renderer
const renderer = new THREE.WebGLRenderer();
probe.observeRenderer(renderer);

// WebGPU Renderer
const gpuRenderer = new THREE.WebGPURenderer();
probe.observeRenderer(gpuRenderer);

WebGPU Detection

The probe detects WebGPU renderers via the isWebGPURenderer property on the renderer object.

isWebGL()

isWebGL(): boolean

Returns true if the current renderer is WebGL.

isWebGPU()

isWebGPU(): boolean

Returns true if the current renderer is WebGPU.

getRendererKind()

getRendererKind(): 'webgl' | 'webgpu' | null

Returns the renderer backend type, or null if no renderer is observed.

getRendererAdapter()

getRendererAdapter(): RendererAdapter | null

Returns the internal renderer adapter for advanced use cases.

attachRendererAdapter()

attachRendererAdapter(adapter: RendererAdapter): void

Attach a custom renderer adapter. For advanced use when auto-detection isn't suitable.

Resource Queries

getTextures()

getTextures(): TextureInfo[]

Get all textures tracked by the renderer.

getGeometries()

getGeometries(): GeometryInfo[]

Get all geometries tracked by the renderer.

getMaterials()

getMaterials(): MaterialInfo[]

Get all materials tracked by the renderer.

getGpuTimings()

async getGpuTimings(): Promise<GpuTimingInfo | null>

Get GPU timing information (if available).

Scene Management

observeScene()

observeScene(scene: THREE.Scene): void

Start observing a scene for changes. Multiple scenes can be observed simultaneously.

const mainScene = new THREE.Scene();
const uiScene = new THREE.Scene();

probe.observeScene(mainScene);
probe.observeScene(uiScene);

unobserveScene()

unobserveScene(scene: THREE.Scene): void

Stop observing a scene.

getObservedScenes()

getObservedScenes(): THREE.Scene[]

Get all currently observed scenes.

Render Target Management

observeRenderTarget()

observeRenderTarget(
  renderTarget: THREE.WebGLRenderTarget,
  usage?: RenderTargetUsage
): void

Register a render target for observation.

Parameter	Type	Default	Description
renderTarget	WebGLRenderTarget	-	The render target to observe
usage	RenderTargetUsage	'custom'	Usage hint for categorization

RenderTargetUsage values:

• 'shadow-map' - Shadow mapping
• 'post-process' - Post-processing effects
• 'reflection' - Environment reflections
• 'refraction' - Refraction effects
• 'custom' - Other uses

const depthTarget = new THREE.WebGLRenderTarget(1024, 1024);
probe.observeRenderTarget(depthTarget, 'post-process');

unobserveRenderTarget()

unobserveRenderTarget(renderTarget: THREE.WebGLRenderTarget): void

Stop observing a render target.

getRegisteredRenderTargets()

getRegisteredRenderTargets(): Map<string, { 
  rt: THREE.WebGLRenderTarget; 
  usage: RenderTargetUsage 
}>

Get all registered render targets.

THREE.js Reference

setThreeReference()

setThreeReference(three: typeof import('three')): void

Provide a reference to the THREE.js library. Required for:

• Selection highlighting (bounding boxes)
• Visualization helpers (wireframe, normals)
• Transform gizmos

import * as THREE from 'three';

const probe = createProbe({ appName: 'My App' });
probe.setThreeReference(THREE);

updateSelectionHighlight()

updateSelectionHighlight(): void

Manually update selection highlight. Call this in your animation loop if selected objects move.

Object Selection

See Selection API for detailed documentation.

selectObject()

selectObject(obj: THREE.Object3D | null): void

Select an object or clear selection (pass null).

selectByDebugId()

selectByDebugId(debugId: string | null): boolean

Select an object by its debug ID. Returns true if found.

getSelectedObject()

getSelectedObject(): THREE.Object3D | null

Get the currently selected object.

onSelectionChanged()

onSelectionChanged(
  callback: (obj: THREE.Object3D | null, meta?: ObjectMeta) => void
): Unsubscribe

Subscribe to selection changes.

const unsubscribe = probe.onSelectionChanged((obj, meta) => {
  if (obj) {
    console.log('Selected:', meta?.name, obj.type);
  } else {
    console.log('Selection cleared');
  }
});

// Later: unsubscribe()

Inspect Mode

See Inspect Mode API for detailed documentation.

initializeInspectMode()

initializeInspectMode(
  canvas: HTMLCanvasElement,
  camera: THREE.Camera,
  three: typeof import('three')
): void

Initialize inspect mode for interactive object picking.

setInspectModeEnabled()

setInspectModeEnabled(enabled: boolean): void

Enable or disable inspect mode.

isInspectModeEnabled()

isInspectModeEnabled(): boolean

Check if inspect mode is currently enabled.

setInspectModeCamera()

setInspectModeCamera(camera: THREE.Camera): void

Update the camera used for raycasting.

setInspectModePickableObjects()

setInspectModePickableObjects(objects: THREE.Object3D[]): void

Limit which objects can be picked.

Visual Overlays

toggleWireframe()

toggleWireframe(obj: THREE.Object3D, enabled: boolean): void

Toggle wireframe visualization for an object.

toggleBoundingBox()

toggleBoundingBox(obj: THREE.Object3D, enabled: boolean): void

Toggle bounding box visualization for an object.

toggleGlobalWireframe()

toggleGlobalWireframe(enabled: boolean): void

Toggle wireframe mode for all meshes in all scenes.

isWireframeEnabled()

isWireframeEnabled(obj: THREE.Object3D): boolean

Check if wireframe is enabled for an object.

isBoundingBoxEnabled()

isBoundingBoxEnabled(obj: THREE.Object3D): boolean

Check if bounding box is enabled for an object.

Frame Stats

getLatestFrameStats()

getLatestFrameStats(): FrameStats | null

Get the most recent frame statistics.

const stats = probe.getLatestFrameStats();
if (stats) {
  console.log(`FPS: ${stats.performance?.fps}`);
  console.log(`Draw calls: ${stats.drawCalls}`);
  console.log(`Triangles: ${stats.triangles}`);
}

getFrameStatsHistory()

getFrameStatsHistory(count?: number): FrameStats[]

Get historical frame stats. Defaults to all history (up to 300 frames).

// Get last 60 frames
const history = probe.getFrameStatsHistory(60);
const avgFps = history.reduce((sum, s) => sum + (s.performance?.fps ?? 0), 0) / history.length;

onFrameStats()

onFrameStats(callback: (stats: FrameStats) => void): Unsubscribe

Subscribe to frame stats updates.

const unsubscribe = probe.onFrameStats((stats) => {
  updateDebugDisplay(stats);
});

Snapshots

takeSnapshot()

takeSnapshot(): SceneSnapshot

Manually capture a snapshot of all observed scenes.

onSnapshot()

onSnapshot(callback: (snapshot: SceneSnapshot) => void): Unsubscribe

Subscribe to snapshot events.

Custom Metrics

metric()

metric(name: string, value: number, tags?: Record<string, string>): void

Record a custom metric value.

probe.metric('enemy-count', enemies.length, { level: 'boss' });
probe.metric('particle-count', particleSystem.count);

event()

event(name: string, data?: Record<string, unknown>): void

Record a custom event.

probe.event('level-complete', { level: 5, time: 120, score: 15000 });

Material Live Editing

updateMaterialProperty()

updateMaterialProperty(
  materialUuid: string, 
  property: string, 
  value: unknown
): void

Update a material property by UUID. Used for live editing from the overlay.

// Change material color
probe.updateMaterialProperty(material.uuid, 'color', 0xff0000);

// Change roughness
probe.updateMaterialProperty(material.uuid, 'roughness', 0.5);

Transport & Connection

connect()

connect(transport: Transport): void

Connect to a transport for communication with devtools.

disconnect()

disconnect(): void

Disconnect from the current transport.

isConnected()

isConnected(): boolean

Check if connected to a devtool UI.

onCommand()

onCommand(handler: (command: DebugMessage) => void): Unsubscribe

Handle commands from the devtool UI.

Lifecycle

See Probe Lifecycle for detailed documentation.

dispose()

dispose(): void

Clean up all resources. Always call this when done.

// React cleanup
useEffect(() => {
  const probe = createProbe({ appName: 'My App' });
  return () => probe.dispose();
}, []);

Additional Systems

The DevtoolProbe also provides access to:

• Transform Gizmo - 3D manipulation controls
• Camera Controller - Focus, fly-to animations
• Logical Entities - Component ↔ Object mapping
• Plugin System - Extensibility
• Configuration - Rule checking

See their respective documentation pages for details.

Type Definitions

FrameStats

interface FrameStats {
  timestamp: number;
  frameNumber: number;
  drawCalls: number;
  triangles: number;
  points: number;
  lines: number;
  geometryCount: number;
  textureCount: number;
  programCount: number;
  memory?: MemoryStats;
  performance?: PerformanceMetrics;
  violations?: RuleViolation[];
}

ObjectMeta

interface ObjectMeta {
  debugId: string;
  uuid: string;
  name: string;
  type: string;
  visible: boolean;
  path: string;
}

Unsubscribe

type Unsubscribe = () => void;

Related

• createProbe() - Factory function
• Probe Lifecycle - init, dispose, connect
• Selection API - Object selection details
• Inspect Mode API - Interactive picking
• FrameStats Reference - Stats structure