test-ue-project/Plugins/UnrealAgentLink/Resources/Docs/蓝图节点开发接口文档.md

蓝图节点开发接口文档

本文档聚焦 蓝图“逻辑与图表（EventGraph）” 开发能力：变量、节点、连线，以及用于闭环自修复的编译诊断。

核心原则（强制）：

1. 不要猜引脚名：连线必须使用 blueprint.add_node 或 blueprint.get_graph 返回的 pins[].name（真实引脚名），禁止使用 UI 显示名/label。
2. node_id 是唯一引用：后续连线/修复必须基于 node_id（GUID），不要依赖“节点标题文本”。

---

接口总览（节点/图表）

Method	名称	说明
blueprint.create_function	创建函数	创建自定义函数图表（Functions），可定义输入/输出参数
blueprint.add_variable	定义变量	添加蓝图成员变量（可选数组/对象引用/软引用）
blueprint.get_graph	上帝视角	获取图表全貌（节点 GUID + 真实引脚名）
blueprint.add_node	添加节点	添加 Event/Function/VariableGet/VariableSet，并返回 pins 说明书
blueprint.add_timeline	添加 Timeline	添加 Timeline（创建 TimelineTemplate + Timeline 节点），并返回 pins 说明书
blueprint.connect_pins	逻辑连线	基于 node_id + pin.name 连接执行流/数据流
blueprint.compile	编译与诊断	编译并返回 diagnostics（用于自修复闭环）

---

0. 创建函数图表 blueprint.create_function

用于创建一个新的函数图表（Functions），并可选定义输入/输出参数。创建成功后，返回该函数图表名与入口/返回节点 GUID，供后续在该函数图表中编写逻辑（graph_name）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_create_fn","method":"blueprint.create_function","params":{
  "blueprint_path":"/Game/BP_MyHero",
  "function_name":"CalculateHealth",
  "inputs":[
    {"name":"BaseValue","type":"Float"},
    {"name":"Multiplier","type":"Float"}
  ],
  "outputs":[
    {"name":"FinalResult","type":"Float"}
  ],
  "pure":false
}}

响应

{"ver":"1.0","type":"res","id":"bp_create_fn","code":200,"result":{
  "ok":true,
  "graph_name":"CalculateHealth",
  "entry_node_id":"GUID-Entry...",
  "result_node_id":"GUID-Result..."
}}

说明

• graph_name 就是函数图表名；后续 blueprint.get_graph / add_node / connect_pins 的 graph_name 传这个值即可在函数内部编写逻辑。
• inputs/outputs 的 type 支持与 blueprint.add_variable 相同；若传入不支持类型会被忽略（并在日志中提示）。
• pure:true 为 best-effort（不同 UE 版本内部字段不同）；若发现仍有 Exec 引脚，可用 compile.diagnostics 与图表检查确认。

---

1. 添加蓝图变量 blueprint.add_variable

添加蓝图成员变量（Blueprint Member Variable）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_add_var","method":"blueprint.add_variable","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero",
  "name":"Health",
  "type":"float",
  "is_array":false,
  "default_value":"100.0"
}}

对象/类引用示例

{"ver":"1.0","type":"req","id":"bp_add_var2","method":"blueprint.add_variable","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero",
  "name":"TargetActor",
  "type":"object",
  "object_class":"/Script/Engine.Actor"
}}

响应

{"ver":"1.0","type":"res","id":"bp_add_var","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"
  }
}}

参数说明

• blueprint_path：蓝图路径或短名（会自动在 AssetRegistry 中查找）。
• name：变量名。
• 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），缺省为 /Script/Engine.Object。
• is_array：是否数组（默认 false）。
• default_value：默认值（字符串形式；UE 会按蓝图变量默认值规则解析）。

错误码

• 400：参数缺失/类型不支持
• 404：蓝图或类找不到
• 409：变量已存在

---

2. 获取图表全貌 blueprint.get_graph

获取指定图表的节点列表与引脚元数据（真实引脚名）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_get_graph","method":"blueprint.get_graph","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph"
}}

graph_name 可省略，默认 EventGraph。若要读取函数图表（例如 CalculateHealth），请将 graph_name 设置为函数名。

响应（节选）

{"ver":"1.0","type":"res","id":"bp_get_graph","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,"is_reference":false,"is_const":false}
      ]
    }
  ]
}}

字段说明

• nodes[].node_id：节点 GUID（后续连线/定位必须用它）。
• nodes[].pins[]：
  • name：真实 pin 名（连线必须用它）
  • dir：Input/Output
  • category/sub_category/sub_category_object：Pin 类型元数据
  • friendly_name：UI 友好名（仅供展示，不要用来连线）

---

3. 添加节点 blueprint.add_node

在图表中添加节点，并返回该节点的 pins 说明书（真实引脚名）。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_add_node","method":"blueprint.add_node","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph",
  "node_type":"Event",
  "node_name":"BeginPlay",
  "node_position":{"x":0,"y":0}
}}

添加函数节点示例（PrintString）

{"ver":"1.0","type":"req","id":"bp_add_node2","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}
}}

响应（节选）

{"ver":"1.0","type":"res","id":"bp_add_node2","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,"is_reference":false,"is_const":false},
    {"name":"Then","dir":"Output","category":"exec","sub_category":"","is_array":false,"is_reference":false,"is_const":false},
    {"name":"InString","dir":"Input","category":"string","sub_category":"","is_array":false,"is_reference":false,"is_const":false}
  ]
}}

参数说明

• node_type 当前支持：
  • Event：事件（常用 BeginPlay 会自动映射为 ReceiveBeginPlay）
  • Function：函数调用（建议使用 ClassName.FunctionName 形式，如 KismetSystemLibrary.PrintString）
  • VariableGet / VariableSet：变量 Get/Set（node_name 填变量名）
• node_position：可选 {x,y}。

错误码

• 400：参数缺失/不支持的 node_type
• 404：蓝图/图表/函数/变量找不到

---

3.1 添加 Timeline blueprint.add_timeline

Timeline（时间轴）是蓝图里的特殊资源：

• 不能用 blueprint.add_variable 直接创建
• 也不适合走 blueprint.add_node 的普通节点创建流程

本接口会：

1. 在 Blueprint 上创建（或复用）同名 TimelineTemplate
2. 在指定图表中放置 Timeline 节点并绑定该模板
3. 返回该节点的 pins（真实 pin 名）用于后续连线

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_add_timeline","method":"blueprint.add_timeline","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "graph_name":"EventGraph",
  "timeline_name":"TL_Move",
  "node_position":{"x":600,"y":0},
  "reuse_existing":true
}}

响应（节选）

{"ver":"1.0","type":"res","id":"bp_add_timeline","code":200,"result":{
  "ok":true,
  "blueprint_path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
  "graph_name":"EventGraph",
  "timeline_name":"TL_Move",
  "node_id":"GUID-...",
  "node_class":"K2Node_Timeline",
  "template_created":true,
  "pins":[
    {"name":"Play","dir":"Input","category":"exec","sub_category":"","is_array":false,"is_reference":false,"is_const":false}
  ]
}}

参数说明

• timeline_name：Timeline 名称（建议 TL_ 前缀，避免与变量/函数重名）。
• reuse_existing：默认 true，若图表中已存在同名 Timeline 节点则直接复用返回（幂等）。
• node_position/force_position：与 blueprint.add_node 同语义；若不传位置，会自动放置在图表右侧。

---

4. 连接引脚 blueprint.connect_pins

基于 node_id + pin.name 连接执行流/数据流。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_connect","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"
}}

响应

{"ver":"1.0","type":"res","id":"bp_connect","code":200,"result":{
  "ok":true,
  "message":"Connection created"
}}

说明

• 连接前请确保 pin 名来自 get_graph/add_node 的 pins[].name。
• 当连接被 schema 判定为不允许时，会返回 code:400，并在错误 message 中包含原因。

---

5. 编译与诊断 blueprint.compile

编译蓝图，并返回 diagnostics 用于自修复闭环。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"bp_compile","method":"blueprint.compile","params":{
  "blueprint_path":"/Game/Blueprints/BP_Greeter",
  "save":true
}}

响应（含 diagnostics）

{"ver":"1.0","type":"res","id":"bp_compile","code":200,"result":{
  "ok":false,
  "status":"Error",
  "saved":false,
  "path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
  "diagnostics":[
    {"type":"Error","message":"Pin 'InString' is missing a connection ...","node_id":"GUID-...","pin":"InString"}
  ]
}}

说明

• ok 仅表示编译结果是否为 UpToDate；即使 ok:false 也会返回 code:200，请以 status + diagnostics 做闭环修复。
• diagnostics[].node_id/pin 为 best-effort（在 UE5.0 可能无法总是绑定到对象 token）。

---

SOP 示例：BeginPlay 打印 Hello（闭环）

1. blueprint.add_node(Event, BeginPlay) → 得到 NODE_A 与 pins（拿到真实 Then）
2. blueprint.add_node(Function, KismetSystemLibrary.PrintString) → 得到 NODE_B 与 pins（拿到真实 Exec/InString）
3. blueprint.connect_pins(NODE_A.Then -> NODE_B.Exec)
4. （可选）补一个字符串常量节点并把输出连到 NODE_B.InString，或用默认值
5. blueprint.compile()
   • 若 ok:true：完成
   • 若 ok:false：读取 diagnostics，修正节点/引脚/连线后再次 compile