PlayCanvas Inspector

| User Manual | Blog | Forum |

A debug panel for running PlayCanvas apps. It shows the entity hierarchy and every component's properties, and tabs for the cameras, assets, frame graph, render targets, textures, meshes, materials, scripts, memory, shaders and physics of the app, with live previews of textures and render targets, picking and flying in the view, and a debug frame mode that steps through the draw calls of a render pass.

The inspector is read-only, apart from toggling entities on and off, pausing and stepping the app, and view-only overrides (render modes, wireframe, a flown or orbited camera) it removes when it closes.

Install

npm install @playcanvas/inspector

It requires PlayCanvas Engine 2.23 or newer. playcanvas is a peer dependency: the inspector works on your app's own engine, so it must be the same playcanvas package your app imports.

TypeScript declarations are included, generated from the JSDoc of the sources.

Use

import { Inspector } from '@playcanvas/inspector';

const inspector = new Inspector(app, { dock: 'left', width: 480 });

Press ` to show or hide the panel, F9 to pause and F10 to step a frame while paused. The keys, dock side, width and more are options of the constructor.

Or, from the Editor or a scripted scene, as a script on an entity:

import { EntityInspector } from '@playcanvas/inspector';

const entity = new Entity('inspector');
entity.addComponent('script');
entity.script.create(EntityInspector, { properties: { dock: 'left' } });
app.root.addChild(entity);

Step through a frame

In the Frame graph tab, select a forward pass or one of its layer steps and turn on Debug frame. The app pauses and the pass draws only up to the selected draw; the arrow keys step through the draws one at a time, with each one outlined in the view and listed with its mesh and material. It needs the debug build of the engine.

Edit transforms

Click a position, rotation or the local scale in the Transform section of an entity to edit it as three numbers separated by commas (one number for a uniform scale); Enter applies it and Escape gives up. Or turn on Move, Rotate or Scale in the toolbar and drag the handles of the gizmo drawn on the selected entity. A drag on a handle is kept from the app, while away from the handles the app has the view as usual. Pick, Fly and Orbit are off while a gizmo is on; Esc or its button turns it off. An entity with a physics body takes its body along.

Copy as JSON

Right-click a row, a section title or an item of a list to copy it to the clipboard as JSON, with numbers at full precision. Right-click the header of a group, such as Textures on the Memory tab, to copy the group, or the name of a tab to copy everything it lists: the Hierarchy tab copies the hierarchy from its root. Copy as JSON copies it on its own; Copy N levels deep also copies what it links to, such as the children of an entity, its mesh instances, their materials and their textures, up to N links away; Copy all levels follows every link, so copying the root copies the whole hierarchy. A link that is not followed is named by $type and its name or id, and marked $stub; an object already copied elsewhere in the copy is marked $ref. A node's parent and the lists of what uses an object are left out, so a copy never climbs out of what was copied.

Engine versions

Each inspector release names the engine versions it supports in its playcanvas peer dependency. The inspector reads engine internals to show what it shows, so a new engine release can need a new inspector release. The range takes later 2.x releases but not prereleases of them, such as 2.24.0-beta.1, as npm does not match prereleases of other versions than the range names.

The devtools hook

From engine 2.23, every PlayCanvas app announces itself to a hook defined on the global object, which is how the upcoming browser extension finds apps on any page:

globalThis[Symbol.for('playcanvas.inspector')] = {
    register(app, { version, revision, protocol }) {},
    unregister(app) {}
};

The hook must be defined before the engine creates the app. register is called once each app is initialized, and unregister when it is destroyed. protocol is 1.

Development

Node 22.19 or newer.

npm install
npm run lint
npm test
npm run build:types # writes the TypeScript declarations to types/
npm run test:types  # compiles a TypeScript usage of the package against them
npm run publint     # checks the package is publishable

The tests run against the playcanvas version in devDependencies, on the engine's null graphics device under jsdom.

A few engine helpers the inspector draws with are copied into src/renderers, src/picker and src/input, so the inspector does not depend on them being in the app's engine build. See COPIED_FROM.md.

License

MIT