assets-pipeline

Godot 4.3+ 中的资源管线

所有示例均面向 Godot 4.3+，不使用已弃用的 API。先展示 GDScript，再展示 C#。

相关技能： audio-system 用于音频播放和总线架构，3d-essentials 用于 3D 材质和光照，2d-essentials 用于 2D 渲染和精灵，animation-system 用于导入动画，godot-optimization 用于资源相关的性能优化，multithreading 用于多线程资源加载。

---

1. 导入的工作原理

导入系统

将文件添加到 res:// 时，Godot 会根据文件类型自动导入。导入设置存储在原始文件旁边的 .import 旁置文件中。

project/
├── textures/
│   ├── player.png           ← original file (committed to VCS)
│   └── player.png.import    ← import settings (committed to VCS)
└── .godot/
    └── imported/            ← compiled cache (NOT committed — .gitignore it)

关键规则

• 切勿修改 .godot/imported/ 中的文件——它们会根据原始文件重新生成
• 将 .import 文件提交到版本控制——它们存储了你的设置
• 更改设置后重新导入：选择文件 → Import 停靠面板 → 点击 Reimport
• .godot/ 应添加到你的 .gitignore 中

更改导入设置

1. 在 FileSystem 停靠面板中选择文件
2. 打开 Import 停靠面板（默认位于 Scene 停靠面板旁边）
3. 更改设置
4. 点击 Reimport（批量更改时点击 Reimport All）

对于 3D 场景，也可以通过 Advanced Import Settings 设置导入选项（双击 .glb/.gltf 文件）。

---

2. 图像导入

压缩模式

模式	质量	显存	文件大小	用途
Lossless	完美	高	大	像素画、UI 元素
Lossy	良好	高	小	大型照片、背景
VRAM Compressed	降低	低	小	3D 纹理、大型 2D 精灵
VRAM Uncompressed	完美	高	大	无法接受显存压缩伪影时
Basis Universal	降低	低	极小	跨平台、多种 GPU 格式

各模式的适用场景

Pixel art / UI icons       → Lossless (no artifacts, crisp pixels)
2D game sprites            → Lossless (small sprites) or VRAM Compressed (large sprites)
3D textures (albedo, normal) → VRAM Compressed (saves GPU memory)
Large backgrounds          → Lossy or VRAM Compressed
Mobile targets             → VRAM Compressed (essential for memory)

关键导入设置

设置	说明	默认值
Compress > Mode	压缩算法（见上表）	Lossless（在 3D 预设中为 VRAM Compressed；检测到用于 3D 的纹理时，会切换为此模式）
Mipmaps > Generate	生成用于远距离渲染的 mipmap	Off（在 3D 预设中为 On）
Process > Fix Alpha Border	防止透明精灵出现暗色轮廓	On
Process > Premult Alpha	预乘 Alpha（避免出现暗色光晕）	Off

在 Godot 4 中，过滤和重复不是导入选项：它们是每个 CanvasItem 上的 texture_filter / texture_repeat（或 3D 中材质采样器上的设置）。

像素画设置

要让像素画显示清晰，请在整个项目中设置：

Project Settings > Rendering > Textures > Canvas Textures > Default Texture Filter → Nearest

也可以按节点设置：CanvasItem.texture_filter → Nearest

启用 Mipmap

Mipmap 可防止从远处或倾斜角度观看纹理时出现闪烁。3D 纹理必须启用；2D 纹理可选。

• **3D 纹理：**始终启用 mipmap（Import 停靠面板 → Mipmaps → Generate → On）
• **2D 精灵：**通常关闭（除非使用 Camera2D 缩放）
• **UI 纹理：**关闭（以固定比例渲染）

**Godot 4.7+：**DDS 导入支持 R8 和 R8G8 纹理格式。（GH-116307）

---

3. 3D 场景导入

支持的格式

格式	扩展名	建议
glTF	.gltf, .glb	推荐 — 开放标准，支持最佳
Blend	.blend	直接导入 Blender（需要安装 Blender）
FBX	.fbx	适用于旧版工作流
Collada	.dae	较旧的格式，尽可能使用 glTF
OBJ	.obj	仅静态网格 — 不包含动画/骨架

glTF 是推荐格式。 它对 Godot 的支持最好，是开放标准，并能准确保留材质、动画和骨架。

节点命名约定

Godot 会根据 3D 模型对象名称中的后缀自动创建相应的节点类型：

后缀	生成的节点	示例名称
-col	StaticBody3D + 碰撞	Wall-col
-convcol	ConvexPolygonShape3D	Rock-convcol
-rigid	RigidBody3D	Barrel-rigid
-navmesh	NavigationRegion3D	Floor-navmesh
-occ	OccluderInstance3D（-occonly 会移除网格）	BigWall-occ

In Blender:                  In Godot (after import):
Wall-col (mesh object)    →  Wall (MeshInstance3D)
                               └── StaticBody3D
                                   └── CollisionShape3D (auto-generated)

导入面板设置

在文件系统中选择导入的 .glb/.gltf，然后在导入面板中：

设置	说明
Root Type	覆盖根节点类型（Node3D、RigidBody3D 等）
Root Name	自定义根节点名称
Meshes > Generate LOD	自动生成 LOD 级别（默认启用）
Meshes > Light Baking	用于光照贴图烘焙的静态或动态模式
Animation > Import	启用/禁用动画导入
Animation > FPS	按此帧率烘焙动画

Godot 4.7+： 导入面板的导入类型选项还可以将 3D 场景文件导入为单个 Mesh 资源或 MeshLibrary（用于 GridMap），而不是完整场景 — 无需在 3D 创作工具中单独导出。(GH-107856)

⚠️ Godot 4.7 中的变更： EditorSceneFormatImporter 的 IMPORT_SCENE、IMPORT_ANIMATION、IMPORT_FAIL_ON_MISSING_DEPENDENCIES、IMPORT_GENERATE_TANGENT_ARRAYS、IMPORT_USE_NAMED_SKIN_BINDS、IMPORT_DISCARD_MESHES_AND_MATERIALS 和 IMPORT_FORCE_DISABLE_MESH_COMPRESSION 常量已移至新的 ImportFlags 枚举（位域）中。该变更兼容 GDScript；引用旧类级常量的 C# 导入器插件必须改用枚举成员。请参阅 4.7 migration guide。

运行时场景加载

对编译时已知的路径使用 preload()，对数据驱动的路径使用 load()。GDScript 和 C# 代码片段：references/runtime-resource-loading.md。

运行时 glTF 导入标志（Godot 4.7+）

GLTFDocument 提供 ImportFlags 位域 — IMPORT_FLAG_GENERATE_TANGENT_ARRAYS（8）、IMPORT_FLAG_USE_NAMED_SKIN_BINDS（16）、IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS（32）、IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION（64）— 由 append_from_file()、append_from_buffer() 和 append_from_scene() 的 flags: int = 0 参数接受：

var doc := GLTFDocument.new()
var state := GLTFState.new()
doc.append_from_file("user://mods/enemy.glb", state,
        GLTFDocument.IMPORT_FLAG_GENERATE_TANGENT_ARRAYS | GLTFDocument.IMPORT_FLAG_USE_NAMED_SKIN_BINDS)
add_child(doc.generate_scene(state))

var doc = new GltfDocument();
var state = new GltfState();
doc.AppendFromFile("user://mods/enemy.glb", state,
    (uint)(GltfDocument.ImportFlags.GenerateTangentArrays | GltfDocument.ImportFlags.UseNamedSkinBinds));
AddChild(doc.GenerateScene(state));

---

4. 动画导入

拆分动画

如果 3D 文件包含一条由多个动画组成的时间轴，可在高级导入设置中将它们拆分：

1. 双击 .glb 文件以打开高级导入设置
2. 转到动画选项卡
3. 添加动画片段，并设置起始帧和结束帧
4. 为每个片段设置循环模式（无、线性、乒乓）

重定向动画

在骨骼不同的角色之间共享动画：

1. 导入源模型（动画）和目标模型（角色）
2. 在目标模型上打开 Advanced Import Settings
3. 前往 Skeleton3D > Retarget 设置
4. 将源骨骼映射到目标骨骼
5. 使用 SkeletonProfile 资源设置标准人形骨骼映射

动画导入设置

设置	描述
Import	启用／禁用动画导入
FPS	烘焙帧率（标准值为 30）
Trimming	移除开头／结尾的空帧
Remove Immutable Tracks	移除没有变化的轨道

---

5. 音频导入

有关音频播放、总线设置和音乐管理的深入内容，请参阅 audio-system 技能。

格式建议

格式	导入为	用途	关键设置
WAV	AudioStreamWAV	短音效	Loop Mode、Max Rate
OGG	AudioStreamOggVorbis	音乐、长音效	Loop、Loop Offset
MP3	AudioStreamMP3	音乐（备用）	Loop、BPM

关键导入设置

设置	描述	使用场景
Loop	启用循环播放	音乐、环境循环音效
Loop Offset	循环重新开始的位置	避免循环时播放前奏
Force Mono（仅限 WAV）	将立体声转换为单声道	3D 定位音频
BPM	每分钟节拍数	节奏游戏
Beat Count	音轨的总节拍数	节奏同步

导入提示： 短音效使用 WAV（PCM 无解码开销；4.4+ 默认将 WAV 导入为 QOA，解码开销很低）。音乐使用 OGG（文件较小，音质良好）。与 AudioStreamPlayer3D 搭配使用的音频请使用单声道文件（WAV：Force Mono）——立体声无法正确实现空间化。

---

6. 资源格式

.tres 与 .res

格式	类型	可读	用途
.tres	文本	是	手动编辑或进行差异比较的资源
.res	二进制	否	大型资源，加载速度更快

# Save as text resource
ResourceSaver.save(my_resource, "res://data/item.tres")

# Save as binary resource
ResourceSaver.save(my_resource, "res://data/item.res")

# Load (either format)
var resource: Resource = load("res://data/item.tres")

ResourceSaver.Save(myResource, "res://data/item.tres");
ResourceSaver.Save(myResource, "res://data/item.res");
var resource = GD.Load<Resource>("res://data/item.tres");

何时使用各格式

• .tres —— 自定义资源，用于创建和编辑（物品数据、配置、技能定义）。便于版本控制。
• .res —— 生成的或大型二进制数据（烘焙的光照贴图、导航网格、大型网格）。加载速度更快。
• .tscn —— 文本场景文件（场景始终使用文本格式，可在 VCS 中比较差异）
• .scn —— 二进制场景文件（较少使用——仅适用于对加载时间有要求的超大型场景）

线程化资源加载

使用 ResourceLoader.load_threaded_request() / load_threaded_get_status() / load_threaded_get() 模式加载大型资源，避免游戏卡顿。完整的加载画面实现方案（GDScript + C#）：references/runtime-resource-loading.md。

---

7. 常见问题

现象	原因	解决方法
纹理看起来模糊	像素画使用了 Linear 过滤	在 Project Settings 中将 Default Texture Filter 设为 Nearest
透明精灵周围有深色轮廓	导入时未修复 Alpha 边缘	在 Import 停靠面板中启用 "Fix Alpha Border"
3D 模型没有碰撞	源模型中没有命名后缀	在 Blender 中为网格名称添加 -col 后缀，或手动添加
导入的动画缺失	Import 停靠面板中禁用了 "Import Animation"	启用 Animation > Import，然后重新导入
移动设备上的纹理 VRAM 占用过高	大纹理使用了 Lossless 压缩	对大于 256px 的纹理切换为 VRAM Compressed
3D 纹理在远处闪烁	未生成 Mipmaps	在 Import 停靠面板中启用 Mipmaps > Generate
音频在循环点处出现爆音／咔嗒声	循环偏移设置不正确	在 Import 停靠面板中调整 Loop Offset；在音频编辑器中添加淡入
场景文件过大	使用了二进制 .scn，而不是 .tscn	将场景保存为 .tscn（文本）以便用于 VCS；仅在需要时使用 .scn
重新克隆后导入设置丢失	.import 文件未提交到 VCS	始终提交 .import 文件；只有 .godot/ 应加入 .gitignore
多线程加载导致游戏卡住	使用 load() 每帧检查状态	使用 ResourceLoader.load_threaded_request/get_status 模式

⚠️ Godot 4.7 中的变更： 字体导入 hinting 的默认值从 1（Light）改为 3（Light (Except Pixel Fonts)）——现在，新导入的像素风格字体会自动禁用 hinting。已导入的字体会保留其 .import 文件中存储的 hinting=1；只有新字体或重新生成 .import 文件的字体才会采用新的默认值。若要与 4.6 保持一致，请在 Import 停靠面板中将 hinting 设为 1（Light）。请参阅 4.7 迁移指南。

---

8. 实施检查清单

• .gitignore 排除 .godot/，但不排除 .import 文件
• 像素画项目在 Project Settings 中将 Default Texture Filter 设为 Nearest
• 3D 纹理已启用 mipmaps（Import 停靠面板 → Mipmaps → Generate）
• 大纹理使用 VRAM Compressed（尤其是在移动设备目标平台上）
• 3D 模型主要使用 glTF 格式（.glb 或 .gltf）作为导入格式
• 碰撞形状在 3D 创作工具中使用命名后缀（-col、-convcol）
• 在 Advanced Import Settings 中将动画拆分为单独的片段
• 音效使用 WAV；音乐使用 OGG Vorbis
• 3D 定位音频文件为单声道（导入 WAV 时启用 Force Mono）
• 自定义数据资源使用 .tres（文本），以便在版本控制中查看差异
• 大型或运行时加载的资源使用 ResourceLoader.load_threaded_request()
• 场景文件使用 .tscn（文本格式），以便进行版本控制