Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

BaseMaterial3D

Inherits: Material < Resource < RefCounted < Object

Inherited By: ORMMaterial3D, StandardMaterial3D

Default 3D rendering material.

Description

This provides a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details.

Tutorials

• Standard Material 3D

Properties

Color	albedo_color	Color(1, 1, 1, 1)
Texture2D	albedo_texture
bool	albedo_texture_force_srgb	false
bool	albedo_texture_msdf	false
float	alpha_antialiasing_edge
AlphaAntiAliasing	alpha_antialiasing_mode
float	alpha_hash_scale
float	alpha_scissor_threshold
float	anisotropy	0.0
bool	anisotropy_enabled	false
Texture2D	anisotropy_flowmap
bool	ao_enabled	false
float	ao_light_affect	0.0
bool	ao_on_uv2	false
Texture2D	ao_texture
TextureChannel	ao_texture_channel	0
Color	backlight	Color(0, 0, 0, 1)
bool	backlight_enabled	false
Texture2D	backlight_texture
bool	billboard_keep_scale	false
BillboardMode	billboard_mode	0
BlendMode	blend_mode	0
float	clearcoat	1.0
bool	clearcoat_enabled	false
float	clearcoat_roughness	0.5
Texture2D	clearcoat_texture
CullMode	cull_mode	0
DepthDrawMode	depth_draw_mode	0
Texture2D	detail_albedo
BlendMode	detail_blend_mode	0
bool	detail_enabled	false
Texture2D	detail_mask
Texture2D	detail_normal
DetailUV	detail_uv_layer	0
DiffuseMode	diffuse_mode	0
bool	disable_ambient_light	false
bool	disable_receive_shadows	false
float	distance_fade_max_distance	10.0
float	distance_fade_min_distance	0.0
DistanceFadeMode	distance_fade_mode	0
Color	emission	Color(0, 0, 0, 1)
bool	emission_enabled	false
float	emission_energy_multiplier	1.0
float	emission_intensity
bool	emission_on_uv2	false
EmissionOperator	emission_operator	0
Texture2D	emission_texture
bool	fixed_size	false
bool	grow	false
float	grow_amount	0.0
bool	heightmap_deep_parallax	false
bool	heightmap_enabled	false
bool	heightmap_flip_binormal	false
bool	heightmap_flip_tangent	false
bool	heightmap_flip_texture	false
int	heightmap_max_layers
int	heightmap_min_layers
float	heightmap_scale	5.0
Texture2D	heightmap_texture
float	metallic	0.0
float	metallic_specular	0.5
Texture2D	metallic_texture
TextureChannel	metallic_texture_channel	0
float	msdf_outline_size	0.0
float	msdf_pixel_range	4.0
bool	no_depth_test	false
bool	normal_enabled	false
float	normal_scale	1.0
Texture2D	normal_texture
Texture2D	orm_texture
int	particles_anim_h_frames
bool	particles_anim_loop
int	particles_anim_v_frames
float	point_size	1.0
float	proximity_fade_distance	1.0
bool	proximity_fade_enabled	false
bool	refraction_enabled	false
float	refraction_scale	0.05
Texture2D	refraction_texture
TextureChannel	refraction_texture_channel	0
float	rim	1.0
bool	rim_enabled	false
Texture2D	rim_texture
float	rim_tint	0.5
float	roughness	1.0
Texture2D	roughness_texture
TextureChannel	roughness_texture_channel	0
ShadingMode	shading_mode	1
bool	shadow_to_opacity	false
SpecularMode	specular_mode	0
bool	subsurf_scatter_enabled	false
bool	subsurf_scatter_skin_mode	false
float	subsurf_scatter_strength	0.0
Texture2D	subsurf_scatter_texture
float	subsurf_scatter_transmittance_boost	0.0
Color	subsurf_scatter_transmittance_color	Color(1, 1, 1, 1)
float	subsurf_scatter_transmittance_depth	0.1
bool	subsurf_scatter_transmittance_enabled	false
Texture2D	subsurf_scatter_transmittance_texture
TextureFilter	texture_filter	3
bool	texture_repeat	true
Transparency	transparency	0
bool	use_particle_trails	false
bool	use_point_size	false
Vector3	uv1_offset	Vector3(0, 0, 0)
Vector3	uv1_scale	Vector3(1, 1, 1)
bool	uv1_triplanar	false
float	uv1_triplanar_sharpness	1.0
bool	uv1_world_triplanar	false
Vector3	uv2_offset	Vector3(0, 0, 0)
Vector3	uv2_scale	Vector3(1, 1, 1)
bool	uv2_triplanar	false
float	uv2_triplanar_sharpness	1.0
bool	uv2_world_triplanar	false
bool	vertex_color_is_srgb	false
bool	vertex_color_use_as_albedo	false

Methods

bool	get_feature ( Feature feature ) const
bool	get_flag ( Flags flag ) const
Texture2D	get_texture ( TextureParam param ) const
void	set_feature ( Feature feature, bool enable )
void	set_flag ( Flags flag, bool enable )
void	set_texture ( TextureParam param, Texture2D texture )

---

Enumerations

enum TextureParam:

TextureParam TEXTURE_ALBEDO = 0

Texture specifying per-pixel color.

TextureParam TEXTURE_METALLIC = 1

Texture specifying per-pixel metallic value.

TextureParam TEXTURE_ROUGHNESS = 2

Texture specifying per-pixel roughness value.

TextureParam TEXTURE_EMISSION = 3

Texture specifying per-pixel emission color.

TextureParam TEXTURE_NORMAL = 4

Texture specifying per-pixel normal vector.

TextureParam TEXTURE_RIM = 5

Texture specifying per-pixel rim value.

TextureParam TEXTURE_CLEARCOAT = 6

Texture specifying per-pixel clearcoat value.

TextureParam TEXTURE_FLOWMAP = 7

Texture specifying per-pixel flowmap direction for use with anisotropy.

TextureParam TEXTURE_AMBIENT_OCCLUSION = 8

Texture specifying per-pixel ambient occlusion value.

TextureParam TEXTURE_HEIGHTMAP = 9

Texture specifying per-pixel height.

TextureParam TEXTURE_SUBSURFACE_SCATTERING = 10

Texture specifying per-pixel subsurface scattering.

TextureParam TEXTURE_SUBSURFACE_TRANSMITTANCE = 11

Texture specifying per-pixel transmittance for subsurface scattering.

TextureParam TEXTURE_BACKLIGHT = 12

Texture specifying per-pixel backlight color.

TextureParam TEXTURE_REFRACTION = 13

Texture specifying per-pixel refraction strength.

TextureParam TEXTURE_DETAIL_MASK = 14

Texture specifying per-pixel detail mask blending value.

TextureParam TEXTURE_DETAIL_ALBEDO = 15

Texture specifying per-pixel detail color.

TextureParam TEXTURE_DETAIL_NORMAL = 16

Texture specifying per-pixel detail normal.

TextureParam TEXTURE_ORM = 17

Texture holding ambient occlusion, roughness, and metallic.

TextureParam TEXTURE_MAX = 18

Represents the size of the TextureParam enum.

---

enum TextureFilter:

TextureFilter TEXTURE_FILTER_NEAREST = 0

The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized.

TextureFilter TEXTURE_FILTER_LINEAR = 1

The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps.

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 2

The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 3

The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera.

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 4

The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 5

The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.

TextureFilter TEXTURE_FILTER_MAX = 6

Represents the size of the TextureFilter enum.

---

enum DetailUV:

DetailUV DETAIL_UV_1 = 0

Use UV with the detail texture.

DetailUV DETAIL_UV_2 = 1

Use UV2 with the detail texture.

---

enum Transparency:

Transparency TRANSPARENCY_DISABLED = 0

The material will not use transparency. This is the fastest to render.

Transparency TRANSPARENCY_ALPHA = 1

The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting.

Transparency TRANSPARENCY_ALPHA_SCISSOR = 2

The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows.

Transparency TRANSPARENCY_ALPHA_HASH = 3

The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering.

Transparency TRANSPARENCY_ALPHA_DEPTH_PRE_PASS = 4

The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows.

Transparency TRANSPARENCY_MAX = 5

Represents the size of the Transparency enum.

---

enum ShadingMode:

ShadingMode SHADING_MODE_UNSHADED = 0

The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights.

ShadingMode SHADING_MODE_PER_PIXEL = 1

The object will be shaded per pixel. Useful for realistic shading effects.

ShadingMode SHADING_MODE_PER_VERTEX = 2

The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like SHADING_MODE_PER_PIXEL).

ShadingMode SHADING_MODE_MAX = 3

Represents the size of the ShadingMode enum.

---

enum Feature:

Feature FEATURE_EMISSION = 0

Constant for setting emission_enabled.

Feature FEATURE_NORMAL_MAPPING = 1

Constant for setting normal_enabled.

Feature FEATURE_RIM = 2

Constant for setting rim_enabled.

Feature FEATURE_CLEARCOAT = 3

Constant for setting clearcoat_enabled.

Feature FEATURE_ANISOTROPY = 4

Constant for setting anisotropy_enabled.

Feature FEATURE_AMBIENT_OCCLUSION = 5

Constant for setting ao_enabled.

Feature FEATURE_HEIGHT_MAPPING = 6

Constant for setting heightmap_enabled.

Feature FEATURE_SUBSURFACE_SCATTERING = 7

Constant for setting subsurf_scatter_enabled.

Feature FEATURE_SUBSURFACE_TRANSMITTANCE = 8

Constant for setting subsurf_scatter_transmittance_enabled.

Feature FEATURE_BACKLIGHT = 9

Constant for setting backlight_enabled.

Feature FEATURE_REFRACTION = 10

Constant for setting refraction_enabled.

Feature FEATURE_DETAIL = 11

Constant for setting detail_enabled.

Feature FEATURE_MAX = 12

Represents the size of the Feature enum.

---

enum BlendMode:

BlendMode BLEND_MODE_MIX = 0

Default blend mode. The color of the object is blended over the background based on the object's alpha value.

BlendMode BLEND_MODE_ADD = 1

The color of the object is added to the background.

BlendMode BLEND_MODE_SUB = 2

The color of the object is subtracted from the background.

BlendMode BLEND_MODE_MUL = 3

The color of the object is multiplied by the background.

---

enum AlphaAntiAliasing:

AlphaAntiAliasing ALPHA_ANTIALIASING_OFF = 0

Disables Alpha AntiAliasing for the material.

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE = 1

Enables AlphaToCoverage. Alpha values in the material are passed to the AntiAliasing sample mask.

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE = 2

Enables AlphaToCoverage and forces all non-zero alpha values to 1. Alpha values in the material are passed to the AntiAliasing sample mask.

---

enum DepthDrawMode:

DepthDrawMode DEPTH_DRAW_OPAQUE_ONLY = 0

Default depth draw mode. Depth is drawn only for opaque objects during the opaque prepass (if any) and during the opaque pass.

DepthDrawMode DEPTH_DRAW_ALWAYS = 1

Objects will write to depth during the opaque and the transparent passes. Transparent objects that are close to the camera may obscure other transparent objects behind them.

Note: This does not influence whether transparent objects are included in the depth prepass or not. For that, see Transparency.

DepthDrawMode DEPTH_DRAW_DISABLED = 2

Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled).

---

enum CullMode:

CullMode CULL_BACK = 0

Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible.

CullMode CULL_FRONT = 1

Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior.

CullMode CULL_DISABLED = 2

No face culling is performed; both the front face and back face will be visible.

---

enum Flags:

Flags FLAG_DISABLE_DEPTH_TEST = 0

Disables the depth test, so this object is drawn on top of all others drawn before it. This puts the object in the transparent draw pass where it is sorted based on distance to camera. Objects drawn after it in the draw order may cover it. This also disables writing to depth.

Flags FLAG_ALBEDO_FROM_VERTEX_COLOR = 1

Set ALBEDO to the per-vertex color specified in the mesh.

Flags FLAG_SRGB_VERTEX_COLOR = 2

Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also vertex_color_is_srgb.

Note: Only effective when using the Forward+ and Mobile rendering methods.

Flags FLAG_USE_POINT_SIZE = 3

Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use POINT_COORD instead of UV.

Flags FLAG_FIXED_SIZE = 4

Object is scaled by depth so that it always appears the same size on screen.

Flags FLAG_BILLBOARD_KEEP_SCALE = 5

Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when billboard_mode is BILLBOARD_ENABLED.

Flags FLAG_UV1_USE_TRIPLANAR = 6

Use triplanar texture lookup for all texture lookups that would normally use UV.

Flags FLAG_UV2_USE_TRIPLANAR = 7

Use triplanar texture lookup for all texture lookups that would normally use UV2.

Flags FLAG_UV1_USE_WORLD_TRIPLANAR = 8

Use triplanar texture lookup for all texture lookups that would normally use UV.

Flags FLAG_UV2_USE_WORLD_TRIPLANAR = 9

Use triplanar texture lookup for all texture lookups that would normally use UV2.

Flags FLAG_AO_ON_UV2 = 10

Use UV2 coordinates to look up from the ao_texture.

Flags FLAG_EMISSION_ON_UV2 = 11

Use UV2 coordinates to look up from the emission_texture.

Flags FLAG_ALBEDO_TEXTURE_FORCE_SRGB = 12

Forces the shader to convert albedo from sRGB space to linear space. See also albedo_texture_force_srgb.

Flags FLAG_DONT_RECEIVE_SHADOWS = 13

Disables receiving shadows from other objects.

Flags FLAG_DISABLE_AMBIENT_LIGHT = 14

Disables receiving ambient light.

Flags FLAG_USE_SHADOW_TO_OPACITY = 15

Enables the shadow to opacity feature.

Flags FLAG_USE_TEXTURE_REPEAT = 16

Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture.

Flags FLAG_INVERT_HEIGHTMAP = 17

Invert values read from a depth texture to convert them to height values (heightmap).

Flags FLAG_SUBSURFACE_MODE_SKIN = 18

Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin.

Flags FLAG_PARTICLE_TRAILS_MODE = 19

Enables parts of the shader required for GPUParticles3D trails to function. This also requires using a mesh with appropriate skinning, such as RibbonTrailMesh or TubeTrailMesh. Enabling this feature outside of materials used in GPUParticles3D meshes will break material rendering.

Flags FLAG_ALBEDO_TEXTURE_MSDF = 20

Enables multichannel signed distance field rendering shader.

Flags FLAG_MAX = 21

Represents the size of the Flags enum.

---

enum DiffuseMode:

DiffuseMode DIFFUSE_BURLEY = 0

Default diffuse scattering algorithm.

DiffuseMode DIFFUSE_LAMBERT = 1

Diffuse scattering ignores roughness.

DiffuseMode DIFFUSE_LAMBERT_WRAP = 2

Extends Lambert to cover more than 90 degrees when roughness increases.

DiffuseMode DIFFUSE_TOON = 3

Uses a hard cut for lighting, with smoothing affected by roughness.

---

enum SpecularMode:

SpecularMode SPECULAR_SCHLICK_GGX = 0

Default specular blob.

SpecularMode SPECULAR_TOON = 1

Toon blob which changes size based on roughness.

SpecularMode SPECULAR_DISABLED = 2

No specular blob. This is slightly faster to render than other specular modes.

---

enum BillboardMode:

BillboardMode BILLBOARD_DISABLED = 0

Billboard mode is disabled.