Click an object in your three.js scene. Get the line of code that made it.
An inspector and a profiler that run in the page, next to your scene. For people, a bar in the corner; for scripts and coding agents, the same answers as JSON. Play with it.
npm install --save-dev github:joydle/ThreeToolsimport * as THREE from 'three';
import { attach } from '@joydle/threetools';
attach({ THREE, scene, camera, renderer });| Pick or ` | pause the game and click anything in it; Esc to resume |
| Object | the selection: the line that made it, transform, material, userData |
| Scene | the scene graph and the HUD as one tree |
| Perf | frame time, draw calls, memory, a 0–100 score and what to fix |
three has to say where each object is constructed. In dev, the Vite plugin
swaps three for a 1.6 KB wrapper that records the calling line. A production
build is untouched.
// vite.config.js
import threetools from '@joydle/threetools/vite';
export default { plugins: [threetools()] };
// main.js: the wrapper finds the scene, camera and renderer itself
if (import.meta.env.DEV) (await import('@joydle/threetools')).attach();TypeScript and bundles resolve through their source maps. Without a bundler,
an import map does the same: see site/demo.html. A working
Vite project is in examples/vite.
Read-only: asking never pauses, selects or draws.
const { inspector, profiler } = window.__threetools;
await inspector.agent.at(640, 360); // what is at this pixel, topmost first
await inspector.agent.named('boat'); // by name
inspector.agent.tree(); // the scene graph and the HUD
await inspector.agent.errors(); // runtime errors with their source lines
profiler.getReport(); // the frame profile as Markdown{
"kind": "object",
"name": "tower",
"metadata": {
"typeName": "Mesh",
"position": { "x": 0, "y": 2.3, "z": 0 },
"material": { "type": "MeshStandardMaterial", "color": "#f4efe4" },
"originalSource": "/demo.js",
"originalLine": 68,
"originalSourceLine": "const tower = new THREE.Mesh(new THREE.CylinderGeometry(0.75, 1.15, 4.6, 10), flat('#f4efe4'));"
}
}In an iframe the tools speak postMessage; the built-in bar is one such host
and can be left out. Every message is in docs/PROTOCOL.md.
attach({ panel: false, host: { origin: 'https://editor.example' } });
// the editor
frame.contentWindow.postMessage({ type: 'INSPECTOR_PAUSE' }, gameOrigin);
addEventListener('message', (e) => {
if (e.data?.source === 'threetools' && e.data.type === 'OBJECT_SELECTED') show(e.data.metadata);
});Name the host's origin on any page other sites can frame.
- Objects: meshes, groups, lights, sprites, lines and points by raycast; HUD elements over the canvas by geometry.
- Source: file, line and the text of the line, through source maps.
- Looks: material type, colour and map, several materials per mesh, visible here and in every parent. A field three has no concept of is left out, never a made-up zero.
- Errors: uncaught errors, rejected promises and
console.error. - Frames: frame time and percentiles, CPU and GPU time, draw calls, triangles, shader programs, texture and geometry memory, long frames.
- Advice: the bottleneck, and warnings with the number that tripped them.
- Pictures: the view with the HUD composited in, or a dragged region.
- Types ship with the package.
attachchecks its arguments by shape, so it needs no three types. - three r150 and later (developed on r186), WebGL renderer.
- A dev tool: it wraps
renderer.renderand a few WebGL calls to count them, and the wrapper turns onpreserveDrawingBufferfor screenshots. Keep it out of what you ship; the Vite plugin does. - Your own names: every global, id, attribute and message source is in
src/brand.ts. Build from@joydle/threetools/src/*(the TypeScript source ships in the package) with that file replaced to ship the tools under another name. - For Pixi: PixiTools. The two share
their core;
npm run checkfails if a shared file names either tool.
npm install
npm run check # typecheck, tests, build
npm run serve # the site and demo on http://127.0.0.1:4173MIT. Made by Joydle.
