TEngine 内置 Unity Pipeline 捕获命令实战指南:让 AI Agent 无显示环境"看见"Unity 编辑器

原创2026-10-14 20:29:511,702 阅读
文章标签:游戏开发

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):

  1. 若传了 camera 名字,先在 Camera.allCameras(仅包含启用的相机)中按名字匹配;没找到再扫描所有已加载的相机(含禁用相机),这样即使目标相机当前禁用、只要显式指名也能捕获;
  2. 未指名时优先 Camera.main;
  3. 否则取 Camera.allCameras 中第一个启用的相机;
  4. 全都匹配不到时,命令抛出 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):

  1. RenderTexture.GetTemporary(w, h, 24) 申请临时深度缓冲 RenderTexture;
  2. 把相机 targetTexture 指到该 RT 上执行 cam.Render(),将 RenderTexture.active 切到 RT;
  3. 创建 Texture2D(w, h, TextureFormat.RGB24, false),ReadPixels 回读并 EncodeToPNG;
  4. 在 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 提供视觉验收闭环:

  1. 打开窗口 / 进入界面:先用 editor_play、menu 或场景命令把目标界面准备好;
  2. 捕获:capture_editor_element --window InspectorWindow --selector "#target"(编辑器内)或 capture_runtime_element --panel MainUI --selector "#title"(运行时 UI);
  3. 读取结果:从响应的 base64 字段还原 PNG,或直接使用 path 字段指向的落盘文件;
  4. 验证:结合视觉判断(或外部视觉模型)核对布局、配色、控件状态是否符合预期,再继续下一步操作。

元素级捕获(而非整屏截图)特别适合验证单个控件:某按钮是否处于 :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 受项目沙箱约束,越权路径被拒绝

相关文档

登录后查看全文
TEngine