游戏引擎 / 系统课时
导入模型并检查资源结构
导入模型并检查资源结构
本课把一个从 Blender 等建模工具导出的 3D 模型导入 Godot 4,并确认它能作为场景实例使用。你将沿着源文件、节点、网格、材质和贴图逐层检查,发现缺失依赖时也能定位到具体环节,而不是只看模型是否出现在视口中。
学习目标
- 使用 glTF/GLB 文件完成模型导入与场景实例化。
- 识别
MeshInstance3D、Mesh、材质和贴图之间的引用关系。 - 用编辑器与脚本检查表面、材质及外部资源是否正常。
理清源文件和导入资源
推荐先用 .glb 验证流程:它通常将几何、材质及可嵌入的贴图打包在一个文件中,便于搬移。.gltf 也受支持,但可能另行引用 .bin 文件与图片;复制时必须保留这些文件及其相对路径。导出时还应确认模型朝向、单位尺寸和 UV 已在源工具中整理好。
Godot 会将 3D 源文件导入为可实例化的场景资源。场景里的 MeshInstance3D 节点负责显示几何;其 mesh 引用 Mesh,一个 Mesh 可以包含多个表面(surface),每个表面可使用不同材质。材质进一步引用颜色、法线等贴图。材质或贴图内嵌在导入场景中时,不一定会以独立文件出现在文件系统面板。

完成导入并查看节点
- 在项目文件系统中建立
res://assets/models/,把示例crate.glb复制进去。回到 Godot,等待编辑器自动导入;检查输出面板有无导入错误。 - 在 FileSystem(文件系统)面板单击该模型,打开 Import(导入)面板。需要查看每个节点、网格或材质时,点击底部的
Advanced...;在高级导入设置中分别检查 Scene、Meshes、Materials 页面。 - 将模型从 FileSystem 拖入自己创建的
Level.tscn,确认它作为场景实例出现,并检查尺寸、朝向、网格是否完整。需要附加碰撞体或游戏逻辑时,优先在外层关卡或继承场景中扩展,避免直接修改源导入结构。 - 如果改动导入选项,执行重新导入,再返回关卡确认结果。材质需要长期单独编辑时,可在高级导入窗口使用
Actions... > Extract Materials将内嵌材质提取为外部资源。

用脚本核对模型绑定
在新建的 ImportCheck.tscn 中使用 Node3D 作为根节点,挂载下列完整 GDScript。运行前,在 Inspector 中将 model_scene 指向已导入的 crate.glb。脚本遍历实例节点,统计实际存在的网格表面与未绑定材质的表面;这比仅凭外观判断更明确。
extends Node3D
@export var model_scene: PackedScene
func _ready() -> void:
if model_scene == null:
push_error("请先在 Inspector 绑定导入的模型场景")
return
var root := model_scene.instantiate()
add_child(root)
var report := {"meshes": 0, "surfaces": 0, "no_material": 0}
_inspect(root, report)
print("网格节点:%d,表面:%d,未绑定材质:%d" % [
report["meshes"], report["surfaces"], report["no_material"]
])
func _inspect(node: Node, report: Dictionary) -> void:
if node is MeshInstance3D:
var item := node as MeshInstance3D
if item.mesh == null:
push_warning("%s 的 Mesh 为空" % item.name)
else:
report["meshes"] += 1
# 同一个网格可以有多个材质表面,逐个检查有效材质。
for i in range(item.mesh.get_surface_count()):
report["surfaces"] += 1
if item.get_active_material(i) == null:
report["no_material"] += 1
for child in node.get_children():
_inspect(child, report)预期输出(以包含一个网格节点、一个表面且已设置材质的模型为例):
网格节点:1,表面:1,未绑定材质:0实际数字由模型决定。出现“未绑定材质”不必然意味着导入失败:Godot 仍可能使用默认材质渲染,但需要确认这是否符合美术预期。无网格或空 Mesh 才是更直接的结构异常。
定位常见的导入问题
- 网格缺失或形状不对:先检查高级导入窗口的节点与网格,再回源工具确认对象是否参与导出、变换是否应用,修复后重新导出。
- 颜色贴图没有出现:检查
.gltf依赖的图片是否在原相对路径,查看材质是否确实引用了纹理,并确认模型具有 UV;.glb的内嵌贴图不要求在项目中另找同名图片。 - 改动材质后重新导入丢失:不要直接依赖对内嵌导入资源的临时修改。将需要长期维护的材质提取为
.tres,或在继承场景中覆盖材质。
最终验收应同时满足:场景能实例化、节点数量符合源模型、各表面引用正确、贴图外观与光照下的预期一致。出现异常时沿着“源文件 → 网格 → 材质 → 贴图”逐层回查,通常比反复调场景属性更有效。