本项目面向“作业 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 内置规则说明、提示模板、示例，可扩展新规则与新分析策略 |

系统架构

整体链路如下：

1. MCP 客户端（Cursor / Claude Desktop / Windsurf）发起工具调用
2. Python MCP Server（FastMCP）接收调用并转发到 UE 插件
3. UE 插件执行 export_material_ir 导出材质 IR
4. Python 规则模块进行性能分析并生成报告
5. 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 工程与插件

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

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

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

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）

扩展规则

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

扩展 AI 分析策略

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

状态说明

本项目仍处于实验阶段：

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

许可证

MIT