# Blender↔UE Bridge v2

AI 驱动的 Blender ↔ Unreal Engine 全流程桥接系统，通过 MCP 协议统一控制两个引擎。

**v2 核心升级**（对比 v1）：
- ✅ **自带 Blender Addon**（零依赖，线程安全）— 不再依赖外部 MCP 插件
- ✅ **分层工具**：宏层（墙/屋顶/门窗/楼梯）→ 原子层 → 验证层 → 视觉层
- ✅ **真实拓扑建模**：墙壁门窗开洞为四边面构造，非堆叠方块
- ✅ **网格质量检查**：非流形边/孤立顶点/零面积面/质量评分
- ✅ **测量与断言**：距离/间隙/对齐/接触验证
- ✅ **AI 动画层**：关键帧/约束/刚体物理/相机运镜（环绕/推拉/转盘）/多帧视觉验证/渲染
- ✅ **7 个专家提示词**：拓扑/尺度/PBR 材质/灯光/自审/动画工作流
- ✅ **线程安全协议**：长度前缀 JSON + 主线程队列 + 大操作直连
- ✅ **83 个 MCP 工具**（v1 为 27 个）

## 架构

```
Claude Code / AI Client
        │
        ▼ (MCP stdio)
┌─────────────────────────┐
│  Blender↔UE Bridge      │
│  MCP Server (FastMCP)   │
├────────────┬────────────┤
│ Blender    │ UE         │
│ Client     │ Client     │  ← JSON over TCP
└──────┬─────┴──────┬─────┘
       │ TCP:9876  │ TCP:55557
       ▼           ▼
┌──────────────┐ ┌──────────┐
│ blender_addon│ │ Unreal   │
│ (Blender 插件)│ │ MCP 插件 │
│ 线程安全队列  │ │          │
└──────────────┘ └──────────┘
```

**Blender 通信协议**：4 字节大端长度头 + UTF-8 JSON
- 常规命令：入队 → 返回排号 → 客户端轮询（主线程安全）
- 大操作（导出/烘焙）：标记 `large` → 专用线程执行 → 直接回写
- 自动重试：addon 重启后可自动恢复连接

## 安装

### 前置要求
- Python 3.11+
- Blender 4.0+（只装了 `bpy` 就够 — addon 零依赖）
- Unreal Engine 5.3+（UnrealMCP 插件已启用）

### 步骤

1. **安装 Blender Addon**：
```bash
cd blender-ue-bridge
python scripts/install_addon.py          # 自动检测 Blender 版本目录
# 或指定: python scripts/install_addon.py --blender-version 4.2
# 或打包: python scripts/install_addon.py --zip blender_addon.zip
```
然后在 Blender 中启用：**编辑 > 偏好设置 > 插件 > 搜索 "BlenderUE Bridge" > 勾选**。
启用后 Sidebar 右侧出现 "Bridge" 面板显示服务器状态。

2. **安装 MCP 依赖**：
```bash
pip install mcp fastmcp
```

3. **配置 Claude Code MCP**：
```bash
python scripts/setup_mcp.py install
```

4. **测试连接**：
```bash
python scripts/test_bridge.py    # 端到端测试 (需 Blender 运行中)
python scripts/test_protocol.py  # 协议层测试 (无需 Blender)
```

5. **演示**：
```bash
python scripts/demo_precision.py         # 精确建模演示 (中世纪村庄)
python scripts/demo_precision.py --to-ue  # 构建后导入 UE
```

## MCP 工具总览 (62 个)

### 宏层 — LLM 首选（任务级，已验证拓扑）

| 工具 | 说明 |
|------|------|
| `create_wall` | 墙壁（真实门窗开洞，全四边面） |
| `create_roof` | 屋顶（gable/hip/flat/pyramid，带挑檐） |
| `create_door` / `create_window` | 门（框+扇+把手）/ 窗（框+玻璃+竖棂+窗台） |
| `create_staircase` | 楼梯（单一网格，全四边面） |
| `create_table` / `create_chair` | 家具 |
| `create_column` | 柱（柱身+柱头+柱基） |
| `create_tree` / `create_rock` | 程序化自然资产 |
| `build_medieval_house` | **完整房屋工作流**（墙开洞+门+窗+屋顶+烟囱+斜切+材质） |

### 原子层（精确控制）

| 工具 | 说明 |
|------|------|
| `create_blender_object` | 精确尺寸几何体（米） |
| `set_blender_transform` / `set_blender_origin` | 变换 / 原点（bottom/center/top） |
| `extrude_blender_face` / `inset_blender_face` | 挤出 / 内缩 |
| `loop_cut_blender` / `bevel_blender_edges` | 环切 / 斜切 |
| `boolean_blender` | 布尔（union/difference/intersect） |
| `add_blender_modifier` / `apply_blender_modifier` | bevel/solidify/subdivision/mirror/... |
| `set_blender_material` | PBR 材质 |

### 验证层（质量保证）

| 工具 | 说明 |
|------|------|
| `check_mesh_quality` / `check_scene_quality` | 非流形/孤立顶点/零面积/质量分（目标 ≥90） |
| `measure_distance` / `measure_gap` / `measure_alignment` | 距离/间隙/对齐 |
| `assert_dimensions` / `assert_contact` | 尺寸/接触断言 |

### 动画层（AI 影视工作流）

| 工具 | 说明 |
|------|------|
| `set_animation_range` / `set_current_frame` | 时间轴控制 |
| `insert_keyframe` / `animate_location/rotation/scale` | 关键帧动画（角度/插值：bezier/linear/bounce） |
| `camera_setup` / `camera_orbit` / `camera_dolly` | **相机运镜**（环绕 360°/推拉，自动跟踪目标） |
| `animate_turntable` / `animate_float` / `animate_appear` | 转盘/漂浮/出现（产品展示三件套） |
| `add_constraint` / `remove_constraint` | 约束（track_to/follow_path/copy_*） |
| `add_rigid_body` / `setup_rigid_body_world` | **刚体物理**（active/passive，AI 设参→引擎模拟） |
| `capture_animation_frames` | **多帧截图**（动画视觉验证核心：AI 对比帧看运动） |
| `render_animation` | 渲染帧序列（eevee 预览/cycles 成片） |
| `follow_path` | 沿曲线路径运动 |

### 视觉层

| 工具 | 说明 |
|------|------|
| `capture_blender_screenshot` | OpenGL 快速截图（毫秒级，用于自审） |
| `export_blender_model` | 导出 FBX/GLB（正确轴/单位/嵌入纹理） |

### UE 层 + 传输层

| 工具 | 说明 |
|------|------|
| `spawn_ue_actor` / `set_ue_actor_transform` / `delete_ue_actor` | Actor 管理 |
| `create_ue_blueprint` + 组件/变量/编译 | Blueprint 结构化操作 |
| `apply_ue_material` / `get_ue_materials` | 材质 |
| `transfer_model` / `batch_transfer_models` | Blender→UE 完整管线 |
| `create_ue_town` / `create_ue_castle` / `create_ue_maze` | 场景生成 |

### 专家提示词（6 个）

`blender_best_practices` · `topology_best_practices` · `scale_reference_guide` ·
`material_workflow_guide` · `lighting_principles` · `auto_critique_workflow` ·
`animation_workflow`

## 使用示例

```
"检查 Blender 和 UE 的连接状态"                     → bridge_status

"在 Blender 建一栋 6x5x3m 的中世纪房屋，
 门宽1m 高2.1m 在中间，3个窗，山墙屋顶"              → build_medieval_house

"检查刚才的房屋网格质量，然后截图看看"               → check_scene_quality + capture_blender_screenshot

"墙宽0.2m，验证厚度对不对"                          → assert_dimensions

"让相机环绕房屋转一圈，120帧，然后多帧截图验证"      → camera_orbit + capture_animation_frames

"把房屋导出FBX并导入UE的 /Game/VillageDemo/"         → transfer_model / export_blender_model
```

## AI 动画演示

```bash
python scripts/demo_animation.py              # 动画设置 + 多帧验证
python scripts/demo_animation.py --render     # 额外渲染成片 (eevee)
```

流程: 建模 → 相机运镜 (环绕/推拉) → 物体动画 (转盘/漂浮/出现) →
刚体物理 (掉落模拟) → **多帧截图验证** → 渲染成片

## 配置

`config.json`：
- `unreal.content_dir`：UE 项目 Content 目录（可用环境变量 `UE_CONTENT_DIR` 覆盖，多项目）
- `shared_assets.base_dir`：留空 = 项目内 `shared_assets/`（可用 `BRIDGE_SHARED_DIR` 覆盖）
- Blender 端口 9876（addon 固定），UE 端口 55557

## 项目结构

```
blender-ue-bridge/
├── blender_addon/             # Blender 插件 (零依赖)
│   ├── __init__.py            # 注册 + 启停
│   ├── server.py              # TCP 服务器 + 线程安全队列
│   ├── protocol.py            # 长度前缀协议
│   ├── commands.py            # 原子命令 (创建/变换/网格编辑/材质/测量/质量)
│   ├── macros.py              # 宏命令 (墙/屋顶/门窗/楼梯/家具/房屋工作流)
│   └── ui.py                  # Sidebar 面板
├── mcp_server/
│   ├── server.py              # MCP 主服务器 (62 工具)
│   ├── blender_tools.py       # 分层工具注册
│   ├── blender_client.py      # 新协议客户端 (排队/轮询/重试)
│   ├── ue_client.py           # UE 客户端
│   ├── asset_pipeline.py      # 资产管线
│   ├── vision_feedback.py     # 视觉反馈
│   └── prompts.py             # 专家提示词
├── scripts/
│   ├── install_addon.py       # Addon 安装器
│   ├── setup_mcp.py           # MCP 配置
│   ├── test_bridge.py         # 端到端测试
│   ├── test_protocol.py       # 协议层测试 (无需 Blender)
│   └── demo_precision.py      # 精确建模演示
├── shared_assets/             # 资产交换目录
├── config.json
└── pyproject.toml
```

## 许可证

MIT License