Inspector

Inspector 是运行中 PlayCanvas 应用的调试面板。它停靠在画布上，显示应用当前场景、GPU 资源和渲染帧，下方属性视图实时更新所选对象的属性。

它可以回答以下问题：

实体为什么没有显示，组件当前如何设置？
网格使用哪种材质和着色器，引用了哪些纹理？
一帧渲染哪些内容，经过哪些通道，顺序是什么？
显存用在了哪里？
哪些帧较慢，瓶颈是什么？

Inspector 主要读取应用。它仅执行你主动要求的修改：启停实体、暂停和逐帧运行，以及渲染模式、线框和飞行或环绕相机等仅影响查看的覆盖设置；关闭时会移除这些查看覆盖。

添加 Inspector

Inspector 发布为 @playcanvas/inspector 包，需要引擎 2.23 或更高版本。

npm install @playcanvas/inspector

在应用上创建：

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

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

playcanvas 是此包的 peer dependency。Inspector 使用应用自身的引擎，因此必须与应用导入同一份 playcanvas 包。调用 inspector.destroy() 可移除面板。

也可以将其作为脚本添加到场景中的独立实体：

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

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

选项

选项	默认值	说明
`visible`	`true`	面板初始是否显示。
`dock`	`'right'`	停靠在画布哪一侧，可为 `'left'` 或 `'right'`。
`width`	`420`	面板宽度，单位为 CSS 像素。
`top`	`0`	面板上方保留的间距，单位为 CSS 像素，用于避开其他叠加界面。
`toggleKey`	`'Backquote'`	显示和隐藏面板的按键。
`pauseKey`	`'F9'`	暂停和恢复应用的按键。
`stepKey`	`'F10'`	暂停时前进一帧的按键。
`record`	`false`	是否立即在 Performance 标签页记录帧。如果在应用首帧前创建，还能记录启动过程，参见记录应用启动。
`storageKey`	`'pc-inspector'`	保存活动标签页、面板宽度等设置所用的本地存储键；设为 `null` 则不保存。

按钮	说明
Pause / Resume（F9）	暂停应用：时间停止，但仍继续渲染。
Step（F10）	暂停时前进一帧。
Pick	悬停时勾勒指针下的实体，点击选中。
Fly	使用鼠标和 WASD 飞行查看，不移动应用自身的相机。
Orbit	绕所选实体观察：拖动环绕，右键拖动平移，滚轮缩放。
Pop out	将面板移入独立窗口，避免遮挡画布。
Hide（`）	隐藏面板。

按 Esc 停止拾取、飞行或环绕模式。

标签页

每个标签页列出一种对象，下方属性视图显示所选对象。材质纹理、通道渲染目标等对象引用会显示为链接，点击可在相应标签页中选中。

标签页	说明
Hierarchy	实体树，可按实体名、组件或脚本名筛选。属性视图显示变换、全部组件及脚本属性，视口中勾勒所选实体。各行复选框控制实体启用状态。
Cameras	按渲染顺序显示相机及输出位置。渲染模式可为单台或全部相机显示基础颜色、世界法线、光照等材质输入，代替最终图像，也可显示线框。
Assets	注册表中的全部资源，包含文件、加载状态及使用方。
Frame graph	按顺序显示上一帧的渲染通道及其图层、绘制和渲染目标。设备支持时，GPU timings 显示各通道 GPU 耗时；Freeze 在应用继续运行时固定显示当前帧；Preview 在视口上预览所选通道的渲染目标。
Performance	记录帧数据，绘制帧、CPU、GPU、脚本耗时，以及加载、内存和资源随时间变化的图表，每帧有独立时间线。参见 Inspector 性能分析。
Render targets	设备上的渲染目标、写入它们的通道，以及所选附件的实时预览。
Textures	设备纹理，按大小降序排列，支持实时预览和通道选择。
Meshes	应用网格，按大小降序排列，显示几何信息及使用方。
Materials	应用材质，按使用数量降序排列，显示纹理、已编译着色器变体及使用方。
Scripts	应用脚本类，以及使用各脚本的实体、属性和源码。
Memory	按资源类型统计显存，以及设备上的顶点、索引、统一和存储缓冲区。
Shaders	已编译着色器及其源码。
Physics	物理世界的刚体与关节，并可将物理世界叠加绘制到场景上。

逐步查看一帧

Frame graph 可以一次只执行一个绘制调用，观察图像如何逐步形成，以及哪个调用绘制了什么。

打开 Frame graph，选择一个前向渲染通道，或其中的图层步骤，例如 World 图层中的不透明网格。
启用 Debug frame。应用暂停，通道仅绘制到选中的调用，视图显示该位置为止的帧结果。
按上下方向键，逐个后退或前进绘制调用。属性视图列出网格实例并高亮当前项，视图中勾勒它，状态栏显示序号，例如 draw 8 of 12 · World opaque。展开条目可查看网格和材质等详情。
关闭 Debug frame，恢复完整帧绘制。

备注

逐步查看绘制调用需要引擎调试构建，其他构建中此选项会禁用。Vite 等打包工具会在开发环境通过 playcanvas 包的 development 导出条件选择调试构建。

示例

实体检查器示例会在包含灯光、物理刚体、脚本和动画角色的小场景中打开 Inspector。可以在层级中选择实体或在视口中拾取，飞行或环绕相机，并探索其他标签页。按反引号（`）显示或隐藏面板。

实体检查器示例

添加 Inspector​

选项​

工具栏​

标签页​

逐步查看一帧​

示例​

添加 Inspector

选项

工具栏

标签页

逐步查看一帧

示例