Split the "Importing 3D scenes" article into multiple pages

_tools/redirects/redirects.csv

@@ -343,6 +343,7 @@ source,destination
 /tutorials/assetlib/uploading_to_assetlib.html,/community/asset_library/uploading_to_assetlib.html
 /tutorials/assetlib/using_assetlib.html,/community/asset_library/using_assetlib.html
 /tutorials/assetlib/what_is_assetlib.html,/community/asset_library/what_is_assetlib.html
+/tutorials/assets_pipeline/importing_scenes.html,/tutorials/assets_pipeline/importing_3d_scenes/index.html
 /tutorials/content/making_trees.html,/tutorials/shaders/making_trees.html
 /tutorials/content/procedural_geometry/arraymesh.html,/tutorials/3d/procedural_geometry/arraymesh.html
 /tutorials/content/procedural_geometry/immediategeometry.html,/tutorials/3d/procedural_geometry/immediategeometry.html

classes/class_editorscenepostimport.rst

@@ -80,7 +80,7 @@ The :ref:`_post_import<class_EditorScenePostImport_method__post_import>` callbac
 Tutorials
 ---------
 
-- `Importing 3D scenes: Custom script <../tutorials/assets_pipeline/importing_scenes.html#custom-script>`__
+- `Importing 3D scenes: Configuration: Using import scripts for automation <../tutorials/assets_pipeline/importing_3d_scenes/import_configuration.html#using-import-scripts-for-automation>`__
 
 .. rst-class:: classref-reftable-group
 

classes/class_resourceimporterobj.rst

@@ -28,7 +28,7 @@ See also :ref:`ResourceImporterScene<class_ResourceImporterScene>`, which is use
 Tutorials
 ---------
 
-- :doc:`Importing 3D scenes <../tutorials/assets_pipeline/importing_scenes>`
+- :doc:`Importing 3D scenes <../tutorials/assets_pipeline/importing_3d_scenes/index>`
 
 .. rst-class:: classref-reftable-group
 

classes/class_resourceimporterscene.rst

@@ -30,7 +30,7 @@ Additional options (such as extracting individual meshes or materials to files)
 Tutorials
 ---------
 
-- :doc:`Importing 3D scenes <../tutorials/assets_pipeline/importing_scenes>`
+- :doc:`Importing 3D scenes <../tutorials/assets_pipeline/importing_3d_scenes/index>`
 
 .. rst-class:: classref-reftable-group
 
@@ -149,7 +149,7 @@ If ``true``, trim the beginning and end of animations if there are no keyframe c
 
 :ref:`String<class_String>` **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 <../tutorials/assets_pipeline/importing_scenes.html#doc-importing-3d-scenes-import-script>`__ for more information.
+Path to an import script, which can run code after the import process has completed for custom processing. See `Using import scripts for automation <../tutorials/assets_pipeline/importing_3d_scenes/import_configuration.html#using-import-scripts-for-automation>`__ for more information.
 
 .. rst-class:: classref-item-separator
 

tutorials/3d/csg_tools.rst

@@ -87,7 +87,7 @@ Custom meshes
 ~~~~~~~~~~~~~
 
 Any mesh can be used for :ref:`CSGMesh3D <class_CSGMesh3D>`; the mesh can be
-modelled in other software and imported into Godot. Multiple materials are
+modeled in other software and imported into Godot. Multiple materials are
 supported. There are some restrictions for geometry:
 
 - it must be closed,

tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst

@@ -0,0 +1,172 @@
+.. _doc_importing_3d_scenes_available_formats:
+
+Available 3D formats
+====================
+
+When dealing with 3D assets, Godot has a flexible and configurable importer.
+
+Godot works with *scenes*. This means that the entire scene being worked on in
+your favorite 3D modeling software will be transferred as close as possible.
+
+Godot supports the following 3D *scene file formats*:
+
+- glTF 2.0 **(recommended)**. Godot has support for both text (``.gltf``)
+  and binary (``.glb``) formats.
+- ``.blend`` (Blender). This works by calling Blender to export to glTF in a
+  transparent manner (requires Blender to be installed).
+- DAE (COLLADA), an older format that is supported.
+- OBJ (Wavefront) format + their MTL material files. This is also
+  supported, but pretty limited given the format's limitations (no support for
+  pivots, skeletons, animations, UV2, PBR materials, ...).
+- FBX, supported via `FBX2glTF <https://github.com/godotengine/FBX2glTF>`__ integration.
+  This requires installing an external program that links against the proprietary FBX SDK,
+  so we recommend using other formats listed above (if suitable for your workflow).
+
+Copy the scene file together with the textures and mesh data (if separate) to
+the project repository, then Godot will do a full import when focusing the
+editor window.
+
+Exporting glTF 2.0 files from Blender (recommended)
+---------------------------------------------------
+
+There are 3 ways to export glTF files from Blender:
+
+- As a glTF binary file (``.glb``).
+- As a glTF text-based file with embedded binary data (``.gltf`` file)
+- As a glTF text-based file with separate binary data and textures (``.gltf``
+  file + ``.bin`` file + textures).
+
+glTF binary files (``.glb``) are the smallest of the three options. They include
+the mesh and textures set up in Blender. When brought into Godot the textures
+are part of the object's material file.
+
+glTF embedded files (``.gltf``) function the same way as binary files. They
+don't provide extra functionality in Godot, and shouldn't be used since they
+have a larger file size.
+
+There are two reasons to use glTF with the textures separate. One is to have the
+scene description in a text based format and the binary data in a separate
+binary file. This can be useful for version control if you want to review
+changes in a text-based format. The second is you need the texture files
+separate from the material file. If you don't need either of those, glTF binary
+files are fine.
+
+.. warning::
+
+    If your model contains blend shapes (also known as "shape keys" and "morph
+    targets"), your glTF export setting **Export Deformation Bones Only** needs
+    to be configured to **Enabled** under the Animation export configurations.
+
+    Exporting non-deforming bones anyway will lead to incorrect shading.
+
+.. note::
+
+    Blender versions older than 3.2 do not export emissive textures with the
+    glTF file. If your model uses one and you're using an older version of
+    Blender, it must be brought in separately.
+
+    By default, Blender has backface culling disabled on materials and will
+    export materials to match how they render in Blender. This means that
+    materials in Godot will have their cull mode set to **Disabled**. This can
+    decrease performance since backfaces will be rendered, even when they are
+    being culled by other faces. To resolve this, enable **Backface Culling** in
+    Blender's Materials tab, then export the scene to glTF again.
+
+Importing ``.blend`` files directly within Godot
+------------------------------------------------
+
+.. note::
+
+    This functionality requires Blender 3.0 or later. For best results, we
+    recommend using Blender 3.5 or later, as it includes many fixes to the glTF
+    exporter.
+
+    It is **strongly** recommended to use an official Blender release downloaded
+    from blender.org, as opposed to a Linux distribution package or Flatpak.
+    This avoids any issues related to packaging, such as different library
+    versions that can cause incompatibilities or sandboxing restrictions.
+
+From Godot 4.0 onwards, the editor can directly import ``.blend`` files by
+calling `Blender <https://www.blender.org/>`__'s glTF export functionality in a
+transparent manner.
+
+This allows you to iterate on your 3D scenes faster, as you can save the scene
+in Blender, alt-tab back to Godot then see your changes immediately. When
+working with version control, this is also more efficient as you no longer need
+to commit a copy of the exported glTF file to version control.
+
+To use ``.blend`` import, you must install Blender before opening the Godot
+editor (if opening a project that already contains ``.blend`` files). If you
+keep Blender installed at its default location, Godot should be able to detect
+its path automatically. If this isn't the case, configure the path to the
+directory containing the Blender executable in the Editor Settings
+(**Filesystem > Import > Blender > Blender 3 Path**).
+
+If you keep ``.blend`` files within your project folder but don't want them to
+be imported by Godot, disable **Filesystem > Import > Blender > Enabled** in the
+advanced Project Settings.
+
+.. note::
+
+    When working in a team, keep in mind using ``.blend`` files in your project
+    will require *all* team members to have Blender installed. While Blender is
+    a free download, this may add friction when working on the project.
+    ``.blend`` import is also not available on the Android and web editors, as
+    these platforms can't call external programs.
+
+    If this is problematic, consider using glTF scenes exported from Blender
+    instead.
+
+Exporting DAE files from Blender
+--------------------------------
+
+Blender has built-in COLLADA support, but it does not work properly for the
+needs of game engines and shouldn't be used as-is. However, scenes exported with
+the built-in Collada support may still work for simple scenes without animation.
+
+For complex scenes or scenes that contain animations, Godot provides a
+`Blender plugin <https://github.com/godotengine/collada-exporter>`_
+that will correctly export COLLADA scenes for use in Godot.
+
+Importing OBJ files in Godot
+----------------------------
+
+OBJ is one of the simplest 3D formats out there, so Godot should be able to
+import most OBJ files successfully. However, OBJ is also a very limited format:
+it doesn't support skinning, animation, UV2 or PBR materials.
+
+There are 2 ways to use OBJ meshes in Godot:
+
+- Load them directly in a MeshInstance3D node, or any other property that
+  expects as mesh (such as GPUParticles3D). This is the default mode.
+- Change their import mode to **OBJ as Scene** in the Import dock then restart
+  the editor. This allows you to use the same import options as glTF or Collada
+  scenes, such as unwrapping UV2 on import (for :ref:`doc_using_lightmap_gi`).
+
+.. note::
+
+    Blender 3.4 and later can export RGB vertex colors in OBJ files (this is a
+    nonstandard extension of the OBJ format). Godot is able to import those
+    vertex colors since Godot 4.0, but they will not be displayed on the
+    material unless you enable **Vertex Color > Use As Albedo** on the material.
+
+    Vertex colors from OBJ meshes keep their original color space once imported
+    (sRGB/linear), but their brightness is clamped to 1.0 (they can't be
+    overbright).
+
+Importing FBX files in Godot
+----------------------------
+
+When opening a project containing FBX scenes, you will see a dialog asking you
+to configure FBX import. Click the link in the dialog to download an FBX2glTF
+binary, then extract the ZIP archive, place the binary anywhere you wish, then
+specify its path in the dialog.
+
+If you keep ``.fbx`` files within your project folder but don't want them to
+be imported by Godot, disable **Filesystem > Import > FBX > Enabled** in the
+advanced Project Settings.
+
+.. seealso::
+
+    The full installation process for using FBX in Godot is described on the
+    `FBX import page of the Godot website <https://godotengine.org/fbx-import>`__.

tutorials/assets_pipeline/importing_scenes.rst → tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst

@@ -1,253 +1,21 @@
-.. _doc_importing_3d_scenes:
+.. _doc_importing_3d_scenes_import_configuration:
 
-Importing 3D scenes
-===================
+Import configuration
+====================
 
-Godot scene importer
---------------------
+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.
 
-When dealing with 3D assets, Godot has a flexible and configurable importer.
-
-Godot works with *scenes*. This means that the entire scene being worked on in
-your favorite 3D modeling software will be transferred as close as possible.
-
-Godot supports the following 3D *scene file formats*:
-
-- glTF 2.0 **(recommended)**. Godot has full support for both text (``.gltf``)
-  and binary (``.glb``) formats.
-- ``.blend`` (Blender). This works by calling Blender to export to glTF in a
-  transparent manner (requires Blender to be installed).
-- DAE (COLLADA), an older format that is fully supported.
-- OBJ (Wavefront) format + their MTL material files. This is also fully
-  supported, but pretty limited given the format's limitations (no support for
-  pivots, skeletons, animations, UV2, PBR materials, ...).
-- FBX, supported via `FBX2glTF <https://github.com/godotengine/FBX2glTF>`__ integration.
-  This requires installing an external program that links against the proprietary FBX SDK,
-  so we recommend using other formats listed above (if suitable for your workflow).
-
-Copy the scene file together with the textures and mesh data (if separate) to
-the project repository, then Godot will do a full import when focusing the
-editor window.
-
-3D asset direction conventions
-------------------------------
-
-Godot uses a right-handed, Y-is-up coordinate system, with the -Z axis as
-the camera's forward direction. This is the same as OpenGL. This implies
-that +Z is back, +X is right, and -X is left for a camera.
-
-The convention for 3D assets is to face the opposite direction as the camera,
-so that characters and other assets are facing the camera by default.
-This convention is extremely common in 3D modeling applications, and is
-`codified in glTF as part of the glTF 2.0 specification <https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units>`__.
-This means that for oriented 3D assets (such as characters),
-the +Z axis is the direction of the front, so -Z is the rear,
-+X is the left side, and -X is the right side for a 3D asset.
-In Blender, this means that +Y is rear and -Y is front for an asset.
-
-When rotating an oriented 3D asset in Godot, use the ``use_model_front``
-option on the ``look_at`` functions, and use the ``Vector3.MODEL_*``
-constants to perform calculations in the oriented asset's local space.
-
-For assets without an intrinsic front side or forward direction, such as
-a game map or terrain, take note of the cardinal directions instead.
-The convention in Godot and the vast majority of other applications is
-that +X is east and -X is west. Due to Godot's right-handed Y-is-up
-coordinate system, this implies that +Z is south and -Z is north.
-In Blender, this means that +Y is north and -Y is south.
-
-Exporting glTF 2.0 files from Blender (recommended)
----------------------------------------------------
-
-There are 3 ways to export glTF files from Blender:
-
-- As a glTF binary file (``.glb``).
-- As a glTF text-based file with embedded binary data (``.gltf`` file)
-- As a glTF text-based file with separate binary data and textures (``.gltf``
-  file + ``.bin`` file + textures).
-
-glTF binary files (``.glb``) are the smallest of the three options. They include
-the mesh and textures set up in Blender. When brought into Godot the textures
-are part of the object's material file.
-
-glTF embedded files (``.gltf``) function the same way as binary files. They
-don't provide extra functionality in Godot, and shouldn't be used since they
-have a larger file size.
-
-There are two reasons to use glTF with the textures separate. One is to have the
-scene description in a text based format and the binary data in a separate
-binary file. This can be useful for version control if you want to review
-changes in a text-based format. The second is you need the texture files
-separate from the material file. If you don't need either of those, glTF binary
-files are fine.
-
-.. warning::
-
-    If your model contains blend shapes (also known as "shape keys" and "morph
-    targets"), your glTF export setting **Export Deformation Bones Only** needs
-    to be configured to **Enabled** under the Animation export configurations.
-
-    Exporting non-deforming bones anyway will lead to incorrect shading.
-
-.. note::
-
-    Blender versions older than 3.2 do not export emissive textures with the
-    glTF file. If your model uses one and you're using an older version of
-    Blender, it must be brought in separately.
-
-    By default, Blender has backface culling disabled on materials and will
-    export materials to match how they render in Blender. This means that
-    materials in Godot will have their cull mode set to **Disabled**. This can
-    decrease performance since backfaces will be rendered, even when they are
-    being culled by other faces. To resolve this, enable **Backface Culling** in
-    Blender's Materials tab, then export the scene to glTF again.
-
-Importing ``.blend`` files directly within Godot
-------------------------------------------------
-
-.. note::
-
-    This functionality requires Blender 3.0 or later. For best results, we
-    recommend using Blender 3.5 or later, as it includes many fixes to the glTF
-    exporter.
-
-    It is **strongly** recommended to use an official Blender release downloaded
-    from blender.org, as opposed to a Linux distribution package or Flatpak.
-    This avoids any issues related to packaging, such as different library
-    versions that can cause incompatibilities or sandboxing restrictions.
-
-From Godot 4.0 onwards, the editor can directly import ``.blend`` files by
-calling `Blender <https://www.blender.org/>`__'s glTF export functionality in a
-transparent manner.
-
-This allows you to iterate on your 3D scenes faster, as you can save the scene
-in Blender, alt-tab back to Godot then see your changes immediately. When
-working with version control, this is also more efficient as you no longer need
-to commit a copy of the exported glTF file to version control.
-
-To use ``.blend`` import, you must install Blender before opening the Godot
-editor (if opening a project that already contains ``.blend`` files). If you
-keep Blender installed at its default location, Godot should be able to detect
-its path automatically. If this isn't the case, configure the path to the
-directory containing the Blender executable in the Editor Settings
-(**Filesystem > Import > Blender > Blender 3 Path**).
-
-If you keep ``.blend`` files within your project folder but don't want them to
-be imported by Godot, disable **Filesystem > Import > Blender > Enabled** in the
-advanced Project Settings.
-
-.. note::
-
-    When working in a team, keep in mind using ``.blend`` files in your project
-    will require *all* team members to have Blender installed. While Blender is
-    a free download, this may add friction when working on the project.
-    ``.blend`` import is also not available on the Android and web editors, as
-    these platforms can't call external programs.
-
-    If this is problematic, consider using glTF scenes exported from Blender
-    instead.
-
-Exporting DAE files from Blender
---------------------------------
-
-Blender has built-in COLLADA support, but it does not work properly for the
-needs of game engines and shouldn't be used as-is. However, scenes exported with
-the built-in Collada support may still work for simple scenes without animation.
-
-For complex scenes or scenes that contain animations, Godot provides a
-`Blender plugin <https://github.com/godotengine/collada-exporter>`_
-that will correctly export COLLADA scenes for use in Godot.
-
-Importing OBJ files in Godot
-----------------------------
-
-OBJ is one of the simplest 3D formats out there, so Godot should be able to
-import most OBJ files successfully. However, OBJ is also a very limited format:
-it doesn't support skinning, animation, UV2 or PBR materials.
-
-There are 2 ways to use OBJ meshes in Godot:
-
-- Load them directly in a MeshInstance3D node, or any other property that
-  expects as mesh (such as GPUParticles3D). This is the default mode.
-- Change their import mode to **OBJ as Scene** in the Import dock then restart
-  the editor. This allows you to use the same import options as glTF or Collada
-  scenes, such as unwrapping UV2 on import (for :ref:`doc_using_lightmap_gi`).
-
-.. note::
-
-    Blender 3.4 and later can export RGB vertex colors in OBJ files (this is a
-    nonstandard extension of the OBJ format). Godot is able to import those
-    vertex colors since Godot 4.0, but they will not be displayed on the
-    material unless you enable **Vertex Color > Use As Albedo** on the material.
-
-    Vertex colors from OBJ meshes keep their original color space once imported
-    (sRGB/linear), but their brightness is clamped to 1.0 (they can't be
-    overbright).
-
-Importing FBX files in Godot
-----------------------------
-
-When opening a project containing FBX scenes, you will see a dialog asking you
-to configure FBX import. Click the link in the dialog to download a fbx2gltf
-binary, then extract the ZIP archive, place the binary anywhere you wish, then
-specify its path in the dialog.
-
-If you keep ``.fbx`` files within your project folder but don't want them to
-be imported by Godot, disable **Filesystem > Import > FBX > Enabled** in the
-advanced Project Settings.
-
-.. seealso::
-
-    The full installation process for using FBX in Godot is described on the
-    `FBX import page of the Godot website <https://godotengine.org/fbx-import>`__.
-
-Exporting textures separately
------------------------------
-
-While textures can be exported with a model in certain file formats, such as glTF 2.0, you can also export them
-separately. Godot uses PBR (physically based rendering) for its materials, so if a texturing program can export PBR
-textures they can work in Godot. This includes the `Substance suite <https://www.substance3d.com/>`__,
-`ArmorPaint (open source) <https://armorpaint.org/>`__, and `Material Maker (open source) <https://github.com/RodZill4/material-maker>`__.
-
-.. note:: For more information on Godot's materials, see :ref:`doc_standard_material_3d`.
-
-Exporting considerations
-------------------------
-
-Since GPUs can only render triangles, meshes that contain quads or N-gons have
-to be *triangulated* before they can be rendered. Godot can triangulate meshes
-on import, but results may be unpredictable or incorrect, especially with
-N-gons. Regardless of the target application, triangulating *before* exporting
-the scene will lead to more consistent results and should be done whenever
-possible.
-
-To avoid issues with incorrect triangulation after importing in Godot, it is
-recommended to make the 3D modeling software triangulate objects on its own. In
-Blender, this can be done by adding a Triangulate modifier to your objects and
-making sure **Apply Modifiers** is checked in the export dialog. Alternatively,
-depending on the exporter, you may be able to find and enable a **Triangulate
-Faces** option in the export dialog.
-
-To avoid issues with 3D selection in the editor, it is recommended to apply the
-object transform in the 3D modeling software before exporting the scene.
-
-.. note::
-
-    It is important that the mesh is not deformed by bones when exporting. Make sure
-    that the skeleton is reset to its T-pose or default rest pose before exporting
-    with your favorite 3D editor.
-
-Lighting considerations
------------------------
-
-While it's possible to import lights from a 3D scene using the glTF, ``.blend``
-or Collada formats, it's generally advised to design the scene's lighting in the
-Godot editor after importing the scene.
-
-This allows you to get a more accurate feel for the final result, as different
-engines will render lights in a different manner. This also avoids any issues
-with lights appearing excessively strong or faint as a result of the import
-process.
+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
+:ref:`doc_importing_3d_scenes_model_export_considerations` and
+:ref:`doc_importing_3d_scenes_node_type_customization` articles
+for more information.
 
 Import workflows
 ----------------
@@ -756,127 +524,3 @@ In inherited scenes, the only limitations for modification are:
 Other than that, everything is allowed.
 
 .. _doc_importing_3d_scenes_import_hints:
-
-Import hints
-------------
-
-Many times, when editing a scene, there are common tasks that need to be done
-after exporting:
-
-- Adding collision detection to objects.
-- Setting objects as navigation meshes.
-- Deleting nodes that are not used in the game engine (like specific lights used
-  for modeling).
-
-To simplify this workflow, Godot offers several suffixes that can be added to
-the names of the objects in your 3D modeling software. When imported, Godot
-will detect suffixes in object names and will perform actions automatically.
-
-.. warning::
-
-    All the suffixes described below are **case-sensitive**.
-
-Remove nodes (-noimp)
-^^^^^^^^^^^^^^^^^^^^^
-
-Objects that have the ``-noimp`` suffix will be removed at import-time no matter
-what their type is. They will not appear in the imported scene.
-
-This is equivalent to enabling **Skip Import** for a node in the Advanced Import
-Settings dialog.
-
-Create collisions (-col, -convcol, -colonly, -convcolonly)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The option ``-col`` will work only for Mesh objects. If it is detected, a child
-static collision node will be added, using the same geometry as the mesh. This
-will create a triangle mesh collision shape, which is a slow, but accurate
-option for collision detection. This option is usually what you want for level
-geometry (but see also ``-colonly`` below).
-
-The option ``-convcol`` will create a :ref:`class_ConvexPolygonShape3D` instead of
-a :ref:`class_ConcavePolygonShape3D`. Unlike triangle meshes which can be concave,
-a convex shape can only accurately represent a shape that doesn't have any
-concave angles (a pyramid is convex, but a hollow box is concave). Due to this,
-convex collision shapes are generally not suited for level geometry. When
-representing simple enough meshes, convex collision shapes can result in better
-performance compared to a triangle collision shape. This option is ideal for
-simple or dynamic objects that require mostly-accurate collision detection.
-
-However, in both cases, the visual geometry may be too complex or not smooth
-enough for collisions. This can create physics glitches and slow down the engine
-unnecessarily.
-
-To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon
-importing and will create a :ref:`class_StaticBody3D` collision instead.
-This helps the visual mesh and actual collision to be separated.
-
-The option ``-convcolonly`` works in a similar way, but will create a
-:ref:`class_ConvexPolygonShape3D` instead using convex decomposition.
-
-With Collada files, the option ``-colonly`` can also be used with Blender's
-empty objects. On import, it will create a :ref:`class_StaticBody3D` with a
-collision node as a child. The collision node will have one of a number of
-predefined shapes, depending on Blender's empty draw type:
-
-.. figure:: img/importing_3d_scenes_blender_empty_draw_types.webp
-   :align: center
-   :alt: Choosing a draw type for an Empty on creation in Blender
-
-   Choosing a draw type for an Empty on creation in Blender
-
-- Single arrow will create a :ref:`class_SeparationRayShape3D`.
-- Cube will create a :ref:`class_BoxShape3D`.
-- Image will create a :ref:`class_WorldBoundaryShape3D`.
-- Sphere (and the others not listed) will create a :ref:`class_SphereShape3D`.
-
-When possible, **try to use a few primitive collision shapes** instead of triangle
-mesh or convex shapes. Primitive shapes often have the best performance and
-reliability.
-
-.. note::
-
-    For better visibility on Blender's editor, you can set the "X-Ray" option
-    on collision empties and set some distinct color for them by changing
-    **Edit > Preferences > Themes > 3D Viewport > Empty**.
-
-    If using Blender 2.79 or older, follow these steps instead:
-    **User Preferences > Themes > 3D View > Empty**.
-
-.. seealso::
-
-    See :ref:`doc_collision_shapes_3d` for a comprehensive overview of collision
-    shapes.
-
-Create navigation (-navmesh)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh.
-The original Mesh object will be removed at import-time.
-
-Create a VehicleBody (-vehicle)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A mesh node with the ``-vehicle`` suffix will be imported as a child to a
-:ref:`class_VehicleBody3D` node.
-
-Create a VehicleWheel (-wheel)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A mesh node with the ``-wheel`` suffix will be imported as a child to a
-:ref:`class_VehicleWheel3D` node.
-
-Rigid Body (-rigid)
-^^^^^^^^^^^^^^^^^^^
-
-A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody3D`.
-
-Animation loop (-loop, -cycle)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Animation clips in the source 3D file that start or end with the token ``loop`` or ``cycle``
-will be imported as a Godot :ref:`class_Animation` with the loop flag set.
-**Unlike the other suffixes described above, this does not require a hyphen.**
-
-In Blender, this requires using the NLA Editor and naming the Action with the ``loop`` or
-``cycle`` prefix or suffix.

tutorials/assets_pipeline/importing_3d_scenes/index.rst

@@ -0,0 +1,21 @@
+.. _doc_importing_3d_scenes:
+
+Importing 3D scenes
+===================
+
+Godot supports importing 3D scenes from various file formats.
+This documentation section describes what those formats are, and how to use
+them, including exporting with the correct conventions and best practices,
+and how to customize the node type using a suffix in the node name.
+The import configuration article describes how to customize the
+imported data using the import dock, the advanced import settings
+dialog, and inherited scenes.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-workflow-assets-importing_3d_scenes
+
+   available_formats
+   model_export_considerations
+   node_type_customization
+   import_configuration

tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst

@@ -0,0 +1,83 @@
+.. _doc_importing_3d_scenes_model_export_considerations:
+
+Model export considerations
+===========================
+
+Before exporting a 3D model from a 3D modeling application, such as Blender,
+there are some considerations that should be taken into account to ensure that
+the model follows the conventions and best practices for Godot.
+
+3D asset direction conventions
+------------------------------
+
+Godot uses a right-handed, Y-is-up coordinate system, with the -Z axis as
+the camera's forward direction. This is the same as OpenGL. This implies
+that +Z is back, +X is right, and -X is left for a camera.
+
+The convention for 3D assets is to face the opposite direction as the camera,
+so that characters and other assets are facing the camera by default.
+This convention is extremely common in 3D modeling applications, and is
+`codified in glTF as part of the glTF 2.0 specification <https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units>`__.
+This means that for oriented 3D assets (such as characters),
+the +Z axis is the direction of the front, so -Z is the rear,
++X is the left side, and -X is the right side for a 3D asset.
+In Blender, this means that +Y is rear and -Y is front for an asset.
+
+When rotating an oriented 3D asset in Godot, use the ``use_model_front``
+option on the ``look_at`` functions, and use the ``Vector3.MODEL_*``
+constants to perform calculations in the oriented asset's local space.
+
+For assets without an intrinsic front side or forward direction, such as
+a game map or terrain, take note of the cardinal directions instead.
+The convention in Godot and the vast majority of other applications is
+that +X is east and -X is west. Due to Godot's right-handed Y-is-up
+coordinate system, this implies that +Z is south and -Z is north.
+In Blender, this means that +Y is north and -Y is south.
+
+Exporting textures separately
+-----------------------------
+
+While textures can be exported with a model in certain file formats, such as glTF 2.0, you can also export them
+separately. Godot uses PBR (physically based rendering) for its materials, so if a texturing program can export PBR
+textures they can work in Godot. This includes the `Substance suite <https://www.substance3d.com/>`__,
+`ArmorPaint (open source) <https://armorpaint.org/>`__, and `Material Maker (open source) <https://github.com/RodZill4/material-maker>`__.
+
+.. note:: For more information on Godot's materials, see :ref:`doc_standard_material_3d`.
+
+Exporting considerations
+------------------------
+
+Since GPUs can only render triangles, meshes that contain quads or N-gons have
+to be *triangulated* before they can be rendered. Godot can triangulate meshes
+on import, but results may be unpredictable or incorrect, especially with
+N-gons. Regardless of the target application, triangulating *before* exporting
+the scene will lead to more consistent results and should be done whenever
+possible.
+
+To avoid issues with incorrect triangulation after importing in Godot, it is
+recommended to make the 3D modeling software triangulate objects on its own. In
+Blender, this can be done by adding a Triangulate modifier to your objects and
+making sure **Apply Modifiers** is checked in the export dialog. Alternatively,
+depending on the exporter, you may be able to find and enable a **Triangulate
+Faces** option in the export dialog.
+
+To avoid issues with 3D selection in the editor, it is recommended to apply the
+object transform in the 3D modeling software before exporting the scene.
+
+.. note::
+
+    It is important that the mesh is not deformed by bones when exporting. Make sure
+    that the skeleton is reset to its T-pose or default rest pose before exporting
+    with your favorite 3D editor.
+
+Lighting considerations
+-----------------------
+
+While it's possible to import lights from a 3D scene using the glTF, ``.blend``
+or Collada formats, it's generally advised to design the scene's lighting in the
+Godot editor after importing the scene.
+
+This allows you to get a more accurate feel for the final result, as different
+engines will render lights in a different manner. This also avoids any issues
+with lights appearing excessively strong or faint as a result of the import
+process.

tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst

@@ -0,0 +1,125 @@
+.. _doc_importing_3d_scenes_node_type_customization:
+
+Node type customization using name suffixes
+===========================================
+
+Many times, when editing a scene, there are common tasks that need to be done
+after exporting:
+
+- Adding collision detection to objects.
+- Setting objects as navigation meshes.
+- Deleting nodes that are not used in the game engine (like specific lights used
+  for modeling).
+
+To simplify this workflow, Godot offers several suffixes that can be added to
+the names of the objects in your 3D modeling software. When imported, Godot
+will detect suffixes in object names and will perform actions automatically.
+
+.. warning::
+
+    All the suffixes described below are **case-sensitive**.
+
+Remove nodes (-noimp)
+^^^^^^^^^^^^^^^^^^^^^
+
+Objects that have the ``-noimp`` suffix will be removed at import-time no matter
+what their type is. They will not appear in the imported scene.
+
+This is equivalent to enabling **Skip Import** for a node in the Advanced Import
+Settings dialog.
+
+Create collisions (-col, -convcol, -colonly, -convcolonly)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The option ``-col`` will work only for Mesh objects. If it is detected, a child
+static collision node will be added, using the same geometry as the mesh. This
+will create a triangle mesh collision shape, which is a slow, but accurate
+option for collision detection. This option is usually what you want for level
+geometry (but see also ``-colonly`` below).
+
+The option ``-convcol`` will create a :ref:`class_ConvexPolygonShape3D` instead of
+a :ref:`class_ConcavePolygonShape3D`. Unlike triangle meshes which can be concave,
+a convex shape can only accurately represent a shape that doesn't have any
+concave angles (a pyramid is convex, but a hollow box is concave). Due to this,
+convex collision shapes are generally not suited for level geometry. When
+representing simple enough meshes, convex collision shapes can result in better
+performance compared to a triangle collision shape. This option is ideal for
+simple or dynamic objects that require mostly-accurate collision detection.
+
+However, in both cases, the visual geometry may be too complex or not smooth
+enough for collisions. This can create physics glitches and slow down the engine
+unnecessarily.
+
+To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon
+importing and will create a :ref:`class_StaticBody3D` collision instead.
+This helps the visual mesh and actual collision to be separated.
+
+The option ``-convcolonly`` works in a similar way, but will create a
+:ref:`class_ConvexPolygonShape3D` instead using convex decomposition.
+
+With Collada files, the option ``-colonly`` can also be used with Blender's
+empty objects. On import, it will create a :ref:`class_StaticBody3D` with a
+collision node as a child. The collision node will have one of a number of
+predefined shapes, depending on Blender's empty draw type:
+
+.. figure:: img/importing_3d_scenes_blender_empty_draw_types.webp
+   :align: center
+   :alt: Choosing a draw type for an Empty on creation in Blender
+
+   Choosing a draw type for an Empty on creation in Blender
+
+- Single arrow will create a :ref:`class_SeparationRayShape3D`.
+- Cube will create a :ref:`class_BoxShape3D`.
+- Image will create a :ref:`class_WorldBoundaryShape3D`.
+- Sphere (and the others not listed) will create a :ref:`class_SphereShape3D`.
+
+When possible, **try to use a few primitive collision shapes** instead of triangle
+mesh or convex shapes. Primitive shapes often have the best performance and
+reliability.
+
+.. note::
+
+    For better visibility on Blender's editor, you can set the "X-Ray" option
+    on collision empties and set some distinct color for them by changing
+    **Edit > Preferences > Themes > 3D Viewport > Empty**.
+
+    If using Blender 2.79 or older, follow these steps instead:
+    **User Preferences > Themes > 3D View > Empty**.
+
+.. seealso::
+
+    See :ref:`doc_collision_shapes_3d` for a comprehensive overview of collision
+    shapes.
+
+Create navigation (-navmesh)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh.
+The original Mesh object will be removed at import-time.
+
+Create a VehicleBody (-vehicle)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A mesh node with the ``-vehicle`` suffix will be imported as a child to a
+:ref:`class_VehicleBody3D` node.
+
+Create a VehicleWheel (-wheel)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A mesh node with the ``-wheel`` suffix will be imported as a child to a
+:ref:`class_VehicleWheel3D` node.
+
+Rigid Body (-rigid)
+^^^^^^^^^^^^^^^^^^^
+
+A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody3D`.
+
+Animation loop (-loop, -cycle)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Animation clips in the source 3D file that start or end with the token ``loop`` or ``cycle``
+will be imported as a Godot :ref:`class_Animation` with the loop flag set.
+**Unlike the other suffixes described above, this does not require a hyphen.**
+
+In Blender, this requires using the NLA Editor and naming the Action with the ``loop`` or
+``cycle`` prefix or suffix.

tutorials/assets_pipeline/index.rst

@@ -9,7 +9,7 @@ Assets pipeline
    importing_images
    importing_audio_samples
    importing_translations
-   importing_scenes
+   importing_3d_scenes/index
    retargeting_3d_skeletons
    exporting_3d_scenes
    escn_exporter/index