项目模型资源包导入

将本机模型包导入为能在美术资源库预览、在地编放置的项目资源。导入已有文件不需要连接模型生成服务；使用 Maker 生成资产仍需 Maker 使用资格。

选择入口

先通过 Editor MCP tools/list 确认当前工具与参数。

输入	入口
FBX 源文件	resource_import_fbx_batch
XML prefab、静态或骨骼 UMD2 MDL、材质、贴图、UANI 动作组成的目录或 ZIP	resource_import_model_package
可用的星火 JSON prefab 与依赖	放入项目 res，再 resource_reload / resource_open_preview

资源包导入支持静态网格、带骨骼的 AnimatedModel 和匹配该骨骼的未压缩 UANI .ani 动作。支持不透明 PBRDiff / PBRDiffNormal 及 Diff / DiffNormal 源材质、多个节点和材质槽。Morph、透明材质、压缩动作、不能保留的组件或剪切变换明确报错。Maker 的 XML prefab 与 UUID .meta 属于此路线，无需寻找 FBX 或重复转换网格。Diff 材质适配为非金属 PBR，粗糙度由高光指数近似换算；检查预览光照，必要时覆盖 roughness / metallic。

预览与执行导入

对木箱资源包，可调用 resource_import_model_package：

{
  "sourcePath": "D:/Assets/crate-package",
  "destination": "res/deco/my_crate",
  "displayName": "木箱",
  "sourceUpAxis": "y",
  "targetWidth": 256,
  "alignGround": true,
  "roughness": 0.85,
  "metallic": 0,
  "dryRun": true
}

sourcePath 为本机目录/ZIP 的绝对路径；包内多份 prefab 时用 entryPoint 指定相对路径。destination 为当前项目 res 下的目标目录。工具保留源文件，输出 model.prefab 及网格、材质、贴图依赖。

dryRun 不写项目文件，返回适配值、资源路径、包围盒与变换。检查计划符合用途后，在用户授权的范围内将相同请求改为 dryRun=false 执行。

• sourceUpAxis 默认 preserve；x/y/z 将指定源向上轴转为星火 Z 向上，不自动猜测模型朝向。
• targetWidth 是转换后的世界 X 包围盒宽度，与等比 scale 互斥；未设置时 scale=1。
• alignGround 使模型整体最低点位于本地 Z=0。
• roughness / metallic 可覆盖为 0 到 1；未指定时读取源材质。木材 0.85/0 是示例，不是所有模型的通用默认值。

输出位于 res/deco/my_crate/model.prefab，配套文件在 Meshes、Materials、Textures 子目录。引擎路径为 deco/my_crate/model.prefab，不含 res/。

默认已有 prefab 时返回 skipped；overwrite=error 可改为报错。工具不覆盖既有资源。文件先在暂存目录完成，转换失败不会提交半套资源。若调用超时，先检查目标目录和目录状态，不盲目重新生成或重放写请求。

导入后自动刷新项目资源树并返回 validation。验证失败时 status=imported_with_validation_errors；mutatedProject=true 表示文件已导入，需要根据 diagnostics 修复，不能当作可用资源交付。

颜色空间与混合贴图

resource_import_model_package 为输出的颜色贴图生成同名 XML，声明 sRGB=true；有源法线时，生成线性的 RGBA 混合贴图，R/G=法线 X/Y、B=粗糙度、A=金属度，并声明 sRGB=false。粗糙度和金属度已写入混合图时，输出材质的两个 Factor 为 1，避免重复相乘；没有法线混合图时，直接在材质系数中保存这些值。

这些设置属于模型包导入适配，直接复制 MDL/贴图或调用 Texture2D.Load(...) 不会自动完成。不要把普通 RGB 法线的 B 通道当作粗糙度，也不要把这一布局套给使用独立法线和 R/G 数据图的 MaterialPBRVertexColor。手动适配、线性颜色例外、缓存重载和运行时验证见材质贴图规则。

骨骼与动作导入

绑骨只会生成骨骼及蒙皮，不代表包内已有动作。导入骨骼模型时指定绑骨后生成的 prefab；Maker 本地目录可能同时保留静态版本和绑骨版本。

{
  "sourcePath": "D:/Assets/robot-package",
  "entryPoint": "Prefabs/rig.prefab",
  "destination": "res/characters/my_robot",
  "displayName": "测试机器人",
  "animations": { "idle": "Animations/wait.ani", "walk": "Animations/walk.ani" },
  "dryRun": true
}

animations 将目标动作名映射到包内路径或 uuid://。省略时扫描包内 .ani；空对象仅导入模型。idle 用于默认循环预览，可将一个合适的待机动作映射到它。没有 idle 时提示以绑定姿势导入，其他动作可在模型预览的动作列表中选择播放。不要把 FBX、GLB 或任意不匹配的官方动作改后缀当作 ANI。

导入保留 MDL 骨骼、蒙皮及 ANI 原始字节，写入 skeletalMesh 和 animationSet；模型的方向、缩放和贴地变换应用在骨骼模型外层。动作轨道须匹配包内模型骨骼，否则返回 animation_skeleton_mismatch，需要使用同一骨骼导出的动作或先完成重定向。工具返回 boneCount、skeletalMeshCount 和动作时长、轨道、关键帧数量；dryRun 不写文件。

完成导入后，先检查骨骼和动作依赖，再打开 prefab 预览。在预览中间的组件树选择「骨骼模型(组件)」，切到右侧「动画」页签，选择导入的动作；底部可暂停、播放和拖动时间轴。确认动作列表、循环播放和实际姿势变化，重新加载项目后复验。界面的「未完成重定向」提示针对套用另一套骨骼的动作库；本模型的兼容 ANI 不需要为此强行重定向。Maker 的动作生成能力以实时 tools/list 为准；仅支持 rig 的工具不能直接生成动作。

官方动作重定向

带骨骼的外部模型需要把官方动作重定向到自己的骨架，不能只改骨骼名字或复制不匹配的 ANI。

1. 从目标 prefab 的 resource_get_preview_info 中找到 MDL，再用 resource_get_skeleton 分别读取目标 MDL 与原动作对应的源 MDL。结果包含骨名、父节点与绑定姿势。
2. 根据语义和层级建立 boneMap：键是源骨名，值是目标骨名。补齐骨盆、脊柱、头、双臂、双腿及手脚的对应，检查未映射骨骼。
3. 用 alignmentBones 指定已映射的躯干上下与左右骨骼，统一模型空间方向与单位。调用 resource_retarget_animations，先 dryRun=true 检查内存生成结果，再改为 false 写入新的资源目录。默认不覆盖任何已有目录或原资源。
4. 打开新 prefab，选「骨骼模型(组件) → 动画」，检查实际动作、时间轴、肢体拉伸及脚底位置，再重新加载项目复验。

请求结构如下；示例 boneMap 只展示字段格式，执行前须依据两套真实骨架补齐，不能把三行映射当成完整人形映射：

{
  "targetPrefab": "characters/my_robot/model.prefab",
  "sourceModel": "characters0/human/body/model/m.mdl",
  "boneMap": {
    "Bip001": "Hip",
    "Bip001 Pelvis": "Pelvis",
    "Bip001 L Forearm": "L_Forearm"
  },
  "alignmentBones": {
    "upStart": "Bip001 Pelvis",
    "upEnd": "Bip001 Head",
    "rightStart": "Bip001 L UpperArm",
    "rightEnd": "Bip001 R UpperArm"
  },
  "animations": [
    { "source": "anim/human/sword_anim/DaJianZhanShi/idle.ani", "name": "idle" },
    { "source": "anim/human/sword_anim/DaJianZhanShi/skill_01.ani", "name": "attack" }
  ],
  "destination": "res/characters/my_robot_sword",
  "displayName": "机器人双手剑动作",
  "sampleRate": 30,
  "dryRun": true
}

这里的源模型对应 anim/human/... 标准人形动作；其它动作家族要使用其实际参考模型，不能因骨名相同就假定姿态、轴向和比例相同。工具支持单骨骼网格 JSON prefab，以及一批最多 32 个原始动作。稀疏或压缩轨道按原时长统一重采样，保留命中、取消打点；逻辑多段动作应分别重定向其原片段。现有算法要求单个 Root 位于骨骼数组首位、父节点在前，Root 开关控制是否包含根骨骼，默认启用，与既有重定向流程一致；它不是游戏单位移动开关。

生成摘要包含映射数量、未映射目标骨骼、动作轨道、关键帧和活动骨骼数量，以及源到目标的空间旋转和单位比例。alignmentBones 的四个源骨名都必须有对应 boneMap 条目；上例省略的骨骼映射也须补全。不能只旋转 prefab 来修复动作内部的错轴。

生成前用源参考姿势构造恒等动作，检查它能否还原目标参考姿势；bindPosePositionError / bindPoseRotationError 返回误差，不满足检查时明确失败。未知骨名、重复目标映射、源骨架不匹配或生成失败会返回原因，不会把未转换的源动作当作成功结果。dryRun 会实际计算内存中的动作，但不写项目文件。

执行后生成新 MDL、ANI、model.prefab 和骨骼映射配置，保留原资源。新 prefab 仍引用原项目目录的材质和贴图，需保留原目录。这些项目资源随客户端包封装，无需资源统计。retargeted_with_validation_errors 表示文件已生成但依赖检查失败，修复诊断后才能交付。

未映射的骨骼保留原绑定关系；重定向不会补出模型没有的手指骨或蒙皮。数据匹配与活动骨骼数量不能证明握剑、手指开合、脚底接触或所有动作都正确。需要武器时还要实测挂点和握持效果。

对齐按两套骨架的实际参考方向计算，不依据 MDL 文件名或 Maker 来源套用固定旋转。同骨架、同空间的普通星火模型应得到单位旋转和比例 1。现有 UMD2 与 UUID 元信息没有统一的 Maker 来源标记，记录出处与决定坐标转换是不同的用途。

诊断与实际预览

调用 resource_get_preview_info，pathOrId=deco/my_crate/model.prefab，includeCatalog=false。

• meshLoaded 表示网格实际加载；dependenciesReady 表示材质、贴图和 technique 可用。
• 依赖错误时 success=false、loadStatus=loaded_with_dependency_errors，preview 仍保留部分包围盒、网格和贴图摘要。
• diagnostics 的 code / path / owner 定位 mesh_load_failed、material_load_failed、texture_missing、texture_load_failed、technique_load_failed 等问题。
• 骨骼网格的 animations 摘要提供 length、trackCount、matchedTrackCount；动作加载失败或轨道不匹配时返回 animation_load_failed / animation_skeleton_mismatch。
• 材质摘要包含 techniques / techniquesReady。shaderValidation=not_evaluated 表示未验证所有 GPU shader 变体，不能据此宣称画面必然正确。

用 resource_open_preview 请求打开美术资源库并定位 prefab：

{ "path": "deco/my_crate/model.prefab" }

返回 previewStatus=requested，窗口在后续 UI 帧定位。查看画面确认贴图、方向、大小和底面。外部修改文件后使用 resource_reload，path 同样为当前项目资源路径；它只重载该资源目录的缓存。

旧编辑器没有这些工具时，可按 Maker 模型手动适配 处理，从「美术资源库 → 美术素材 → 项目资源」选中 model.prefab。

地编放置与保存

打开场景，选择工具面板「素材」，来源选「项目资源」，展开 res/deco/my_crate，将 model.prefab 条目拖到地形。检查左侧树、大小、方向和贴地位置，保存后重新打开场景确认。

AI 也可用现有地形 MCP 查询 resource_id 并通过 preview/apply/query 放置；这套装饰物 MCP 适用于离散瓦片地形。两种方式使用同一 prefab，不必再建 GameDataUnit。

项目 res 资源随客户端包封装，不需要资源统计或 objref.txt 条目。资源统计用于预下载云资源。导入本地包不会上传云素材或自动发布项目。