用途:在 Unreal Engine 编辑器中编写或扩展 toolset——一组通过 ToolsetRegistry 注册、经 MCP 服务器暴露给 AI 调用的静态函数,用于扩大 Claude 在编辑器内可执行的操作范围。
设计原则:API 应简洁(不照搬 Unreal 现有复杂接口)、完整(支持 CRUD 对称)、可组合(同类操作使用一致类型)、DRY(不重复实现,如 ObjectTools 已提供通用 UObject 属性读写)。
编写前先确认:功能是否已存在(可用 MCP 的 list_toolsets、describe_toolset 查询,或搜索代码库中的 Toolsets 目录);需求是否比表面更通用;是否应加入已有 toolset;是否需要独立插件;选择 Python 还是 C++(Python 迭代更快,需检查 PythonStub/unreal.py,必要时在项目设置中启用 Python 开发者模式;C++ 适用于 Python 覆盖不足时)。若两种语言都缺少所需 API,应停止并告知用户扩展引擎,不要绕过。
通用约定:不重复已有工具;必须编写文档;使用真实类型(由 ToolsetRegistry 自动序列化,避免在调用内转换 JSON 字符串);返回值承载数据而非状态,出错应抛出异常而非返回布尔或错误字符串;所有工具方法为静态;必须有测试覆盖。
C++:继承 UToolsetDefinition,每个 .h/.cpp 一个类,AI 可调用方法用 UFUNCTION(meta=(AICallable)),私有辅助函数省略该宏。异步工具返回 UToolCallAsyncResult 子类,成功调用 SetValue()、失败调用 SetError()。注册通常在模块 StartupModule/ShutdownModule 中调用 RegisterToolsetClass/UnregisterToolsetClass。自定义 JSON 转换器需继承 FToolsetJsonConverter,仅在确有需要时使用。错误处理用 RaiseScriptError 并立即返回空值。测试用 BEGIN_DEFINE_SPEC/END_DEFINE_SPEC,运行前先用 LiveCodingToolset.CompileLiveCoding 编译。
Python:类用 @unreal.uclass() 装饰并继承 unreal.ToolsetDefinition,每个 .py 一个类,工具用 @toolset_registry.tool_call 加 @staticmethod,docstring 即 AI 可见描述,参数与返回值必须有类型注解,使用标准 Python 类型(如 list[str])而非 unreal.Array。
限制:资料未提供具体收费、价格、平台支持范围等信息;部分内容(如 Python 测试细节)在给定资料中未完整展开。