|
| 1 | +.. _doc_importing_3d_scenes_available_formats: |
| 2 | + |
| 3 | +Available 3D formats |
| 4 | +==================== |
| 5 | + |
| 6 | +When dealing with 3D assets, Godot has a flexible and configurable importer. |
| 7 | + |
| 8 | +Godot works with *scenes*. This means that the entire scene being worked on in |
| 9 | +your favorite 3D modeling software will be transferred as close as possible. |
| 10 | + |
| 11 | +Godot supports the following 3D *scene file formats*: |
| 12 | + |
| 13 | +- glTF 2.0 **(recommended)**. Godot has support for both text (``.gltf``) |
| 14 | + and binary (``.glb``) formats. |
| 15 | +- ``.blend`` (Blender). This works by calling Blender to export to glTF in a |
| 16 | + transparent manner (requires Blender to be installed). |
| 17 | +- DAE (COLLADA), an older format that is supported. |
| 18 | +- OBJ (Wavefront) format + their MTL material files. This is also |
| 19 | + supported, but pretty limited given the format's limitations (no support for |
| 20 | + pivots, skeletons, animations, UV2, PBR materials, ...). |
| 21 | +- FBX, supported via `FBX2glTF <https://github.com/godotengine/FBX2glTF>`__ integration. |
| 22 | + This requires installing an external program that links against the proprietary FBX SDK, |
| 23 | + so we recommend using other formats listed above (if suitable for your workflow). |
| 24 | + |
| 25 | +Copy the scene file together with the textures and mesh data (if separate) to |
| 26 | +the project repository, then Godot will do a full import when focusing the |
| 27 | +editor window. |
| 28 | + |
| 29 | +Exporting glTF 2.0 files from Blender (recommended) |
| 30 | +--------------------------------------------------- |
| 31 | + |
| 32 | +There are 3 ways to export glTF files from Blender: |
| 33 | + |
| 34 | +- As a glTF binary file (``.glb``). |
| 35 | +- As a glTF text-based file with embedded binary data (``.gltf`` file) |
| 36 | +- As a glTF text-based file with separate binary data and textures (``.gltf`` |
| 37 | + file + ``.bin`` file + textures). |
| 38 | + |
| 39 | +glTF binary files (``.glb``) are the smallest of the three options. They include |
| 40 | +the mesh and textures set up in Blender. When brought into Godot the textures |
| 41 | +are part of the object's material file. |
| 42 | + |
| 43 | +glTF embedded files (``.gltf``) function the same way as binary files. They |
| 44 | +don't provide extra functionality in Godot, and shouldn't be used since they |
| 45 | +have a larger file size. |
| 46 | + |
| 47 | +There are two reasons to use glTF with the textures separate. One is to have the |
| 48 | +scene description in a text based format and the binary data in a separate |
| 49 | +binary file. This can be useful for version control if you want to review |
| 50 | +changes in a text-based format. The second is you need the texture files |
| 51 | +separate from the material file. If you don't need either of those, glTF binary |
| 52 | +files are fine. |
| 53 | + |
| 54 | +.. warning:: |
| 55 | + |
| 56 | + If your model contains blend shapes (also known as "shape keys" and "morph |
| 57 | + targets"), your glTF export setting **Export Deformation Bones Only** needs |
| 58 | + to be configured to **Enabled** under the Animation export configurations. |
| 59 | + |
| 60 | + Exporting non-deforming bones anyway will lead to incorrect shading. |
| 61 | + |
| 62 | +.. note:: |
| 63 | + |
| 64 | + Blender versions older than 3.2 do not export emissive textures with the |
| 65 | + glTF file. If your model uses one and you're using an older version of |
| 66 | + Blender, it must be brought in separately. |
| 67 | + |
| 68 | + By default, Blender has backface culling disabled on materials and will |
| 69 | + export materials to match how they render in Blender. This means that |
| 70 | + materials in Godot will have their cull mode set to **Disabled**. This can |
| 71 | + decrease performance since backfaces will be rendered, even when they are |
| 72 | + being culled by other faces. To resolve this, enable **Backface Culling** in |
| 73 | + Blender's Materials tab, then export the scene to glTF again. |
| 74 | + |
| 75 | +Importing ``.blend`` files directly within Godot |
| 76 | +------------------------------------------------ |
| 77 | + |
| 78 | +.. note:: |
| 79 | + |
| 80 | + This functionality requires Blender 3.0 or later. For best results, we |
| 81 | + recommend using Blender 3.5 or later, as it includes many fixes to the glTF |
| 82 | + exporter. |
| 83 | + |
| 84 | + It is **strongly** recommended to use an official Blender release downloaded |
| 85 | + from blender.org, as opposed to a Linux distribution package or Flatpak. |
| 86 | + This avoids any issues related to packaging, such as different library |
| 87 | + versions that can cause incompatibilities or sandboxing restrictions. |
| 88 | + |
| 89 | +From Godot 4.0 onwards, the editor can directly import ``.blend`` files by |
| 90 | +calling `Blender <https://www.blender.org/>`__'s glTF export functionality in a |
| 91 | +transparent manner. |
| 92 | + |
| 93 | +This allows you to iterate on your 3D scenes faster, as you can save the scene |
| 94 | +in Blender, alt-tab back to Godot then see your changes immediately. When |
| 95 | +working with version control, this is also more efficient as you no longer need |
| 96 | +to commit a copy of the exported glTF file to version control. |
| 97 | + |
| 98 | +To use ``.blend`` import, you must install Blender before opening the Godot |
| 99 | +editor (if opening a project that already contains ``.blend`` files). If you |
| 100 | +keep Blender installed at its default location, Godot should be able to detect |
| 101 | +its path automatically. If this isn't the case, configure the path to the |
| 102 | +directory containing the Blender executable in the Editor Settings |
| 103 | +(**Filesystem > Import > Blender > Blender 3 Path**). |
| 104 | + |
| 105 | +If you keep ``.blend`` files within your project folder but don't want them to |
| 106 | +be imported by Godot, disable **Filesystem > Import > Blender > Enabled** in the |
| 107 | +advanced Project Settings. |
| 108 | + |
| 109 | +.. note:: |
| 110 | + |
| 111 | + When working in a team, keep in mind using ``.blend`` files in your project |
| 112 | + will require *all* team members to have Blender installed. While Blender is |
| 113 | + a free download, this may add friction when working on the project. |
| 114 | + ``.blend`` import is also not available on the Android and web editors, as |
| 115 | + these platforms can't call external programs. |
| 116 | + |
| 117 | + If this is problematic, consider using glTF scenes exported from Blender |
| 118 | + instead. |
| 119 | + |
| 120 | +Exporting DAE files from Blender |
| 121 | +-------------------------------- |
| 122 | + |
| 123 | +Blender has built-in COLLADA support, but it does not work properly for the |
| 124 | +needs of game engines and shouldn't be used as-is. However, scenes exported with |
| 125 | +the built-in Collada support may still work for simple scenes without animation. |
| 126 | + |
| 127 | +For complex scenes or scenes that contain animations, Godot provides a |
| 128 | +`Blender plugin <https://github.com/godotengine/collada-exporter>`_ |
| 129 | +that will correctly export COLLADA scenes for use in Godot. |
| 130 | + |
| 131 | +Importing OBJ files in Godot |
| 132 | +---------------------------- |
| 133 | + |
| 134 | +OBJ is one of the simplest 3D formats out there, so Godot should be able to |
| 135 | +import most OBJ files successfully. However, OBJ is also a very limited format: |
| 136 | +it doesn't support skinning, animation, UV2 or PBR materials. |
| 137 | + |
| 138 | +There are 2 ways to use OBJ meshes in Godot: |
| 139 | + |
| 140 | +- Load them directly in a MeshInstance3D node, or any other property that |
| 141 | + expects as mesh (such as GPUParticles3D). This is the default mode. |
| 142 | +- Change their import mode to **OBJ as Scene** in the Import dock then restart |
| 143 | + the editor. This allows you to use the same import options as glTF or Collada |
| 144 | + scenes, such as unwrapping UV2 on import (for :ref:`doc_using_lightmap_gi`). |
| 145 | + |
| 146 | +.. note:: |
| 147 | + |
| 148 | + Blender 3.4 and later can export RGB vertex colors in OBJ files (this is a |
| 149 | + nonstandard extension of the OBJ format). Godot is able to import those |
| 150 | + vertex colors since Godot 4.0, but they will not be displayed on the |
| 151 | + material unless you enable **Vertex Color > Use As Albedo** on the material. |
| 152 | + |
| 153 | + Vertex colors from OBJ meshes keep their original color space once imported |
| 154 | + (sRGB/linear), but their brightness is clamped to 1.0 (they can't be |
| 155 | + overbright). |
| 156 | + |
| 157 | +Importing FBX files in Godot |
| 158 | +---------------------------- |
| 159 | + |
| 160 | +When opening a project containing FBX scenes, you will see a dialog asking you |
| 161 | +to configure FBX import. Click the link in the dialog to download an FBX2glTF |
| 162 | +binary, then extract the ZIP archive, place the binary anywhere you wish, then |
| 163 | +specify its path in the dialog. |
| 164 | + |
| 165 | +If you keep ``.fbx`` files within your project folder but don't want them to |
| 166 | +be imported by Godot, disable **Filesystem > Import > FBX > Enabled** in the |
| 167 | +advanced Project Settings. |
| 168 | + |
| 169 | +.. seealso:: |
| 170 | + |
| 171 | + The full installation process for using FBX in Godot is described on the |
| 172 | + `FBX import page of the Godot website <https://godotengine.org/fbx-import>`__. |
0 commit comments