SpectorJS
Summary
Explore and Troubleshoot your WebGL scenes (All engines and Vanilla script support) with ease.
Spector is a tool aimed at WebGL developers wanting to know what happens in their context. It enables capturing of all the available information from a frame. You will be able to look at your entire commands list with their associated visual states and context information.
This can be used either as a browser extension or directly from your page with a Standalone Version.
Table of Content
- Why
- Browser extension
- Use as a Module
- Use as a Script Reference
- CDN
- From the repository
- Node_Modules
- How To Reference
- Basic usage
- Custom data
- OffscreenCanvas Support
- Main-thread OffscreenCanvas
- Worker OffscreenCanvas
- Auto-injection
- MCP Server
- Available APIs
- Build Locally
- Contribute
- ChangeLog
- Learn WebGl
Why
Back to top
As a core member of the BabylonJS team I often found the need to debug what was happening to my webgl context. I was a huge fan of webgl inspector until we introduced WebGL2 in Babylon. As the WebGL community as a whole is our focus, I thought it would be great to share an extension compatible with all the Webgl/Webgl2 engines available.
You can use the library inside of your own application easily as it is transpiled as a UMD module. It will either work as a script reference or with your favorite bundling tools like webpack.
Browser extension
Back to top
If you are willing to use the browser extension, you can direclty install it from the store:
You can find on Real Time Rendering a complete tutorial about the Spector extension. Else, you can refer to the extension documentation to learn how to use it.
Or you can take a look at the following documentation to load it from the source: Browser Extension.
Use as a Module
Back to top
In order to install the library in your application directory, please type the following command on a command line prompt open on the application directory:
npm install spectorjs
From this point you are all set to use it in your app.
Webpack sample
Back to top
As a quick demo, here is a simple way to use the spector module with webpack.
Please follow the instructions below to create a new directory and install the required tools:
mkdir sample
cd sample
npm init
npm install --save-dev webpack webpack-cli
npm install spectorjs --save-dev
Following the HelloWorld example from Webpack, you can now create it in the sample folder:
A js file named entry.js containing the following code:
var SPECTOR = require("spectorjs");
var spector = new SPECTOR.Spector();
spector.displayUI();
And an html file named index.html containing the following code:
<html>
<head>
</head>
<body>
<script type="text/javascript" src="dist/main.js" charset="utf-8"></script>
</body>
</html>
Now your application is ready. Go back to your command line and bundle the javascript file:
npx webpack entry.js
You are all set. You can open your index.html file and see the inspector running e.g. open index.html on Linux and macOS. It obviously won't be that useful on an empty page but at least you get the integration idea.
Use as a Script Reference
Back to top
CDN
Feel free to leverage the jsDeliver CDN to use the library from your own projets: https://cdn.jsdelivr.net/npm/[email protected]/dist/spector.bundle.js
Repo
If you prefer to host your own version, the library is available in the dist folder of the repo.
node_modules
If you used npm to install the library you can find the spector.bundle.js file in the node_module/spectorjs/dist folder.
How To Reference
Simply add the following tag in your html page header:
<script type="text/javascript" src="https://spectorcdn.babylonjs.com/spector.bundle.js"></script>
Basic Usage
Back to top
Once available in your app, you can instantiate an inspector by inserting the following command in your script:
var spector = new SPECTOR.Spector();
You can then display the embedded UI directly in your page:
spector.displayUI();
Or launch a capture and reuse its JSON result at your will:
spector.onCapture.add((capture) => {
// Do something with capture.
var myEvent = new CustomEvent("SpectorOnCaptureEvent", { detail: { captureString: JSON.stringify(capture) } });
document.dispatchEvent(myEvent);
});
var canvas = document.getElementById("renderCanvas");
spector.captureCanvas(canvas);
Another api you can rely upon is:
spector.spyCanvases();
This will enable a complete tracking of the gl calls even before capturing which enables for instance access to the texture inputs or memory consumption information.
Custom Data
Back to top
You can simply add custom data to the capture by adding a special field named __SPECTOR_Metadata to your WebGLObjects.
var cubeVerticesColorBuffer = gl.createBuffer();
cubeVerticesColorBuffer.__SPECTOR_Metadata = { name: "cubeVerticesColorBuffer" };
This will enable the visibility of your custom name in your capture. This can be an invaluable asset during troubleshoot session. This can also help with referencing your materials' friendly names from your captures.
OffscreenCanvas Support
Back to top
Spector supports capturing WebGL commands from OffscreenCanvas — both on the main thread and inside Web Workers.
Bundles
| Bundle | Use |
|---|
dist/spector.bundle.js | Main thread (includes UI) |
dist/spector.worker.bundle.js | Inside Workers (headless, no UI) |
Main-thread OffscreenCanvas
No special setup needed — captureCanvas works with OffscreenCanvas the same way it works with a regular <canvas>:
var spector = new SPECTOR.Spector();
var offscreen = new OffscreenCanvas(800, 600);
var gl = offscreen.getContext('webgl2');
// ... render ...
spector.onCapture.add(function(capture) {
console.log('Captured', capture.commands.length, 'commands');
});
spector.captureCanvas(offscreen);
See sample/offscreen.html for a working example.
Worker OffscreenCanvas (Manual API — recommended)
Use spyWorker() to bridge a specific Worker, then captureWorker() to trigger a capture. The Worker must load spector.worker.bundle.js.
Main thread:
var spector = new SPECTOR.Spector();
var worker = new Worker('myWorker.js');
// Bridge the Worker for capture
spector.spyWorker(worker);
// Capture from the Worker
spector.onCapture.add(function(capture) {
console.log('Captured from Worker:', capture.commands.length, 'commands');
spector.getResultUI().display();
spector.getResultUI().addCapture(capture);
});
spector.captureWorker(worker);
Inside myWorker.js:
importScripts('spector.worker.bundle.js');
// OffscreenCanvas received via message or created directly
var canvas = new OffscreenCanvas(800, 600);
var gl = canvas.getContext('webgl2');
function render() {
// ... draw calls ...
setTimeout(render, 16); // rAF may not be available in Workers
}
render();
See sample/worker.html for a working example.
Auto-injection (best-effort)
spyWorkers() monkey-patches the global Worker constructor to automatically inject the Spector bundle into every new Worker:
var spector = new SPECTOR.Spector();
spector.spyWorkers('spector.worker.bundle.js');
// All subsequent new Worker() calls get Spector injected automatically
// Stop intercepting:
// spector.stopSpyingWorkers();
⚠️ Limitations: Auto-injection may fail with cross-origin Workers, strict CSP policies, or ES module Workers. Use the manual API as a reliable fallback.
API Reference
| Method | Description |
|---|
spyWorker(worker) | Bridge a specific Worker for capture. Returns a WorkerBridge. |
captureWorker(worker, commandCount?, quickCapture?, fullCapture?) | Trigger a capture on a bridged Worker. Auto-bridges if needed. |
spyWorkers(bundleUrl?) | Intercept all new Worker() calls to auto-inject Spector. |
stopSpyingWorkers() | Stop intercepting Worker construction. |
MCP Server
Back to top
Spector.js includes an MCP (Model Context Protocol) server that lets AI assistants debug any WebGL website directly. Load a URL, capture frames, and inspect draw calls, shaders, textures, and GL state — all from your AI-powered editor.
npm run mcp:install
npm run mcp:build
Then add to your MCP client config:
{
"mcpServers": {
"spector": {
"command": "node",
"args": ["<path-to-repo>/mcp/dist/index.js"]
}
}
}
See the full documentation in mcp/README.md.
Learn About WebGL
Back to top
I would advise you to check out and start with the Awesome BabylonJS the community there will be more than happy to welcome anybody willing to learn Web 3d.
