From 4bb6cdbb700c67674b5ec0312e98826a5c51c620 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sat, 14 Jan 2023 00:26:56 +0100 Subject: [PATCH] Update Importing 3D scenes documentation for Godot 4.0 - Mention `.blend` import. - Mention `.fbx` import. - Document OBJ import modes and limitations. - Mention Blender's built-in Collada usually working OK for simple scenes without animation. - Remove mentions of ESCN export as the exporter is currently not compatible with Godot 4.0. --- about/list_of_features.rst | 9 +- .../assets_pipeline/importing_scenes.rst | 154 ++++++++++++++---- 2 files changed, 122 insertions(+), 41 deletions(-) diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 063fb44fea1..7727a42ef56 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -474,14 +474,13 @@ Import - Ogg Vorbis. - MP3. -- *3D scenes:* +- *3D scenes:* See :ref:`doc_importing_3d_scenes`. - glTF 2.0 *(recommended)*. - - `ESCN `__ - (direct export from Blender). - - FBX (static meshes only). + - ``.blend`` (by calling Blender's glTF export functionality transparently). + - FBX (by calling fbx2gltf transparently). - Collada (.dae). - - Wavefront OBJ (static scenes only, can be loaded directly as a mesh). + - Wavefront OBJ (static scenes only, can be loaded directly as a mesh or imported as a 3D scene). - Support for loading glTF 2.0 scenes at run-time, including from an exported project. - 3D meshes use `Mikktspace `__ to generate tangents diff --git a/tutorials/assets_pipeline/importing_scenes.rst b/tutorials/assets_pipeline/importing_scenes.rst index c587b2fbcc1..84a802ce706 100644 --- a/tutorials/assets_pipeline/importing_scenes.rst +++ b/tutorials/assets_pipeline/importing_scenes.rst @@ -13,42 +13,54 @@ 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. -* DAE (COLLADA), an older format that is fully supported. -* OBJ (Wavefront) format + their MTL material files. This is also fully supported, but pretty limited (no support for pivots, skeletons, animations, PBR materials, ...). -* ESCN, a Godot-specific format that Blender can export with a plugin. -* FBX, supported via a reverse engineered importer. So we recommend using other formats listed above, if suitable - for your workflow. +- 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). Just copy the scene file together with the texture to the project repository, and Godot will do a full import. 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. -Exporting glTF 2.0 files from Blender -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Exporting glTF 2.0 files from Blender (recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are three ways to export glTF files from Blender. As a glTF binary (``.glb`` file), glTF embedded (``.gltf`` file), -and with textures (``gltf`` + ``.bin`` + textures). +There are 3 ways to export glTF files from Blender: -glTF binary files 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. +- 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 embedded files 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. +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. -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. +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. + 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 in GLES3. + Exporting non-deforming bones anyway will lead to incorrect shading. .. note:: @@ -63,27 +75,97 @@ either of those glTF binary files are fine. 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. + +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 +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 should not be used as is. +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. -Godot provides a `Blender plugin `_ -that will correctly export COLLADA scenes for use in Godot. It does not work in Blender 2.8 or -newer, but there are plans to update it in the future. +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_baked_lightmaps`). + +.. note:: -Exporting ESCN files from Blender -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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. -The most powerful one, called `godot-blender-exporter -`__. -It uses a .escn file, which is kind of another name for a .tscn file (Godot scene file); -it keeps as much information as possible from a Blender scene. However, it is considered -experimental. + 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 ESCN exporter has a detailed `document `__ describing -its functionality and usage. + The full installation process for using FBX in Godot is described on the + `FBX import page of the Godot website `__. Exporting textures separately ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~