Maker 模型导入、预览与装饰物放置

生成资产仍要求已有 TapTap Maker 限定测试资格。本页处理生成后的本地资源，不要求把星火项目初始化为 Maker 项目。

优先通过 tools/list 查找 resource_import_model_package，按 项目模型资源包导入 执行 dryRun、导入、依赖验证、resource_open_preview 和地编放置。下面的手动包装用于旧编辑器或需要明确适配的源格式；已有导入 MCP 时不要默认重复手写转换脚本。

识别格式与解析依赖

检查内容，不要只看 prefab 后缀。Maker prefab 通常是 XML 的 node，使用 Model;uuid://...、Material;uuid://...；星火 prefab 是 JSON 数组，包含 staticMesh / skeletalMesh 等条目。Maker XML 直接在星火资源库打开可能提示「Prefab为空」。改名或复制文件不能完成转换。

先从 create_3d_asset 的完成结果读取 local_delivery.model.local_path 和实际文件，当前本地代理可将 MDL 包解到 assets/model/<asset_id>/。优先使用它已下载的完整目录，保留生成记录；不要硬编码旧版 assets/Meshes 目录或另行寻找 FBX。若代理未落盘，按结果的 model_files 与 delivery_failures 排查。

先读取 Maker 输出的 .meta 文件建立 UUID 到实际文件的映射。Meshes/prop.mdl.meta 的 uuid 对应 Meshes/prop.mdl，材质和贴图同理。材质 XML 内的 uuid:// 也要解析，缺失或重复映射应报告具体资源，不能按文件排序猜测。保留 Maker 原始输出。

裸 MDL 可通过 resource_get_preview_info 读取网格元数据，但美术资源库可视预览与地编装饰物使用 prefab。已有星火 JSON 包装时，优先检查依赖、材质和变换，不重复转换。

骨骼模型与动作

Maker 绑骨后的包使用 AnimatedModel，应通过新版 resource_import_model_package 导入为 skeletalMesh。同一资产目录可能同时保留静态和绑骨版本，使用 entryPoint 指向实际绑骨 prefab。绑骨不等于生成动作；Maker 是否提供动作生成以实时 schema 为准，不调用未开放的 animate 操作。

Maker MDL 默认按外部骨架处理。MDL 可以读取骨骼名、父子层级和绑定姿势，但这些信息不能可靠证明它与星火共享 Humanoid 骨架的语义、参考空间和单位一致。不要因为模型已经写入 GameDataModel.Asset，就直接把官方动作填入 HumanoidSourceAnimations 并宣称完成重定向；该字段只是正常动画烘焙清单的输入，不保存 sourceModel、boneMap 或 alignmentBones。

使用 Maker 模型搭配星火官方动作时，先选定模型和动作家族，再读取目标 MDL 与动作源 MDL 的骨架，建立完整映射并通过 resource_retarget_animations 生成新的项目 prefab 和动作。只有在导入资源已经带有经过验证的 rig 配置、且目标模型与动作源确实同骨架同空间时，才可以把 HumanoidSourceAnimations 作为兼容模型的快捷声明。显式重定向完成后，可以把生成的项目动画列入该字段用于资源收集，但不要让它承担首次映射。

已有同骨骼的未压缩 UANI .ani 时，按 骨骼与动作导入 使用 animations 映射；将待机动作命名为 idle 可默认循环预览。无需对已交付的 MDL 再做网格转换。导入返回骨骼数量和动作摘要；预览检查轨道匹配，再看实际动作播放，保存重开复验。不能直接套用另一套骨骼的官方动作，也不能把 XML AnimatedModel 手工改成 staticMesh。

绑骨包可能使用 Techniques/DiffNormal.xml；导入器会将其适配为非金属 PBR，以高光指数近似换算粗糙度。该适配需要查看实际光照效果。

需要大剑劈砍等官方动作时，先按 官方动作重定向 读取两套骨架、补齐明确映射，并通过 resource_retarget_animations 生成新的项目 prefab 与动作。源模型须对应所选动作家族，不统一套用同一个标准骨架。保留原资源目录，因为新 prefab 仍引用其材质和贴图；检查实际播放与项目重载，不能以绑骨成功、动画描述字段或 HumanoidSourceAnimations 已填写代替验收。

无骨架静态道具的包装

此示例适用于单个静态模型。骨架、动画、复杂节点层级需要按对应导入流程处理，不能把 AnimatedModel 直接改成 staticMesh。

项目目录：

res/deco/maker_prop/model.prefab
res/deco/maker_prop/Meshes/prop.mdl
res/deco/maker_prop/Materials/prop.material
res/deco/maker_prop/Textures/prop_D.jpg
res/deco/maker_prop/Textures/prop_D.xml

目录名称在项目内保持唯一，model.prefab 是模型目录的惯用入口。引擎引用从 res/ 以下开始，不写绝对路径、res/ 或 Maker 的 assets/ 前缀。资源库和 MCP 可能返回带 res/ 的项目文件定位路径，不要把该前缀写进 mesh/material 引用。

model.prefab 内容：

[
  {
    "type": "projectResourceInfo",
    "map_name": "maker_prop",
    "good_path": "deco/maker_prop/model.prefab/",
    "show_name": "自定义道具"
  },
  { "type": "prefabInfo", "importType": "deco", "sourceInfo": "" },
  {
    "type": "staticMesh",
    "staticMesh": "deco/maker_prop/Meshes/prop.mdl",
    "materials": ["deco/maker_prop/Materials/prop.material"],
    "position": { "x": 0, "y": 0, "z": 0 },
    "rotation": { "w_": 1, "x_": 0, "y_": 0, "z_": 0 },
    "scale": { "x": 1, "y": 1, "z": 1 },
    "uuid": "REPLACE_WITH_NEW_STABLE_ID"
  }
]

为 mesh 条目生成稳定且唯一的 uuid，例如 GUID；后续编辑保留它。materials 按 MDL 的 geometry 槽位排列，多材质模型不能只保留第一个材质。projectResourceInfo 提供显示名与项目资源信息，无需伪造账号素材记录或手写 project_resources.json。

适配材质

不要假定 Maker 的 Techniques/PBR/PBRDiffNormal.xml 在星火存在，也不要根据名称拼接 technique 路径。先建立可渲染基线。无透明度道具可用下面的仅颜色贴图 Materials/prop.material：

<?xml version="1.0"?>
<material>
  <technique name="Editor/Techniques/PBR_PackedNormal/DefaultMetallicRoughness.xml" quality="0" loddistance="0" />
  <texture unit="diffuse" name="deco/maker_prop/Textures/prop_D.jpg" />
  <parameter name="ColorFactor" value="1 1 1 1" />
  <parameter name="MetalMul0or1" value="0" />
  <parameter name="MetallicFactor" value="1" />
  <parameter name="RoughnessFactor" value="0.85" />
  <cull value="ccw" />
  <shadowcull value="ccw" />
</material>

常见 sRGB 编码的颜色贴图在首次加载前添加同名参数文件 Textures/prop_D.xml；直接引用贴图不会自动补齐声明。源素材明确使用线性颜色时保留源约定。示例：

<texture><srgb enable="true" /></texture>

此基线保留颜色并使用网格法线，适合定位不可见问题，不代表完整保留 Maker PBR 材质。透明模型另选星火透明材质模板。DefaultMetallicRoughnessSolid.xml 使用无贴图路径，不能直接替代需要显示颜色贴图的材质；DefaultMetallicRoughnessPackedNormal.xml 不是此模板的正确名称。

上述星火 PBR 材质的 normal 槽使用混合通道：R/G 为法线 X/Y，B 为粗糙度，A 为金属度。普通 RGB 法线的蓝色通道是法线 Z，不能原样当粗糙度。需要接入时保留源法线 R/G，填入实际粗糙度 B 和金属度 A，保存为 RGBA 新文件，保留原始法线；例如石质道具可先用粗糙度 0.85、金属度 0。混合贴图同名参数 XML 设置 srgb enable="false"。

接入混合贴图后，RoughnessFactor / MetallicFactor 会乘以通道值。图中已保存最终值时将两者设为 1，避免把 0.85 再乘 0.85；需要金属度时在材质文件中显式配置 MetalMul0or1=1，并验证实际反光。缺少表面数据时先用仅颜色贴图和网格法线建立基线；需要法线时再根据已确定的粗糙度/金属度生成混合图。

上述布局仅用于这个 packed-normal Technique；MaterialPBRVertexColor 使用独立法线图与 R=粗糙度、G=金属度的数据图。不要按 .tga 后缀判断内容或颜色空间，也不要按 Maker 来源自动翻转法线绿色通道。完整规则见材质贴图颜色空间与通道契约。

模型包导入 MCP 已生成颜色图 sRGB=true、混合图 sRGB=false 的 XML；手动复制或 GameGraph 直接引用时自行补齐。修改 XML 后重载贴图和材质，必要时重进调试；用 material.probe 检查实际 s_rgb、槽位和系数，并在固定镜头/光照下对照画面。不要把对已加载纹理调用 SRGB setter 当作 GPU 资源已重建的证明。

材质验收应覆盖所有实际使用的颜色贴图路径，包括地板和道具等手动复制或直接通过 Texture2D.Load 加载的资源。逐张核对同名 XML，重载后检查运行时 s_rgb，并在固定镜头、光照和材质系数下比较画面；某个模型已生成正确配置不代表其他资源也已配置。具体步骤见逐张贴图验收。

朝向、尺寸与底面

星火以 XY 为水平面、Z 为高度。用 resource_get_preview_info 查看 bboxMin、bboxMax、bboxSize，结合画面判断模型实际方向，不要假定每个 Maker 模型一致。

• 宽度约 1 单位的模型在 256 单位地形瓦片上很难看到。按目标宽度除以模型宽度计算比例；256 倍只是这种尺寸的示例，不能套到所有模型。
• Y 向上的模型可用绕 X 轴 +90° 的四元数 {w_:0.70710678,x_:0.70710678,y_:0,z_:0} 转为 Z 向上，再检查朝向。
• 地砖薄面可能沿 X 而非 Y，此时按实际情况选旋转，如绕 Y 轴 +90°，不要机械使用相同 X 旋转。
• 模型原点在中心时，旋转、缩放后计算最低点，调整 mesh 的 position.z 使底面落在 Z=0，否则地表吸附会埋入半个模型。

将基础尺寸、方向和锚点写进 prefab，地编实例就能使用默认变换。

美术资源库查看

1. 打开目标项目，点击顶部「美术资源库」，切到「美术素材」。
2. 左上选择「项目资源」。项目 res/ 文件从这里找，「我的资源」对应另一处来源。
3. 展开 res → deco → maker_prop，选中 model.prefab。新版项目文件树直接读取磁盘，不要求账号素材登记；目录没更新时收起再展开，或重载项目。
4. 检查实际 3D 预览中的材质、尺寸、方向和底面。外部修改已经加载的文件后用条目右键「重载」；依赖仍使用旧缓存时重新打开项目。

地编放为装饰物

1. 打开项目场景，在场景视图工具面板选择「素材」（树形图标）。
2. 素材浏览来源选择「项目资源」，展开道具目录。
3. 将列表中的 model.prefab 条目拖到地形上；不要拖裸 MDL、贴图、文件夹或 Maker XML prefab。
4. 检查显示、尺寸、方向和贴地位置，确认左侧场景树出现实例，按需调整变换并保存场景。

AI 有地形 MCP 时，可通过 terrain_list_decoration_resources 获取 resource_id，按实时 schema 执行 terrain_preview_decoration_edit → terrain_apply_decoration_edit → terrain_query_decorations 验证放置。这套装饰物 MCP 当前适用于离散瓦片地形，其它地形按编辑器支持的交互操作。resource_id 来自当前目录，不自行计算或拿路径替代。放置会修改场景，只在用户要求的目标位置或测试副本执行。

完成判据与排错

交付准确 prefab 路径、资源库位置与地编放置步骤。依次验证：文件引用存在且无残留 UUID；preview-info 返回非零模型/顶点/三角形、有效 bbox 和预期贴图；实际画面可见、材质正确、能放置和保存。元数据 success=true 不能证明 technique 或 shader 渲染正确，同时检查编辑器本次运行的资源/technique/shader 错误。

现象	优先检查
文件复制后找不到	当前项目、项目资源来源、目录展开状态、model.prefab 入口
Prefab为空	Maker XML 与星火 JSON 格式、UUID 映射
加载成功却看不见	technique 是否存在、shader 错误、尺寸、相机和朝向
导入模型发白	优先检查颜色图 sRGB；常见 sRGB 颜色图若实际 SRGB=false，先在同名 XML 设置 true，重载并固定光照对照，再查光源、环境反射、曝光和系数；线性颜色与法线/数据图保持 false
材质不正确	diffuse 路径、sRGB、普通法线与混合通道、材质系数
放置后竖起或埋入地面	薄面轴、四元数、缩放、Z=0 底面锚点
发布缺失	项目资源查 res 文件及引用；云资源预下载查资源统计与 objref.txt

项目内 res 资源随客户端包封装，不需要资源统计或 objref.txt 条目；通过场景、数编或代码加载都遵循这个边界。资源统计用于让客户端预下载云资源。Maker 模型按本页导入项目 res 后，保留完整依赖、保存场景并确认重新打开后可见即可，不要为它运行资源统计或增加无用途代码引用。