Import configuration
- 导入工作流程
- 场景继承

Import configuration

Godot provides several ways to customize the imported data, such as the import dock, the advanced import setting dialog, and inherited scenes. This can be used to make further changes to the imported scene, such as adjusting meshes, adding physics information, and adding new nodes. You can also write a script that runs code at the end of the import process to perform arbitrary customization.

Note that, when applicable, modifying the original data should be preferred to configuring the scene after import. This helps minimize the differences between the 3D modeling application and the imported scene. See the Model export considerations and Node type customization using name suffixes articles for more information.

导入工作流程

Since Godot can only save its own scene format (.tscn/.scn), Godot cannot save over the original 3D scene file (which uses a different format). This is also a safer approach as it avoids making accidental changes to the source file.

To allow customizing the scene and its materials, Godot’s scene importer allows for different workflows regarding how data is imported.

在文件系统停靠面板中找到脚本

This import process is customizable using 3 separate interfaces, depending on your needs:

The Import dock, after selecting the 3D scene by clicking it once in the FileSystem dock.
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.
Import hints, which are special suffixes added to object names in the 3D modeling software. This allows you to customize per-object options in the 3D modeling software.

For basic customization, using the Import dock suffices. However, for more complex operations such as defining material overrides on a per-material basis, you’ll need to use the Advanced Import Settings dialog, import hints, or possibly both.

Using the Import dock

The following options can be adjusted in the Import dock after selecting a 3D scene in the FileSystem dock:

Root Type: The node type to use as a root node. Using node types that inherit from Node3D is recommended. Otherwise, you’ll lose the ability to position the node directly in the 3D editor.
Root Name: The name of the root node in the imported scene. This is generally not noticeable when instancing the scene in the editor (or drag-and-dropping from the FileSystem dock), as the root node is renamed to match the filename in this case.
Apply Root Scale: If enabled, Root Scale will be applied on the meshes and animations directly, while keeping the root node’s scale to the default (1, 1, 1). This means that if you add a child node later on within the imported scene, it won’t be scaled. If disabled, Root Scale will multiply the scale of the root node instead.

网格

Ensure Tangents: If checked, generate vertex tangents using Mikktspace if the input meshes don’t have tangent data. When possible, it’s recommended to let the 3D modeling software generate tangents on export instead on relying on this option. Tangents are required for correct display of normal and height maps, along with any material/shader features that require tangents. If you don’t need material features that require tangents, disabling this can reduce output file size and speed up importing if the source 3D file doesn’t contain tangents.
Generate LODs: If checked, generates lower detail variants of the mesh which will be displayed in the distance to improve rendering performance. Not all meshes benefit from LOD, especially if they are never rendered from far away. Disabling this can reduce output file size and speed up importing. See 网格的细节级别（LOD） for more information.
Create Shadow Meshes: If checked, enables the generation of shadow meshes on import. This optimizes shadow rendering without reducing quality by welding vertices together when possible. This in turn reduces the memory bandwidth required to render shadows. Shadow mesh generation currently doesn’t support using a lower detail level than the source mesh (but shadow rendering will make use of LODs when relevant).
Light Baking: Configures the meshes’ global illumination mode in the 3D scene. If set to Static Lightmaps, sets the meshes’ GI mode to Static and generates UV2 on import for lightmap baking.
Lightmap Texel Size: Only visible if Light Baking is set to Static Lightmaps. Controls the size of each texel on the baked lightmap. A smaller value results in more precise lightmaps, at the cost of larger lightmap sizes and longer bake times.

Skins

Use Named Skins: If checked, use named Skins for animation. The MeshInstance3D node contains 3 properties of relevance here: a skeleton NodePath pointing to the Skeleton3D node (usually ..), a mesh, and a skin:
- The Skeleton3D node contains a list of bones with names, their pose and rest, a name and a parent bone.
- The mesh is all of the raw vertex data needed to display a mesh. In terms of the mesh, it knows how vertices are weight-painted and uses some internal numbering often imported from 3D modeling software.
- The skin contains the information necessary to bind this mesh onto this Skeleton3D. For every one of the internal bone IDs chosen by the 3D modeling software, it contains two things. Firstly, a Matrix known as the Bind Pose Matrix, Inverse Bind Matrix, or IBM for short. Secondly, the Skin contains each bone’s name (if Use Named Skins is enabled), or the bone’s index within the Skeleton3D list (if Use Named Skins is disabled).

Together, this information is enough to tell Godot how to use the bone poses in the Skeleton3D node to render the mesh from each MeshInstance3D. Note that each MeshInstance3D may share binds, as is common in models exported from Blender, or each MeshInstance3D may use a separate Skin object, as is common in models exported from other tools such as Maya.

动画

Import: If checked, import animations from the 3D scene.
FPS: The number of frames per second to use for baking animation curves to a series of points with linear interpolation. It’s recommended to configure this value to match the value you’re using as a baseline in your 3D modeling software. Higher values result in more precise animation with fast movement changes, at the cost of higher file sizes and memory usage. Thanks to interpolation, there is usually not much benefit in going above 30 FPS (as the animation will still appear smooth at higher rendering framerates).
Trimming: Trim the beginning and end of animations if there are no keyframe changes. This can reduce output file size and memory usage with certain 3D scenes, depending on the contents of their animation tracks.
Remove Immutable Tracks: Remove animation tracks that only contain default values. This can reduce output file size and memory usage with certain 3D scenes, depending on the contents of their animation tracks.

Import Script

Path: Path to an import script, which can run code after the import process has completed for custom processing. See Using import scripts for automation for more information.

glTF

Embedded Texture Handling: Controls how textures embedded within glTF scenes should be handled. Discard All Textures will not import any textures, which is useful if you wish to manually set up materials in Godot instead. Extract Textures extracts textures to external images, resulting in smaller file sizes and more control over import options. Embed as Basis Universal and Embed as Uncompressed keeps the textures embedded in the imported scene, with and without VRAM compression respectively.

使用高级导入设置对话框

你看到的第一个选项卡是场景选项卡。右侧面板中的选项与“导入”面板相同，但是你还可以看到 3D 预览。按住鼠标左键并拖动鼠标就能够旋转 3D 预览。缩放可以通过鼠标滚轮调整。

高级导入设置对话框（场景选项卡）。作者：Modern Arm Chair 01 - Poly Haven

配置节点导入选项

在场景选项卡中，可以在左侧的树状视图中单独选中构成场景的节点：

在高级导入设置对话框（材质选项卡）中选中节点

这样就会出现针对节点的导入选项：

跳过导入：勾选后，该节点不会出现在最终导入的场景中。启用这个选项会禁用其他所有选项。
生成 > 物理：勾选后，会生成一个 PhysicsBody3D 父节点，碰撞形状会作为该 MeshInstance3D 节点的兄弟节点。
生成 > 导航网格：勾选后，会生成一个 NavigationRegion3D 子节点用于进行导航。Mesh + NavMesh 会保持原有网格可见，而 NavMesh Only 则只会导入导航网格（不带可视化表示）。NavMesh Only 应该在手动制作了用于导航的简化网格时使用。
生成 > 遮挡器：勾选后，会生成一个 OccluderInstance3D 兄弟节点用于进行遮挡剔除，会使用网格的几何体作为遮挡器形状的基础。Mesh + Occluder 会保持原有网格可见，而 Occluder Only 则只会导入遮挡器（不带可视化表示）。Occluder Only 应该在手动制作了用于遮挡剔除的简化网格时使用。

These options are only visible if some of the above options are enabled:

Physics > Body Type: Only visible if Generate > Physics is enabled. Controls the PhysicsBody3D that should be created. Static creates a StaticBody3D, Dynamic creates a RigidBody3D, Area creates an Area3D.
Physics > Shape Type: Only visible if Generate > Physics is enabled. Trimesh allows for precise per-triangle collision, but it can only be used with a Static body type. Other types are less precise and may require manual configuration, but can be used with any body type. For static level geometry, use Trimesh. For dynamic geometry, use primitive shapes if possible for better performance, or use one of the convex decomposition modes if the shape is large and complex.
Decomposition > Advanced: Only visible if Physics > Shape Type is Decompose Convex. If checked, allows adjusting advanced decomposition options. If disabled, only a preset Precision can be adjusted (which is usually sufficient).
Decomposition > Precision: Only visible if Physics > Shape Type is Decompose Convex. Controls the precision to use for convex decomposition. Higher values result in more detailed collision, at the cost of slower generation and increased CPU usage during physics simulation. To improve performance, it’s recommended to keep this value as low as possible for your use cases.
Occluder > Simplification Distance: Only visible if Generate > Occluder is set to Mesh + Occluder or Occluder Only. Higher values result in a occluder mesh with fewer vertices (resulting in decreased CPU utilization), at the cost of more occlusion culling issues (such as false positives or false negatives). If you run into objects disappearing when they shouldn’t when the camera is near a certain mesh, try decreasing this value.

Configuring mesh and material import options

In the Advanced Import Settings dialog, there are 2 ways to select individual meshes or materials:

Switch to the Meshes or Materials tab in the top-left corner of the dialog.
Stay in the Scene tab, but unfold the options on the tree view on the left. After choosing a mesh or material, this presents the same information as the Meshes and Materials tabs, but in a tree view instead of a list.

If you select a mesh, different options will appear in the panel on the right:

Advanced Import Settings dialog (Meshes tab)

The options are as follows:

Save to File: Saves the Mesh resource to an external file (this isn’t a scene file). You generally don’t need to use this for placing the mesh in a 3D scene – instead, you should instance the 3D scene directly. However, having direct access to the Mesh resource is useful for specific nodes, such as MeshInstance3D, MultiMeshInstance3D, GPUParticles3D or CPUParticles3D. - You will also need to specify an output file path using the option that appears after enabling Save to File. It’s recommended to use the .res output file extension for smaller file sizes and faster loading speeds, as .tres is inefficient for writing large amounts of data.
Generate > Shadow Meshes: Per-mesh override for the Meshes > Create Shadow Meshes scene-wide import option described in Using the Import dock. Default will use the scene-wide import option, while Enable or Disable can forcibly enable or disable this behavior on a specific mesh.
Generate > Lightmap UV: Per-mesh override for the Meshes > Light Baking scene-wide import option described in Using the Import dock. Default will use the scene-wide import option, while Enable or Disable can forcibly enable or disable this behavior on a specific mesh. - Setting this to Enable on a scene with the Static light baking mode is equivalent to configuring this mesh to use Static Lightmaps. Setting this to Disable on a scene with the Static Lightmaps light baking mode is equivalent to configuring this mesh to use Static instead.
Generate > LODs: Per-mesh override for the Meshes > Generate LODs scene-wide import option described in Using the Import dock. Default will use the scene-wide import option, while Enable or Disable can forcibly enable or disable this behavior on a specific mesh.
LODs > Normal Split Angle: The minimum angle difference between two vertices required to preserve a geometry edge in mesh LOD generation. If running into visual issues with LOD generation, decreasing this value may help (at the cost of less efficient LOD generation).
LODs > Normal Merge Angle: The minimum angle difference between two vertices required to preserve a geometry edge in mesh LOD generation. If running into visual issues with LOD generation, decreasing this value may help (at the cost of less efficient LOD generation).

If you select a material, only one option will appear in the panel on the right:

Advanced Import Settings dialog (Materials tab)

When Use External is checked and an output path is specified, this lets you use an external material instead of the material that is included in the original 3D scene file; see the section below.

Extracting materials to separate files

While Godot can import materials authored in 3D modeling software, the default configuration may not be suitable for your needs. For example:

You want to configure material features not supported by your 3D application.
You want to use a different texture filtering mode, as this option is configured in the material since Godot 4.0 (and not in the image).
You want to replace one of the materials with an entirely different material, such as a custom shader.

To be able to modify the 3D scene’s materials in the Godot editor, you need to use external material resources.

In the top-left corner of the Advanced Import Settings dialog, choose Actions… > Extract Materials:

Extracting all built-in materials to external resources in the Advanced Import Settings dialog

After choosing this option, select a folder to extract material .tres files to, then confirm the extraction:

Confirming material extraction in the Advanced Import Settings subdialog

备注

After extracting materials, the 3D scene will automatically be configured to use external material references. As a result, you don’t need to manually enable Use External on every material to make the external .tres material effective.

When Use External is enabled, remember that the Advanced Import Settings dialog will keep displaying the mesh’s original materials (the ones designed in the 3D modeling software). This means your customizations to the materials won’t be visible within this dialog. To preview your modified materials, you need to place the imported 3D scene in another scene using the editor.

Godot will not overwrite changes made to extracted materials when the source 3D scene is reimported. However, if the material name is changed in the source 3D file, the link between the original material and the extracted material will be lost. As a result, you’ll need to use the Advanced Import Settings dialog to associate the renamed material to the existing extracted material.

The above can be done in the dialog’s Materials tab by selecting the material, enabling Save to File, then specifying the save path using the Path option that appears after enabling Save to File.

Using import scripts for automation

A special script to process the whole scene after import can be provided. This is great for post-processing, changing materials, doing funny stuff with the geometry, and more.

Create a script that is not attached to any node by right-clicking in the FileSystem dock and choosing New > Script…. In the script editor, write the following:

@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 节点引用此动画库。

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

过滤脚本

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

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

脚本必须以动画过滤器语句开头（如以 @ 开头的行表示）。例如，如果我们想要将过滤器应用在所有以 "_Loop" 结尾的导入动画上：

@+*_Loop

类似地，还可以在同一行中添加其他模式，以逗号分隔。下面是一个修改后的例子，它额外包含所有名称以 "Arm_Left" 开头的动画，同时排除所有名称以 "Attack" 结尾的动画：

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

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

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

例如：包含动画中所有名字以 "_Loop" 结尾的轨道，但忽略任何以 "Control" 结尾的 "Skeleton" 轨道，除非它们的名字中有 "Arm"：

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

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

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

存储

默认情况下, 动画保存为内置. 可以将它们保存到一个文件中. 这允许向动画添加自定义轨道并在重新导入后保留它们.

优化

导入动画时, 会运行优化程序, 从而大大减少动画的大小. 一般情况下, 除非你怀疑动画可能因启用而被破坏, 否则应始终启用此功能.

剪辑

可以指定单个时间轴中的多个动画作为剪辑. 这样做的话, 模型必须只有一个命名为 default 的动画. 为了创建剪辑, 把剪辑数量改成比0大的数. 然后可以修改剪辑名字, 指定开始和结束帧, 选择动画是否循环.

场景继承

在许多情况下，可能需要手动修改导入的场景。默认情况下，不太可能，因为如果源 3D 资产更改， Godot 将重新导入整个场景。

However, it is possible to make local modifications by using scene inheritance. If you try to open the imported scene using Scene > Open Scene… or Scene > Quick Open Scene…, the following dialog will appear:

Dialog when opening an imported 3D scene in the editor

In inherited scenes, the only limitations for modification are:

Nodes from the base scene can’t be removed, but additional nodes can be added anywhere.
子资源无法被编辑（如上所述它们将保存在外部）。

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

Previous Next

Built with Sphinx using a theme provided by Read the Docs.