MetaCore 资产导入契约（R2）

本文定义 R2 首版的正式输入范围、诊断语义和缓存身份。未列为“支持”的格式不得产生可被 Registry 当作成功结果的 .mcasset。

支持矩阵

输入	状态	说明
glTF 2.0 `.gltf`	支持	JSON、外部 Buffer、Data URI、外部或嵌入图片、节点层级、Mesh、PBR Material、UV 和动画元数据
glTF 2.0 `.glb`	支持	与 `.gltf` 使用相同导入契约；容器、JSON 或 Buffer 损坏时失败
PNG/JPEG/TGA/BMP/PSD/GIF/HDR/PPM	支持	进入统一纹理解码、色彩/法线处理、尺寸限制和 Mipmap 链
MetaCore Material	支持	`.mcmaterial.json`，引用只保存 Asset GUID
FBX `.fbx`	不支持	写入失败诊断，不写占位 `.mcasset`
Wavefront OBJ `.obj`	不支持	写入失败诊断，不写占位 `.mcasset`

glTF 合法但尚未实现的可选能力应产生 Warning 并保留可用部分；无法解析容器/JSON、无法加载必需 Buffer 或无法解码必需图片应产生 Error。Error 不覆盖上一次成功产物。

代码	级别	含义
`gltf_import_failed`	Error	glTF/GLB 解析或必需 Buffer 加载失败
`unsupported_model_format`	Error	FBX/OBJ 在当前版本不受支持
`missing_texture_reference`	Warning	PBR Base Color 贴图索引无效
`missing_metallic_roughness_texture_reference`	Warning	金属粗糙贴图索引无效
`subasset_guid_ambiguity`	Warning	重名或匿名子资产无法按唯一规范名称匹配旧 GUID
`generated_root_node`	Info	源文件没有节点层级，导入器生成逻辑根节点

诊断码属于持久化契约，UI 文案可以本地化，但代码含义不得在不提升 Importer Version 的情况下改变。

.mcmeta Schema 2 保留原 GUID，并记录 Importer Version、规范化 Import Settings、Settings Hash、Artifact Key、最近导入结果和诊断。旧元数据读取时补默认值，不因升级生成新 GUID。

Artifact/DDC Key 的输入集合为：源内容 Hash、规范化 Settings Hash、Importer/生成器版本、目标平台和工具版本。派生包位于 Library/DerivedData，缩略图位于 Library/Thumbnails，两者均可删除并重建，不进入版本控制。

Linux 纹理压缩后端使用 vcpkg 提供的 Basis Universal 编码器生成 UASTC KTX2。颜色纹理按 sRGB 编码，数据与法线纹理保持 Linear，法线缩放后可重新归一化；关闭压缩时保留未压缩 RGBA 像素链。编码器进程属于可取消的导入阶段，进入原子提交后不再中断。

子资产首先按稳定导入键匹配；键变化时，仅在“类型 + 规范名称”在新旧集合中都唯一的情况下恢复旧 GUID。歧义项使用稳定序号并报告 Warning。