SuperAPI AI 工具集

niagara-systems

编程与开发

查看项目

更新于 11-06 16:23

技能介绍

用途

Niagara Systems 是一个面向虚幻引擎 Niagara 粒子系统的操作技能,用于在编辑器内快速调参、排查问题,并编写 Custom HLSL 暂存板模块图。它并不替代引擎自带的 Niagara 工具集,两者分工明确:引擎侧负责系统/发射器/参数的增删改查与编译,本技能负责引擎工具集未覆盖的快速迭代参数调节、诊断,以及暂存板图编写。

架构与职责划分

VibeUE 扩展虚幻引擎原生 MCP 端点。系统、发射器、参数的创建/添加/复制/移除/列出/编译由引擎工具集 NiagaraToolsets.NiagaraToolset_System(以及 _Assets、_Component、_Blueprint、_Info)通过 call_tool 调用完成。VibeUE 的 NiagaraService 只保留快速迭代参数读写与诊断,NiagaraScratchPadService 则提供独有的 Custom-HLSL 图编写能力。

技能加载通过引擎的 AgentSkillToolset(ListSkills / GetSkills)完成,没有独立的 vibeue-skills-manager 工具。调用 VibeUE 各服务的主要方式是 execute_python_code(调用 unreal.<Service>.<method>() 及完整 unreal.* Python API);引擎工具集通过 call_tool 访问,可用 list_toolsets / describe_toolset 发现。

主要能力(VibeUE NiagaraService)

  • 快速迭代参数:list_rapid_iteration_params 列出某个发射器的快速迭代参数及其脚本类型和当前值;set_rapid_iteration_param 一次性写入所有匹配阶段(推荐用于颜色类参数);set_rapid_iteration_param_by_stage 在参数存在于多个阶段时只写入指定阶段(如 ParticleUpdate)。
  • 诊断:compare_systems 比较两个系统并输出差异数量与逐项差异;get_emitter_lifecycle 返回发射器的循环行为与生命周期模式;debug_activation 用于排查系统为何没有播放。

user.* 与 System.* 参数、系统级设置和编译不在 NiagaraService 内,需通过引擎 NiagaraToolsets 的参数工具读写。发射器颜色/曲线编写属于 niagara-emitters 技能;暂存板模块图(Custom HLSL、Map Get/Set、Op、类型化引脚、连线)由 NiagaraScratchPadService 处理。

使用方式

先通过 list_toolsets 和 describe_toolset 查看引擎 Niagara 工具集的确切工具名与参数结构,再用 call_tool 调用。参数调优示例:先用 unreal.NiagaraService.list_rapid_iteration_params(path, "Sparks") 打印每个参数的脚本类型、名称和值,确认精确参数名后再写入;调优结束后通过引擎工具集编译,或用 unreal.EditorAssetLibrary.save_asset(path) 持久化。新建系统后应立即执行 save_asset(path, only_if_is_dirty=False) 并确认磁盘上 .uasset 存在(does_asset_exist),因为新系统可能未挂根而被垃圾回收。创建系统前应先用 …_Info / …_Assets 工具集搜索并查看现有系统,把现有特效复制为模板前需征得用户同意。

注意事项与限制

  • 用户参数崩溃风险:引擎 NiagaraToolset_System.AddUserVariables 在变量类型/默认值不产生字节负载时可能触发致命断言(NiagaraVariant.cpp:108 InCount > 0),直接导致编辑器崩溃;被失败操作半修改的系统在后续读取(GetUserVariables、GetSystemCompileState、GetEmitterTopology、GetEmitterSummary 等)时会因数组越界崩溃。在问题修复前不要通过该工具添加用户参数;如确需,必须为确切类型提供非空的具体默认值,并在继续操作前验证系统仍可正常读取。暂存板相关操作优先使用经扫描验证的 NiagaraScratchPadService。
  • AddUserVariables 即使成功也可能返回 null(issue #557),null 不代表失败,写入后需用 GetUserVariables 复核。
  • 新建精灵渲染器默认 Material=None 因而不可见;AddVelocityInCone 的 Velocity Strength 默认为 0;应使用 V2 InitializeParticle 模块并通过 SetStackInputData 驱动模式输入。
  • 用户参数类型需使用 Niagara 规范类型名(如 Float、Int、Vector、LinearColor,或 NiagaraDataInterfaceArrayFloat3 等数据接口类名),不要臆造类似 "array(float3)" 的字符串;数据接口类型的默认值会被忽略并自动分配默认实例。