Merge pull request #7830 from aaronfranke/split-importing-3d-scenes

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>`__.