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/ThreeTools

Click 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.

  1. AttachPass the scene, camera and renderer. You have picking, the tree and the profiler.
  2. Add the pluginIn dev, three becomes a wrapper that records each object's line.
  3. 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.