From c7c8d7562746e621129eb68775db54c7dec4bd3c Mon Sep 17 00:00:00 2001 From: skyace65 Date: Sun, 20 Jul 2025 11:30:51 -0400 Subject: [PATCH] Move advanced import settings to their own page --- .../advanced_import_settings.rst | 247 ++++++++++++++++++ ...cenes_advanced_import_settings_button.webp | Bin 0 -> 9448 bytes .../import_configuration.rst | 222 +--------------- .../importing_3d_scenes/index.rst | 1 + 4 files changed, 251 insertions(+), 219 deletions(-) create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/advanced_import_settings.rst create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_button.webp diff --git a/tutorials/assets_pipeline/importing_3d_scenes/advanced_import_settings.rst b/tutorials/assets_pipeline/importing_3d_scenes/advanced_import_settings.rst new file mode 100644 index 00000000000..a6c7f23d093 --- /dev/null +++ b/tutorials/assets_pipeline/importing_3d_scenes/advanced_import_settings.rst @@ -0,0 +1,247 @@ +.. _doc_advanced_import_settings: + +Advanced Import Settings +======================== + +While the regular import panel provides many essential options for imported 3D +models, the advanced import settings provides per object options, model previews, +and animation previews. To open it select the :button:`Advanced...` button at the +bottom of the import dock. + +.. figure:: img/importing_3d_scenes_advanced_import_settings_button.webp + :align: center + +This is available for 3D models imported as scenes, as well as animation libraries. + +.. note:: + + This page does not go over options also available in the import dock, or anything + outside of the advanced import settings. For information on those please read the + :ref:`doc_importing_3d_scenes_import_configuration` page. + +Using the Advanced Import Settings dialog +----------------------------------------- + +The first tab you'll see is the **Scene** tab. The options available in the +panel on the right are identical to the Import dock, but you have access to a 3D +preview. The 3D preview can be rotated by holding down the left mouse button +then dragging the mouse. Zoom can be adjusted using the mouse wheel. + +.. figure:: img/importing_3d_scenes_advanced_import_settings_scene.webp + :align: center + :alt: Advanced Import Settings dialog (Scene tab) + + Advanced Import Settings dialog (Scene tab). + Credit: `Modern Arm Chair 01 - Poly Haven `__ + +Configuring node import options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can select individual nodes that compose the scene while in the **Scene** +tab using the tree view at the left: + +.. figure:: img/importing_3d_scenes_advanced_import_settings_node.webp + :align: center + :alt: Selecting a node in the Advanced Import Settings dialog (Scene tab) + + Selecting a node in the Advanced Import Settings dialog (Materials tab) + +This exposes several per-node import options: + +- **Skip Import:** If checked, the node will not be present in the final + imported scene. Enabling this disables all other options. +- **Generate > Physics:** If checked, generates a PhysicsBody3D *parent* node + with collision shapes that are *siblings* to the MeshInstance3D node. +- **Generate > NavMesh:** If checked, generates a NavigationRegion3D *child* + node for :ref:`navigation `. **Mesh + NavMesh** + will keep the original mesh visible, while **NavMesh Only** will only import + the navigation mesh (without a visual representation). **NavMesh Only** is + meant to be used when you've manually authored a simplified mesh for navigation. +- **Generate > Occluder:** If checked, generates an OccluderInstance3D *sibling* + node for :ref:`occlusion culling ` using the mesh's + geometry as a basis for the occluder's shape. **Mesh + Occluder** will keep + the original mesh visible, while **Occluder Only** will only import the + occluder (without a visual representation). **Occluder Only** is meant to be + used when you've manually authored a simplified mesh for occlusion culling. + +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 an 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: + +.. figure:: img/importing_3d_scenes_advanced_import_settings_meshes.webp + :align: center + :alt: Advanced Import Settings dialog (Meshes tab) + + Advanced Import Settings dialog (Meshes tab) + +The options are as follows: + +- **Save to File:** Saves the :ref:`class_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 :ref:`class_MeshInstance3D`, :ref:`class_MultiMeshInstance3D`, + :ref:`class_GPUParticles3D` or :ref:`class_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 + :ref:`doc_importing_3d_scenes_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 + :ref:`doc_importing_3d_scenes_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 + :ref:`doc_importing_3d_scenes_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 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: + +.. figure:: img/importing_3d_scenes_advanced_import_settings_materials.webp + :align: center + :alt: Advanced Import Settings dialog (Materials tab) + + 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**: + +.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials.webp + :align: center + :alt: Extracting all built-in materials to external resources in the Advanced Import Settings dialog + + 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: + +.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp + :align: center + :alt: Confirming material extraction in the Advanced Import Settings subdialog + + Confirming material extraction in the Advanced Import Settings subdialog + +.. note:: + + 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**. + +Animation options +----------------- + +Several extra options are available for the generated :ref:`class_AnimationPlayer` +nodes, as well as their individual animations when they're selected in the +**Scene** tab. + +Optimizer +~~~~~~~~~ + +When animations are imported, an optimizer is run, which reduces the size of the +animation considerably. In general, this should always be turned on unless you +suspect that an animation might be broken due to it being enabled. + +Save to file +~~~~~~~~~~~~ + +By default, animations are saved as built-in. It is possible to save them to a +file instead. This allows adding custom tracks to the animations and keeping +them after a reimport. + +Slices +~~~~~~ + +It is possible to specify multiple animations from a single timeline as slices. +For this to work, the model must have only one animation that is named +``default``. To create slices, change the slice amount to something greater than +zero. You can then name a slice, specify which frames it starts and stops on, and +choose whether the animation loops or not. diff --git a/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_button.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_button.webp new file mode 100644 index 0000000000000000000000000000000000000000..6b7cb649040c49850ff8917801e60432ff487967 GIT binary patch literal 9448 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 literal 0 HcmV?d00001 diff --git a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst index c90d0bf8940..8792bfbfdc1 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst @@ -40,7 +40,9 @@ This import process is customizable using 3 separate interfaces, depending on yo 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. + the Import dock. This allows you to customize per-object options in Godot, and + preview models and animations. please see the :ref:`doc_advanced_import_settings` + page for more information. - :ref:`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. @@ -172,201 +174,6 @@ exported from other tools such as Maya. Universal** and **Embed as Uncompressed** keeps the textures embedded in the imported scene, with and without VRAM compression respectively. -Using the Advanced Import Settings dialog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first tab you'll see is the **Scene** tab. The options available in the -panel on the right are identical to the Import dock, but you have access to a 3D -preview. The 3D preview can be rotated by holding down the left mouse button -then dragging the mouse. Zoom can be adjusted using the mouse wheel. - -.. figure:: img/importing_3d_scenes_advanced_import_settings_scene.webp - :align: center - :alt: Advanced Import Settings dialog (Scene tab) - - Advanced Import Settings dialog (Scene tab). - Credit: `Modern Arm Chair 01 - Poly Haven `__ - -**Configuring node import options** - -You can select individual nodes that compose the scene while in the **Scene** -tab using the tree view at the left: - -.. figure:: img/importing_3d_scenes_advanced_import_settings_node.webp - :align: center - :alt: Selecting a node in the Advanced Import Settings dialog (Scene tab) - - Selecting a node in the Advanced Import Settings dialog (Materials tab) - -This exposes several per-node import options: - -- **Skip Import:** If checked, the node will not be present in the final - imported scene. Enabling this disables all other options. -- **Generate > Physics:** If checked, generates a PhysicsBody3D *parent* node - with collision shapes that are *siblings* to the MeshInstance3D node. -- **Generate > NavMesh:** If checked, generates a NavigationRegion3D *child* - node for :ref:`navigation `. **Mesh + NavMesh** - will keep the original mesh visible, while **NavMesh Only** will only import - the navigation mesh (without a visual representation). **NavMesh Only** is - meant to be used when you've manually authored a simplified mesh for navigation. -- **Generate > Occluder:** If checked, generates an OccluderInstance3D *sibling* - node for :ref:`occlusion culling ` using the mesh's - geometry as a basis for the occluder's shape. **Mesh + Occluder** will keep - the original mesh visible, while **Occluder Only** will only import the - occluder (without a visual representation). **Occluder Only** is meant to be - used when you've manually authored a simplified mesh for occlusion culling. - -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 an 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: - -.. figure:: img/importing_3d_scenes_advanced_import_settings_meshes.webp - :align: center - :alt: Advanced Import Settings dialog (Meshes tab) - - Advanced Import Settings dialog (Meshes tab) - -The options are as follows: - -- **Save to File:** Saves the :ref:`class_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 :ref:`class_MeshInstance3D`, :ref:`class_MultiMeshInstance3D`, - :ref:`class_GPUParticles3D` or :ref:`class_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 - :ref:`doc_importing_3d_scenes_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 - :ref:`doc_importing_3d_scenes_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 - :ref:`doc_importing_3d_scenes_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 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: - -.. figure:: img/importing_3d_scenes_advanced_import_settings_materials.webp - :align: center - :alt: Advanced Import Settings dialog (Materials tab) - - 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**: - -.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials.webp - :align: center - :alt: Extracting all built-in materials to external resources in the Advanced Import Settings dialog - - 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: - -.. figure:: img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp - :align: center - :alt: Confirming material extraction in the Advanced Import Settings subdialog - - Confirming material extraction in the Advanced Import Settings subdialog - -.. note:: - - 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**. - .. _doc_importing_3d_scenes_import_script: Using import scripts for automation @@ -489,29 +296,6 @@ would be retained. Any track filter lines that do not begin with a ``+`` or ``-`` are ignored. -Storage -~~~~~~~ - -By default, animations are saved as built-in. It is possible to save them to a -file instead. This allows adding custom tracks to the animations and keeping -them after a reimport. - -Optimizer -~~~~~~~~~ - -When animations are imported, an optimizer is run, which reduces the size of the -animation considerably. In general, this should always be turned on unless you -suspect that an animation might be broken due to it being enabled. - -Slices -~~~~~~ - -It is possible to specify multiple animations from a single timeline as slices. -For this to work, the model must have only one animation that is named -``default``. To create slices, change the slice amount to something greater than -zero. You can then name a slice, specify which frames it starts and stops on, and -choose whether the animation loops or not. - Scene inheritance ----------------- diff --git a/tutorials/assets_pipeline/importing_3d_scenes/index.rst b/tutorials/assets_pipeline/importing_3d_scenes/index.rst index 0bf4e38c546..b3c538c7ffa 100644 --- a/tutorials/assets_pipeline/importing_3d_scenes/index.rst +++ b/tutorials/assets_pipeline/importing_3d_scenes/index.rst @@ -21,6 +21,7 @@ dialog, and inherited scenes. model_export_considerations node_type_customization import_configuration + advanced_import_settings .. seealso::