Skip to content

About

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.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ThreeTools

ThreeTools

Click an object in your three.js scene. Get the line of code that made it.

CI License: MIT Demo

A small sailing game with its lighthouse tower picked: the card shows the line of demo.js that created it, its transform and its material.

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.

Install

npm install --save-dev github:joydle/ThreeTools

Use

import * 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

Source lines

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.

For scripts and agents

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'));"
  }
}

Inside an editor

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.

What it reports

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

Notes

  • Types ship with the package. attach checks 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.render and a few WebGL calls to count them, and the wrapper turns on preserveDrawingBuffer for 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 check fails if a shared file names either tool.

Develop

npm install
npm run check     # typecheck, tests, build
npm run serve     # the site and demo on http://127.0.0.1:4173

License

MIT. Made by Joydle.

About

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.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages