POLYMASON

How to import an OBJ into Godot 4

Part of The OBJ file format, explained for game engines

Godot imports an OBJ the moment it appears in the project folder, and gives you a mesh you can use right away. This article has the steps, explains the choice between importing a mesh and importing a scene, and goes through the settings in the Import dock that matter. What an OBJ carries is in the OBJ guide. The same import is written up for Unity and Unreal, and if you still need models, there's free low poly assets for Godot.

The import

  1. Copy the .obj, its .mtl and any texture into the project folder together. Godot's FileSystem dock notices them and imports them.
  2. Add a MeshInstance3D to your scene and set its Mesh property to the imported .obj, or drag the file from the FileSystem dock into the 3D viewport, which makes the node for you.
  3. Look at it. Materials from the .mtl come with the mesh, one surface per material, and appear under the mesh's Surface Material Override slots if you want to replace them.

Mesh or scene

By default an OBJ imports as a Mesh resource, which is one mesh with a surface per material. That's right for a prop you'll place with a MeshInstance3D.

If the file has several objects and you want a node per object, select the .obj in the FileSystem dock, open the Import dock beside the Scene dock, change Import As to Scene, and press Reimport. The file now opens as a scene with a MeshInstance3D per object, which you can instance into your own scene or open as an inherited scene to edit.

Scale

Godot's unit is the meter. A file made in meters arrives at the right size, and one made in centimeters arrives a hundred times too big. In the Import dock the mesh importer has a Scale Mesh setting. Set it to 0.01 for a centimeter file and press Reimport. Fix the scale here and not on the node, so that colliders, children and anything that reads the node's transform stay sane.

There's also an Offset Mesh setting for a model whose origin is in the wrong place. A tree whose origin is at the middle of the trunk needs an offset of half its height in Y so that it stands on the ground.

Materials

Godot reads the .mtl and makes a StandardMaterial3D per material, with Kd as the albedo color and map_Kd as the albedo texture if the file is found. Two settings on those materials suit low poly models. Turn Specular down to 0 under the Metallic section, so flat color doesn't pick up a highlight. For a palette texture, set Filter to Nearest under Sampling if you want hard-edged blocks.

To edit a material outside the importer, right-click the mesh's surface material in the Inspector and choose Make Unique, or set a Surface Material Override on the node.

Normals and flat shading

Godot uses the normals in the file. If the file has none, Godot generates smooth ones, and there's no smoothing angle to change. The fix for a low poly model that arrives smooth is a file with flat normals, which means re-exporting it from the tool that made it with flat shading set. The flat shading guide explains the same problem as it shows up in Unity.

Reimporting

When the file changes on disk, Godot reimports it and keeps the Import dock settings. When you change the settings, press Reimport to apply them. The .import file beside the model holds those settings, so commit it to version control along with the model.

Levels of detail

Godot 4 can generate LODs when it imports a mesh. For an OBJ imported as a mesh, the Import dock has a Generate LODs checkbox, which is on by default in current versions. Older 4.x releases only generated LODs for scene imports, so if you don't see the option, set Import As to Scene and reimport. The engine then picks a level automatically from the mesh's size on screen. If you want control over what each level looks like, or want to use levels made by hand, the Godot LOD article covers visibility ranges.

Collision

A MeshInstance3D has no collision of its own. With the node selected, the Mesh menu in the viewport's toolbar has Create Trimesh Collision Sibling for exact collision on a static prop, and Create Single Convex Collision Sibling for a cheaper hull. Both need the node to be under a StaticBody3D or similar to do anything. For a tree, skip both and add a CollisionShape3D with a cylinder or capsule the size of the trunk, so the player can walk under the canopy.

The things that go wrong

  • Gray: the .mtl or texture wasn't beside the .obj at import. Put them together and press Reimport.
  • Tiny or huge: the units are wrong. Set Scale Mesh in the Import dock.
  • On its side: the file was exported Z-up. Re-export with -Z forward and Y up.
  • Smooth: the file has no normals. Re-export it with flat shading.
  • Leaves dark from underneath: the leaf planes have a single-sided material. Set the material's Cull Mode to Disabled, or use a closed foliage mesh.

What PolyMason's files need

Copy the zip's contents into the project together and that's all they need. The tree builder writes meters, Y up, standing at the origin, with flat normals and one material whose palette PNG is shared by every file in the zip.

More in this guide

  • The OBJ file format, explained for game enginesWhat's in an OBJ file and its MTL, what it leaves out (units, axes, colors), how it compares with FBX, GLB and STL, and how to import one into Unity, Godot and Unreal so the model doesn't arrive tiny, sideways or gray.
  • OBJ vs FBX vs GLB vs STL: which format, and whenThe four formats a game or a printer will ask for, what each one can and can't carry, how Unity, Godot and Unreal read each, and which to ask a pack for. There's one table, then a section on each format.
  • Import an OBJ into Unity: size, color, shadingThe steps for getting an OBJ and its materials into Unity, the Scale Factor and Convert Units settings that make a model the right size, what to do when a model arrives a hundred times too big, the Materials tab, normals for flat shading, and colliders.
  • Import an OBJ into Unreal at the right scaleThe steps for importing an OBJ as a Static Mesh in Unreal Engine 5, the Import Uniform Scale of 100 that a file in meters needs, Convert Scene for the up axis, Normal Import Method for flat shading, what happens to the MTL's materials, collision, LODs and Nanite.

Or build a tree and see what comes out.