From 073ae48a61196b4909666e7c2965c9e2586484d8 Mon Sep 17 00:00:00 2001
From: ud18010 <ud18010@xworld.ren>
Date: Wed, 15 Jul 2026 11:51:05 +0800
Subject: [PATCH] ModelTranslator: README and gitignore

---
 Tools/ModelTranslator/.gitignore |  2 ++
 Tools/ModelTranslator/README.md  | 57 ++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 Tools/ModelTranslator/.gitignore
 create mode 100644 Tools/ModelTranslator/README.md

diff --git a/Tools/ModelTranslator/.gitignore b/Tools/ModelTranslator/.gitignore
new file mode 100644
index 00000000..ea93687f
--- /dev/null
+++ b/Tools/ModelTranslator/.gitignore
@@ -0,0 +1,2 @@
+out/
+__pycache__/
diff --git a/Tools/ModelTranslator/README.md b/Tools/ModelTranslator/README.md
new file mode 100644
index 00000000..d283151e
--- /dev/null
+++ b/Tools/ModelTranslator/README.md
@@ -0,0 +1,57 @@
+# ModelTranslator
+
+用 headless Blender 把带 PBR 贴图的 FBX 转换为 **XPbr shader**（`Test/XPbr`）可用的资源：
+
+- 纯模型 FBX（剥离全部贴图，保留材质名/槽位）
+- 每材质一套贴图（≤2048×2048）：
+  - **基础贴图** `<模型>_<材质>_base.png`：RGB=颜色，A=透明或 AO
+  - **混合贴图** `<模型>_<材质>_mix.png`：RG=球面编码法线，B=金属度，A=粗糙度
+- Unity 开箱即用：`.mat`（已挂 XPbr、已连贴图）与全部 `.meta`（含 sRGB 设置、FBX 材质重映射）都预生成
+
+## 依赖
+
+- Blender 5.0（默认路径 `D:\tools\blender-5.0.0-windows-x64\blender.exe`；也可用 `--blender` 参数或环境变量 `BLENDER_EXE` 指定）
+- 系统 Python 3.x（仅标准库）
+
+## 用法
+
+```bash
+cd Tools/ModelTranslator
+python model_translator.py src/tong.fbx          # 单文件
+python model_translator.py src/                  # 目录批量（*.fbx）
+python model_translator.py src/tong.fbx -o out --max-size 2048 --blender "D:\...\blender.exe"
+```
+
+输出到 `out/<模型名>/`：
+
+```
+out/tong/
+  tong.fbx (+.meta)                  # 纯模型，材质槽已重映射到下面的 .mat
+  tong_Material_base.png (+.meta)    # sRGB 开
+  tong_Material_mix.png  (+.meta)    # sRGB 关（线性数据，勿改）
+  tong_Material.mat      (+.meta)    # Test/XPbr
+```
+
+**把整个 `out/<模型名>/` 文件夹拷进 `Client/Assets/` 任意位置即可**，模型拖进场景直接生效。重复转换会复用已有 `.meta` 里的 GUID，不会破坏 Unity 引用。
+
+## 转换规则
+
+- 贴图识别：沿材质 Principled BSDF 连线找 Base Color / Alpha / Normal / Metallic / Roughness；AO 按贴图名匹配（含 `ao`/`occlusion`/`ambient`）
+- 基础贴图 A 通道自动判定：**透明贴图 > 颜色贴图自带 alpha > AO 贴图 > 填白(255)**；判定为透明时 `.mat` 自动勾选 `Alpha As Transparency`（AlphaTest 裁剪）
+- 无对应贴图的通道用 Principled 常量值填充（会在日志中标注 `(常量)`）
+- 目标尺寸 = min(2048, 源贴图最大边)，所有贴图缩放到统一尺寸
+- 法线编码：`enc = n.xy / sqrt(2*(1+n.z)) * 0.5 + 0.5`，与 `XPbr_Base.hlsl` 的 `DecodeSphereMap` 配对
+
+## 局限
+
+- 材质必须是贴图直连 Principled BSDF 的标准 PBR；程序纹理/复杂混合节点无法识别（会打警告并退化为常量）
+- 法线按 OpenGL 约定（+Y 向上）处理，不提供绿通道翻转
+- 不做多材质图集合并/UV 重排；每材质一套贴图
+- 动画/骨骼随 FBX 原样导出，不做处理
+
+## 开发
+
+```bash
+python -m unittest tests.test_unity_assets                # Unity 模板/GUID 测试
+"<blender>" -b --factory-startup --python tests/bl_test_encode.py   # 法线编码 round-trip
+```