363 lines
13 KiB
Markdown
363 lines
13 KiB
Markdown
# 蓝图开发接口
|
||
|
||
## 接口总览
|
||
|
||
| 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"
|
||
}}
|
||
```
|
||
|