uloop-screenshot

uloop 截图

按名称截取任意 Unity EditorWindow 的屏幕截图并保存为 PNG。

用法

uloop screenshot [--window-name <name>] [--resolution-scale <scale>] [--match-mode <mode>] [--capture-mode <mode>] [--annotate-elements] [--annotate-raycast-grid] [--raycast-layer-mask <layers>] [--elements-only] [--output-directory <path>]

参数

参数	类型	默认值	描述
--window-name	string	Game	要截取的窗口名称（例如 Game、Scene、Console、Inspector）。如果最终确定的截取模式为渲染模式，则忽略此参数（Play Mode 期间的 auto 会解析为渲染模式）。如果 Game 标签页是 Device Simulator，且标题为 Simulator，则默认值 Game 会回退为 Simulator。
--resolution-scale	number	1.0	分辨率缩放比例（0.1 至 1.0）
--match-mode	enum	exact	窗口名称匹配模式：exact、prefix 或 contains。如果最终确定的截取模式为渲染模式，则忽略此参数（Play Mode 期间的 auto 会解析为渲染模式）。
--capture-mode	enum	auto	auto - 在 PlayMode 下截取渲染画面，否则截取窗口；window - 截取包含工具栏的 EditorWindow；rendering - 仅截取游戏渲染画面（需要 PlayMode）；GameView - rendering 的别名。渲染截图会返回 ScreenshotToInputFormula，用于在调用 simulate-mouse-input（包括 --dry-run）或 simulate-mouse-ui 前转换原始图像像素。
--output-directory	string	""	保存截图的输出目录路径。为空时使用默认路径（.uloop/outputs/Screenshots/）。接受绝对路径。
--annotate-elements	flag	-	为交互式 UI 元素标注索引标签和交互提示（A / CLICK、B / DRAG 等）。响应会包含一个 AnnotatedElements 数组，其中的元素元数据按 SortingOrder、再按 SiblingIndex 排序（这是对 Z 轴顺序的近似，并非保证的绘制顺序）。仅当最终确定的截取模式为渲染模式（Play Mode 期间的 auto 会解析为渲染模式）且处于 PlayMode 时有效。
--annotate-raycast-grid	flag	-	将聚类后的 3D 物理碰撞体候选项作为 AnnotatedElements 中的 PhysicsCollider 条目标注。使用 Camera.main 的可见性，并采用与 simulate-mouse-input 相同的左上角起始 Game View 坐标。仅当最终确定的截取模式为渲染模式（Play Mode 期间的 auto 会解析为渲染模式）且处于 PlayMode 时有效。
--raycast-layer-mask	string	""	以逗号分隔的物理层名称，用于缩小 --annotate-raycast-grid 的聚类范围。命中仅限于 Camera.main.cullingMask 也可见的层。省略时，按 Physics.DefaultRaycastLayers 进行聚类。
--elements-only	flag	-	仅返回标注元素的 JSON，不截取屏幕截图。需要 --annotate-elements 或 --annotate-raycast-grid，并且最终确定的截取模式为渲染模式（Play Mode 期间的 auto 会解析为渲染模式）且处于 PlayMode。

匹配模式

模式	描述	示例
exact	窗口名称必须完全匹配（不区分大小写）	"Project" 仅匹配 "Project"
prefix	窗口名称必须以输入内容开头	"Project" 匹配 "Project" 和 "Project Settings"
contains	窗口名称中必须包含输入内容	"set" 匹配 "Project Settings"

窗口名称

窗口名称是窗口标题栏（标签页）中显示的文本。常见名称包括：Game、Simulator、Scene、Console、Inspector、Project、Hierarchy、Animation、Animator、Profiler。也支持自定义 EditorWindow 标题。

设备模拟器

• 对于 annotate → click 流程，优先使用 --capture-mode rendering。它适用于常规 Game 视图和设备模拟器，且坐标与 simulate-mouse-ui / simulate-mouse-input（包括 --dry-run）一致。
• --capture-mode window 会捕获 Editor 窗口框架（工具栏／边框）。如果设备模拟器是播放视图，且没有 Game 标签页，默认的 --window-name Game 会回退到 Simulator；你也可以传入 --window-name Simulator。
• 模拟器的 Fit to Screen / Scale / Safe Area 覆盖层仅属于窗口框架，不会改变 rendering 模式下的输入坐标。设备旋转后，点击前请重新运行 annotate：旋转会改变 Game View 的大小，因此所有先前的 AnnotatedElements 条目（边界、SimX / SimY、探测和遮挡结果）都会过期。

输出

返回包含以下内容的 JSON：

• ScreenshotCount：捕获的窗口数量
• ResolvedCaptureMode："window" 或 "rendering" — 解析 auto 后实际使用的模式
• Warning：当 Play Mode 运行时捕获窗口且至少包含一张图像，以及在 Play Mode 暂停时捕获任何图像，都会显示此项（UGUI／canvas 内容可能显示暂停前渲染的帧；运行一次 uloop control-play-mode --action Step，然后重新捕获以刷新内容）。
• Screenshots：截图信息数组，每项包含：
  • ImagePath：已保存 PNG 文件的绝对路径。使用 --elements-only 时为空（""），因为不会写入图像文件；此时 FileSizeBytes、Width 和 Height 均为 0，而 GameViewWidth / GameViewHeight 和 AnnotatedElements 仍包含实际值。此项非空时，务必打开此处指定的文件 — 输出目录会累积所有历史捕获结果，因此使用目录列表（ls -t 或类似命令）猜测最新文件，可能会悄悄选中早前运行时的过期截图。
  • FileSizeBytes：已保存文件的大小（字节）
  • Width：捕获图像的宽度（像素）
  • Height：捕获图像的高度（像素）
  • ImageCoordinateSystem："top-left-game-view" 或 "top-left-window"
  • ResolutionScale：捕获时使用的分辨率缩放比例
  • ImageToInputOffsetY：用于 top-left-game-view 坐标转换的 Y 偏移量
  • GameViewWidth、GameViewHeight：捕获时以输入坐标表示的 Game View 大小 — 是 SimX / SimY 以及 simulate-mouse-input 内部 Y 轴翻转的依据。rendering 捕获时会填充，包括使用 --elements-only 的情况
  • ScreenshotToInputFormula：将原始图像像素转换为 simulate-mouse 输入坐标的公式
  • AnnotatedElements：已标注的 UI 元素元数据数组。除非使用 --annotate-elements 或 --annotate-raycast-grid，否则为空。
  • RaycastLayerSummaries / RaycastLayerNamesChecked：使用 --annotate-raycast-grid 时填充的物理层诊断信息。

使用截图坐标调用鼠标模拟工具前，请先阅读 references/annotated-elements.md，了解 AnnotatedElements / RaycastLayerSummaries 字段和 gameView 坐标转换。

当多个窗口匹配时（例如存在多个 Inspector 窗口，或使用 contains 模式时），会捕获所有匹配的窗口，并使用带编号的文件名（例如 Inspector_1_*.png、Inspector_2_*.png）。

注意事项

• 如有需要，先使用 uloop focus-window
• 目标窗口必须在 Unity Editor 中打开
• 窗口名称匹配始终不区分大小写