# ui

> UI 操作。节点: ui_create_control, ui_container_add, ui_build_layout。布局: ui_set_layout, ui_get_layout, ui_anchor_preset。原型: ui_import_prototype(几何 JSON 一次调用翻译+构建+测量+校验+持久化;bg/fill/borderRadius/border→StyleBoxFlat,落盘 theme_override_styles/<slot>;返回 style_verify 逐槽位样式 diff/flow_verify flow 直接子层 rect diff)。像素终验: ui_pixel_verify(bg 节点截图采样 vs 目标色 RGB 距离;Windows 窗口模式会弹窗,几何+style_verify 全绿后跑一次)。主题: ui_set_theme, theme_create, theme_set_property。绘图: ui_draw_recipe。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | danger-api |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 否 |

## Actions

- `ui_create_control`
- `ui_set_layout`
- `ui_get_layout`
- `ui_anchor_preset`
- `ui_set_theme`
- `ui_container_add`
- `ui_draw_recipe`
- `ui_build_layout`
- `ui_measure_layout`
- `ui_import_prototype`
- `ui_pixel_verify`
- `theme_create`
- `theme_set_property`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (13 项) | ✓ | 操作类型 |
| `project_path` | string |  | Godot 项目目录路径 |
| `scene_path` | string |  | 场景路径（相对项目路径）。ui_set_theme/theme_set_property 可选;ui_pixel_verify: 必填,已构建场景(ui_import_prototype persist 产物) |
| `node_path` | string |  | 节点路径（ui_set_layout/ui_get_layout/ui_anchor_preset/ui_set_theme/ui_container_add/ui_draw_recipe） |
| `node_type` | enum (29 项) |  | ui_create_control/ui_container_add: Control 子类类型 |
| `node_name` | string |  | ui_create_control: 新节点名称 |
| `parent_node_path` | string |  | ui_create_control: 父节点路径（默认 root） |
| `properties` | object |  | ui_create_control: 可选属性（支持 string/number/bool/null） |
| `anchors` | object |  | ui_set_layout: 锚点 {left, right, top, bottom}，值 0-1 |
| `offsets` | object |  | ui_set_layout: 边距 {left, right, top, bottom}，像素值 |
| `min_size` | object |  | ui_set_layout: 最小尺寸 {x, y} |
| `custom_minimum_size` | object |  | ui_set_layout: 自定义最小尺寸 {x, y} |
| `grow_direction` | enum (5 项) |  | ui_set_layout: 增长方向 |
| `preset` | enum (16 项) |  | ui_anchor_preset: 锚点预设名称 |
| `theme_action` | enum (4 项) |  | ui_set_theme: 操作类型（set_params/create/save/load） |
| `theme_path` | string |  | ui_set_theme: Theme 资源路径（save/load 时必填） |
| `params` | object |  | ui_set_theme(set_params): 键值对（number/bool/string/array[4]→Color） |
| `child_type` | enum (29 项) |  | ui_container_add: 子节点 Control 类型 |
| `child_name` | string |  | ui_container_add: 子节点名称 |
| `child_properties` | object |  | ui_container_add: 子节点属性（支持 string/number/bool/null） |
| `theme_create_action` | enum: create | extract |  | theme_create: 操作类型（create 创建空 Theme | extract 从节点提取） |
| `source_node_path` | string |  | theme_create(extract): 源节点路径 |
| `save_path` | string |  | theme_create: 可选保存路径（res://themes/xxx.tres） |
| `theme_node_path` | string |  | theme_set_property: 拥有 Theme 的节点路径 |
| `item_type` | enum (4 项) |  | theme_set_property: 属性类型 |
| `prop_name` | string |  | theme_set_property: 属性名 |
| `theme_type` | string |  | theme_set_property: Theme 类型名（可选） |
| `value` | any |  | theme_set_property: 属性值（default_font/stylebox 为资源路径，color 为 [r,g,b,a]，constant 为数字） |
| `ops` | array |  | ui_draw_recipe: 绘图操作数组（最多 200 个） |
| `max_depth` | number |  | ui_measure_layout: 最大遍历深度(默认 16,上限 64) |
| `expect_tree` | object |  | ui_measure_layout: 可选目标树(同 ui_build_layout tree,含 rect);提供时输出逐节点 diff/重叠/越界 |
| `geometry` | object |  | ui_import_prototype/ui_pixel_verify: 原型几何 JSON(inline,{viewport,nodes},扁平视口坐标;与 geometry_path 二选一,同时给时本参优先;样式字段:bg/fill(ProgressBar fill 槽色)/borderRadius(number 或 {tl,tr,br,bl})/border({width,color})→StyleBoxFlat 四控件槽位(Panel/ProgressBar/Button/Label)) |
| `geometry_path` | string |  | ui_import_prototype/ui_pixel_verify: 几何 JSON 文件路径(相对项目,支持 res:// 前缀;与 geometry 二选一) |
| `tolerance` | number |  | ui_import_prototype: layout_verify 容差(px,默认 2) |
| `parent_path` | string |  | ui_build_layout: 父节点路径;ui_import_prototype: 须为原点对齐(global_position≈0,0)的节点,默认 root——非原点挂载时 layout_verify 根级条目期望按视口原点求解,根级 diff 恒误报 |
| `tree` | object |  | ui_build_layout: UI 节点树（最大深度 10）;节点可带 styleboxes: [{slot: panel|normal|background|fill|hover|pressed|disabled, box: {bg_color:[r,g,b,a]0-1, corner_radius: 数值或{tl,tr,br,bl}, border_width, border_color, draw_center}}]→add_theme_stylebox_override(StyleBoxFlat) |
| `load_autoloads` | boolean |  | 是否加载 Autoload 上下文（默认 true） |
| `viewport` | object |  | ui_build_layout: 根节点 rect 的求解基准 {w, h}(默认 1280x720,须为正数;与项目 display/window/size 一致时根 rect 即视口绝对几何);ui_import_prototype: 可选,默认取 geometry.viewport |
| `persist` | boolean |  | ui_build_layout: 持久化到 .tscn（原子写；默认 false 运行时） |

## 风险分布

读 2 / 写 11

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->