Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

导入配置

Godot提供了多种自定义导入数据的方法，比如导入停靠面板、高级导入设置对话框和继承场景。这可以用来对导入的场景进行进一步的更改，比如调整网格、添加物理信息和添加新节点。你还可以编写一个脚本，在导入过程结束时运行代码，以执行任意的自定义操作。

请尽可能在导入前修改初始数据，而不是导入后再配置场景。这有助于最大程度降低场景在 3D 建模软件中与实际导入场景之间的差异。可参考 导出模型的注意事项 及 使用名称后缀自定义节点类型 来获取更多信息。

导入工作流程

由于 Godot 只能保存自己的场景格式（.tscn/.scn），Godot 无法保存原始 3D 场景文件（使用不同的格式）。由于可以避免对源文件进行意外更改，这也是一种更安全的做法。

为了允许自定义场景及其材质，Godot 的场景导入器允许不同的工作流程，视数据的导入方式而定。

在文件系统面板中选择 3D 场景后的导入面板

这个导入过程可以通过3个不同的界面进行自定义，具体取决于你的需求：

• 在“文件系统”面板中单击一次 3D 场景后，可以在导入面板进行操作。

• The Advanced Import Settings dialog, which can be accessed by double-clicking the 3D scene in the FileSystem dock or by clicking the Advanced… button in the Import dock. This allows you to customize per-object options in Godot, and preview models and animations. please see the Advanced Import Settings page for more information.

• 导入提示是添加到 3D 建模软件中的对象名称的特殊后缀，它可以允许你在 3D 建模软件中自定义每个对象的选项。

对于基本自定义，使用导入面板的配置就足够了。但是对于更复杂的操作（例如基于每种材质定义材质覆盖），你需要使用“高级导入设置”对话框或导入提示，亦或者同时使用两者。

使用导入面板

在文件系统面板选中一个 3D 场景之后，可以在导入面板中调整以下选项：

• 根类型： 被用作为根节点的节点类型。建议使用一个继承自 Node3D 的节点。否则你可能会无法直接在 3D 编辑器里面设置节点的位置。

• 根名称： （Root Name）导入场景中根节点的名称。在编辑器中实例化场景（或从文件系统面板拖放）时，这通常不太明显，因为在这种情况下，根节点会被重命名以匹配文件名。

• 应用根缩放： （Apply Root Scale）如果启用， 根缩放 将直接 应用 于网格和动画，同时保持根节点的缩放为默认值 (1, 1, 1) 。这意味着如果你稍后在导入的场景中添加一个子节点，它不会被缩放。如果禁用， 根缩放 将乘以根节点的缩放。

网格

• 确保切线： （Ensure Tangents）如果勾选，在导入的网格没有提供切线数据时，将会使用 Mikktspace 生成顶点的切线。但更推荐使用 3D 建模软件在导出的时候生成切线图像，而不是依赖这个选项。正确显示法线和高度贴图以及需要切线的任何材质/着色器功能都需要切线。如果你不使用需要切线的材质特性，关闭这个选项可以减少导出文件的大小，并且能更快地导入没有存储切线的 3D 文件。

• 生成 LOD： 如果勾选，则会生成网格的低细节的变体，这些变体将显示在远处以提高渲染性能。并非所有网格体都会受益于 LOD，特别是如果它们从未从远处渲染。禁用此功能可以减少输出文件大小并加快导入速度。请参阅 网格的细节级别（LOD） 了解更多信息。

• 创建阴影网格： 如果勾选，则可以在导入时生成阴影网格。这可以通过在可能的情况下将顶点接在一起来优化阴影渲染，而不会降低质量。这反过来又减少了渲染阴影所需的内存带宽。阴影网格生成当前不支持使用比源网格更低的细节级别（但阴影渲染将在相关时使用 LOD）。

• Light Baking：光照烘焙，在 3D 场景中配置网格的全局光照模式。如果设置为 Static Lightmaps（静态光照贴图），则将网格的 GI 模式设置为 Static（静态）并在导入时生成 UV2，用于烘焙光照贴图。

• 光照贴图纹素大小： （Lightmap Texel Size）仅当 光照烘焙 设置为 Static Lightmaps 时可见。用来控制烘焙光照贴图上每个纹素的大小。较小的值会产生更精确的光照贴图，但代价是更大的光照贴图大小和更长的烘焙时间。

蒙皮

• 使用具名蒙皮： 如果勾选，则为动画使用命名的 Skins。MeshInstance3D 节点包含 3 个相关属性：指向 Skeleton3D 节点的骨架 NodePath（通常为 .. ）、一个网格和一个蒙皮：

  • Skeleton3D 节点包含一个骨骼列表，其中包括骨骼的名称、它们的姿势和休息状态、一个名称和一个父骨骼。

  • 网格是显示网格所需的所有原始顶点数据。就网格而言，它知道如何对顶点进行加权绘制，并使用一些通常从 3D 建模软件导入的内部编号。

  • 蒙皮包含将此网格物体绑定到此 Skeleton3D 上所需的信息。对于 3D 建模软件选择的每一个内部骨骼 ID，它都包含两个内容。首先，一个矩阵，称为绑定姿势矩阵（Bind Pose Matrix）、逆绑定矩阵（ Inverse Bind Matrix），或者简称 IBM。其次，蒙皮包含每个骨骼的名称（如果启用 使用具名蒙皮 选项），或者骨骼在 Skeleton3D 列表中的索引（如果禁用了 使用具名蒙皮 选项）。

这些信息加在一起，足以告诉 Godot 如何使用骨骼 3D 节点中的骨骼姿势来渲染每个 MeshInstance3D 中的网格。请注意，每个 MeshInstance3D 都可以共享绑定，这在从 Blender 导出的模型中很常见；或者每个 MeshInstance3D 都可以使用单独的蒙皮对象，这在从其他工具（如 Maya）导出的模型中很常见。

动画

• 导入： 如果选中，则从 3D 场景导入动画。

• FPS： 用线性插值将动画曲线烘焙为一系列点时使用的每秒帧数。建议将此值设置为与 3D 建模软件中的基准值相匹配。数值越大，动画越精确，动作变化越快，但文件大小和内存使用量也越大。由于采用了插值技术，超过 30 FPS 通常不会有太大的好处（因为动画在更高的渲染帧频下仍会显得流畅）。

• 修剪： 如果没有关键帧变化，则修剪动画的开头和结尾。这可以减少某些 3D 场景的输出文件大小和内存使用量，具体取决于其动画轨道的内容。

• 移除不可修改的轨道： 移除只包含默认值的动画轨道。这可以减少某些 3D 场景的输出文件大小和内存使用量，具体取决于其动画轨道的内容。

导入脚本

• Path：路径，导入脚本的路径，该脚本可在导入过程完成后运行代码，以进行自定义处理。更多信息请参阅 使用导入脚本实现自动化。

glTF

• 嵌入图像处理： 控制如何处理嵌入 glTF 场景中的纹理。 Discard All Textures （忽略所有纹理）不会导入任何纹理，如果你想在 Godot 中手动设置材质，该选项将非常有用。 Extract Textures （提取纹理）将纹理提取到外部图像中，从而减小文件大小，并对导入选项进行更多控制。 Embed as Basis Universal （嵌入为基础通用）和 Embed as Uncompressed （嵌入为未压缩）分别将纹理嵌入已导入的场景中，并对 VRAM 进行压缩和不压缩。

FBX

• Importer Which import method is used. ubfx handles fbx files as fbx files. FBX2glTF converts FBX files to glTF on import and requires additional setup. FBX2glTF is not recommended unless you have a specific rason to use it over ufbx or working with a different file format.

• Allow Geometry Helper Nodes 启用或禁用几何辅助节点

• 嵌入图像处理： 控制如何处理嵌入 glTF 场景中的纹理。 Discard All Textures （忽略所有纹理）不会导入任何纹理，如果你想在 Godot 中手动设置材质，该选项将非常有用。 Extract Textures （提取纹理）将纹理提取到外部图像中，从而减小文件大小，并对导入选项进行更多控制。 Embed as Basis Universal （嵌入为基础通用）和 Embed as Uncompressed （嵌入为未压缩）分别将纹理嵌入已导入的场景中，并对 VRAM 进行压缩和不压缩。

使用导入脚本实现自动化

可以提供一个特殊脚本来处理导入后的整个场景。这非常适合后期处理、更换材质和用几何图形做有趣的事情等等。

通过右键单击文件系统面板并选择 新建脚本… ，创建一个不附加到任何节点的脚本。在脚本编辑器中，编写以下内容：

@tool # Needed so it runs in editor.
extends EditorScenePostImport

# This sample changes all node names.
# Called right after the scene is imported and gets the root node.
func _post_import(scene):
    # Change all node names to "modified_[oldnodename]"
    iterate(scene)
    return scene # Remember to return the imported scene

# Recursive function that is called on every node
# (for demonstration purposes; EditorScenePostImport only requires a `_post_import(scene)` function).
func iterate(node):
    if node != null:
        print_rich("Post-import: [b]%s[/b] -> [b]%s[/b]" % [node.name, "modified_" + node.name])
        node.name = "modified_" + node.name
        for child in node.get_children():
            iterate(child)

_post_import(scene: Node) 函数以导入的场景为参数（参数实际上是场景的根节点）。最终使用的场景必须被返回，即使该场景可以完全不同。

要使用你的脚本，请在导入选项卡的“导入脚本”类别下的“路径”选项中找到该脚本。

使用动画库

从 Godot 4.0 开始，可以选择从 glTF 文件导入 仅 动画，而不导入其他信息。这在某些资产管线中用于将动画与模型分开分发。比如，给多个角色使用一套动画，而每个角色不必有重复的动画数据。

那么，请在文件系统栏目中选择 glTF 文件，然后在导入栏中更改导入模式为动画库：

在导入栏目中将导入类型更改为动画库

单击 重新导入 ，并根据提示重启编辑器。重启后， glTF 文件将作为 AnimationLibrary 导入，而不是 PackedScene 。然后，可以使用 AnimationPlayer 节点引用此动画库。

更改导入模式为动画库后，可见的导入选项与使用场景导入模式时相同。有关更多信息，请参阅 使用导入面板 。

过滤脚本

可以使用特殊语法指定过滤器脚本, 以决定应保留哪些动画的哪些轨道.

过滤脚本对每个导入的动画执行。语法由两种类型的语句组成，第一种用于选择要过滤的动画，第二种用于过滤匹配动画中的单个轨道。所有名称模式都使用不区分大小写的表达式匹配，并支持 ? 和 * 通配符（底层使用 String.matchn() ）。

The script must start with an animation filter statement (as denoted by the line beginning with an @). For example, if we would like to apply filters to all imported animations which have a name ending in "_Loop":

@+*_Loop

Similarly, additional patterns can be added to the same line, separated by commas. Here is a modified example to additionally include all animations with names that begin with "Arm_Left", but also exclude all animations which have names ending in "Attack":

@+*_Loop, +Arm_Left*, -*Attack

在动画选择过滤器语句之后, 我们添加轨道过滤模式来指示保留或丢弃哪些动画轨道. 如果未指定轨道过滤器模式, 则匹配动画中的所有轨道都会被丢弃！

需要注意的是, 轨道过滤器表达式是按顺序作用于动画中的每条轨道, 这意味着, 一行表达式可能包含某个轨道, 但后续的规则仍然可以忽略它. 同样, 一个被之前规则排除的轨道, 可能被过滤器脚本后续的规则重新包含进来.

For example: include all tracks in animations with names ending in "_Loop", but discard any tracks affecting a "Skeleton" which end in "Control", unless they have "Arm" in their name:

@+*_Loop
+*
-Skeleton:*Control
+*Arm*

在上面的示例中，像 "Skeleton:Leg_Control" 这样的轨道会被丢弃，而像 "Skeleton:Head" 或 "Skeleton:Arm_Left_Control" 这样的轨道会被保留。

任何不是以 + 或 - 开头的轨道过滤器行将会被忽略.

场景继承

在许多情况下，可能需要对导入的场景进行手动修改。默认情况下，这是不可能的，因为如果源 3D 资产发生变化，Godot 将重新导入整个场景。

然而，可以使用场景继承来创建本地修改。如果你尝试使用场景 > 打开场景... 或场景 > 快速打开场景... 来打开已导入的场景，以下对话框将会出现：

在编辑器中打开导入的 3D 场景时的对话框

在继承场景中，修改的唯一限制是：

• 无法删除基础场景中的节点，但可以在任何地方添加其他节点。

• 子资源无法被编辑（如上所述它们将保存在外部）。

除此之外，一切都是允许的。