unity-ui

**在调用本模块中的任何技能之前：**如果你要根据技能名称或描述猜测参数来调用技能，请停下——先阅读本文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已通过 recommend/schema 获得参数定义，则可直接进行 dryRun。

触发条件

• 构建 UGUI 界面
• 添加 Canvas 元素
• 排布 UI 布局
• 搭建 UGUI 界面、添加 Canvas 元素、排布 UI 布局

Unity UI 技能

将本模块用于 Unity UGUI / Canvas 工作流。它与 UI Toolkit 分开。

优先批量处理：创建 2+ 个 UI 元素时，优先使用 ui_create_batch。

运行模式

• Approval：查询类 skill（源码标记为 SkillMode.SemiAuto 的 ui_find_all）直接执行；其他创建/修改类 skill（ui_create_* / ui_set_* / ui_add_* / ui_layout_children / ui_align_selected 等，标记为 SkillMode.FullAuto）需要用户授权；授权后由服务端一步执行并返回结果。
• Auto / Bypass：所有 skill 均直接执行；Auto 模式由 AI 自行评估，Bypass 模式全部放行。
• 本模块不包含 Delete / PlayMode / Reload / 高危 skill，也没有仅限 Bypass 的拦截项。删除 UI 节点请使用 gameobject 模块。

不要（常见臆测）：

• ui_add_canvas 不存在 → 使用 ui_create_canvas
• ui_create_label 不存在 → 使用 ui_create_text
• ui_create_checkbox 不存在 → 使用 ui_create_toggle
• ui_set_color 不存在 → 对 Image/Text 使用 component_set_property，或在可用时使用专用 UI 属性 skill
• 不要混淆 UGUI（ui）与 UI Toolkit（uitoolkit）

路由：

• 对于 UXML/USS/UIDocument → 使用 uitoolkit
• 对于 XR 兼容的世界空间 Canvas 转换 → 使用 xr_setup_ui_canvas
• 创建后更新文本 → 使用 ui_set_text
• 对于布局和对齐 → 使用 ui_layout_children、ui_align_selected、ui_distribute_selected

技能

创建技能

技能	用途	关键参数
ui_create_canvas	创建 Canvas	name?、renderMode?
ui_create_panel	创建面板容器	name?、parent?、r/g/b/a?
ui_create_button	创建按钮	name?、parent?、text?、width/height?
ui_create_text	创建文本标签	name?、parent?、text?、fontSize?、r/g/b?
ui_create_image	创建图像	name?、parent?、spritePath?、width/height?
ui_create_inputfield	创建输入字段	name?、parent?、placeholder?、width/height?
ui_create_slider	创建滑块	name?、parent?、minValue?、maxValue?、value?
ui_create_toggle	创建开关	name?、parent?、label?、isOn?
ui_create_dropdown	创建下拉菜单	name?、parent?、options?、width/height?
ui_create_scrollview	创建 ScrollRect 层级结构	name?、parent?、width/height?、horizontal?、vertical?
ui_create_rawimage	创建 RawImage	name?、parent?、texturePath?、width/height?
ui_create_scrollbar	创建滚动条	name?、parent?、direction?、value?、size?
ui_create_batch	创建多个 UI 元素	items（JSON 字符串数组）

查询与布局技能

技能	用途	关键参数
ui_find_all	查找场景中的 UI 元素	uiType?、limit?
ui_set_text	更新文本内容	name、text
ui_set_rect	设置 RectTransform 大小/偏移	target、width、height、posX、posY、left/right/top/bottom?
ui_get_rect_transform	读取完整的 RectTransform 数据	target
ui_set_rect_transform	设置完整的 RectTransform 数据	锚点、轴心点、偏移、本地变换、宽/高
ui_set_rect_transform_batch	为多个元素设置完整的 RectTransform 数据	items
ui_set_anchor	应用锚点预设	target、preset?、setPivot?
ui_layout_children	垂直/水平/网格布局	target、layoutType?、spacing?
ui_align_selected	对齐当前选中项	alignment?
ui_distribute_selected	分布当前选中项	direction?

属性与效果技能

技能	用途	关键参数
ui_set_image	图像类型／填充／精灵	target、type?、fillMethod?、fillAmount?、spritePath?
ui_add_layout_element	添加 LayoutElement 约束	target、宽度／高度首选值、弹性值
ui_add_canvas_group	添加 CanvasGroup	target、alpha?、interactable?、blocksRaycasts?
ui_add_mask	添加 Mask 或 RectMask2D	target、maskType?、showMaskGraphic?
ui_add_outline	添加 Shadow／Outline 效果	target、effectType?、r/g/b/a?、distanceX/Y?
ui_configure_selectable	配置过渡／导航／颜色	target、transition?、navigationMode?、颜色值

高频默认值

Canvas 与父级关系

• ui_create_canvas 默认使用 ScreenSpaceOverlay。
• 大多数创建技能都接受 parent；如果省略，Unity 会根据实现上下文在活动 Canvas 或场景根节点下创建。
• 对于可复用的菜单组，先创建一次 Canvas，再创建一个 Panel，并将所有子控件放在该面板下。

常用创建参数

技能	高频字段
ui_create_button	text、width、height
ui_create_text	text、fontSize、r/g/b
ui_create_image	spritePath、width、height
ui_create_slider	minValue、maxValue、value
ui_create_toggle	label、isOn
ui_create_dropdown	options
ui_create_scrollview	horizontal、vertical、movementType

重要：

• 大多数创建技能不接受显式的 x/y 定位参数。
• 先创建，再使用 ui_set_rect、ui_set_anchor 或 ui_layout_children 设置位置／锚点。

完整 RectTransform 编辑

如果需要 Inspector 级别的 RectTransform 覆盖范围，而非预设，请使用 ui_set_rect_transform。

技能	参数
ui_get_rect_transform	name、instanceId、path
ui_set_rect_transform	target + anchorMinX/Y、anchorMaxX/Y、pivotX/Y、anchoredPosX/Y/Z、sizeDeltaX/Y、offsetMinX/Y、offsetMaxX/Y、localPosX/Y/Z、localRotX/Y/Z、localScaleX/Y/Z、width、height
ui_set_rect_transform_batch	items JSON 数组，包含相同的逐目标字段

ui_get_rect_transform

获取 UI 元素的完整 RectTransform 数据。

参数	类型	必填	默认值	说明
name	string	否*	null	GameObject 名称
instanceId	int	否*	0	GameObject 实例 ID
path	string	否*	null	层级路径

返回： { success, name, instanceId, path, anchorMin, anchorMax, pivot, anchoredPosition3D, sizeDelta, offsetMin, offsetMax, localPosition, localEulerAngles, localScale, rect }

ui_set_rect_transform

设置 UI 元素的完整 RectTransform 数据。

参数	类型	必填	默认值	描述
name	string	否*	null	GameObject 名称
instanceId	int	否*	0	GameObject 实例 ID
path	string	否*	null	层级路径
anchorMinX / anchorMinY	float	否	null	锚点最小值
anchorMaxX / anchorMaxY	float	否	null	锚点最大值
pivotX / pivotY	float	否	null	轴心
anchoredPosX / anchoredPosY / anchoredPosZ	float	否	null	锚定位置（3D）
sizeDeltaX / sizeDeltaY	float	否	null	尺寸增量
offsetMinX / offsetMinY	float	否	null	最小偏移
offsetMaxX / offsetMaxY	float	否	null	最大偏移
localPosX / localPosY / localPosZ	float	否	null	局部位置
localRotX / localRotY / localRotZ	float	否	null	局部欧拉旋转
localScaleX / localScaleY / localScaleZ	float	否	null	局部缩放
width / height	float	否	null	使用当前锚点的尺寸

**返回：**与 ui_get_rect_transform 返回的数据结构相同。

ui_set_rect_transform_batch

为多个 UI 元素设置完整的 RectTransform 数据。

参数	类型	必填	默认值	描述
items	json string	是	-	每个目标及其 RectTransform 字段组成的 JSON 数组

返回：{ success, totalItems, successCount, failCount, results }

布局与锚定规则

• 将控件移至标准布局位置，最快的方法是使用 ui_set_anchor。
• 锚定后需要精确调整尺寸或偏移时，使用 ui_set_rect 更合适。
• 构建垂直、水平或网格菜单时，优先使用 ui_layout_children，而不是手动定位每个子元素。

生产环境中常用的锚点预设：

• MiddleCenter 用于模态窗口／菜单面板
• TopLeft 或 TopRight 用于 HUD 角落
• StretchAll 用于全屏背景

TextMeshPro 说明

创建文本时会自动检测 TMP：

• TMP 可用 -> TextMeshProUGUI
• TMP 不可用 -> legacy Text

如果需要了解创建的是哪种类型，以便后续进行特定组件的编辑，请读取响应负载。

工作流说明

1. 首先创建 Canvas。
2. 使用面板将相关控件分组。
3. 创建菜单、HUD 组和重复使用的小组件时，优先使用 ui_create_batch。
4. 先使用锚点和布局组，再逐一手动放置子元素。
5. 创建文本时会自动检测 TextMeshPro。响应会指明是否使用了 TMP。
6. 对于世界空间游戏 UI，先在此处构建 Canvas，仅在需要时再转换为 XR。
7. ui_create_batch 主要用于批量创建，不适合精确定位。之后可通过布局或矩形／锚点调整进行微调。
8. 在当前 REST/API 层中，ui_create_batch.items 是 JSON 字符串参数，而不是原始数组对象。

最简示例

import unity_skills
import json

unity_skills.call_skill("ui_create_canvas", name="MainMenu")
unity_skills.call_skill("ui_create_panel", name="MenuPanel", parent="MainMenu", a=0.7)
unity_skills.call_skill("ui_set_rect", name="MenuPanel", width=320, height=240)
unity_skills.call_skill("ui_create_batch", items=json.dumps([
    {"type": "Button", "name": "StartBtn", "parent": "MenuPanel", "text": "Start", "width": 220, "height": 44},
    {"type": "Button", "name": "OptionsBtn", "parent": "MenuPanel", "text": "Options", "width": 220, "height": 44},
    {"type": "Button", "name": "QuitBtn", "parent": "MenuPanel", "text": "Quit", "width": 220, "height": 44}
]))

unity_skills.call_skill("ui_set_anchor", name="MenuPanel", preset="MiddleCenter")
unity_skills.call_skill("ui_layout_children", name="MenuPanel", layoutType="Vertical", spacing=12)

精确签名

确切的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而不是由此文件定义。 如需了解更详细的元素创建说明、属性表和较大的 UGUI 示例，请加载 UI_REFERENCE.md。

常见错误

完整的传输层错误代码（COMPILING/RATE_LIMIT 等）→ ../../references/protocol-error-codes.md

错误	触发条件	修复方法
TARGET_NOT_FOUND	未找到父级 GameObject、UI 元素、RectTransform、Text/Image/Selectable 组件或精灵资源。	使用 ui_find_all、gameobject_find 或 scene_get_hierarchy 定位元素，并使用 asset_find 验证精灵路径。
SEMANTIC_INVALID	提供了无效值，例如未知的锚点预设、布局类型、对齐方式，或包含分隔符的名称/路径。	根据错误上下文选择有效的预设/类型（例如 MiddleCenter、Vertical、TopLeft），然后重试。
SKILL_ERROR	基于选择的操作失败，因为选中的 UI 元素少于所需数量（例如 Select at least 2 UI elements）。	调用对齐/分布技能前，请在 Hierarchy 中选中所需的 UI 元素。