From 7d9ab84ac187d4319734e7e90e3797276dda3eaf Mon Sep 17 00:00:00 2001 From: Aaron Franke Date: Mon, 21 Aug 2023 17:56:20 -0500 Subject: [PATCH] Split the "Importing 3D scenes" article into multiple pages --- _tools/redirects/redirects.csv | 1 + classes/class_editorscenepostimport.rst | 2 +- classes/class_resourceimporterobj.rst | 2 +- classes/class_resourceimporterscene.rst | 4 +- tutorials/3d/csg_tools.rst | 2 +- .../importing_3d_scenes/available_formats.rst | 172 ++++++++ ...ced_import_settings_extract_materials.webp | Bin ...rt_settings_extract_materials_confirm.webp | Bin ...es_advanced_import_settings_materials.webp | Bin ...cenes_advanced_import_settings_meshes.webp | Bin ..._scenes_advanced_import_settings_node.webp | Bin ...scenes_advanced_import_settings_scene.webp | Bin ...ng_3d_scenes_blender_empty_draw_types.webp | Bin ...orting_3d_scenes_changing_import_type.webp | Bin ..._scenes_create_inherited_scene_dialog.webp | Bin .../img/importing_3d_scenes_import_dock.webp | Bin .../import_configuration.rst} | 386 +----------------- .../importing_3d_scenes/index.rst | 21 + .../model_export_considerations.rst | 83 ++++ .../node_type_customization.rst | 125 ++++++ tutorials/assets_pipeline/index.rst | 2 +- 21 files changed, 423 insertions(+), 377 deletions(-) create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_extract_materials.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_materials.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_meshes.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_node.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_advanced_import_settings_scene.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_blender_empty_draw_types.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_changing_import_type.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_create_inherited_scene_dialog.webp (100%) rename tutorials/assets_pipeline/{ => importing_3d_scenes}/img/importing_3d_scenes_import_dock.webp (100%) rename tutorials/assets_pipeline/{importing_scenes.rst => importing_3d_scenes/import_configuration.rst} (59%) create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/index.rst create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst create mode 100644 tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst diff --git a/_tools/redirects/redirects.csv b/_tools/redirects/redirects.csv index f2321cc7b..dcdf8a09a 100644 --- a/_tools/redirects/redirects.csv +++ b/_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 diff --git a/classes/class_editorscenepostimport.rst b/classes/class_editorscenepostimport.rst index 83fbf5537..14e21da07 100644 --- a/classes/class_editorscenepostimport.rst +++ b/classes/class_editorscenepostimport.rst @@ -80,7 +80,7 @@ The :ref:`_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 diff --git a/classes/class_resourceimporterobj.rst b/classes/class_resourceimporterobj.rst index a2f7acd74..0ea956f0f 100644 --- a/classes/class_resourceimporterobj.rst +++ b/classes/class_resourceimporterobj.rst @@ -28,7 +28,7 @@ See also :ref:`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 diff --git a/classes/class_resourceimporterscene.rst b/classes/class_resourceimporterscene.rst index 378bbbe53..4dc7d866c 100644 --- a/classes/class_resourceimporterscene.rst +++ b/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` **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 diff --git a/tutorials/3d/csg_tools.rst b/tutorials/3d/csg_tools.rst index 0d26435bb..d0883b538 100644 --- a/tutorials/3d/csg_tools.rst +++ b/tutorials/3d/csg_tools.rst @@ -87,7 +87,7 @@ Custom meshes ~~~~~~~~~~~~~ Any mesh can be used for :ref:`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, diff --git a/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst b/tutorials/assets_pipeline/importing_3d_scenes/available_formats.rst new file mode 100644 index 000000000..611f32c94 --- /dev/null +++ b/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 `__ 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 `__'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 `_ +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 `__. diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_extract_materials.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_extract_materials.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_extract_materials.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_extract_materials.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_extract_materials_confirm.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_materials.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_materials.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_materials.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_materials.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_meshes.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_meshes.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_meshes.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_meshes.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_node.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_node.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_node.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_node.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_scene.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_scene.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_advanced_import_settings_scene.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_advanced_import_settings_scene.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_blender_empty_draw_types.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_blender_empty_draw_types.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_blender_empty_draw_types.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_blender_empty_draw_types.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_changing_import_type.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_changing_import_type.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_changing_import_type.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_changing_import_type.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_create_inherited_scene_dialog.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_create_inherited_scene_dialog.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_create_inherited_scene_dialog.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_create_inherited_scene_dialog.webp diff --git a/tutorials/assets_pipeline/img/importing_3d_scenes_import_dock.webp b/tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_import_dock.webp similarity index 100% rename from tutorials/assets_pipeline/img/importing_3d_scenes_import_dock.webp rename to tutorials/assets_pipeline/importing_3d_scenes/img/importing_3d_scenes_import_dock.webp diff --git a/tutorials/assets_pipeline/importing_scenes.rst b/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst similarity index 59% rename from tutorials/assets_pipeline/importing_scenes.rst rename to tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst index 57a8a5fb3..941d2759c 100644 --- a/tutorials/assets_pipeline/importing_scenes.rst +++ b/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 `__ 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 `__. -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 `__'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 `_ -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 `__. - -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 `__, -`ArmorPaint (open source) `__, and `Material Maker (open source) `__. - -.. 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. diff --git a/tutorials/assets_pipeline/importing_3d_scenes/index.rst b/tutorials/assets_pipeline/importing_3d_scenes/index.rst new file mode 100644 index 000000000..bba121d61 --- /dev/null +++ b/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 diff --git a/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst b/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.rst new file mode 100644 index 000000000..e4eac5cce --- /dev/null +++ b/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 `__. +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 `__, +`ArmorPaint (open source) `__, and `Material Maker (open source) `__. + +.. 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. diff --git a/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst b/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.rst new file mode 100644 index 000000000..7035f6f26 --- /dev/null +++ b/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. diff --git a/tutorials/assets_pipeline/index.rst b/tutorials/assets_pipeline/index.rst index e01da3993..fee8775f0 100644 --- a/tutorials/assets_pipeline/index.rst +++ b/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