TEngine 内置 Unity Pipeline 捕获命令实战指南:让 AI Agent 无显示环境"看见"Unity 编辑器
TEngine 内置 Unity Pipeline 捕获命令实战指南:让 AI Agent 无显示环境"看见"Unity 编辑器
本篇指南系统讲解 TEngine 仓库内嵌的 Unity Pipeline 包(com.unity.pipeline)中全部四个捕获(Capture)命令:capture_game_view、capture_scene_view、capture_editor_element 与 capture_runtime_element。这些命令负责把相机、Scene View 或 UI Toolkit 元素渲染成 PNG 并以 base64 返回,从而让运行在无显示环境中的 CLI、CI 或 AI Agent 直接"看到"编辑器乃至运行中的 Player。读完本文,你将掌握每个命令的参数语义、返回结构、UI Toolkit 选择器语法、底层离屏渲染原理,以及在 TEngine 的 AI 开发工作流(如 AI-Development-Workflow.md 所描述的 Agent 工作流)中调用与验证这些命令的完整方法。
捕获命令的定位与设计动机
Unity Pipeline 通过本地 HTTP 服务向客户端(CLI、CI 或 Agent)暴露注册命令。捕获命令正是其中的"视觉反馈"通道(源码注释中对应需求项 CLI-199):渲染一张图、编码成 base64 回传,让 Agent 在没有任何显示器的情况下"看见"编辑器或运行中的 Player。
在 TEngine 项目中,该包以独立 UPM 包形式随仓库分发(见 package.json),AI 工作流基线明确为 Pipeline 0.3.1-exp.1(见 AI-Development-Workflow.md)。捕获命令于 0.3.0-exp.1 版本随"Agent 化内容管线"命令集一并加入(见 CHANGELOG.md),与 screenshot 等命令共同构成 Capture & screenshots 命令族。
四个命令分为两类:
| 命令 | 捕获目标 | 运行环境 | 版本要求 |
|---|---|---|---|
capture_game_view |
场景内指定相机 | 编辑器 | 无特殊限制 |
capture_scene_view |
活动的 Scene View | 编辑器 | 无特殊限制 |
capture_editor_element |
编辑器窗口中某个 UI Toolkit 元素 | 编辑器 | Unity 6000.7+ |
capture_runtime_element |
运行时面板(UIDocument / PanelRenderer)中的元素 | 运行时 Player 或编辑器 Play 模式 | Unity 6000.7+ |
其中前两个命令的实现在 CaptureCommands.cs,后两个命令共享一套运行时安全的捕获支撑逻辑,位于 VisualElementCaptureSupport.cs。
capture_game_view:渲染相机为 PNG
该命令把指定相机渲染到一张 PNG,并以 base64 编码返回。参数定义如下(文档参数表与源码 <a href="https://link.gitcode.com/i/5ffa7a0bed2e787e6d1a17924b56e0dc" target="_blank">CliArg] 声明一致,见 [CaptureCommands.cs):
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
width |
否 | 1280 |
输出宽度(px),默认 1280,上限 4096 |
height |
否 | 720 |
输出高度(px),默认 720,上限 4096 |
camera |
否 | – |
可选相机名;默认取 Camera.main,否则取第一个启用的相机 |
save_path |
否 | – |
可选的项目相对路径,同时把 PNG 写入磁盘(如 Screenshots/foo.png) |
返回:CaptureResult
典型调用(通过 unity CLI,参数以 --参数名 值 形式传入):
# 默认 1280x720,取 Camera.main
unity command capture_game_view
# 指定分辨率并锁定某台命名相机
unity command capture_game_view --width 1920 --height 1080 --camera "Main Camera"
# 同时落盘到项目目录
unity command capture_game_view --save_path Screenshots/foo.png
相机的解析规则(源码级)
源码 ResolveCamera 的查找顺序(CaptureCommands.cs):
- 若传了
camera名字,先在Camera.allCameras(仅包含启用的相机)中按名字匹配;没找到再扫描所有已加载的相机(含禁用相机),这样即使目标相机当前禁用、只要显式指名也能捕获; - 未指名时优先
Camera.main; - 否则取
Camera.allCameras中第一个启用的相机; - 全都匹配不到时,命令抛出
ArgumentException("No camera found to capture.")。
分辨率方面,源码用 Mathf.Clamp(width, 1, MaxDimension) 把宽高钳制在 [1, 4096] 区间(MaxDimension = 4096),因此超出 4096 的请求会被静默压回上限。
capture_scene_view:渲染活动的 Scene View
该命令渲染当前活动的 Scene View(即 SceneView.lastActiveSceneView),参数与 capture_game_view 基本一致(见 CaptureCommands.cs):
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
width |
否 | 1280 |
输出宽度(px),默认 1280,上限 4096 |
height |
否 | 720 |
输出高度(px),默认 720,上限 4096 |
save_path |
否 | – |
可选的项目相对路径,同时把 PNG 写入磁盘 |
返回:CaptureResult
unity command capture_scene_view --width 1600 --height 900
若当前没有活动的 Scene View(SceneView.lastActiveSceneView 为 null 或其相机为 null),命令会抛出 ArgumentException("No active Scene View to capture.")。注意:捕获的是 Scene View 的相机(sv.camera),渲染结果即编辑器 Scene 视口内容;返回结果的 source 字段固定为 "sceneView"。
capture_game_view / capture_scene_view 的返回结构:CaptureResult
两个命令返回同一模型 CaptureResult(CaptureCommands.cs),JSON 字段如下:
| 字段 | 类型 | 含义 |
|---|---|---|
width |
int | 渲染宽度(钳制后实际值,px) |
height |
int | 渲染高度(钳制后实际值,px) |
encoding |
string | 图片编码,恒为 "png" |
base64 |
string | PNG 字节的 base64 编码 |
bytes |
int | 原始 PNG 字节数组长度 |
source |
string | 捕获来源,如 "camera:Main Camera" 或 "sceneView" |
savedPath |
string | 落盘的项目相对路径;未请求保存时为 null |
在 Pipeline 的服务端封装下,客户端实际收到的是 CommandExecutionResponse 信封(success / command / result / executionTimeMs / error),result 字段即上述 CaptureResult(见 creating-commands.md)。
capture_editor_element:捕获编辑器窗口中的 UI Toolkit 元素
该命令按 USS 风格选择器 从某个 EditorWindow 中定位一个 VisualElement,渲染为 PNG 并同时返回文件路径与 base64。参数如下(见 CaptureEditorElementCommand.cs):
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
window |
是 | – |
目标 EditorWindow 的类型名(如 InspectorWindow)或窗口标题 |
selector |
是 | – |
元素选择器:#名称、.类名、类型名(如 Button)、后代(空格)/ 子元素(>)链,以及可选伪状态 :checked、:hover、:focus、:active、:enabled、:disabled、:not(...) |
output |
否 | – |
输出 PNG 路径(绝对路径,或相对项目根目录);缺省时写到 <项目>/Temp/pipeline-screenshots/ 下的时间戳文件 |
返回:CaptureElementResponse
注意:MainThreadRequired = true,且仅限 Unity 6000.7+(整个实现包在 #if UNITY_6000_7_OR_NEWER 中)。
# 捕获 Inspector 窗口中的 #target 元素
unity command capture_editor_element --window InspectorWindow --selector "#target"
# 指定输出文件
unity command capture_editor_element --window "Inspector" --selector "Button.primary" --output Screenshots/inspector-btn.png
窗口解析与失败分支(源码级)
源码 ResolveWindow 通过 Resources.FindObjectsOfTypeAll<EditorWindow>() 枚举窗口,按「运行时类型名」或「窗口标题」匹配;因为 FindObjectsOfTypeAll 可能返回陈旧/备份窗口实例(其 rootVisualElement 没有挂到面板上、无法捕获),所以匹配时优先选择 root 已附加到 panel 的窗口,其次才退回普通匹配(CaptureEditorElementCommand.cs)。
典型失败场景及对应错误消息:
- 缺少
window/selector→ 提示A 'window' (...) is required./A 'selector' is required. - 没有匹配的打开窗口 →
No open EditorWindow matched '<window>' (by type name or title). Open the window first. - 窗口没有
rootVisualElement→EditorWindow '<window>' has no rootVisualElement. - 选择器未命中 →
No element matched selector '<selector>' in window '<window>'.
默认输出目录
不传 output 时,命令以 <项目根>/Temp/pipeline-screenshots/ 为默认目录(项目根 = Application.dataPath 的上级目录),生成 element_yyyyMMdd_HHmmss_fff.png 形式的时间戳文件。Temp 目录本就属于 Unity 生成的临时目录,不会污染 Assets 资源库。
capture_runtime_element:捕获运行时 UI 面板中的元素
该命令从运行中的 UI Toolkit 面板(由 UIDocument 或 PanelRenderer 承载)中按选择器捕获元素。它位于运行时程序集(CaptureRuntimeElementCommand.cs),因此既可用于编辑器 Play 模式,也可用于启用了运行时管理器的开发版 Player——Player 中没有 AssetDatabase,所以面板通过名称而非资源路径标识。
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
panel |
否 | – |
目标面板名称:匹配 PanelSettings 资源名或宿主 GameObject 名(UIDocument / PanelRenderer)。当场景中恰好只有一个面板时可省略 |
selector |
是 | – |
元素选择器(语法同 capture_editor_element) |
output |
否 | – |
输出 PNG 路径(绝对路径,或相对 Application.persistentDataPath);缺省写到 Application.persistentDataPath 下的时间戳文件 |
返回:CaptureElementResponse
注意:MainThreadRequired = true、RuntimeOnly = true,且仅限 Unity 6000.7+。
# 连接开发版 Player,捕获名为 MainUI 面板中的 #title
unity command --runtime MyGame.exe capture_runtime_element --panel MainUI --selector "#title"
面板定位逻辑(源码级)
GatherHosts 会同时扫描场景中所有 UIDocument 与 PanelRenderer(CaptureRuntimeElementCommand.cs),每个宿主记录 PanelSettingsName、GameObjectName、SortingOrder 与取根元素的委托:
- 未指定
panel时:若恰好一个面板,直接使用;若存在多个,命令失败并列出可用面板名(Multiple runtime panels exist; specify --panel as one of: ...)。 - 指定
panel时:按PanelSettings资源名或宿主 GameObject 名匹配;无匹配则报No live runtime panel named '<panel>'. Available: ...。 - 匹配后的面板按
SortingOrder升序(先绘制、更靠后)依次查询,返回第一个命中元素,保证多面板叠加时取到的是最上层可见的匹配项。
一个值得注意的实现细节:PanelRenderer.rootVisualElement 是内部 API,无法直接访问;源码通过注册一次 RegisterUIReloadCallback(面板已初始化时回调会同步触发)捕获根元素后立即注销(CaptureRuntimeElementCommand.cs)。
若场景中根本没有活动面板,命令返回失败:No live runtime UI panels found (UIDocument or PanelRenderer). Show the UI first.——即必须先让 UI 实际显示出来才能捕获。
元素选择器语法全解析
capture_editor_element 与 capture_runtime_element 共用一套选择器解析器(VisualElementCaptureSupport.cs),它把迷你 USS 选择器映射到引擎公开的 UQueryBuilder<T> 流式 API(引擎自身的 USS 字符串解析器是内部实现,故自行解析)。
支持的语法:
| 语法 | 含义 | 示例 |
|---|---|---|
#name |
按元素 name 匹配 | #search |
.class |
按 USS 类名匹配 | .toolbar |
Type |
按类型名匹配(含基类,* 表示任意) |
Button、Label、VisualElement |
Type#name.class1.class2 |
组合(类型、id、多类名任意子集) | Button#search.primary |
| 空格 | 后代组合器 | .toolbar #search |
> |
直接子元素组合器 | #toolbar > #search |
:checked / :hover / :focus / :active |
伪状态 | #item:checked |
:enabled / :disabled |
启用/禁用状态 | #title:disabled |
:not(...) |
取反 | #title:not(disabled) |
行为细节(有测试用例背书):
- 类型匹配采用运行时类型名沿继承链向上比对(
TypeNameMatches),所以Button能命中 Button,VisualElement能命中一切元素; :disabled等价于:not(:enabled)(源码映射为NotEnabled()/Enabled());- 未知伪状态、悬空
#或.、多余 id、空选择器均解析失败,返回 null(不抛异常); - 多根(runtime 场景)下按顺序逐根查询,返回第一个命中。
这些规则均有对应的 NUnit 测试覆盖,见 CaptureVisualElementCommandsTests.cs:Resolve_ById、Resolve_ByClass、Resolve_ByType、Resolve_TypeWithNameAndClass、Resolve_DescendantChain、Resolve_ChildCombinator、Resolve_PseudoDisabledAndEnabled、Resolve_Miss_ReturnsNull、Resolve_InvalidSelector_ReturnsNull 等。
返回结构:CaptureElementResponse
元素捕获命令返回 CaptureElementResponse(VisualElementCaptureSupport.cs):
| 字段 | 类型 | 含义 |
|---|---|---|
success |
bool | 捕获是否成功 |
message |
string | 成功时的人类可读说明(失败时为错误文本) |
selector |
string | 用于定位元素的选择器 |
source |
string | 捕获来源,如 "window:Inspector" 或 "panel:MainUI" |
path |
string | PNG 写入的绝对文件系统路径 |
width / height |
int | 捕获到的像素尺寸(按元素自身尺寸,非请求尺寸) |
encoding |
string | 恒为 "png" |
base64 |
string | PNG 字节的 base64 编码 |
bytes |
int | 原始 PNG 字节数组长度 |
失败时返回 Success = false + Message(错误文本),例如 GPU 不可用、面板不可捕获、选择器未命中等;成功时 Message 形如 Captured window:Inspector to <path>。
底层原理:离屏渲染与 GPU 门控
相机/场景视图的渲染管线
capture_game_view 与 capture_scene_view 共用 EncodeCameraToPng(CaptureCommands.cs):
RenderTexture.GetTemporary(w, h, 24)申请临时深度缓冲 RenderTexture;- 把相机
targetTexture指到该 RT 上执行cam.Render(),将RenderTexture.active切到 RT; - 创建
Texture2D(w, h, TextureFormat.RGB24, false),ReadPixels回读并EncodeToPNG; - 在
finally中恢复相机的原targetTexture与全局RenderTexture.active,并ReleaseTemporary释放临时 RT——保证捕获过程绝不污染全局渲染状态。
元素捕获的渲染管线
VisualElementCaptureSupport.CaptureElementToPng(VisualElementCaptureSupport.cs)走同一条思路:element.CaptureToRenderTexture() 以元素自身像素尺寸离屏渲染 → RGBA32 Texture2D 回读 → EncodeToPNG,同样在 finally 中恢复 active RT 并释放全部临时资源。它对相机绘制(世界空间)或已脱离面板的元素会抛出 InvalidOperationException(由捕获 API 上抛),上层统一转为失败响应。
GPU 门控:headless 环境直接拒绝
两个相机类命令与元素捕获公共入口都做了 GPU 守卫:当 SystemInfo.graphicsDeviceType == GraphicsDeviceType.Null(即 batchmode/headless 无 GPU 环境)时:
- 相机命令抛出
InvalidOperationException("No GPU available (batchmode/headless); cannot capture."); - 元素捕获返回
CaptureElementResponse.Fail("No GPU available (batchmode/headless); cannot capture.")。
这样做的目的(源码注释)是让调用方拿到明确报错而不是一张全空图。因此请记住:无 GPU 的无头环境无法使用任何捕获命令;测试代码中也有对应约定——headless 下渲染类测试会 Assert.Ignore 自行跳过而非失败(见 CaptureCommandsTests.cs)。
输出路径解析与项目沙箱
- 元素命令的
output:绝对路径原样使用;相对路径基于各自基准目录(编辑器为项目根,运行时为Application.persistentDataPath)解析;空路径生成element_yyyyMMdd_HHmmss_fff.png时间戳文件(ResolveOutputPath,VisualElementCaptureSupport.cs)。 - 相机命令的
save_path:经ProjectPaths.Resolve沙箱校验后写入,并调用AssetDatabase.Refresh()让新文件立即出现在资源库中(CaptureCommands.cs)。ProjectPaths(ProjectPaths.cs)会拒绝../越权路径与任何项目根之外的写入,默认把写操作限定在Assets/作者根目录内。
如何实际调用:连接与认证
捕获命令本质是 Pipeline 命令,调用方式与其它命令一致(详见 connectivity.md):
# 连接编辑器并列出可用命令(无命令名时列出)
unity command
# 连接特定项目
unity command --project-path /path/to/your/unity/project
# 连接开发版 Player(按进程名或运行时端口文件位置)
unity command --runtime MyGame.exe runtime_status
连接建立后,客户端从端口描述文件读取 port 与 evalToken(编辑器:<项目>/Library/Pipeline/.unity-pipeline-port;运行时:Player 旁的 .unity-pipeline-runtime-port),向 http://127.0.0.1:<port>/api/exec 发起 POST,并携带 Authorization: Bearer <evalToken> 头。服务器只绑定 IPv4 回环地址(127.0.0.1),同一台机器外的任何请求都到不了它。
实战组合:Agent 驱动的"截图-验证"闭环
在 TEngine 的 AI 工作流中,捕获命令最常见的用法是给 Agent 提供视觉验收闭环:
- 打开窗口 / 进入界面:先用
editor_play、menu或场景命令把目标界面准备好; - 捕获:
capture_editor_element --window InspectorWindow --selector "#target"(编辑器内)或capture_runtime_element --panel MainUI --selector "#title"(运行时 UI); - 读取结果:从响应的
base64字段还原 PNG,或直接使用path字段指向的落盘文件; - 验证:结合视觉判断(或外部视觉模型)核对布局、配色、控件状态是否符合预期,再继续下一步操作。
元素级捕获(而非整屏截图)特别适合验证单个控件:某按钮是否处于 :checked / :hover / :disabled 状态、某 Label 是否按预期渲染。TEngine 的 AI 工作流文档也强调,PC / 移动端 / 平板布局与视觉验收必须用实际 Editor / 设备验收,不能用浏览器截图代替(见 AI-Development-Workflow.md)——捕获命令正是把"真实渲染结果"交给 Agent 的官方通道。
限制与注意事项汇总
| 约束 | 说明 |
|---|---|
| GPU 依赖 | 无 GPU 的 batchmode / headless 环境无法捕获(明确报错,避免空图) |
| 版本门槛 | capture_editor_element / capture_runtime_element 仅 Unity 6000.7+ |
| 运行环境 | capture_runtime_element 为 RuntimeOnly:编辑器的命令列表不展示它,只有连到 Runtime/Player 时才列出(仍可直接执行) |
| 主线程要求 | 两个元素命令均 MainThreadRequired = true,由服务器调度到主线程执行 |
| 分辨率上限 | 相机类命令宽高钳制在 [1, 4096],超限静默压回 |
| 多面板歧义 | 运行时存在多个面板时,capture_runtime_element 必须显式传 panel |
| 不可捕获元素 | 世界空间(相机绘制)面板、已脱离面板的元素会捕获失败 |
| 路径安全 | save_path / output 受项目沙箱约束,越权路径被拒绝 |
相关文档
- Creating commands:
[CliCommand]/[CliArg]命令声明 API 与MainThreadRequired/RuntimeOnly语义 - Connectivity:端口发现、Bearer 认证与
unityCLI 用法 - Runtime connection & setup:在开发版 Player 中启用运行时服务器的前置条件
- Editor lifecycle & observability commands:同族的
screenshot命令(按视图整屏截图) - 测试参考:CaptureCommandsTests.cs 与 CaptureVisualElementCommandsTests.cs