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

蓝图开发接口

接口总览

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）

{"ver":"1.0","type":"req","id":"bp0","method":"blueprint.describe","params":{
  "blueprint_path":"/Game/Blueprints/BP_Hero" // 必填：蓝图名称或路径
}}

响应

{"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）

{"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
      }
    }
  ]
}}

响应

{"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）

{"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)"
  }
}}

响应

{"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）

{"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
}}

响应

{"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）

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

响应

{"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）

{"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"
}}

响应

{"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）

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

响应（节选）

{"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）

{"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}
}}

响应（节选）

{"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）

{"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"
}}

响应

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