AIGame/Tools/model_tools/README.md

高模减面与贴图烘焙 + XPbr 打包

复刻自 ClientTrunk ModelTools，并接入 AIC#Project ModelTranslator 的 XPbr 收尾。

高模（FBX / GLB / glTF）
  -> model_decimate：减面 + 重展 UV -> <名>_low.fbx
  -> model_bake：Cycles 烘焙 -> 五通道 PNG + 低模 FBX
  -> model_translator：打包为 XPbr 两张图 + .mat/.meta
       _base.png  RGB=Albedo  A=AO/透明
       _mix.png   RG=球面法线  B=Metallic  A=Roughness
       写出时 PNG 无损压缩（体积更小，像素不变）

环境

• Blender 5.0：默认 D:\tools\Blender\blender-5.0.0-windows-x64\blender.exe
  • 或 BLENDER_EXE / BLENDER_PATH / --blender
• Pillow（UV 观察图）：pip install Pillow
• UVPackmaster 4 可选

FBX 轴向约定

Studio 五步的 GLB 使用标准 glTF Y-up；Blender 默认导入后应在 Z-up 场景中站立。 prepare_game_export 为历史调用保留 Y-up 顶点缓冲；最终必须由 export_fbx_source_yup 在临时副本上恢复 Blender Z-up，再烘焙为 Y-up FBX。 不要直接把准备后的 Y-up 顶点交给默认 FBX 导出器，否则会重复转换，留下 X=-90° 节点旋转。 版本 2 导出器会校验场景 +Y-up、节点旋转 0 和缩放 1；静态导出回执写入 fbxAxes.exportVersion。 lmgirl_tpose_mesh.py 只复用版本匹配的 FBX 缓存，历史资源不会在此次修复中批量重导。

Blender 回归入口：Tools/model_tools/tests/bl_test_fbx_axes.py。验收读取完整节点变换后的世界几何， 同时检查脚底中心原点、UV、源网格不变及重复导入导出，不以顶点包围盒或 axis_up 参数单独判定成功。

一键（推荐）

python Tools/model_tools/model_lowpoly_bake.py prop.glb -o Tools/output/prop_game --tris 5000 --size 2048
# 默认会继续生成 Tools/output/prop_game/prop_xpbr/（base+mix+.mat）
# 跳过 XPbr：加 --no-xpbr

分步

python Tools/model_tools/model_decimate.py prop.glb --tris 5000 -o Tools/output/prop_low
python Tools/model_tools/model_bake.py prop.glb Tools/output/prop_low/prop_low.fbx -o Tools/output/prop_bake --size 2048
python Tools/model_tools/model_translator.py Tools/output/prop_bake/prop/prop.fbx -o Tools/output/prop_xpbr

装入 Unity + 预设

python Tools/install_character_bundles.py -a CaoCao --kind Human -b Tools/output/caocao_game/caocao_xpbr -c Doc/Design/Character/CaoCao/caocao.png
# Unity Pipeline：run_script AgentScripts/SetupCharacter.cs --entry SetupCharacter.SetupCaoCao
# 寻址 Prefab=`CaoCao`，目录 Characters/Human/CaoCao

与 AIC#Project/ModelTranslator 减面烘焙对比

能力	本仓库 Tools/model_tools（现）	AIC#Project ModelTranslator
高模格式	FBX/GLB/glTF	主路径偏 FBX（减面 CLI 文案）
减面后端	Decimate collapse	默认 Quad Remesher，失败回退 collapse
UV 质量门	翻转/重叠 + 最大单岛占比（已对齐）	翻转/重叠/最大单岛 + 更深 seam 扫描
烘焙射线	自适应分离距离（已对齐）	自适应分离距离
收尾	XPbr base/mix + .mat（已接入）	同左（源头）
QR 引擎	未捆绑（无 xremesh 依赖）	需本机 Quad Remesher 引擎

结论：AIC#Project 在「有机角色拓扑」上更优（Quad Remesher + 更深 UV 门）；本仓库已并入其自适应射线、大岛门限与 XPbr 打包，并保留 GLB 输入。若本机已装 QR 引擎，可再把 qr_bridge / --reducer quad 完整迁入作为可选增强。