RealityKit：为导入的USDZ模型局部添加材质

先排查加载逻辑的潜在问题 #

首先，你用try?加载模型的方式可能掩盖了加载失败的情况——如果模型文件不存在或格式错误，coastRanges会直接是nil，此时打印children自然是nil。调试阶段建议改用明确的加载校验：

guard let coastRanges = try? ModelEntity.loadModel(named: "CoastRanges") else {
    fatalError("CoastRanges模型加载失败，请检查文件名或格式")
}

核心问题：模型层级结构的访问方式错误 #

你遇到的children为nil，大概率是以下两种情况之一：

1. 加载方法选错了：ModelEntity.loadModel(named:)只会返回单个ModelEntity，如果你的USDZ根节点是一个用来容纳子实体的容器（非ModelEntity），这种加载方式会直接丢弃层级结构，导致子节点丢失。应该改用通用的Entity.load(named:)加载完整层级：

guard let coastRoot = try? Entity.load(named: "CoastRanges") else {
    fatalError("模型加载失败")
}
// 此时遍历根节点的children就能看到子实体
for child in coastRoot.children {
    print("子实体名称：\(child.name)")
}

2. 模型被合并成单个Mesh：如果在Reality Composer Pro导出时选择了合并网格，原本的子对象会被合并成一个ModelEntity的多个submesh，此时子节点不会出现在children里，而是在model?.mesh.submeshes中。这种情况下需要给submesh分配对应材质：

guard let coastModel = coastRanges as? ModelEntity, let mesh = coastModel.model?.mesh else {
    return
}

// 创建自定义材质
let terrainMat = SimpleMaterial(color: .systemGreen, roughness: 0.6, isMetallic: false)
let oceanMat = SimpleMaterial(color: .systemBlue, roughness: 0.2, isMetallic: false)
let rockMat = SimpleMaterial(color: .systemGray, roughness: 0.9, isMetallic: true)

// 注意：submesh的顺序和建模软件中对象的顺序一致，需要对应好
coastModel.model?.materials = [terrainMat, oceanMat, rockMat]

额外注意事项 #

• Reality Composer Pro导出设置：导出时务必勾选「Preserve Hierarchy」（保留层级）选项，避免自动合并子节点导致层级丢失。
• 递归查找子实体：如果子节点嵌套较深，可以用递归函数快速定位目标实体：

func findTargetEntity(named targetName: String, in parent: Entity) -> ModelEntity? {
    if parent.name == targetName, let modelEntity = parent as? ModelEntity {
        return modelEntity
    }
    for child in parent.children {
        if let found = findTargetEntity(named: targetName, in: child) {
            return found
        }
    }
    return nil
}

// 用法示例：找到名为"Rock"的子实体并替换材质
if let rockEntity = findTargetEntity(named: "Rock", in: coastRoot) {
    rockEntity.model?.materials = [rockMat]
}

内容的提问来源于stack exchange，提问作者Joe