SuperAPI AI 工具集

blueprint-graphs

编程与开发

查看项目

更新于 11-06 16:23

技能介绍

用途

该技能用于 Unreal Engine Blueprint 的节点级图编辑:在事件图和函数图中添加节点、连接引脚、设置引脚值与节点位置、整理布局,并读取图结构信息。它不负责创建新 Blueprint、添加变量/组件或重写函数,这些属于 blueprints 技能的范围;当需要这些操作时应一并加载 blueprints 技能。

主要能力

  • 批量建图:通过 unreal.BlueprintService.build_graph(...) 一次创建 2 个及以上节点,支持的节点类型包括 function_call、event、variable_get、variable_set、branch、print_string、member_get、validated_get 等。
  • 单节点创建:通过 call_tool 调用引擎工具集 editor_toolset.toolsets.blueprint.BlueprintTools 的 create_node,参数为 graph、type_id、pos,type_id 示例包括 'Development|PrintString'、'AddEvent|EventBeginPlay'、'AddEvent|Custom|MyEvent'、宏 'Utilities|FlowControl|ForLoop'、委托处理器 'Default|EventDispatcherOnDamaged' 等;也可在 discover_nodes() 之后用 create_node_by_key() 按 spawner key 确定性创建。
  • 连线与断开:connect_nodes 连接引脚,disconnect_pin 断开单个命名引脚上的全部连接。
  • 读取图结构:get_graph_summary() 返回固定大小的图概览(节点数、连接数、编译状态、入口点、节点类型计数);get_nodes_in_graph() 支持按最大节点数、名称/类型/ID 子串过滤,并可选择是否包含引脚。
  • 读取用户当前选择:get_selected_nodes() 返回已打开 Blueprint 编辑器中高亮的节点,返回对象与 get_nodes_in_graph() 的 FBlueprintNodeInfo 结构一致。
  • 读取聚焦上下文:get_focused_graph_context() 一次性返回当前活跃编辑器标签页对应的资产与聚焦图,适用于 Blueprint 系列编辑器和材质编辑器。
  • 注释框:add_comment_node() 指定位置与尺寸添加注释;add_comment_around_nodes() 根据给定节点包围盒加边距自动生成注释框,两者均返回新注释节点的 node_id。
  • 其他:add_custom_event_node、add_macro_instance_node、时间轴与自定义事件输入 CRUD、auto_layout_* 自动布局等;create_component_bound_event() 用于创建组件/控件绑定事件(如 OnClicked、OnValueChanged、OnComponentBeginOverlap)。

使用方式与关键约定

  • 创建节点有三种途径:优先用 build_graph 批量创建;单节点用引擎 BlueprintTools.create_node(经 call_tool);需要确定性创建时用 create_node_by_key(可先 discover_nodes 查找 spawner key)。
  • 引擎 BlueprintTools 的 call_tool 参数使用 {"refPath": "/Game/Dir/BP.BP"} 形式(需完整对象路径与 .AssetName 后缀),成功时返回 {"returnValue": null};VibeUE 自身的 unreal.BlueprintService.* 方法接受普通字符串路径。
  • 方法名易错点:用 get_nodes_in_graph 而非 list_nodes;用 disconnect_pin 而非 disconnect_nodes;用 get_connections 而非 get_node_connections;用 list_graphs / list_functions 而非 get_graphs / get_functions;用 get_node_details 或 get_node_pins + pin.is_connected 而非 get_connected_nodes;类加载用 unreal.load_class(None, "/Script/Module.ClassName")。
  • disconnect_pin 只接受 4 个参数:路径、图名、node_id、引脚名;删除特定边时断开源节点输出引脚即可。
  • 属性名易错点:用 node.node_title(不是 node_name)、node.pos_x / node.pos_y(不是 node_position_x/y)、pin.is_input(唯一方向字段)、pin.is_connected、pin.default_value(不是 current_value);不存在 pin.sub_pins。
  • 读取顺序建议:先用 get_graph_summary() 获取与图大小无关的概览,再用带过滤的 get_nodes_in_graph() 下钻,仅在确实需要全部引脚时才做完整 dump。
  • 分支节点引脚名为 then 和 else,不是 true/false。
  • UE5.7 数学节点使用 Double 版本:Greater_DoubleDouble、Add_DoubleDouble、MakeLiteralDouble;编辑器显示 "Make Literal Float" 时其 spawner 为 KismetSystemLibrary::MakeLiteralDouble,按 Float 名创建会静默失败。
  • 组件/控件绑定事件必须用 create_component_bound_event() 创建,不能用 create_node_by_key + configure_node,否则编译通过但运行时不触发;该函数幂等,已存在时返回现有节点 id。
  • Override 事件(如 EVENT Actor::ReceiveBeginPlay)与 EVENT CUSTOM::Name 是幂等的,已存在时返回现有节点 id,可直接连线。
  • discover_nodes() 返回 FBlueprintNodeTypeInfo(字段为 display_name、spawner_key、category、tooltip、is_pure、is_latent、keywords),与 get_nodes_in_graph() 返回的 FBlueprintNodeInfo(node_title 等)不同;搜索 discover_nodes 应按函数名而非变量类型。
  • 使用变量前需先在编译后的骨架类上添加变量并编译,然后才能创建 variable_get 节点。
  • Play-In-Editor 期间所有 BlueprintService 方法会静默失败并返回空结果;应先用 unreal.LevelEditorSubsystem 的 is_in_play_in_editor() 检查并停止 PIE。判断依据之一是 does_asset_exist 对已知存在的资产也返回 False。
  • get_selected_nodes() 要求 Blueprint 已在编辑器中打开,关闭编辑器会丢失选择;传入空路径时返回第一个有选择的已打开 Blueprint 编辑器中的选择。
  • get_focused_graph_context() 的字段包括 found、asset_path、asset_name、editor_type、graph_name、graph_kind、graph_node_count、selected_nodes;当 graph_kind 为 "Material" 时不适用 Blueprint 图工具,应改用 MaterialNodeService。

适用场景

适用于在 UE 编辑器中以脚本方式编辑 Blueprint 图的节点层工作,例如批量搭建节点流程、连接/断开引脚、读取图结构与选择、为节点组添加有意义的注释文档、创建组件绑定事件与自定义事件节点、自动布局等。

限制

  • 不覆盖创建 Blueprint、添加变量/组件、重写函数,需配合 blueprints 技能。
  • PIE 运行期间不可用且静默失败,必须先停止 PIE。
  • get_selected_nodes() 依赖编辑器已打开资产,关闭后选择丢失。
  • 材质编辑器的图工具不适用,需使用 MaterialNodeService。
  • blueprint-fundamentals 的 UE 领域知识依赖外部 MCP 工具 unreal-engine-skills-manager;该工具不存在时(如 Claude Code 或 Codex 环境)应跳过相关调用,仅使用本技能。