# 蓝图开发接口

## 接口总览

| Method | 名称 | 说明 |
| --- | --- | --- |
| **blueprint.describe** | 📋 获取结构 | 查看蓝图的组件、变量列表（修改前必用！） |
| **blueprint.create** | 创建蓝图 | 创建新的蓝图类，支持指定父类和添加组件 |
| **blueprint.add_component** | 添加组件 | 为已存在的蓝图添加新组件 |
| **blueprint.set_property** | 设置属性 | 修改蓝图默认值（CDO）或组件属性（SCS） |
| **blueprint.add_variable** | 定义变量 | 添加蓝图成员变量（支持数组/对象引用等） |
| **blueprint.get_graph** | 上帝视角 | 获取图表全貌（节点 GUID + 真实引脚名） |
| **blueprint.add_node** | 添加节点 | 添加节点并返回 pins 说明书（真实引脚名） |
| **blueprint.add_timeline** | 添加 Timeline | 添加 Timeline（创建 TimelineTemplate + Timeline 节点；Timeline 不能用 add_variable/add_node 直接创建） |
| **blueprint.connect_pins** | 逻辑连线 | 基于 node_id + pin.name 连接执行流/数据流 |
| **blueprint.compile** | 编译蓝图 | 手动触发编译并可选保存（返回 diagnostics 供自修复） |

---

## 获取蓝图结构 `blueprint.describe`
获取蓝图完整结构信息：父类、组件列表（SCS 添加 + 继承）、变量列表、编译状态。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp0","method":"blueprint.describe","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero" // 必填：蓝图名称或路径
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp0","code":200,"result":{
  "ok":true,
  "name":"BP_Hero",
  "path":"/Game/Blueprints/BP_Hero.BP_Hero",
  "parent_class":"Character",
  "parent_class_path":"/Script/Engine.Character",
  "generated_class":"/Game/Blueprints/BP_Hero.BP_Hero_C",
  "components":[
    {"name":"DefaultSceneRoot","class":"SceneComponent","class_path":"/Script/Engine.SceneComponent","source":"inherited","editable":true},
    {"name":"PointLight","class":"PointLightComponent","class_path":"/Script/Engine.PointLightComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
  ],
  "variables":[
    {"name":"WalkSpeed","type":"float","editable":true,"default_value":"600.000000"}
  ],
  "compile_status":"UpToDate"
}}
```

### 说明
- `blueprint_path` 支持短名或完整路径；若传入 `/Game/.../BP_XXX`（不带 `.BP_XXX`），插件会自动补全。
- `components[].source`：`added` 表示蓝图自身（SCS）添加，`inherited` 表示从父类 CDO 继承。
- `variables[].default_value` 仅在蓝图变量定义包含默认值时返回。
- 建议在调用 `blueprint.add_component` / `blueprint.set_property` 之前先 `blueprint.describe`，避免组件名/变量名写错。

---

## 创建蓝图资产 `blueprint.create`
创建一个新的蓝图资产，支持指定父类、保存路径，以及在创建时直接添加组件。已实现蓝图重名检测，避免覆盖已有资产导致崩溃。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp1","method":"blueprint.create","params":{
  "name":"BP_MyActor",              // 必填，蓝图名称
  "parent_class":"Actor",           // 可选，父类（默认 Actor），支持短名或完整路径
  "path":"/Game/Blueprints/BP_MyActor", // 可选，完整包路径
  "folder":"/Game/Blueprints",      // 可选，保存目录（与 path 二选一，默认 /Game/UnrealAgent/Blueprints）
  "components":[                    // 可选，创建时附带的组件列表
    {
      "component_type":"StaticMeshComponent",
      "component_name":"MyMesh",
      "attach_to":"root",           // 可选，附加到的父组件
      "location":{"x":0,"y":0,"z":100},
      "rotation":{"pitch":0,"yaw":0,"roll":0},
      "scale":{"x":1,"y":1,"z":1},
      "properties":{                // 可选，组件属性
        "CastShadow":true
      }
    }
  ]
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp1","code":200,"result":{
  "ok":true,
  "name":"BP_MyActor",
  "path":"/Game/Blueprints/BP_MyActor.BP_MyActor",
  "parent_class":"Actor",
  "parent_class_path":"/Script/Engine.Actor",
  "generated_class":"/Game/Blueprints/BP_MyActor.BP_MyActor_C",
  "saved":true,
  "components":[
    {"name":"MyMesh","class":"StaticMeshComponent","class_path":"/Script/Engine.StaticMeshComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
  ],
  "variables":[],
  "compile_status":"Dirty",
  "warnings":[]
}}
```

### 说明
- `parent_class` 支持短名（如 `Actor`、`Pawn`、`Character`）或完整类路径（如 `/Script/Engine.Actor`）。
- 若蓝图已存在，返回 `code: 409` 冲突错误，需先删除或使用 `blueprint.add_component` 修改。
- `components` 数组中每个组件会按顺序添加，`attach_to` 可指定父组件名称，留空或 `root` 则附加到根节点。
- 创建完成后自动保存到磁盘并注册到 AssetRegistry。

---

## 为蓝图添加组件 `blueprint.add_component`
为已存在的蓝图资产添加新组件，支持设置组件变换和属性。组件会被添加到蓝图的 SimpleConstructionScript 中。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp2","method":"blueprint.add_component","params":{
  "blueprint_name":"BP_MyActor",    // 必填，蓝图名称或完整路径
  "component_type":"PointLightComponent", // 必填，组件类型
  "component_name":"MyLight",       // 必填，组件名称
  "attach_to":"MyMesh",             // 可选，附加到的父组件名称（默认 root）
  "location":{"x":0,"y":0,"z":200}, // 可选，相对位置
  "rotation":{"pitch":0,"yaw":0,"roll":0}, // 可选，相对旋转
  "scale":{"x":1,"y":1,"z":1},      // 可选，相对缩放
  "component_properties":{          // 可选，组件属性
    "Intensity":5000,
    "LightColor":"(R=1,G=0.8,B=0.6,A=1)"
  }
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp2","code":200,"result":{
  "ok":true,
  "blueprint_name":"BP_MyActor",
  "blueprint_path":"/Game/Blueprints/BP_MyActor.BP_MyActor",
  "component_name":"MyLight",
  "component_class":"PointLightComponent",
  "attached":true,
  "saved":true,
  "message":"Successfully added component 'MyLight' (PointLightComponent) to blueprint 'BP_MyActor'",
  "all_components":[
    {"name":"DefaultSceneRoot","class":"SceneComponent","class_path":"/Script/Engine.SceneComponent","source":"inherited","editable":true},
    {"name":"MyLight","class":"PointLightComponent","class_path":"/Script/Engine.PointLightComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
  ]
}}
```

### 说明
- `blueprint_name` 支持短名（如 `BP_MyActor`）或完整路径（如 `/Game/Blueprints/BP_MyActor`）。
- 若蓝图不存在返回 `code: 404`；若组件名称已存在返回 `code: 409`。
- 仅 SceneComponent 及其子类支持 `location`、`rotation`、`scale` 设置。
- `attach_to` 留空或设为 `root`/`DefaultSceneRoot` 则附加到根节点。
- 添加完成后自动标记蓝图已修改并保存。

---

## 设置蓝图属性 `blueprint.set_property`
修改蓝图资产的属性，支持两种模式：
1. **CDO 模式**：`component_name` 为空时，修改蓝图类的默认值（Class Default Object）
2. **SCS 模式**：`component_name` 有值时，修改蓝图中指定组件的属性

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp3","method":"blueprint.set_property","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero", // 必填，蓝图路径
  "component_name":"PointLight",   // 可选，为空则修改 CDO，有值则修改组件
  "properties":{                   // 必填，属性键值对
    "Intensity":5000,
    "LightColor":{"r":1,"g":0.8,"b":0.6}
  },
  "auto_compile":true              // 可选，默认 true
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp3","code":200,"result":{
  "ok":true,
  "blueprint_path":"/Game/Blueprints/BP_Hero.BP_Hero",
  "blueprint_name":"BP_Hero",
  "target_type":"component",
  "component_name":"PointLight",
  "modified_properties":[
    {"property":"Intensity","type":"FloatProperty"},
    {"property":"LightColor","type":"StructProperty"}
  ],
  "failed_properties":[],
  "compiled":true,
  "saved":true,
  "message":"Successfully set 2 properties on component 'PointLight'"
}}
```

### 说明
- `blueprint_path` 支持短名或完整路径，会自动在 AssetRegistry 中查找。
- 属性名需与 UE 中的属性名完全匹配（大小写敏感），失败时会返回建议属性名。
- 支持的数据类型：基础类型（int/float/bool/string）、枚举、结构体（FVector/FRotator/FColor等）、对象引用。
- 颜色属性：使用 0-1 浮点数格式 `{r,g,b,a}`，会自动转换为 0-255 格式。
- 返回码：`200` 全部成功，`207` 部分成功，`400` 全部失败，`404` 蓝图或组件未找到。

---

## 编译蓝图 `blueprint.compile`
手动触发蓝图编译，并可选在编译成功后保存（避免写入坏蓝图）。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp4","method":"blueprint.compile","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero", // 必填：蓝图名称或路径
  "save":true                                 // 可选：默认 true，仅在编译成功时保存
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp4","code":200,"result":{
  "ok":true,
  "status":"UpToDate",
  "saved":true,
  "path":"/Game/Blueprints/BP_Hero.BP_Hero",
  "diagnostics":[
    {"type":"Warning","message":"Some warning message ...","node_id":"GUID-...","pin":"InString"}
  ]
}}
```

### 说明
- `ok` 仅表示编译结果是否为 `UpToDate`；即使 `ok:false` 也会返回 `code:200`，可通过 `status` 判断（如 `Error`）。
- `save` 只会在 `ok:true` 时执行保存。
- `diagnostics` 用于 Agent 自修复：包含 `Error/Warning/Info` 等消息，尽可能附带 `node_id`（best-effort）。

---

## 添加蓝图变量 `blueprint.add_variable`
添加蓝图成员变量（Blueprint Member Variable）。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp5","method":"blueprint.add_variable","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero",
  "name":"Health",
  "type":"float",
  "is_array":false,
  "default_value":"100.0"
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp5","code":200,"result":{
  "ok":true,
  "blueprint_path":"/Game/Blueprints/BP_Hero.BP_Hero",
  "variable":{
    "name":"Health",
    "type":"float",
    "is_array":false,
    "default_value":"100.0"
  }
}}
```

### 说明
- `type` 支持：`bool/int/int64/float/double/string/name/text/vector/rotator/color/linearcolor/object/class/soft_object/soft_class`
- `object_class`：当 `type` 为 `object/class/soft_object/soft_class` 时可指定（如 `/Script/Engine.Actor`）。
- 若变量已存在返回 `code:409`。

---

## 获取图表 `blueprint.get_graph`
获取指定图表的节点与引脚元数据（**真实引脚名**），用于“感知优先”的连线编程。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp6","method":"blueprint.get_graph","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph"
}}
```

### 响应（节选）
```json
{"ver":"1.0","type":"res","id":"bp6","code":200,"result":{
  "ok":true,
  "blueprint_path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
  "graph_name":"EventGraph",
  "nodes":[
    {
      "node_id":"GUID-...",
      "class":"K2Node_Event",
      "title":"Event BeginPlay",
      "pos_x":0,"pos_y":0,
      "pins":[{"name":"Then","dir":"Output","category":"exec","sub_category":"","is_array":false}]
    }
  ]
}}
```

### 说明
- `pins[].name` 是 **真实 pin 名**，`blueprint.connect_pins` 必须使用它，不要用 UI 的显示名/label。

---

## 添加节点 `blueprint.add_node`
在图表中添加节点，并返回 pins 说明书（含真实引脚名）。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp7","method":"blueprint.add_node","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph",
  "node_type":"Function",
  "node_name":"KismetSystemLibrary.PrintString",
  "node_position":{"x":300,"y":0}
}}
```

### 响应（节选）
```json
{"ver":"1.0","type":"res","id":"bp7","code":200,"result":{
  "ok":true,
  "blueprint_path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
  "graph_name":"EventGraph",
  "node_id":"GUID-...",
  "node_class":"K2Node_CallFunction",
  "pins":[
    {"name":"Exec","dir":"Input","category":"exec","sub_category":"","is_array":false},
    {"name":"Then","dir":"Output","category":"exec","sub_category":"","is_array":false},
    {"name":"InString","dir":"Input","category":"string","sub_category":"","is_array":false}
  ]
}}
```

### 说明
- `node_type` 当前支持：`Event / Function / VariableGet / VariableSet`
- `Event` 支持 `BeginPlay`（会自动映射为 `ReceiveBeginPlay`）。

---

## 连接引脚 `blueprint.connect_pins`
根据 `node_id` + `pin.name` 连接执行流/数据流。

### 请求（JSON-RPC）
```json
{"ver":"1.0","type":"req","id":"bp8","method":"blueprint.connect_pins","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph",
  "source_node_id":"GUID-A",
  "source_pin":"Then",
  "target_node_id":"GUID-B",
  "target_pin":"Exec"
}}
```

### 响应
```json
{"ver":"1.0","type":"res","id":"bp8","code":200,"result":{
  "ok":true,
  "message":"Connection created"
}}
```