Importing 3D scenes

Godot scene importer

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.

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 Using Lightmap global illumination).

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.

See also

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 Standard Material 3D and ORM 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.

Import workflows

Since Godot can only save its own scene format (.tscn/.scn), Godot cannot save over the original 3D scene file (which uses a different format). This is also a safer approach as it avoids making accidental changes to the source file.

To allow cust