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 straight away. This is the step by step, the choice between a mesh and a scene, and the settings in the Import dock that matter. What an OBJ carries is in the OBJ guide; the same import for Unity and Unreal sits beside this one, and free low poly assets for Godot is where the models come from.

The import

1. Copy the .obj, its .mtl and any texture into the project folder, together. Godot's FileSystem dock notices 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: one mesh, with a surface per material. That is right for a prop you will 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 instance into your own scene or open as an inherited scene to edit.

Scale

Godot's unit is the metre. A file made in metres arrives right; one made in centimetres arrives a hundredth the size. In the Import dock the mesh importer has a Scale Mesh setting; set it to 100 for a centimetre file and Reimport. Fix scale here rather than on the node, so colliders, children and anything that reads the node's transform stay sane.

There is also an Offset Mesh for a model whose origin is in the wrong place; a tree whose origin is at the middle of the trunk gets an offset of half its height in Y so it stands on the ground.

Materials

Godot reads the .mtl and makes a StandardMaterial3D per material, with Kd as the albedo colour and map_Kd as the albedo texture if the file is found. Two settings on those materials suit low poly models: Specular down to 0 under the Metallic section, so flat colour does not pick up a highlight, and, for a palette texture, Filter set 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 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 is 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 from the tool that made it with flat shading set. The flat shading guide explains the same problem for Unity; in Godot the file is the fix.

Reimporting

Change the file on disk and Godot reimports it, keeping the Import dock settings. Change the settings and press Reimport. The .import file beside the model holds the settings, and belongs in version control alongside it.

Levels of detail

Godot 4 can generate LODs for any imported mesh. In the Import dock, the mesh importer's LODs section has Generate LODs, on by default, and the angles that decide how far it simplifies. The engine then picks a level automatically from the mesh's size on screen. For control over what each level looks like, or to use levels made by hand, the Godot LOD article covers visibility ranges.

Collision

A MeshInstance3D has no collision. With the node selected, the Mesh menu in the viewport's toolbar offers 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, add a CollisionShape3D with a cylinder or capsule the size of the trunk instead, so the player walks under the canopy.

The things that go wrong

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

What PolyMason's files need

Nothing beyond copying the zip's contents in together. The tree builder writes metres, Y up, standing at the origin, flat normals, and one material with a palette PNG that every file in the zip shares.

More in this guide

• The OBJ file format, explained for game enginesEverything in an OBJ file and its MTL, everything it leaves out (units, axes, colours), how it compares with FBX, GLB and STL, and how Unity, Godot and Unreal each import one without the model arriving tiny, sideways or grey.
• OBJ vs FBX vs GLB vs STL: which 3D file format to use, and whenThe four formats a game or a printer will ask for, what each can and cannot carry, how Unity, Godot and Unreal read each one, file sizes, and which to ask a pack for. One table, then the reasons.
• How to import an OBJ into Unity, at the right size, in colour, shaded flatStep by step: 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.
• How to import an OBJ into Unreal Engine, at the right scaleStep by step: importing an OBJ as a Static Mesh in Unreal Engine 5, the Import Uniform Scale of 100 that a file in metres 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.