Introduction Meshes define the 3D geometry of objects, while materials determine how they appear visually. Godot provides powerful tools for importing 3D models, applying materials, and creating stunning visuals using PBR (Physically Based Rendering) workflows.
MeshInstance3D MeshInstance3D is the node used to display 3D geometry in your scene. It takes a Mesh resource and renders it in the 3D world.Basic Usage var mesh_instance = MeshInstance3D . new () add_child ( mesh_instance ) # Create a simple box mesh var box_mesh = BoxMesh . new () box_mesh . size = Vector3 ( 2 , 2 , 2 ) mesh_instance . mesh = box_mesh
See doc/classes/MeshInstance3D.xml:128
Built-in Primitive Meshes Godot includes several primitive mesh types for quick prototyping:
BoxMesh Rectangular cuboid
CylinderMesh Cylinder or cone
PrismMesh Triangular prism
# Create a sphere var sphere = SphereMesh . new () sphere . radius = 1.5 sphere . height = 3.0 sphere . radial_segments = 32 sphere . rings = 16 mesh_instance . mesh = sphere
Importing 3D Models Godot supports multiple 3D file formats:
glTF 2.0 (.gltf, .glb) - Recommended format FBX (.fbx) - Widely used in game developmentCollada (.dae) - Open standardWavefront OBJ (.obj) - Simple format, no animations
glTF 2.0 is the preferred format as it’s an open standard with excellent support for modern features like PBR materials, animations, and skinning.
Import Process
Import the Model
Drag and drop your 3D file into the FileSystem dock. Godot will automatically import it.
Configure Import Settings
Select the file and adjust settings in the Import dock (meshes, materials, animations).
Instantiate in Scene
Drag the imported scene into your level or instantiate it via code: var model = preload ( "res://models/character.gltf" ). instantiate () add_child ( model )
Materials Overview Materials control the visual appearance of meshes. Godot’s Material class is the base for all material types (doc/classes/Material.xml:2).
Material Types StandardMaterial3D
ORMMaterial3D
ShaderMaterial
The most common material type with PBR support. Provides a comprehensive set of properties without writing shaders. var material = StandardMaterial3D . new () material . albedo_color = Color . RED material . metallic = 0.8 material . roughness = 0.2 mesh_instance . material_override = material
Optimized variant of StandardMaterial3D that uses ORM (Occlusion, Roughness, Metallic) texture packing. var orm_material = ORMMaterial3D . new () # More memory efficient for complex materials
Custom materials using the Godot shading language for advanced effects. var shader_material = ShaderMaterial . new () shader_material . shader = preload ( "res://shaders/custom.gdshader" ) mesh_instance . material_override = shader_material
StandardMaterial3D Properties Albedo (Base Color) The base color or texture of the material:
var mat = StandardMaterial3D . new () # Set solid color mat . albedo_color = Color ( 1.0 , 0.5 , 0.2 ) # Set texture mat . albedo_texture = preload ( "res://textures/wood_albedo.png" )
See doc/classes/BaseMaterial3D.xml:60-66
These properties define the physically-based rendering characteristics:
# Metallic: 0.0 = non-metal, 1.0 = pure metal mat . metallic = 0.0 mat . metallic_texture = preload ( "res://textures/metal_map.png" ) # Roughness: 0.0 = smooth/glossy, 1.0 = rough/matte mat . roughness = 0.5 mat . roughness_texture = preload ( "res://textures/roughness_map.png" )
Metallic = 0.0 Non-metallic surfaces like wood, plastic, fabric
Metallic = 1.0 Metallic surfaces like iron, gold, chrome
Roughness = 0.0 Smooth, mirror-like surfaces
Roughness = 1.0 Matte, diffuse surfaces
Normal Mapping Add surface detail without additional geometry:
mat . normal_enabled = true mat . normal_texture = preload ( "res://textures/brick_normal.png" ) mat . normal_scale = 1.0 # Intensity of the normal map
Emission Make objects glow:
mat . emission_enabled = true mat . emission = Color ( 0.0 , 1.0 , 0.0 ) # Green glow mat . emission_energy_multiplier = 2.0 mat . emission_texture = preload ( "res://textures/emission.png" )
Textures and UV Mapping UV Coordinates UV coordinates map 2D textures onto 3D surfaces. Most 3D modeling software generates UVs automatically.
# Access UV layers (for multi-UV meshes) mat . uv1_scale = Vector3 ( 2.0 , 2.0 , 1.0 ) # Tile texture 2x mat . uv1_offset = Vector3 ( 0.5 , 0.5 , 0.0 ) # Offset texture
Texture Filtering # Control how textures are sampled mat . texture_filter = BaseMaterial3D . TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC
TEXTURE_FILTER_NEAREST: Pixelated lookTEXTURE_FILTER_LINEAR: Smooth interpolationTEXTURE_FILTER_LINEAR_WITH_MIPMAPS: Smooth with distance optimizationTEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: Best quality for angled surfaces Triplanar Mapping Project textures from three axes (useful for terrain):
mat . uv1_triplanar = true mat . uv1_triplanar_sharpness = 1.0
PBR Workflow The Physically Based Rendering workflow uses real-world material properties:
Set Albedo
Define the base color without lighting information mat . albedo_texture = preload ( "res://textures/wood_albedo.png" )
Configure Metallic
Determine if the surface is metallic mat . metallic = 0.0 # Wood is non-metallic mat . metallic_texture = preload ( "res://textures/wood_metallic.png" )
Adjust Roughness
Control surface glossiness mat . roughness = 0.7 # Slightly rough wood mat . roughness_texture = preload ( "res://textures/wood_roughness.png" )
Add Normal Map
Enhance surface detail mat . normal_enabled = true mat . normal_texture = preload ( "res://textures/wood_normal.png" )
Apply Ambient Occlusion
Add depth to crevices mat . ao_enabled = true mat . ao_texture = preload ( "res://textures/wood_ao.png" )
Surface Override Materials Meshes can have multiple surfaces, each with its own material:
# Get number of surfaces var surface_count = mesh_instance . mesh . get_surface_count () # Override material for specific surface mesh_instance . set_surface_override_material ( 0 , custom_material ) # Get the active material for a surface var active_mat = mesh_instance . get_active_material ( 0 )
See doc/classes/MeshInstance3D.xml:95-101, 117-124
Advanced Material Features Transparency mat . transparency = BaseMaterial3D . TRANSPARENCY_ALPHA mat . albedo_color = Color ( 1 , 1 , 1 , 0.5 ) # 50% transparent # Alpha scissor for cutout effects (grass, leaves) mat . transparency = BaseMaterial3D . TRANSPARENCY_ALPHA_SCISSOR mat . alpha_scissor_threshold = 0.5
Refraction Simulate glass and water:
mat . refraction_enabled = true mat . refraction_scale = 0.1 mat . refraction_texture = preload ( "res://textures/refraction.png" )
Subsurface Scattering For skin, wax, marble:
mat . subsurf_scatter_enabled = true mat . subsurf_scatter_strength = 0.5 mat . subsurf_scatter_texture = preload ( "res://textures/sss.png" )
Rim Lighting Create edge highlights:
mat . rim_enabled = true mat . rim = 1.0 mat . rim_tint = 0.5
Blend Shapes (Morph Targets) Animate mesh deformations:
# Get blend shape count var blend_count = mesh_instance . get_blend_shape_count () # Set blend shape value (0.0 to 1.0) mesh_instance . set_blend_shape_value ( 0 , 0.5 ) # Find blend shape by name var idx = mesh_instance . find_blend_shape_by_name ( "smile" ) if idx >= 0 : mesh_instance . set_blend_shape_value ( idx , 1.0 )
See doc/classes/MeshInstance3D.xml:76-80, 82-87, 109-115
Skeletal Animation For animated characters:
# Link mesh to skeleton mesh_instance . skeleton = NodePath ( "../Skeleton3D" ) # Set skin resource mesh_instance . skin = preload ( "res://models/character_skin.tres" )
See doc/classes/MeshInstance3D.xml:131-134, 135-137
Creating Collision Shapes Generate physics collision from mesh geometry:
# Simple convex collision mesh_instance . create_convex_collision () # Multiple convex shapes (better for complex meshes) mesh_instance . create_multiple_convex_collisions () # Concave collision (for static geometry) mesh_instance . create_trimesh_collision ()
See doc/classes/MeshInstance3D.xml:32-40, 48-53, 55-59
Material Optimization Tips
Combine multiple textures into one atlas to reduce draw calls: # Instead of many small textures, use one large atlas mat . albedo_texture = preload ( "res://textures/atlas.png" ) mat . uv1_scale = Vector3 ( 0.25 , 0.25 , 1.0 ) # Use 1/4 of atlas
Only enable material features you actually use: # Don't enable features you don't need mat . normal_enabled = false # If no normal map mat . emission_enabled = false # If not glowing
Use ORMMaterial3D for Packed Textures
When you have ORM-packed textures, use ORMMaterial3D: var mat = ORMMaterial3D . new () mat . orm_texture = preload ( "res://textures/orm_packed.png" )
Use appropriate texture resolutions:
Small objects: 512x512 or 1024x1024
Medium objects: 2048x2048
Large objects/terrain: 4096x4096
Common Material Recipes var metal = StandardMaterial3D . new () metal . albedo_color = Color ( 0.8 , 0.8 , 0.8 ) metal . metallic = 1.0 metal . roughness = 0.2
Rough Wood var wood = StandardMaterial3D . new () wood . albedo_texture = preload ( "res://textures/wood_color.png" ) wood . normal_enabled = true wood . normal_texture = preload ( "res://textures/wood_normal.png" ) wood . metallic = 0.0 wood . roughness = 0.8
Glowing Emissive var glow = StandardMaterial3D . new () glow . albedo_color = Color . BLACK glow . emission_enabled = true glow . emission = Color ( 0.0 , 1.0 , 0.0 ) glow . emission_energy_multiplier = 3.0
Transparent Glass var glass = StandardMaterial3D . new () glass . transparency = BaseMaterial3D . TRANSPARENCY_ALPHA glass . albedo_color = Color ( 0.9 , 0.9 , 1.0 , 0.3 ) glass . metallic = 0.0 glass . roughness = 0.0 glass . refraction_enabled = true glass . refraction_scale = 0.05
Debugging Meshes # Create debug tangent visualization mesh_instance . create_debug_tangents () # Check mesh validity if mesh_instance . mesh : print ( "Mesh loaded: " , mesh_instance . mesh . resource_name ) print ( "Surface count: " , mesh_instance . mesh . get_surface_count ()) else : push_error ( "No mesh assigned!" )
See doc/classes/MeshInstance3D.xml:42-46
3D Overview Learn 3D fundamentals
Lighting Illuminate your 3D scenes
Physics Add collision and physics
Shaders Write custom shaders
Resources 