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

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.

Transparency TRANSPARENCY_ALPHA = 1

The material will use the texture's alpha values for transparency.

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.

Transparency TRANSPARENCY_ALPHA_HASH = 3

The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque.

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.

Transparency TRANSPARENCY_MAX = 5

Represents the size of the Transparency enum.


enum ShadingMode:

ShadingMode SHADING_MODE_UNSHADED = 0

The object will not receive shadows.

ShadingMode SHADING_MODE_PER_PIXEL = 1

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

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.

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 culling is performed.


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 Vulkan Clustered or Vulkan Mobile backends.

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.