Click an object.
Get the line that made it.
ThreeTools is an inspector and a profiler that run inside the page, next to your three.js scene. Pick anything and see what it is, what it is drawn with, and the file and line that created it.
npm install --save-dev github:joydle/ThreeToolsClick the game and sail with W A S D, N for night, ` to pick. Flood the sea adds 2,500 crates as separate meshes; Instance them draws the same crates in one call. The game is site/demo.js, with no build step; open it on its own page.
What it does
Built for our own game tools, where the one asking is often an agent.
- Picks anything
- Objects by raycast, HUD elements by geometry, and the right one when they overlap. The game is paused for real: its frame loop is held and no input reaches it.
- The line that made it
- File, line and the text of the line, for every mesh, group, light, camera, geometry and material your code constructs.
- What it is drawn with
- Material type, colour and map,
userData, visible here and in every parent. A field three has no concept of is left out, never a made-up zero. - Errors with their source
- Uncaught errors, rejected promises and
console.error, each mapped back to the line. - Every frame, measured
- Frame time and percentiles, CPU and GPU time, draw calls, triangles, shaders, texture and geometry memory, long frames.
- What is slow, in words
- A 0–100 score, the bottleneck, and warnings with the number that tripped them and what to try. Snapshots per build show what a change cost.
For agents
Everything the panel shows, a script can ask for. Asking never pauses, selects or draws.
in the page — from a test, a script or a coding agent's browser
const { inspector, profiler } = window.__threetools; await inspector.agent.at(640, 360); // what is at this pixel: HUD first, then objects, topmost first await inspector.agent.named('boat'); // by name inspector.agent.tree(); // the scene graph and the HUD, as one tree await inspector.agent.errors(); // runtime errors, each with its source line profiler.getReport(); // the frame profile as Markdown
one hit
{
"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(…), flat('#f4efe4'));"
}
}In the panel, Copy for agent puts the same facts on the clipboard as text, and Copy report the profile. Inside an editor's iframe the tools speak postMessage instead: the protocol is a dozen messages.
Use
One call for the panel. One plugin line for source lines.
- AttachPass the scene, camera and renderer. You have picking, the tree and the profiler.
- Add the pluginIn dev,
threebecomes a wrapper that records each object's line. - Ship as beforeThe plugin does nothing in a build; the tools never reach it.
any three.js page
import * as THREE from 'three'; import { attach } from '@joydle/threetools'; attach({ THREE, scene, camera, renderer });
with Vite — vite.config.js, then your entry
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) { const { attach } = await import('@joydle/threetools'); attach(); }
no bundler — an import map
<script type="importmap"> { "imports": { "three": "./lib/threetools.three.js", "@joydle/threetools": "./lib/threetools.js" }, "scopes": { "./lib/": { "three": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js" } } } </script>
Works with three r150 and later, WebGL renderer. It is a dev tool: it wraps renderer.render and a few WebGL calls to count them, and turns on preserveDrawingBuffer so screenshots are never blank.