# ModelTranslator 实现计划 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 用 headless Blender 把带 PBR 贴图的 FBX 转为纯模型 FBX + XPbr 基础/混合贴图 + Unity 开箱即用的 .mat/.meta。 **Architecture:** 外层 CLI（系统 Python，纯 stdlib）负责找 Blender、调子进程、根据转换摘要生成 Unity 资产文件；Blender 内脚本（bpy + 自带 numpy）负责导入 FBX、按 Principled BSDF 连线识别贴图、通道打包出 PNG、导出纯 FBX，并向 stdout 打 JSON 摘要。Unity 资产模板独立成 `unity_assets.py` 纯函数模块（可用系统 Python unittest 测试）。 **Tech Stack:** Python 3.12（stdlib）、Blender 5.0（`bpy.ops.import_scene.fbx`/`export_scene.fbx`、numpy 1.26.4）、Unity 2022.3 资产 YAML。 **约定：** - Blender 路径默认 `D:\tools\blender-5.0.0-windows-x64\blender.exe` - XPbr shader GUID：`cab897163f45445fa34263d6670bfc9e` - 球面编码：`enc = n.xy / sqrt(2*(1+n.z)) * 0.5 + 0.5`；解码（shader 侧）先 `*2-1` - git 提交身份：`git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit ...` **文件结构：** ``` Tools/ModelTranslator/ model_translator.py # CLI：找 blender、跑转换、写 Unity 资产 unity_assets.py # Unity meta/mat 模板 + GUID 复用（纯 stdlib） bl_convert.py # Blender 内脚本（bpy+numpy） tests/test_unity_assets.py # unittest（系统 Python） tests/bl_test_encode.py # 法线编码 round-trip（Blender 内运行） README.md .gitignore # 忽略 out/ ``` --- ### Task 1: XPbr shader 法线解码重映射 **Files:** - Modify: `Client/Assets/Game/shader/XShader/XPbr_Base.hlsl`（`DecodeSphereMap` 函数） - [ ] **Step 1: 修改 DecodeSphereMap** 把： ```hlsl float3 DecodeSphereMap(float2 encoded) { float4 nn = float4(encoded, 1, -1); ``` 改为： ```hlsl float3 DecodeSphereMap(float2 encoded) { encoded = encoded * 2.0 - 1.0; //rg 无符号存储，重映射回有符号 float4 nn = float4(encoded, 1, -1); ``` 同时把注释 `//解码 RG 两通道球面映射压缩法线（与 XTex 的 MixTex 资源格式一致）` 改为 `//解码 RG 两通道球面映射压缩法线（有符号，ModelTranslator 工具编码：enc = n.xy/sqrt(2*(1+n.z)) * 0.5 + 0.5）`。 - [ ] **Step 2: Commit** ```bash git add Client/Assets/Game/shader/XShader/XPbr_Base.hlsl git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "XPbr: remap sphere-map normal decode to signed range for ModelTranslator" ``` --- ### Task 2: unity_assets.py（TDD） **Files:** - Create: `Tools/ModelTranslator/unity_assets.py` - Test: `Tools/ModelTranslator/tests/test_unity_assets.py` - [ ] **Step 1: 写失败测试** `Tools/ModelTranslator/tests/test_unity_assets.py`： ```python import os import re import sys import tempfile import unittest sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) import unity_assets as ua class TestGuid(unittest.TestCase): def test_new_guid_is_32_hex(self): g = ua.new_guid() self.assertTrue(re.fullmatch(r"[0-9a-f]{32}", g)) def test_guid_for_reuses_existing_meta(self): with tempfile.TemporaryDirectory() as d: asset = os.path.join(d, "a.png") with open(asset + ".meta", "w") as f: f.write("fileFormatVersion: 2\nguid: 0123456789abcdef0123456789abcdef\n") self.assertEqual(ua.guid_for(asset), "0123456789abcdef0123456789abcdef") def test_guid_for_generates_when_no_meta(self): with tempfile.TemporaryDirectory() as d: g = ua.guid_for(os.path.join(d, "b.png")) self.assertTrue(re.fullmatch(r"[0-9a-f]{32}", g)) class TestTemplates(unittest.TestCase): def test_texture_meta_srgb_on_off(self): on = ua.texture_meta("a" * 32, srgb=True, max_size=2048) off = ua.texture_meta("b" * 32, srgb=False, max_size=2048) self.assertIn("sRGBTexture: 1", on) self.assertIn("sRGBTexture: 0", off) self.assertIn("maxTextureSize: 2048", on) self.assertIn("guid: " + "a" * 32, on) def test_material_yaml_refs_and_keyword(self): y = ua.material_yaml("tong_wood", "s" * 32, "c" * 32, "d" * 32, alpha_test=True) self.assertIn("m_Name: tong_wood", y) self.assertIn("guid: " + "s" * 32, y) # shader self.assertIn("guid: " + "c" * 32, y) # base tex self.assertIn("guid: " + "d" * 32, y) # mix tex self.assertIn("_ALPHATEST_ON", y) self.assertIn("_AlphaTest: 1", y) def test_material_yaml_no_keyword_when_opaque(self): y = ua.material_yaml("m", "s" * 32, "c" * 32, "d" * 32, alpha_test=False) self.assertNotIn("_ALPHATEST_ON", y) self.assertIn("_AlphaTest: 0", y) def test_model_meta_external_objects(self): m = ua.model_meta("e" * 32, [("wood", "f" * 32), ("iron", "1" * 32)]) self.assertIn("name: wood", m) self.assertIn("guid: " + "f" * 32, m) self.assertIn("name: iron", m) self.assertIn("guid: " + "e" * 32, m) class TestSanitize(unittest.TestCase): def test_safe_name(self): self.assertEqual(ua.safe_name("Mat 01.a/b"), "Mat_01_a_b") if __name__ == "__main__": unittest.main() ``` - [ ] **Step 2: 运行确认失败** Run: `cd Tools/ModelTranslator && python -m unittest tests.test_unity_assets -v` Expected: FAIL（`ModuleNotFoundError: No module named 'unity_assets'`） - [ ] **Step 3: 实现 unity_assets.py** ```python """Unity 资产（.meta / .mat）文本模板与 GUID 管理。纯 stdlib，可独立测试。""" import os import re import uuid XPBR_SHADER_GUID = "cab897163f45445fa34263d6670bfc9e" # Client/Assets/Game/shader/XShader/XPbr.shader.meta _GUID_RE = re.compile(r"^guid: ([0-9a-f]{32})", re.M) def new_guid(): return uuid.uuid4().hex def guid_for(asset_path): """资产已有 .meta 则复用其中 guid（重复转换不破坏 Unity 引用），否则新分配。""" meta = asset_path + ".meta" if os.path.isfile(meta): with open(meta, "r", encoding="utf-8") as f: m = _GUID_RE.search(f.read()) if m: return m.group(1) return new_guid() def safe_name(name): return re.sub(r"[^0-9A-Za-z_\-]", "_", name).strip("_") or "mat" def texture_meta(guid, srgb, max_size): return """fileFormatVersion: 2 guid: {guid} TextureImporter: internalIDToNameTable: [] externalObjects: {{}} serializedVersion: 12 mipmaps: mipMapMode: 0 enableMipMap: 1 sRGBTexture: {srgb} linearTexture: 0 fadeOut: 0 borderMipMap: 0 mipMapsPreserveCoverage: 0 alphaTestReferenceValue: 0.5 mipMapFadeDistanceStart: 1 mipMapFadeDistanceEnd: 3 bumpmap: convertToNormalMap: 0 externalNormalMap: 0 heightScale: 0.25 normalMapFilter: 0 flipGreenChannel: 0 isReadable: 0 streamingMipmaps: 0 streamingMipmapsPriority: 0 vTOnly: 0 ignoreMipmapLimit: 0 grayScaleToAlpha: 0 generateCubemap: 6 cubemapConvolution: 0 seamlessCubemap: 0 textureFormat: 1 maxTextureSize: {max_size} textureSettings: serializedVersion: 2 filterMode: 1 aniso: 1 mipBias: 0 wrapU: 0 wrapV: 0 wrapW: 0 nPOTScale: 1 lightmap: 0 compressionQuality: 50 spriteMode: 0 spriteExtrude: 1 spriteMeshType: 1 alignment: 0 spritePivot: {{x: 0.5, y: 0.5}} spritePixelsToUnits: 100 spriteBorder: {{x: 0, y: 0, z: 0, w: 0}} spriteGenerateFallbackPhysicsShape: 1 alphaUsage: 1 alphaIsTransparency: 0 spriteTessellationDetail: -1 textureType: 0 textureShape: 1 singleChannelComponent: 0 flipbookRows: 1 flipbookColumns: 1 maxTextureSizeSet: 0 compressionQualitySet: 0 textureFormatSet: 0 ignorePngGamma: 0 applyGammaDecoding: 0 swizzle: 50462976 cookieLightType: 0 platformSettings: - serializedVersion: 3 buildTarget: DefaultTexturePlatform maxTextureSize: {max_size} resizeAlgorithm: 0 textureFormat: -1 textureCompression: 1 compressionQuality: 50 crunchedCompression: 0 allowsAlphaSplitting: 0 overridden: 0 ignorePlatformSupport: 0 androidETC2FallbackOverride: 0 forceMaximumCompressionQuality_BC6H_BC7: 0 spriteSheet: serializedVersion: 2 sprites: [] outline: [] physicsShape: [] bones: [] spriteID: internalID: 0 vertices: [] indices: edges: [] weights: [] secondaryTextures: [] nameFileIdTable: {{}} mipmapLimitGroupName: pSDRemoveMatte: 0 userData: assetBundleName: assetBundleVariant: """.format(guid=guid, srgb=1 if srgb else 0, max_size=max_size) def material_yaml(name, shader_guid, base_tex_guid, mix_tex_guid, alpha_test): keywords = "\n - _ALPHATEST_ON" if alpha_test else " []" return """%YAML 1.1 %TAG !u! tag:unity3d.com,2011: --- !u!21 &2100000 Material: serializedVersion: 8 m_ObjectHideFlags: 0 m_CorrespondingSourceObject: {{fileID: 0}} m_PrefabInstance: {{fileID: 0}} m_PrefabAsset: {{fileID: 0}} m_Name: {name} m_Shader: {{fileID: 4800000, guid: {shader_guid}, type: 3}} m_Parent: {{fileID: 0}} m_ModifiedSerializedProperties: 0 m_ValidKeywords:{keywords} m_InvalidKeywords: [] m_LightmapFlags: 4 m_EnableInstancingVariants: 0 m_DoubleSidedGI: 0 m_CustomRenderQueue: -1 stringTagMap: {{}} disabledShaderPasses: [] m_LockedProperties: m_SavedProperties: serializedVersion: 3 m_TexEnvs: - _MainTex: m_Texture: {{fileID: 2800000, guid: {base_tex_guid}, type: 3}} m_Scale: {{x: 1, y: 1}} m_Offset: {{x: 0, y: 0}} - _MixTex: m_Texture: {{fileID: 2800000, guid: {mix_tex_guid}, type: 3}} m_Scale: {{x: 1, y: 1}} m_Offset: {{x: 0, y: 0}} m_Ints: [] m_Floats: - _AO: 1 - _AlphaTest: {alpha_test} - _Cutoff: 0.5 - _Metallic: 1 - _Roughness: 1 m_Colors: - _BaseColor: {{r: 1, g: 1, b: 1, a: 1}} m_BuildTextureStacks: [] """.format(name=name, shader_guid=shader_guid, base_tex_guid=base_tex_guid, mix_tex_guid=mix_tex_guid, keywords=keywords, alpha_test=1 if alpha_test else 0) def material_meta(guid): return """fileFormatVersion: 2 guid: {guid} NativeFormatImporter: externalObjects: {{}} mainObjectFileID: 2100000 userData: assetBundleName: assetBundleVariant: """.format(guid=guid) def model_meta(guid, material_remaps): """material_remaps: [(fbx 内材质名, mat 文件 guid), ...]""" if material_remaps: ext = "externalObjects:\n" for mat_name, mat_guid in material_remaps: ext += (" - first:\n" " type: UnityEngine:Material\n" " assembly: UnityEngine.CoreModule\n" " name: {n}\n" " second: {{fileID: 2100000, guid: {g}, type: 2}}\n" ).format(n=mat_name, g=mat_guid) else: ext = "externalObjects: {}\n" return """fileFormatVersion: 2 guid: {guid} ModelImporter: serializedVersion: 22200 internalIDToNameTable: [] {ext} materials: materialImportMode: 2 materialName: 0 materialSearch: 1 materialLocation: 1 animations: legacyGenerateAnimations: 4 bakeSimulation: 0 resampleCurves: 1 optimizeGameObjects: 0 removeConstantScaleCurves: 0 motionNodeName: animationImportErrors: animationImportWarnings: animationRetargetingWarnings: animationDoRetargetingWarnings: 0 importAnimatedCustomProperties: 0 importConstraints: 0 animationCompression: 1 animationRotationError: 0.5 animationPositionError: 0.5 animationScaleError: 0.5 animationWrapMode: 0 extraExposedTransformPaths: [] extraUserProperties: [] clipAnimations: [] isReadable: 0 meshes: lODScreenPercentages: [] globalScale: 1 meshCompression: 0 addColliders: 0 useSRGBMaterialColor: 1 sortHierarchyByName: 1 importPhysicalCameras: 1 importVisibility: 1 importBlendShapes: 1 importCameras: 1 importLights: 1 nodeNameCollisionStrategy: 1 fileIdsGeneration: 2 swapUVChannels: 0 generateSecondaryUV: 0 useFileUnits: 1 keepQuads: 0 weldVertices: 1 bakeAxisConversion: 0 preserveHierarchy: 0 skinWeightsMode: 0 maxBonesPerVertex: 4 minBoneWeight: 0.001 optimizeBones: 1 meshOptimizationFlags: -1 indexFormat: 0 secondaryUVAngleDistortion: 8 secondaryUVAreaDistortion: 15.000001 secondaryUVHardAngle: 88 secondaryUVMarginMethod: 1 secondaryUVMinLightmapResolution: 40 secondaryUVMinObjectScale: 1 secondaryUVPackMargin: 4 useFileScale: 1 strictVertexDataChecks: 0 tangentSpace: normalSmoothAngle: 60 normalImportMode: 0 tangentImportMode: 3 normalCalculationMode: 4 legacyComputeAllNormalsFromSmoothingGroupsWhenMeshHasBlendShapes: 0 blendShapeNormalImportMode: 1 normalSmoothingSource: 0 referencedClips: [] importAnimation: 1 humanDescription: serializedVersion: 3 human: [] skeleton: [] armTwist: 0.5 foreArmTwist: 0.5 upperLegTwist: 0.5 legTwist: 0.5 armStretch: 0.05 legStretch: 0.05 feetSpacing: 0 globalScale: 1 rootMotionBoneName: hasTranslationDoF: 0 hasExtraRoot: 0 skeletonHasParents: 1 lastHumanDescriptionAvatarSource: {{instanceID: 0}} autoGenerateAvatarMappingIfUnspecified: 1 animationType: 2 humanoidOversampling: 1 avatarSetup: 0 addHumanoidExtraRootOnlyWhenUsingAvatar: 1 importBlendShapeDeformPercent: 1 remapMaterialsIfMaterialImportModeIsNone: 0 additionalBone: 0 userData: assetBundleName: assetBundleVariant: """.format(guid=guid, ext=ext) ``` - [ ] **Step 4: 运行确认通过** Run: `cd Tools/ModelTranslator && python -m unittest tests.test_unity_assets -v` Expected: 全部 PASS（7 tests OK） - [ ] **Step 5: Commit** ```bash git add Tools/ModelTranslator/unity_assets.py Tools/ModelTranslator/tests/test_unity_assets.py git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "ModelTranslator: Unity asset templates (texture/material/model meta) with GUID reuse" ``` --- ### Task 3: bl_convert.py 法线编码函数（Blender 内 TDD） **Files:** - Create: `Tools/ModelTranslator/bl_convert.py`（先只写编码函数，主流程 Task 4） - Test: `Tools/ModelTranslator/tests/bl_test_encode.py` - [ ] **Step 1: 写失败测试** `Tools/ModelTranslator/tests/bl_test_encode.py`（在 Blender 内运行）： ```python """法线球面编码 round-trip 测试。运行： blender -b --factory-startup --python tests/bl_test_encode.py 成功打印 ENCODE_TEST_OK，失败非零退出。""" import os import sys import numpy as np sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from bl_convert import encode_normal_rg, decode_sphere_map def main(): rng = np.random.default_rng(7) # 随机切线空间法线（z>=0 半球），含边缘方向 n = rng.normal(size=(4096, 3)) n[:, 2] = np.abs(n[:, 2]) n /= np.linalg.norm(n, axis=1, keepdims=True) n = np.vstack([n, [[0, 0, 1], [1, 0, 0], [-1, 0, 0], [0, -1, 0], [0.707, -0.707, 0]]]) enc = encode_normal_rg(n) # (N,2) in [0,1] assert enc.min() >= 0.0 and enc.max() <= 1.0, "encode out of [0,1]" enc8 = np.round(enc * 255.0) / 255.0 # 模拟 8bit PNG 存储 dec = decode_sphere_map(enc8) # shader 同款公式 dec /= np.linalg.norm(dec, axis=1, keepdims=True) cos = np.clip(np.sum(n * dec, axis=1), -1.0, 1.0) max_err = np.degrees(np.arccos(cos)).max() assert max_err < 2.0, "max angle error %.3f deg >= 2" % max_err # 平面法线编码值应为 (0.5, 0.5) flat = encode_normal_rg(np.array([[0.0, 0.0, 1.0]])) assert np.allclose(flat, 0.5, atol=1e-6), "flat normal must encode to 0.5" print("ENCODE_TEST_OK max_err=%.4f deg" % max_err) try: main() except Exception as e: print("ENCODE_TEST_FAIL:", e) sys.exit(1) ``` - [ ] **Step 2: 运行确认失败** Run: `cd Tools/ModelTranslator && "/d/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python tests/bl_test_encode.py` Expected: `ENCODE_TEST_FAIL: No module named 'bl_convert'`（退出码 1） - [ ] **Step 3: 实现编码函数（bl_convert.py 首个版本）** ```python """Blender 内运行：FBX -> 纯模型 FBX + XPbr 基础/混合贴图。 调用：blender -b --factory-startup --python bl_convert.py -- """ import numpy as np def encode_normal_rg(n): """切线法线 (N,3) -> 球面编码 (N,2)，范围 [0,1]。 shader 侧 XPbr_Base.hlsl DecodeSphereMap 先 *2-1 再解码。""" n = n / np.maximum(np.linalg.norm(n, axis=-1, keepdims=True), 1e-8) z = np.clip(n[..., 2], -0.99, 1.0) denom = np.sqrt(2.0 * (1.0 + z)) enc = n[..., :2] / denom[..., None] return np.clip(enc * 0.5 + 0.5, 0.0, 1.0) def decode_sphere_map(enc01): """shader DecodeSphereMap 的 numpy 等价（含 *2-1），仅测试用。""" e = enc01 * 2.0 - 1.0 l = 1.0 - e[..., 0] ** 2 - e[..., 1] ** 2 l = np.clip(l, 0.0, 1.0) xy = e * np.sqrt(l)[..., None] return np.concatenate([xy * 2.0, (l * 2.0 - 1.0)[..., None]], axis=-1) ``` - [ ] **Step 4: 运行确认通过** Run: `cd Tools/ModelTranslator && "/d/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python tests/bl_test_encode.py` Expected: 输出 `ENCODE_TEST_OK max_err=... deg`（<2） - [ ] **Step 5: Commit** ```bash git add Tools/ModelTranslator/bl_convert.py Tools/ModelTranslator/tests/bl_test_encode.py git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "ModelTranslator: sphere-map normal encode with round-trip test" ``` --- ### Task 4: bl_convert.py 主流程 **Files:** - Modify: `Tools/ModelTranslator/bl_convert.py`（追加主流程；bpy 导入放到 main 段，保证编码函数可独立测试） - [ ] **Step 1: 追加主流程代码** 在 Task 3 的两个函数之后追加： ```python # ---------------- 以下仅在 Blender 内执行 ---------------- AO_NAME_RE = None # 延迟编译，见 _looks_like_ao def _looks_like_ao(name): import re global AO_NAME_RE if AO_NAME_RE is None: AO_NAME_RE = re.compile(r"(ao|occlusion|ambient)", re.I) return bool(AO_NAME_RE.search(name)) def _image_pixels(img): """bpy Image -> float32 (h, w, 4)，原始值（不做色彩变换）。""" w, h = img.size buf = np.empty(w * h * 4, dtype=np.float32) img.pixels.foreach_get(buf) return buf.reshape(h, w, 4) def _scaled_pixels(img, tw, th): """取缩放到 (tw, th) 的像素；用副本 scale，不污染原图。""" if tuple(img.size) == (tw, th): return _image_pixels(img) cp = img.copy() try: cp.scale(tw, th) return _image_pixels(cp) finally: import bpy bpy.data.images.remove(cp) def _trace_image(socket, warnings, what): """沿输入连线找贴图。返回 (bpy.types.Image | None, channel | None)。 穿透 Normal Map / Separate Color 节点；channel 为 0..3 或 None（用 R/灰度）。""" if not socket.is_linked: return None, None node = socket.links[0].from_node out_name = socket.links[0].from_socket.name if node.type == 'TEX_IMAGE': return node.image, None if node.type == 'NORMAL_MAP': return _trace_image(node.inputs['Color'], warnings, what) if node.type in ('SEPARATE_COLOR', 'SEPRGB'): ch = {'Red': 0, 'Green': 1, 'Blue': 2, 'R': 0, 'G': 1, 'B': 2}.get(out_name, 0) img, _ = _trace_image(node.inputs[0], warnings, what) return img, ch warnings.append("%s: 无法识别的节点 %s，改用常量" % (what, node.type)) return None, None def _material_maps(mat, warnings): """从材质 Principled BSDF 提取贴图与常量。""" maps = {"basecolor": None, "alpha": None, "normal": None, "metallic": None, "roughness": None, "ao": None} consts = {"basecolor": (0.5, 0.5, 0.5, 1.0), "metallic": 0.0, "roughness": 0.5} if not mat.use_nodes: warnings.append("材质未用节点，全部用默认常量") return maps, consts bsdf = next((n for n in mat.node_tree.nodes if n.type == 'BSDF_PRINCIPLED'), None) if bsdf is None: warnings.append("未找到 Principled BSDF，全部用默认常量") return maps, consts def grab(input_name, key): sock = bsdf.inputs.get(input_name) if sock is None: return img, ch = _trace_image(sock, warnings, key) if img is not None: maps[key] = (img, ch) grab('Base Color', 'basecolor') grab('Alpha', 'alpha') grab('Normal', 'normal') grab('Metallic', 'metallic') grab('Roughness', 'roughness') consts["basecolor"] = tuple(bsdf.inputs['Base Color'].default_value) consts["metallic"] = float(bsdf.inputs['Metallic'].default_value) consts["roughness"] = float(bsdf.inputs['Roughness'].default_value) # AO：材质节点树内按名匹配（未连到 BSDF 也算） used = {m[0] for m in maps.values() if m} for n in mat.node_tree.nodes: if n.type == 'TEX_IMAGE' and n.image and n.image not in used \ and _looks_like_ao(n.image.name): maps["ao"] = (n.image, None) break return maps, consts def _target_size(maps, max_size): ws = [m[0].size[0] for m in maps.values() if m] hs = [m[0].size[1] for m in maps.values() if m] if not ws: return 4, 4 return min(max(ws), max_size), min(max(hs), max_size) def _channel(pixels, ch): return pixels[..., ch if ch is not None else 0] def _save_png(path, rgba, srgb_view=False): """float32 (h,w,4) -> PNG。写原始值（Non-Color，避免色彩管理改写数据）。""" import bpy h, w = rgba.shape[:2] img = bpy.data.images.new("mt_tmp", width=w, height=h, alpha=True) img.colorspace_settings.name = 'Non-Color' img.pixels.foreach_set(np.ascontiguousarray(rgba, dtype=np.float32).ravel()) img.filepath_raw = path img.file_format = 'PNG' img.alpha_mode = 'CHANNEL_PACKED' img.save() bpy.data.images.remove(img) def _convert_material(mat, model_name, outdir, max_size): import os warnings = [] maps, consts = _material_maps(mat, warnings) tw, th = _target_size(maps, max_size) # --- 基础贴图 --- base = np.empty((th, tw, 4), dtype=np.float32) if maps["basecolor"]: base[..., :3] = _scaled_pixels(maps["basecolor"][0], tw, th)[..., :3] else: base[..., :3] = np.array(consts["basecolor"][:3], dtype=np.float32) if maps["alpha"]: img, ch = maps["alpha"] base[..., 3] = _channel(_scaled_pixels(img, tw, th), ch) alpha_mode = "transparency" elif maps["basecolor"] and maps["basecolor"][0].channels == 4 and \ _image_has_alpha(maps["basecolor"][0]): base[..., 3] = _scaled_pixels(maps["basecolor"][0], tw, th)[..., 3] alpha_mode = "transparency" elif maps["ao"]: img, ch = maps["ao"] base[..., 3] = _channel(_scaled_pixels(img, tw, th), ch) alpha_mode = "ao" else: base[..., 3] = 1.0 alpha_mode = "white" # --- 混合贴图 --- mix = np.empty((th, tw, 4), dtype=np.float32) if maps["normal"]: npx = _scaled_pixels(maps["normal"][0], tw, th)[..., :3] * 2.0 - 1.0 mix[..., 0:2] = encode_normal_rg(npx) else: mix[..., 0:2] = 0.5 warnings.append("无法线贴图，RG 填平面法线") if maps["metallic"]: img, ch = maps["metallic"] mix[..., 2] = _channel(_scaled_pixels(img, tw, th), ch) else: mix[..., 2] = consts["metallic"] if maps["roughness"]: img, ch = maps["roughness"] mix[..., 3] = _channel(_scaled_pixels(img, tw, th), ch) else: mix[..., 3] = consts["roughness"] import re sname = re.sub(r"[^0-9A-Za-z_\-]", "_", mat.name).strip("_") or "mat" base_png = os.path.join(outdir, "%s_%s_base.png" % (model_name, sname)) mix_png = os.path.join(outdir, "%s_%s_mix.png" % (model_name, sname)) _save_png(base_png, base) _save_png(mix_png, mix) return { "name": mat.name, "safe_name": sname, "base_png": os.path.basename(base_png), "mix_png": os.path.basename(mix_png), "alpha_mode": alpha_mode, "size": [tw, th], "sources": {k: (v[0].name if v else None) for k, v in maps.items()}, "warnings": warnings, } def _image_has_alpha(img): """采样判断 alpha 是否非全白（全白视为无透明信息）。""" px = _image_pixels(img) a = px[..., 3] return bool((a < 0.995).any()) def _strip_textures(): import bpy for mat in bpy.data.materials: if not mat.use_nodes: continue for n in list(mat.node_tree.nodes): if n.type in ('TEX_IMAGE', 'NORMAL_MAP', 'SEPARATE_COLOR', 'SEPRGB'): mat.node_tree.nodes.remove(n) def main(): import bpy, json, os, sys argv = sys.argv[sys.argv.index("--") + 1:] src, outdir, max_size = argv[0], argv[1], int(argv[2]) os.makedirs(outdir, exist_ok=True) model_name = os.path.splitext(os.path.basename(src))[0] bpy.ops.wm.read_factory_settings(use_empty=True) bpy.ops.import_scene.fbx(filepath=src) used_mats = [] for obj in bpy.data.objects: if obj.type != 'MESH': continue for slot in obj.material_slots: if slot.material and slot.material not in used_mats: used_mats.append(slot.material) results = [_convert_material(m, model_name, outdir, max_size) for m in used_mats] _strip_textures() fbx_out = os.path.join(outdir, model_name + ".fbx") bpy.ops.export_scene.fbx(filepath=fbx_out, path_mode='NONE', embed_textures=False) print("MT_SUMMARY " + json.dumps( {"model": model_name, "fbx": os.path.basename(fbx_out), "materials": results}, ensure_ascii=False)) if __name__ == "__main__" and "--" in __import__("sys").argv: main() ``` - [ ] **Step 2: 冒烟运行（tong.fbx）** Run: ```bash cd Tools/ModelTranslator && "/d/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python bl_convert.py -- src/tong.fbx out/tong 2048 2>&1 | grep -E "MT_SUMMARY|Error|Traceback" | head -5 ``` Expected: 一行 `MT_SUMMARY {...}`；`out/tong/` 下有 `tong.fbx` 与每材质 `_base.png`/`_mix.png` - [ ] **Step 3: 检查输出尺寸 ≤2048** Run: `cd Tools/ModelTranslator && python -c "import struct,glob;[print(f,struct.unpack('>II',open(f,'rb').read(24)[16:24])) for f in glob.glob('out/tong/*.png')]"` Expected: 全部宽高 ≤2048 - [ ] **Step 4: 编码测试回归** Run: `cd Tools/ModelTranslator && "/d/tools/blender-5.0.0-windows-x64/blender.exe" -b --factory-startup --python tests/bl_test_encode.py` Expected: `ENCODE_TEST_OK` - [ ] **Step 5: Commit** ```bash git add Tools/ModelTranslator/bl_convert.py git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "ModelTranslator: Blender conversion pipeline (import, classify, pack, export)" ``` --- ### Task 5: model_translator.py CLI **Files:** - Create: `Tools/ModelTranslator/model_translator.py` - [ ] **Step 1: 实现 CLI** ```python """ModelTranslator CLI：FBX -> 纯模型 FBX + XPbr 贴图 + Unity .mat/.meta。 用法：python model_translator.py src/tong.fbx [-o out] [--max-size 2048] [--blender exe]""" import argparse import json import os import shutil import subprocess import sys import unity_assets as ua DEFAULT_BLENDER = r"D:\tools\blender-5.0.0-windows-x64\blender.exe" HERE = os.path.dirname(os.path.abspath(__file__)) def find_blender(cli_arg): for cand in (cli_arg, os.environ.get("BLENDER_EXE"), DEFAULT_BLENDER, shutil.which("blender")): if cand and os.path.isfile(cand): return cand sys.exit("找不到 blender.exe，请用 --blender 指定或设置环境变量 BLENDER_EXE") def run_blender(blender, src, outdir, max_size): cmd = [blender, "-b", "--factory-startup", "--python", os.path.join(HERE, "bl_convert.py"), "--", src, outdir, str(max_size)] proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace") summary = None for line in (proc.stdout or "").splitlines(): if line.startswith("MT_SUMMARY "): summary = json.loads(line[len("MT_SUMMARY "):]) if proc.returncode != 0 or summary is None: sys.stderr.write(proc.stdout[-2000:] + "\n" + proc.stderr[-2000:] + "\n") sys.exit("Blender 转换失败：%s" % src) return summary def write_unity_assets(outdir, summary, max_size): remaps = [] for m in summary["materials"]: base_png = os.path.join(outdir, m["base_png"]) mix_png = os.path.join(outdir, m["mix_png"]) base_guid = ua.guid_for(base_png) mix_guid = ua.guid_for(mix_png) with open(base_png + ".meta", "w", encoding="utf-8", newline="\n") as f: f.write(ua.texture_meta(base_guid, srgb=True, max_size=max_size)) with open(mix_png + ".meta", "w", encoding="utf-8", newline="\n") as f: f.write(ua.texture_meta(mix_guid, srgb=False, max_size=max_size)) mat_name = "%s_%s" % (summary["model"], m["safe_name"]) mat_path = os.path.join(outdir, mat_name + ".mat") mat_guid = ua.guid_for(mat_path) alpha_test = m["alpha_mode"] == "transparency" with open(mat_path, "w", encoding="utf-8", newline="\n") as f: f.write(ua.material_yaml(mat_name, ua.XPBR_SHADER_GUID, base_guid, mix_guid, alpha_test)) with open(mat_path + ".meta", "w", encoding="utf-8", newline="\n") as f: f.write(ua.material_meta(mat_guid)) remaps.append((m["name"], mat_guid)) fbx_path = os.path.join(outdir, summary["fbx"]) with open(fbx_path + ".meta", "w", encoding="utf-8", newline="\n") as f: f.write(ua.model_meta(ua.guid_for(fbx_path), remaps)) def report(summary, outdir): print("== %s -> %s" % (summary["model"], outdir)) for m in summary["materials"]: print(" 材质 %-24s A通道=%s 尺寸=%dx%d" % (m["name"], m["alpha_mode"], m["size"][0], m["size"][1])) for k, v in m["sources"].items(): print(" %-10s %s" % (k, v or "(常量)")) for w in m["warnings"]: print(" [警告] %s" % w) def main(): ap = argparse.ArgumentParser(description=__doc__) ap.add_argument("input", help="FBX 文件或目录") ap.add_argument("-o", "--out", default=os.path.join(HERE, "out")) ap.add_argument("--max-size", type=int, default=2048) ap.add_argument("--blender", default=None) args = ap.parse_args() blender = find_blender(args.blender) if os.path.isdir(args.input): srcs = [os.path.join(args.input, f) for f in sorted(os.listdir(args.input)) if f.lower().endswith(".fbx")] if not srcs: sys.exit("目录中没有 FBX：%s" % args.input) else: srcs = [args.input] for src in srcs: name = os.path.splitext(os.path.basename(src))[0] outdir = os.path.join(args.out, name) summary = run_blender(blender, src, outdir, args.max_size) write_unity_assets(outdir, summary, args.max_size) report(summary, outdir) if __name__ == "__main__": main() ``` - [ ] **Step 2: 单元测试回归** Run: `cd Tools/ModelTranslator && python -m unittest tests.test_unity_assets -v` Expected: PASS - [ ] **Step 3: 集成运行 tong.fbx** Run: `cd Tools/ModelTranslator && python model_translator.py src/tong.fbx` Expected: 打印材质摘要；`out/tong/` 含 `tong.fbx(+.meta)`、每材质 `_base.png(+.meta)`、`_mix.png(+.meta)`、`.mat(+.meta)` - [ ] **Step 4: 检查 GUID 复用** Run: `cd Tools/ModelTranslator && python -c " import re,glob before={f:re.search(r'guid: (\w+)',open(f).read()).group(1) for f in glob.glob('out/tong/*.meta')} import subprocess;subprocess.run(['python','model_translator.py','src/tong.fbx'],check=True) after={f:re.search(r'guid: (\w+)',open(f).read()).group(1) for f in glob.glob('out/tong/*.meta')} assert before==after, 'GUID 变了！' print('GUID_REUSE_OK', len(before))"` Expected: `GUID_REUSE_OK N` - [ ] **Step 5: 集成运行 woodcar.fbx（批量入口顺带验证）** Run: `cd Tools/ModelTranslator && python model_translator.py src/woodcar.fbx` Expected: 同样输出齐全 - [ ] **Step 6: Commit** ```bash git add Tools/ModelTranslator/model_translator.py git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "ModelTranslator: CLI runner with Unity asset generation" ``` --- ### Task 6: README 与 .gitignore **Files:** - Create: `Tools/ModelTranslator/README.md` - Create: `Tools/ModelTranslator/.gitignore` - [ ] **Step 1: 写 README.md** 内容涵盖：用途、依赖（Blender 5.0 路径/环境变量）、用法示例（单文件/目录）、输出结构说明、A 通道自动判定规则（透明>AO>白）、混合贴图通道含义与 sRGB 要求、"拷入 Client/Assets 即可用"说明、局限（程序纹理不支持、法线绿通道按 OpenGL 约定、不做图集合并）。 - [ ] **Step 2: 写 .gitignore** ``` out/ ``` - [ ] **Step 3: Commit** ```bash git add Tools/ModelTranslator/README.md Tools/ModelTranslator/.gitignore git -c user.name=ud18010 -c user.email=ud18010@xworld.ren commit -m "ModelTranslator: README and gitignore" ``` --- ### Task 7: 人工验证（Unity） - [ ] 把 `out/tong/` 拷入 `Client/Assets/`（任意位置），确认：模型直接带 XPbr 材质显示；混合贴图 sRGB 已关；透明/AO 判定正确。此步由用户在 Unity 编辑器执行，工具侧无需改动。