UE AI 材质节点性能分析工具

unreal-mcp / material-performance

本项目面向“作业 3：UE AI 分析材质节点性能工具”，实现了一个运行在 Unreal Engine 上的材质性能分析闭环：

从 UE 材质图中解析节点连接关系与运算逻辑（IR）
使用规则 + AI 工作流分析连接合理性、重复与冗余计算
输出可视化性能分析报告（问题定位、严重级别、优化建议）
将分析逻辑沉淀为可复用 Skills，便于 TA 后续拓展迭代

作业要求映射

| 作业要求 | 本项目实现 | |----------|------------| | 基于 UE API 或文本方式解析材质节点关系与逻辑 | UE 插件提供 export_material_ir，导出 Material IR v1.0，包含表达式节点、输入连接、材质输出连接等结构化信息 | | AI 分析连接合理性、识别重复 / 冗余计算 | analyze_material 串联 IR 导出与规则分析；当前已支持重复纹理采样、冗余常量运算、重复子树、未使用节点等检测 | | 输出可视化性能分析报告（含问题定位、优化建议） | 生成统一 JSON 报告（summary、rule_findings、health_score），并通过 Web 页面可视化展示 | | 沉淀分析规则为可复用 Skills 模块，支持 TA 二次迭代开发 | Skills/material-performance 内置规则说明、提示模板、示例，可扩展新规则与新分析策略 |

系统架构

整体链路如下：

MCP 客户端（Cursor / Claude Desktop / Windsurf）发起工具调用
Python MCP Server（FastMCP）接收调用并转发到 UE 插件
UE 插件执行 export_material_ir 导出材质 IR
Python 规则模块进行性能分析并生成报告
Web 报告页面进行图与问题可视化展示

核心能力

1) 材质 IR 导出

工具：export_material_ir(asset_path)
IR 文档：Docs/material_ir_v1.0.md
关键字段：
- schema_version
- asset_path
- inputs（材质输出端连接）
- expressions（节点及其输入连接）

2) 材质性能分析

工具：analyze_material(asset_path)
实现文件：Python/tools/material_tools.py
分析方式：先导出 IR，再执行规则集合，最后汇总为报告

当前内置规则包含：

duplicate_subtree：检测重复子图 / 重复计算结构
unused_nodes：检测未参与最终输出的节点
duplicate_texture_sample：检测同纹理多次采样
redundant_constant_operation：检测常量冗余计算（如乘 1、加 0）

3) 报告生成与可视化

报告 schema：Docs/report_schema_v1.0.md
报告核心字段：
- summary（统计与健康分）
- rule_findings（问题列表、严重级别、关联节点 GUID）
- ai_issues（AI 深度分析预留位）
Web 页面：Web/index.html

4) Skills 沉淀与复用

Skills 目录：Skills/material-performance
主要内容：
- SKILL.md（技能说明）
- rules/（规则规范）
- prompts/（分析提示模板）
- examples/（正反例）

目录结构

MCPGameProject/：UE 示例工程
MCPGameProject/Plugins/UnrealMCP/：UE 插件源码（命令接收、IR 导出）
Python/unreal_mcp_server.py：MCP Server 入口
Python/tools/material_tools.py：材质工具（IR 导出、分析）
Python/material_rules/：规则注册、规则执行、报告生成
Web/：报告可视化页面
Skills/material-performance/：可复用分析技能
Docs/：IR 与报告格式文档

快速开始

环境要求

Unreal Engine 5.5+
Python 3.12+
MCP 客户端（Cursor / Claude Desktop / Windsurf）

1. 启动 UE 工程与插件

打开 MCPGameProject/MCPGameProject.uproject
生成 Visual Studio 工程文件并编译 Development Editor
在编辑器中确认 UnrealMCP 插件已启用

如果集成到你自己的 UE 项目：

拷贝 MCPGameProject/Plugins/UnrealMCP 到你的 Plugins/ 目录
启用插件并重启编辑器
重新生成工程并编译

2. 启动 Python MCP Server

请参考 Python/README.md 配置并启动服务。

3. 配置 MCP 客户端

参考如下配置（路径按本机修改）：

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/Python>",
        "run",
        "unreal_mcp_server.py"
      ]
    }
  }
}

示例见 mcp.json。

4. 调用材质分析

示例调用：

analyze_material(asset_path="/Game/StarterContent/Materials/M_Brick_Clay_Beveled")

返回结果包含：

规则命中问题
问题关联节点 GUID
健康分 health_score
优化建议文本

5. 打开 Web 报告界面

进入 Web/ 目录启动服务后，在浏览器打开页面查看图结构与问题定位结果。

可扩展开发（面向 TA）

扩展规则

在 Python/material_rules/rules.py 新增规则函数
在 Python/material_rules/registry.yaml 注册规则
在 Skills/material-performance/rules/ 补充规则文档

扩展 AI 分析策略

在 Skills/material-performance/prompts/ 增加提示模板
在报告中扩展 ai_issues 结构与来源
在 Web 界面增加 AI 问题分类与筛选

状态说明

本项目仍处于实验阶段：

API 与输出格式可能调整
规则与 AI 判定会持续迭代
建议用于课程作业、研究和原型验证场景

许可证

MIT

MCP Servers