lens-inspector

When you create objects from a Script at runtime (instantiatePrefab, createSceneObject), they aren't visible in the Scene Hierarchy. This means you can't know what components are attached, or where things ended up spatially, so you end up doing lots of print-debugging.

Lens Inspector fixes this by streaming the full live scene graph to a browser panel over WebSocket while the lens runs in editor. This captures all the objects that are invisible to the Scene Hierarchy such as: runtime-spawned prefabs, dynamically created SceneObjects, all their components (physics, scripts, audio, VFX, interactions, tracking), with transforms updating in real time.

Quick start

You need Node.js installed (any recent version works).

npx lens-inspector

Or clone the repo if you want to modify things:

git clone https://github.com/a-sumo/lens-inspector.git
cd lens-inspector
npm install
node server.js

The server starts and opens the viewer in your browser automatically. You'll see a waiting screen with setup steps:

From there:

1. Download SceneInspector.ts from the running server at localhost:8200/SceneInspector.ts and drop it into your Lens Studio project's Assets/ folder
2. Attach the SceneInspector component to any SceneObject in your scene
3. In Lens Studio, go to Project Settings > General and enable Experimental APIs (required for ws://localhost connections)
4. Hit Play in Lens Studio

Once Lens Studio connects, the welcome screen disappears and your scene tree appears with live updates at about 2Hz.

Demo project

If you want to see it working right away, open the included LSProject/ folder in Lens Studio. It has SceneInspector and a RuntimeSpawner script already set up. Hit Play, and blocks will start appearing in both Lens Studio and the browser viewer.

Features

3D Viewport with WASD Navigation

The viewer renders every SceneObject as a labeled wireframe box in a 3D viewport. Orbit with left-click drag, pan with middle-click or right-click, zoom with scroll wheel. Fly through the scene with WASD (forward/left/back/right), Q/E (down/up), and hold Shift for speed. Navigation keys use physical key positions so they work correctly on AZERTY, QWERTZ, and other keyboard layouts.

Hierarchy Panel

The left panel shows a collapsible tree matching your scene structure. Each node displays a color-coded icon by component category (camera, visual, script, light, physics, audio, VFX, etc.) and a component count badge. Runtime-spawned objects appear in blue.

• Search: type to filter nodes by name, text content, component type, or category
• Category chips: click Camera, Visual, Script, Light, Physics, Audio, Anim, UI, Track, or Empty to show only that type
• Expand/Collapse: click the arrow to fold tree branches without affecting 3D visibility
• Eye toggle: hover a node and click the eye icon to hide or show it in the 3D viewport independently of the tree

Inspector Panel

Click any node in the tree or 3D viewport to see its transform (position, scale, rotation), object properties (enabled, children count, layer, category), color, text content, and a full component list with type-specific details like mesh name, material, script asset, camera FOV, audio track, and physics mass.

MCP Component Enrichment

The runtime scene graph walker detects components by probing 40+ known Lens Studio types individually (Camera, ScriptComponent, RenderMeshVisual, LightSource, etc.). When the generic getComponentCount("Component") returns 0 for certain LS versions or object types, the fallback catches what would otherwise show as empty nodes.

For additional component detail, paste your Lens Studio MCP config JSON into the welcome screen. The viewer proxies MCP calls through the inspector server to avoid CORS, fetching the design-time scene graph and merging component data into live nodes. Copy the config from AI Assistant > MCP in Lens Studio.

Configurable Server

Change the server address in the welcome screen if you run the inspector on a different port or machine. The setting persists in localStorage.

Two modes

Runtime: A Script component inside your lens walks the full scene graph using the SceneObject API, serializes the hierarchy into JSON, and sends it over WebSocket to the browser. This captures everything: both the objects you placed in the Scene Hierarchy and anything created by Scripts at runtime.

Design-time: When your lens isn't running, the viewer can fetch the static scene structure through Lens Studio's MCP server. This is useful for inspecting your Scene Hierarchy without entering preview mode.

To use design-time mode:

1. In Lens Studio, go to AI Assistant > MCP > Configure Server and set a port
2. Click Copy MCP Config to get the JSON with server URL and auth token
3. In the inspector welcome screen, paste the full MCP config JSON into the MCP Config field

If your MCP server runs on a non-default port, you can also pass a token on the command line:

npx lens-inspector --mcp http://localhost:8733/mcp --mcp-token YOUR_TOKEN

The MCP config from Lens Studio also works with AI coding assistants like Claude. Paste it into your assistant's MCP server config to let it read and modify your scene programmatically.

The viewer

The browser shows three synchronized panels. A hierarchy tree on the left with search, category filters, and independent visibility toggles. A 3D viewport in the center with an infinite multi-level grid, axis graduations in centimeters/meters, a navigation gizmo, and WASD fly controls. And an inspector panel on the right showing transform data, component details, text content, and colors for the selected node. All three panels are resizable by dragging the borders between them.

Try it without Lens Studio

An example script simulates a live scene so you can try the viewer without Lens Studio installed:

node server.js          # terminal 1
node example.js         # terminal 2

The browser opens automatically. The example streams a scene with blocks, columns, and new SceneObjects spawning over time, so you can see how the tree, canvas, and inspector panel respond to live changes.

Configuration

The SceneInspector component exposes three inputs in Lens Studio's Inspector panel:

| Input | Default | Description | |---|---|---| | wsUrl | ws://localhost:8200?role=ls | Inspector server address | | updateInterval | 15 | Frames between updates (~2Hz at 30fps) | | maxDepth | 20 | Max tree traversal depth |

The server accepts these flags:

node server.js --port 9000                          # custom port
node server.js --no-open                            # don't auto-open browser
node server.js --mcp http://localhost:8733/mcp      # custom MCP URL
node server.js --mcp-token YOUR_TOKEN               # MCP auth token

Architecture

The entire tool is three files with no build step or external framework:

• SceneInspector.ts (~370 lines): LS component that walks and serializes the scene graph, with fallback type-specific component probing
• server.js (~200 lines): WebSocket relay between LS and browser, with an MCP proxy for design-time queries and live reload
• index.html (single file): the entire browser viewer with Three.js 3D viewport, hierarchy, and inspector

The code is meant to be read and modified. If you want to add custom component introspection or change the viewer layout, everything is right there in plain files.

License

MIT