Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

BaseMaterial3D

繼承: Material < Resource < RefCounted < Object

被繼承: ORMMaterial3D, StandardMaterial3D

用於定義網格 3D 渲染屬性的抽象基底類別。

說明

此類別提供一個預設材質,具備多種渲染功能與屬性,無須撰寫著色器程式。詳情請見下方教學。

教學

屬性

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

bent_normal_enabled

false

Texture2D

bent_normal_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

DepthTest

depth_test

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_fog

false

bool

disable_receive_shadows

false

bool

disable_specular_occlusion

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

float

fov_override

75.0

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

bool

particles_anim_enabled

false

int

particles_anim_h_frames

1

bool

particles_anim_loop

false

int

particles_anim_v_frames

1

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

Color

stencil_color

Color(0, 0, 0, 1)

StencilCompare

stencil_compare

0

int

stencil_flags

0

StencilMode

stencil_mode

0

float

stencil_outline_thickness

0.01

int

stencil_reference

1

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_fov_override

false

bool

use_particle_trails

false

bool

use_point_size

false

bool

use_z_clip_scale

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

float

z_clip_scale

1.0

方法

bool

get_feature(feature: Feature) const

bool

get_flag(flag: Flags) const

Texture2D

get_texture(param: TextureParam) const

void

set_feature(feature: Feature, enable: bool)

void

set_flag(flag: Flags, enable: bool)

void

set_texture(param: TextureParam, texture: Texture2D)


列舉

enum TextureParam: 🔗

TextureParam TEXTURE_ALBEDO = 0

指定每圖元顏色的紋理。

TextureParam TEXTURE_METALLIC = 1

指定每圖元金屬度的紋理。

TextureParam TEXTURE_ROUGHNESS = 2

指定每圖元粗糙度的紋理。

TextureParam TEXTURE_EMISSION = 3

指定每圖元自發光顏色的紋理。

TextureParam TEXTURE_NORMAL = 4

指定每圖元法向量的紋理。

TextureParam TEXTURE_BENT_NORMAL = 18

指定每圖元彎曲法向量的紋理。

TextureParam TEXTURE_RIM = 5

指定每圖元邊緣光值的紋理。

TextureParam TEXTURE_CLEARCOAT = 6

指定每圖元透明漆(Clearcoat)值的紋理。

TextureParam TEXTURE_FLOWMAP = 7

指定每圖元流向,用於 anisotropy 的紋理。

TextureParam TEXTURE_AMBIENT_OCCLUSION = 8

指定每圖元環境遮蔽值的紋理。

TextureParam TEXTURE_HEIGHTMAP = 9

指定每圖元高度的紋理。

TextureParam TEXTURE_SUBSURFACE_SCATTERING = 10

指定每圖元次表面散射的紋理。

TextureParam TEXTURE_SUBSURFACE_TRANSMITTANCE = 11

指定每圖元次表面散射透射率的紋理。

TextureParam TEXTURE_BACKLIGHT = 12

指定每圖元背光顏色的紋理。

TextureParam TEXTURE_REFRACTION = 13

指定每圖元折射強度的紋理。

TextureParam TEXTURE_DETAIL_MASK = 14

指定每圖元細節遮罩混合值的紋理。

TextureParam TEXTURE_DETAIL_ALBEDO = 15

指定每圖元細節顏色的紋理。

TextureParam TEXTURE_DETAIL_NORMAL = 16

指定每圖元細節法線的紋理。

TextureParam TEXTURE_ORM = 17

同時存有環境遮蔽、粗糙度與金屬度的紋理。

TextureParam TEXTURE_MAX = 19

代表 TextureParam 列舉的大小。


enum TextureFilter: 🔗

TextureFilter TEXTURE_FILTER_NEAREST = 0

紋理僅取最鄰近像素,近看呈現馬賽克,遠處因未取樣 mipmap 而顯得顆粒。

TextureFilter TEXTURE_FILTER_LINEAR = 1

紋理在最鄰近 4 像素間插值,近看平滑,遠處因未取樣 mipmap 仍顆粒。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 2

紋理取最鄰近像素,並在兩層最鄰近的 mipmap 間插值(或僅取最近 mipmap,取決於 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter)。近看仍帶像素感,遠處則較平滑。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 3

紋理過濾在最近的 4 個像素和最近的 2 個多級漸遠紋理之間進行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 為 true,則使用最近的多級漸遠紋理)。這使得紋理從近處看起來平滑,從遠處看起來也平滑。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 4

紋理過濾從最近的像素讀取並根據表面和相機檢視之間的角度在 2 個多級漸遠紋理之間進行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 為 true,則使用最近的多級漸遠紋理)。這使得紋理從近處看起來像素化,從遠處看起來平滑。各向異性過濾提高了幾乎與相機位於一條線上的表面上的紋理品質,但速度稍慢。各向異性過濾層級可以通過調整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 來改變。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 5

紋理過濾在最近的 4 個像素之間進行混合,並基於表面與相機檢視之間的角度在 2 個多級漸遠紋理之間進行混合 (或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 為 true,則使用最近的多級漸遠紋理)。這使得紋理從近處看起來平滑,從遠處看起來也平滑。各向異性過濾提高了幾乎與相機位於一條線的表面上的紋理品質,但速度稍慢。各向異性過濾層級可以通過調整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 來改變。

TextureFilter TEXTURE_FILTER_MAX = 6

代表 TextureFilter 列舉的大小。


enum DetailUV: 🔗

DetailUV DETAIL_UV_1 = 0

使用 UV 與細節紋理。

DetailUV DETAIL_UV_2 = 1

使用 UV2 與細節紋理。


enum Transparency: 🔗

Transparency TRANSPARENCY_DISABLED = 0

該材質將不使用透明度。渲染最快。

Transparency TRANSPARENCY_ALPHA = 1

該材質將使用紋理的 Alpha 值作為透明度。渲染最慢,並會停用陰影投射。

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. For textures using this mode see the Preserve Alpha Test Coverage option in the texture import settings to improve distant rendering and popping.

Transparency TRANSPARENCY_ALPHA_HASH = 3

該材質會將所有低於空間確定性閾值的值截斷,其餘部分保持不透明。這比 Alpha 混合快,但比完全不透明稍慢,並支援投射陰影。Alpha 雜湊適合於頭髮渲染。

Transparency TRANSPARENCY_ALPHA_DEPTH_PRE_PASS = 4

該材質將使用紋理的 Alpha 值作為透明度,但在深度預通道階段會丟棄 Alpha 小於 0.99 的片段,在陰影通道期間丟棄 Alpha 小於 0.1 的片段。支援投射陰影。

Transparency TRANSPARENCY_MAX = 5

代表 Transparency 列舉的大小。


enum ShadingMode: 🔗

ShadingMode SHADING_MODE_UNSHADED = 0

該物件不會接收陰影。渲染速度最快,但會停用與光源的所有互動。

ShadingMode SHADING_MODE_PER_PIXEL = 1

物件將逐圖元著色,適用於需要寫實光照效果的情況。

ShadingMode SHADING_MODE_PER_VERTEX = 2

物件將逐頂點著色。當你需要較省效能的著色器且不在意畫質時很實用。

ShadingMode SHADING_MODE_MAX = 3

代表 ShadingMode 列舉的大小。


enum Feature: 🔗

Feature FEATURE_EMISSION = 0

用於設定 emission_enabled 的常數。

Feature FEATURE_NORMAL_MAPPING = 1

用於設定 normal_enabled 的常數。

Feature FEATURE_RIM = 2

用於設定 rim_enabled 的常數。

Feature FEATURE_CLEARCOAT = 3

用於設定 clearcoat_enabled 的常數。

Feature FEATURE_ANISOTROPY = 4

用於設定 anisotropy_enabled 的常數。

Feature FEATURE_AMBIENT_OCCLUSION = 5

用於設定 ao_enabled 的常數。

Feature FEATURE_HEIGHT_MAPPING = 6

用於設定 heightmap_enabled 的常數。

Feature FEATURE_SUBSURFACE_SCATTERING = 7

用於設定 subsurf_scatter_enabled 的常數。

Feature FEATURE_SUBSURFACE_TRANSMITTANCE = 8

用於設定 subsurf_scatter_transmittance_enabled 的常數。

Feature FEATURE_BACKLIGHT = 9

用於設定 backlight_enabled 的常數。

Feature FEATURE_REFRACTION = 10

用於設定 refraction_enabled 的常數。

Feature FEATURE_DETAIL = 11

用於設定 detail_enabled 的常數。

Feature FEATURE_BENT_NORMAL_MAPPING = 12

用於設定 bent_normal_enabled 的常數。

Feature FEATURE_PARTICLES_ANIMATION = 13

Constant for setting particles_anim_enabled.

Feature FEATURE_MAX = 14

代表 Feature 列舉的大小。


enum BlendMode: 🔗

BlendMode BLEND_MODE_MIX = 0

預設混合模式。依物件的 Alpha 值,將其顏色混到背景上。

BlendMode BLEND_MODE_ADD = 1

物件的顏色加算到背景中。

BlendMode BLEND_MODE_SUB = 2

從背景中減去物件的顏色。

BlendMode BLEND_MODE_MUL = 3

物件的顏色與背景相乘。

BlendMode BLEND_MODE_PREMULT_ALPHA = 4

物件的顏色會加算到背景,並以 Alpha 通道遮罩背景。此模式結合了混合與加算,適合如火焰般希望火苗加亮、煙霧則正常混合的效果。預設可搭配未著色材質和預乘 (Premultiplied) 紋理使用;若材質有光照,請在著色器中使用 PREMUL_ALPHA_FACTOR 以同時調整光照。


enum AlphaAntiAliasing: 🔗

AlphaAntiAliasing ALPHA_ANTIALIASING_OFF = 0

停用此材質的 Alpha 反鋸齒。

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE = 1

啟用 AlphaToCoverage。材質中的 Alpha 值會傳遞到反鋸齒取樣遮罩中。

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE = 2

啟用 AlphaToCoverage,並將所有非零 Alpha 值強制為 1。材質中的 Alpha 值會傳遞到反鋸齒取樣遮罩中。


enum DepthDrawMode: 🔗

DepthDrawMode DEPTH_DRAW_OPAQUE_ONLY = 0

預設深度繪製模式:僅在不透明預通道(若啟用)與不透明主通道期間,為不透明物件寫入深度。

DepthDrawMode DEPTH_DRAW_ALWAYS = 1

物件會在不透明與透明通道皆寫入深度。靠近相機的透明物件可能遮蔽後方的其他透明物件。

注意:此設定不影響透明物件是否參與深度預通道,相關設定請見 Transparency。

DepthDrawMode DEPTH_DRAW_DISABLED = 2

物件不會將深度寫入深度緩衝,包含已啟用的深度預通道階段。


enum DepthTest: 🔗

DepthTest DEPTH_TEST_DEFAULT = 0

深度測試會丟棄位於其他像素後面的像素。

DepthTest DEPTH_TEST_INVERTED = 1

深度測試會丟棄位於其他像素前面的像素。適用於範本效果。


enum CullMode: 🔗

CullMode CULL_BACK = 0

預設剔除模式:背面在不可見時被剔除。面向相機時會剔除背面三角形,因此僅繪製正面。對封閉網格而言,只有外表面可見。

CullMode CULL_FRONT = 1

面向相機時會剔除正面三角形,因此僅繪製背面。對封閉網格而言,將看到其內部而非外部。

CullMode CULL_DISABLED = 2

不進行面剔除;正反面皆可見。


enum Flags: 🔗

Flags FLAG_DISABLE_DEPTH_TEST = 0

停用深度測試,該物件會被繪製在之前所有內容之上,並進入透明通道以與其他物件依距離排序。之後繪製的物件仍可能蓋過它,同時也不會寫入深度。

Flags FLAG_ALBEDO_FROM_VERTEX_COLOR = 1

將 ALBEDO 設為網格內的每頂點顏色。

Flags FLAG_SRGB_VERTEX_COLOR = 2

頂點顏色被認為以非線性 sRGB 編碼儲存,並在渲染期間轉換為線性編碼。另見 vertex_color_is_srgb。

注意:僅在使用 Forward+ 和移動渲染方式時有效。

Flags FLAG_USE_POINT_SIZE = 3

使用點大小調整圖元點尺寸,並將反照率紋理取樣由 UV 改為 POINT_COORD。

Flags FLAG_FIXED_SIZE = 4

依深度縮放,使物件在畫面上大小恆定。

Flags FLAG_BILLBOARD_KEEP_SCALE = 5

著色器會保留網格原有縮放,否則做公告板時縮放會遺失。僅於 billboard_mode 設為 BILLBOARD_ENABLED 時適用。

Flags FLAG_UV1_USE_TRIPLANAR = 6

將所有原本以 UV 取樣的紋理改為三平面取樣。

Flags FLAG_UV2_USE_TRIPLANAR = 7

將所有原本以 UV2 取樣的紋理改為三平面取樣。

Flags FLAG_UV1_USE_WORLD_TRIPLANAR = 8

將所有原本以 UV 取樣的紋理改為三平面取樣。

Flags FLAG_UV2_USE_WORLD_TRIPLANAR = 9

將所有原本以 UV2 取樣的紋理改為三平面取樣。

Flags FLAG_AO_ON_UV2 = 10

使用 UV2 座標取樣 ao_texture。

Flags FLAG_EMISSION_ON_UV2 = 11

使用 UV2 座標取樣 emission_texture。

Flags FLAG_ALBEDO_TEXTURE_FORCE_SRGB = 12

強制著色器將反照率從非線性 sRGB 編碼轉換為線性編碼。另見 albedo_texture_force_srgb。

Flags FLAG_DONT_RECEIVE_SHADOWS = 13

停用接收其他物件的陰影。

Flags FLAG_DISABLE_AMBIENT_LIGHT = 14

停用接收環境光。

Flags FLAG_USE_SHADOW_TO_OPACITY = 15

啟用「陰影轉不透明度」功能。

Flags FLAG_USE_TEXTURE_REPEAT = 16

當 UV 超出 0–1 時允許紋理重複。如果使用線性過濾模式,取樣器跨越紋理邊界時可能在邊緣產生偽影。

Flags FLAG_INVERT_HEIGHTMAP = 17

反轉從深度紋理讀取的值,將其轉為高度值(高度圖)。

Flags FLAG_SUBSURFACE_MODE_SKIN = 18

啟用「皮膚模式」以改進用於人體皮膚時的次表面散射效果。

Flags FLAG_PARTICLE_TRAILS_MODE = 19

啟用 GPUParticles3D 尾跡所需的著色器部分。需配合具蒙皮的網格(如 RibbonTrailMesh、TubeTrailMesh)。若在非 GPUParticles3D 材質上啟用,將導致渲染錯誤。

Flags FLAG_ALBEDO_TEXTURE_MSDF = 20

啟用多通道 SDF(Signed Distance Field)渲染著色器。

Flags FLAG_DISABLE_FOG = 21

停用接收深度式或體積式霧效。

Flags FLAG_DISABLE_SPECULAR_OCCLUSION = 22

停用鏡面遮蔽。

Flags FLAG_USE_Z_CLIP_SCALE = 23

啟用 z_clip_scale。

Flags FLAG_USE_FOV_OVERRIDE = 24

啟用 fov_override。

Flags FLAG_MAX = 25

代表 Flags 列舉的大小。


enum DiffuseMode: 🔗

DiffuseMode DIFFUSE_BURLEY = 0

預設漫反射散射演算法。

DiffuseMode DIFFUSE_LAMBERT = 1

漫散射忽略粗糙度。

DiffuseMode DIFFUSE_LAMBERT_WRAP = 2

在粗糙度增大時,將 Lambert 延伸至超過 90°。

DiffuseMode DIFFUSE_TOON = 3

使用硬斷差的光照,平滑度受粗糙度影響。


enum SpecularMode: 🔗

SpecularMode SPECULAR_SCHLICK_GGX = 0

預設鏡面斑點。

注意:Forward+ 會使用多重散射以獲得更精確的反射,其影響在粗糙金屬表面尤為明顯。

注意:Mobile 與 Compatibility 管線為了效能僅做單次散射,因此粗糙金屬表面可能會略暗。

SpecularMode SPECULAR_TOON = 1

依粗糙度改變大小的 Toon 鏡面斑點。

SpecularMode SPECULAR_DISABLED = 2

無鏡面斑點,比其他鏡面模式稍快。


enum BillboardMode: 🔗

BillboardMode BILLBOARD_DISABLED = 0

已停用公告板模式。

BillboardMode BILLBOARD_ENABLED = 1

物件的 Z 軸永遠朝向相機。

BillboardMode BILLBOARD_FIXED_Y = 2

物件的 X 軸永遠朝向相機。

BillboardMode BILLBOARD_PARTICLES = 3

Used for particle systems when assigned to GPUParticles3D and CPUParticles3D nodes (flipbook animation). Enables particles_anim_* properties.

The ParticleProcessMaterial.anim_speed_min or CPUParticles3D.anim_speed_min should also be set to a value bigger than zero for the animation to play.

For animations without bilboarding, see particles_anim_enabled.


enum TextureChannel: 🔗

TextureChannel TEXTURE_CHANNEL_RED = 0

讀取紋理的紅色通道。

TextureChannel TEXTURE_CHANNEL_GREEN = 1

讀取紋理的綠色通道。

TextureChannel TEXTURE_CHANNEL_BLUE = 2

讀取紋理的藍色通道。

TextureChannel TEXTURE_CHANNEL_ALPHA = 3

讀取紋理的 Alpha 通道。

TextureChannel TEXTURE_CHANNEL_GRAYSCALE = 4

讀取紋理 R、G、B 通道的線性(非感知)平均值。


enum EmissionOperator: 🔗

EmissionOperator EMISSION_OP_ADD = 0

將自發光顏色加到自發光紋理顏色上。

EmissionOperator EMISSION_OP_MULTIPLY = 1

將自發光顏色乘以自發光紋理顏色。


enum DistanceFadeMode: 🔗

DistanceFadeMode DISTANCE_FADE_DISABLED = 0

不使用距離淡化。

DistanceFadeMode DISTANCE_FADE_PIXEL_ALPHA = 1

依各像素與相機的距離,用 Alpha 通道平滑淡出物件。

DistanceFadeMode DISTANCE_FADE_PIXEL_DITHER = 2

依各像素與相機的距離,透過抖動方式平滑淡出。抖動依固定圖樣丟棄像素,達到無需透明即可淡出的效果,在部分硬體上比 DISTANCE_FADE_PIXEL_ALPHA 更快。

DistanceFadeMode DISTANCE_FADE_OBJECT_DITHER = 3

依物件與相機的距離,以抖動方式平滑淡出。抖動依固定圖樣丟棄像素,可在不啟用透明的情況下淡出;在某些硬體上比 DISTANCE_FADE_PIXEL_ALPHA 與 DISTANCE_FADE_PIXEL_DITHER 更快。


enum StencilMode: 🔗

StencilMode STENCIL_MODE_DISABLED = 0

停用範本運算。

StencilMode STENCIL_MODE_OUTLINE = 1

範本預設,為物體新增輪廓。

注意:需要自動應用 Material.next_pass 材質。修改範本屬性或重新載入場景時,對 Material.next_pass 的手動更改會丟失。要安全地對使用範本預設的材質應用 Material.next_pass 材質,請改用 GeometryInstance3D.material_overlay。

StencilMode STENCIL_MODE_XRAY = 2

範本預設,為牆後的物體顯示剪影。

注意:需要自動應用 Material.next_pass 材質。修改範本屬性或重新載入場景時,對 Material.next_pass 的手動更改會丟失。要安全地對使用範本預設的材質應用 Material.next_pass 材質,請改用 GeometryInstance3D.material_overlay。

StencilMode STENCIL_MODE_CUSTOM = 3

啟用範本運算,但不使用預設。


enum StencilFlags: 🔗

StencilFlags STENCIL_FLAG_READ = 1

材質僅當其通過與現有範本緩衝區值的範本比較時才會被渲染。

StencilFlags STENCIL_FLAG_WRITE = 2

材質通過深度測試時會將參考值寫入範本緩衝區。

StencilFlags STENCIL_FLAG_WRITE_DEPTH_FAIL = 4

材質未通過深度測試時會將參考值寫入範本緩衝區。


enum StencilCompare: 🔗

StencilCompare STENCIL_COMPARE_ALWAYS = 0

始終通過範本測試。

StencilCompare STENCIL_COMPARE_LESS = 1

當參考值小於現有範本值時,通過範本測試。

StencilCompare STENCIL_COMPARE_EQUAL = 2

當參考值等於現有範本值時,通過範本測試。

StencilCompare STENCIL_COMPARE_LESS_OR_EQUAL = 3

當參考值小於或等於現有範本值時,通過範本測試。

StencilCompare STENCIL_COMPARE_GREATER = 4

當參考值大於現有範本值時,通過範本測試。

StencilCompare STENCIL_COMPARE_NOT_EQUAL = 5

當參考值不等於現有範本值時,通過範本測試。

StencilCompare STENCIL_COMPARE_GREATER_OR_EQUAL = 6

當參考值大於或等於現有範本值時,通過範本測試。


屬性說明

Color albedo_color = Color(1, 1, 1, 1) 🔗

  • void set_albedo(value: Color)

  • Color get_albedo()

材質的基礎顏色。

注意: 若 detail_enabled 為 true 且已設定 detail_albedo 紋理,則 albedo_color 將 不會 調變該細節紋理。此技巧可透過不設定反照率紋理、改用帶透明度的 detail_albedo 來僅為材質部分區域上色。


Texture2D albedo_texture 🔗

會與 albedo_color 相乘的紋理,用於物件的基本貼圖。

若紋理顯得異常過暗或過亮,請檢查 albedo_texture_force_srgb 設定。


bool albedo_texture_force_srgb = false 🔗

如果為 true,則強制將 albedo_texture 從非線性 sRGB 編碼轉換為線性編碼。另見 vertex_color_is_srgb。

該屬性應該只在需要時啟用(通常在使用 ViewportTexture 作為 albedo_texture 時)。如果 albedo_texture_force_srgb 在不應該的情況下為 true,則紋理會顯得太暗。如果 albedo_texture_force_srgb 在不應該的情況下為 false,則紋理會顯得太亮。


bool albedo_texture_msdf = false 🔗

啟用多通道 Signed Distance Field 渲染著色器。可透過 msdf_pixel_range 與 msdf_outline_size 調整 MSDF 參數。


float alpha_antialiasing_edge 🔗

  • void set_alpha_antialiasing_edge(value: float)

  • float get_alpha_antialiasing_edge()

在 Alpha 通道上套用反鋸齒的臨界值。


AlphaAntiAliasing alpha_antialiasing_mode 🔗

要套用的 Alpha 反鋸齒類型。


float alpha_hash_scale 🔗

  • void set_alpha_hash_scale(value: float)

  • float get_alpha_hash_scale()

Alpha Hash 的雜湊比例,建議值介於 0 與 2 之間。


float alpha_scissor_threshold 🔗

  • void set_alpha_scissor_threshold(value: float)

  • float get_alpha_scissor_threshold()

Alpha 剪刀將丟棄值的閾值。較高的值將導致更多像素被丟棄。如果材質在遠處變得太不透明,請嘗試增加 alpha_scissor_threshold。如果材質在遠處消失,請嘗試降低 alpha_scissor_threshold。


float anisotropy = 0.0 🔗

  • void set_anisotropy(value: float)

  • float get_anisotropy()

各向異性效果的強度。若 anisotropy_flowmap 為含 Alpha 的紋理,則會與其 Alpha 通道相乘。


bool anisotropy_enabled = false 🔗

若為 true,啟用各向異性。各向異性會改變鏡面高光形狀並依切線空間對齊,適合用於拉絲金屬或頭髮反射。

注意: 網格必須包含切線資料,否則效果會破碎。

注意: 此處的各向異性與「各向異性紋理過濾」不同,後者可將 texture_filter 設為 TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC 來啟用。


Texture2D anisotropy_flowmap 🔗

用於在各向異性計算中偏移切線,並可(透過 Alpha 通道)控制效果強度的方向圖。此紋理應為導數圖:紅通道代表 X 軸扭曲,綠通道代表 Y 軸扭曲;值低於 0.5 為負向扭曲,高於 0.5 為正向扭曲。

若存在 Alpha 通道,會與 anisotropy 強度相乘:完全不透明保留原始強度,完全透明則完全關閉各向異性。藍通道會被忽略。


bool ao_enabled = false 🔗

若為 true,啟用環境遮蔽,會依 ao_texture 使區域變暗。


float ao_light_affect = 0.0 🔗

  • void set_ao_light_affect(value: float)

  • float get_ao_light_affect()

環境遮蔽對動態光源亮度的影響比例。為 0 時僅影響環境光;為 1 時對動態光源與環境光影響相同。雖可藉此加強 AO 效果,但通常會降低真實感。


bool ao_on_uv2 = false 🔗

若為 true,使用 UV2 座標讀取 ao_texture。


Texture2D ao_texture 🔗

定義物體各處環境遮蔽量的紋理。


TextureChannel ao_texture_channel = 0 🔗

指定 ao_texture 中存放環境遮蔽資訊的色彩通道。當多種效果資訊共用同一張紋理時相當實用;例如將金屬度放紅通道、粗糙度放藍通道、把 AO 放綠通道,藉此減少紋理數量。


Color backlight = Color(0, 0, 0, 1) 🔗

  • void set_backlight(value: Color)

  • Color get_backlight()

背光效果使用的顏色,代表穿透物體的光線色彩。


bool backlight_enabled = false 🔗

若為 true,啟用背光效果。另見 subsurf_scatter_transmittance_enabled。


Texture2D backlight_texture 🔗

逐像素控制背光量的紋理,最終會與 backlight 值相加。


bool bent_normal_enabled = false 🔗

若為 true,啟用彎曲法線貼圖,可獲得更精確的間接光與鏡面遮蔽。


Texture2D bent_normal_texture 🔗

用於指定給定像素的入射環境光平均方向的紋理。bent_normal_texture 只使用紅色和綠色通道;會忽略藍色和 alpha 通道。從 bent_normal_texture 讀取的法線是圍繞 Mesh 所提供的表面法線的進行朝向的。

注意:彎曲法線貼圖與常規法線貼圖不同。烘焙彎曲法線貼圖時,請確保使用余弦分布,彎曲法線貼圖才能正常工作。

注意:該網格必須在其頂點資料中同時定義法線和切線。否則法線貼圖將無法正確渲染,只會使整個表面變暗。如果使用 SurfaceTool 建立幾何體,可以使用 SurfaceTool.generate_normals() 和 SurfaceTool.generate_tangents() 分別自動生成法線和切線。

注意:Godot 期望彎曲法線貼圖使用 X+、Y+、Z+ 座標系。比較流行的引擎所期望的法線貼圖座標系見這個頁面。


bool billboard_keep_scale = false 🔗

若為 true,公告板渲染時仍保留網格原有縮放;否則縮放會被忽略。僅於 billboard_mode 非 BILLBOARD_DISABLED 時適用。


BillboardMode billboard_mode = 0 🔗

控制物件面向相機的方式。

注意: 公告板模式不適用於 VR,因為頭戴裝置時相機的左右向量並非水平。詳情見 GitHub Issue #41567。


BlendMode blend_mode = 0 🔗

材質的混合模式。

注意: 除 Mix 以外的模式都會將物件強制進入透明渲染流程。


float clearcoat = 1.0 🔗

  • void set_clearcoat(value: float)

  • float get_clearcoat()

設定清漆層的強度;設為 0 等同停用清漆效果。


bool clearcoat_enabled = false 🔗

若為 true,啟用清漆渲染,於照明中加入透明次通道產生額外高光,使材質看起來像有一層光滑或霧面的透明塗層。

注意: 若材質的 shading_mode 為 SHADING_MODE_UNSHADED,則不會顯示清漆效果。


float clearcoat_roughness = 0.5 🔗

  • void set_clearcoat_roughness(value: float)

  • float get_clearcoat_roughness()

設定清漆層的粗糙度;值越高越霧面,越低越光滑。


Texture2D clearcoat_texture 🔗

定義清漆強度與光澤度的紋理;紅通道為強度,綠通道為光澤度。


CullMode cull_mode = 0 🔗

決定要依三角形面向相機與否來剔除哪一側。


DepthDrawMode depth_draw_mode = 0 🔗

決定何時進行深度寫入,另見 transparency。


DepthTest depth_test = 0 🔗

實驗性: May be affected by future rendering pipeline changes.

決定深度測試時使用的比較運算符。

注意:將 depth_test 設為非預設值只有用於透明材質、depth_draw_mode 為 DEPTH_DRAW_DISABLED 的材質時才有可見的效果。


Texture2D detail_albedo 🔗

指定細節覆蓋層顏色的紋理。即使材質為不透明,detail_albedo 的 Alpha 通道仍作為遮罩;若需使用獨立紋理當遮罩,請參考 detail_mask。

注意: detail_albedo 不會 受到 albedo_color 影響。


BlendMode detail_blend_mode = 0 🔗

指定 detail_albedo 與現有 ALBEDO 的混合方式。


bool detail_enabled = false 🔗

若為 true,啟用細節覆蓋。系統會依 detail_mask 與 detail_albedo Alpha 通道,在物件表面混合第二張紋理,可用於增加變化或在兩組反照率/法線間平滑過渡。


Texture2D detail_mask 🔗

指定細節紋理與基礎紋理混合方式的紋理。detail_mask 可與 detail_albedo 的 Alpha 通道一併使用。


Texture2D detail_normal 🔗

用於指定細節覆蓋層逐像素法線的紋理。detail_normal 紋理只使用紅色和綠色通道;會忽略藍色和 alpha 通道。從 detail_normal 讀取的法線是圍繞 Mesh 所提供的表面法線的進行朝向的。

注意:Godot 期望法線貼圖使用 X+、Y+、Z+ 座標系。比較流行的引擎所期望的法線貼圖座標系見這個頁面。


DetailUV detail_uv_layer = 0 🔗

指定細節層使用 UV 或 UV2。


DiffuseMode diffuse_mode = 0 🔗

用於漫反射光散射的演算法。


bool disable_ambient_light = false 🔗

若為 true,物件將不受環境光影響。


bool disable_fog = false 🔗

若為 true,物件不受任何霧效(體積霧或深度霧)影響。對於無陰影或全透明材質(例如粒子)特別實用,否則即便完全透明仍會被霧影響。


bool disable_receive_shadows = false 🔗

若為 true,物件不會接收落在其上的陰影。


bool disable_specular_occlusion = false 🔗

如果為 true 則停用鏡面反射遮蔽,即便 ProjectSettings.rendering/reflections/specular_occlusion/enabled 為 false。


float distance_fade_max_distance = 10.0 🔗

  • void set_distance_fade_max_distance(value: float)

  • float get_distance_fade_max_distance()

物體看起來完全不透明的距離。

注意:如果 distance_fade_max_distance 小於 distance_fade_min_distance,則行為相反。物體將在 distance_fade_max_distance 處開始逐漸消失,並在到達 distance_fade_min_distance 時完全消失。


float distance_fade_min_distance = 0.0 🔗

  • void set_distance_fade_min_distance(value: float)

  • float get_distance_fade_min_distance()

物體開始變得可見的距離。如果物體的距離小於這個距離,它將是不可見的。

注意:如果 distance_fade_min_distance 大於 distance_fade_max_distance,則行為將相反。物體將在 distance_fade_max_distance 處開始逐漸消失,並在到達 distance_fade_min_distance 時完全消失。


DistanceFadeMode distance_fade_mode = 0 🔗

指定淡入淡出的類型,可為任何 DistanceFadeMode 值。


Color emission = Color(0, 0, 0, 1) 🔗

  • void set_emission(value: Color)

  • Color get_emission()

發光色彩,詳見 emission_enabled。


bool emission_enabled = false 🔗

若為 true,物件會自體發光,使其看起來更明亮。若場景使用 VoxelGI、SDFGI 或 LightmapGI 且此物件參與光照烘焙,發出的光也會影響其他物件。


float emission_energy_multiplier = 1.0 🔗

  • void set_emission_energy_multiplier(value: float)

  • float get_emission_energy_multiplier()

發光亮度倍率,詳見 emission_enabled。


float emission_intensity 🔗

  • void set_emission_intensity(value: float)

  • float get_emission_intensity()

發光亮度(nits,cd/m²)。僅在 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 啟用時可用;預設值約等同室內燈泡。


bool emission_on_uv2 = false 🔗

使用 UV2 座標讀取 emission_texture。


EmissionOperator emission_operator = 0 🔗

設定 emission 與 emission_texture 的組合方式,為加法或乘法。


Texture2D emission_texture 🔗

指定各像素發光強度的紋理。


bool fixed_size = false 🔗

若為 true,無論與相機距離多遠,物件都以固定大小呈現;效果相當於相機永遠距離物件 1.0 單位。但 Camera3D 的視野角(或正交/斜投模式下的 Camera3D.size)仍會影響螢幕大小。


float fov_override = 75.0 🔗

  • void set_fov_override(value: float)

  • float get_fov_override()

覆寫 Camera3D 的視野角度(度)。

注意: 行為類似於於一台 Camera3D.keep_aspect 設為 Camera3D.KEEP_HEIGHT 的相機上設定 FOV。若使用非透視相機(FOV 無效)可能無法正確顯示。


bool grow = false 🔗

  • void set_grow_enabled(value: bool)

  • bool is_grow_enabled()

若為 true,啟用頂點擴張,可配合第二個材質分段並將 cull_mode 設為 CULL_FRONT 來產生網格外框。另見 grow_amount。

注意: 擴張不會新增頂點,銳角處可能出現縫隙。可於 DCC 軟體使用 面權重法線 並保持光滑法線以減少破口,讓擴張後的外框能完整閉合。


float grow_amount = 0.0 🔗

沿頂點法線方向擴張網格;僅當 grow 為 true 時有效。


bool heightmap_deep_parallax = false 🔗

  • void set_heightmap_deep_parallax(value: bool)

  • bool is_heightmap_deep_parallax_enabled()

若為 true,使用視差遮蔽貼圖取代單純的偏移貼圖(見 heightmap_enabled),以呈現更真實的深度效果,但 GPU 負擔也更高。僅在確實需要時啟用。


bool heightmap_enabled = false 🔗

若為 true,啟用高度貼圖(亦稱視差貼圖或深度貼圖),另見 normal_enabled。此功能對 GPU 耗費較高,僅套用至視覺差異顯著的材質。

注意: 若同一材質啟用了三平面貼圖(uv1_triplanar),則不支援高度貼圖,heightmap_enabled 會被忽略。


bool heightmap_flip_binormal = false 🔗

  • void set_heightmap_deep_parallax_flip_binormal(value: bool)

  • bool get_heightmap_deep_parallax_flip_binormal()

若為 true,解析高度貼圖時會翻轉網格的副法線。若相機移動時高度效果異常(即便已調整 heightmap_scale),可嘗試啟用此選項。


bool heightmap_flip_tangent = false 🔗

  • void set_heightmap_deep_parallax_flip_tangent(value: bool)

  • bool get_heightmap_deep_parallax_flip_tangent()

若為 true,解析高度貼圖時會翻轉網格切線。若相機移動時高度效果異常(即便已調整 heightmap_scale),可嘗試啟用此選項。


bool heightmap_flip_texture = false 🔗

若設為 true,則把高度圖紋理視為深度圖,亮部會顯得「較低」,暗部則顯得較高。

此選項用於相容某些為 Godot 3.x 製作的材質;若在 Godot 3.x 匯入時已使用「Invert」反轉深度圖,則無需啟用,並應讓 heightmap_flip_texture 維持 false。


int heightmap_max_layers 🔗

  • void set_heightmap_deep_parallax_max_layers(value: int)

  • int get_heightmap_deep_parallax_max_layers()

當相機靠近材質時,視差遮蔽貼圖所使用的層數。數值越高,深度效果越真實,特別是高度差劇烈的材質;但也會顯著提高 GPU 成本,因此僅在確實有需要時再行提高。

注意:僅於 heightmap_deep_parallax 為 true 時生效。


int heightmap_min_layers 🔗

  • void set_heightmap_deep_parallax_min_layers(value: int)

  • int get_heightmap_deep_parallax_min_layers()

當相機遠離材質時,視差遮蔽貼圖所使用的層數。數值越高,深度效果越真實,特別是高度差劇烈的材質;但也會顯著提高 GPU 成本,因此僅在確實有需要時再行提高。

注意:僅於 heightmap_deep_parallax 為 true 時生效。


float heightmap_scale = 5.0 🔗

  • void set_heightmap_scale(value: float)

  • float get_heightmap_scale()

用於視差效果的高度圖縮放(參見 heightmap_enabled)。調整預設值,使最高點(值 = 255)看起來比最低點(值 = 0)高 5 釐米。較高的值會導致更深的外觀,但可能會導致從傾斜角度查看材質時出現偽影,尤其是在相機移動時。負值可用於反轉視差效果,但這與使用 heightmap_flip_texture 反轉紋理不同,因為材質也會看起來“更接近”相機。在大多數情況下,heightmap_scale 應保持為正值。

注意:如果忽略這個值後高度圖效果看起來很奇怪,請嘗試調整 heightmap_flip_binormal 和 heightmap_flip_tangent。另見 heightmap_texture 以取得有關創作高度圖紋理的建議,因為創作高度圖紋理的方式會影響 heightmap_scale 的行為方式。


Texture2D heightmap_texture 🔗

指定高度圖紋理;亦參見 heightmap_enabled。

為獲得最佳結果,應先將紋理正規化(並相應降低 heightmap_scale)。在 GIMP 中可透過 Colors > Auto > Equalize 完成。若紋理只使用到亮度範圍的一小部分,鏡頭移動時視差效果可能異常。

注意:高度圖多為低頻資訊,可使用較低解析度以減少記憶體占用並加速載入。


float metallic = 0.0 🔗

  • void set_metallic(value: float)

  • float get_metallic()

數值越高,材質越像金屬。非金屬將反照率做為漫反射顏色,並在鏡面反射中加入漫反射,因此反射會覆蓋於反照率之上;金屬則以反照率乘上鏡面反射,並把漫反射設為黑色,形成帶色反射。建議材質設定為純金屬或純非金屬;介於 0 與 1 的值僅用於漸層過渡。要調整反射強度請改變 roughness。


float metallic_specular = 0.5 🔗

  • void set_specular(value: float)

  • float get_specular()

調整鏡面反射的強度。鏡面反射由場景反射和鏡面波瓣組成,鏡面波瓣是從光源反射的亮點。當設定為 0.0 時,鏡面反射將不可見。這與 SPECULAR_DISABLED SpecularMode 不同,因為 SPECULAR_DISABLED 僅適用於來自光源的鏡面波瓣。

注意:與 metallic 不同,這能量不守恆的,所以在大多數情況下應將其保留在 0.5。另見 roughness。


Texture2D metallic_texture 🔗

指定物件金屬度的紋理,會與 metallic 相乘。


TextureChannel metallic_texture_channel = 0 🔗

設定金屬度資訊位於 metallic_texture 的哪個通道。當多種貼圖資訊合併於單張紋理時非常有用,例如:紅色通道放金屬度、藍色放粗糙度、綠色放環境遮蔽,即可減少貼圖數量。


float msdf_outline_size = 0.0 🔗

  • void set_msdf_outline_size(value: float)

  • float get_msdf_outline_size()

形狀輪廓寬度。


float msdf_pixel_range = 4.0 🔗

  • void set_msdf_pixel_range(value: float)

  • float get_msdf_pixel_range()

形狀周圍最小至最大可表距離範圍的寬度。


bool no_depth_test = false 🔗

若設為 true,將停用深度測試,物件依繪製順序顯示。


bool normal_enabled = false 🔗

若設為 true,啟用法線貼圖;在行動 GPU 上會稍降效能。


float normal_scale = 1.0 🔗

  • void set_normal_scale(value: float)

  • float get_normal_scale()

法線貼圖強度。


Texture2D normal_texture 🔗

用於指定給定像素的法線的紋理。normal_texture 只使用紅色和綠色通道;會忽略藍色和 alpha 通道。從 normal_texture 讀取的法線是圍繞 Mesh 所提供的表面法線的進行朝向的。

注意:該網格必須在其頂點資料中同時定義法線和切線。否則法線貼圖將無法正確渲染,只會使整個表面變暗。如果使用 SurfaceTool 建立幾何體,可以使用 SurfaceTool.generate_normals() 和 SurfaceTool.generate_tangents() 分別自動生成法線和切線。

注意:Godot 期望法線貼圖使用 X+、Y+、Z+ 座標系。比較流行的引擎所期望的法線貼圖座標系見這個頁面。

注意:如果 detail_enabled 為 true,則 detail_albedo 紋理將在 normal_texture 下方繪製。要在 detail_albedo 紋理之上顯示法線貼圖,請改用 detail_normal。


Texture2D orm_texture 🔗

指定遮蔽/粗糙度/金屬度(ORM)紋理,為 ORMMaterial3D 中 ao_texture、roughness_texture 與 metallic_texture 的更有效率替代方案:紅通道存環境遮蔽、綠通道存粗糙度、藍通道存金屬度,Alpha 通道忽略。


bool particles_anim_enabled = false 🔗

If true, enables particles_anim_* properties. The ParticleProcessMaterial.anim_speed_min or CPUParticles3D.anim_speed_min should also be set to a value bigger than zero for the animation to play.

Note: For compatibility reasons, this property is ignored and always enabled when billboard_mode is set to BILLBOARD_PARTICLES.


int particles_anim_h_frames = 1 🔗

  • void set_particles_anim_h_frames(value: int)

  • int get_particles_anim_h_frames()

The number of horizontal frames in the particle sprite sheet.

Only enabled when particles_anim_enabled is true or billboard_mode is set to BILLBOARD_PARTICLES.


bool particles_anim_loop = false 🔗

  • void set_particles_anim_loop(value: bool)

  • bool get_particles_anim_loop()

If true, particle animations are looped.

Only enabled when particles_anim_enabled is true or billboard_mode is set to BILLBOARD_PARTICLES.


int particles_anim_v_frames = 1 🔗

  • void set_particles_anim_v_frames(value: int)

  • int get_particles_anim_v_frames()

The number of vertical frames in the particle sprite sheet.

Only enabled when particles_anim_enabled is true or billboard_mode is set to BILLBOARD_PARTICLES.


float point_size = 1.0 🔗

  • void set_point_size(value: float)

  • float get_point_size()

點大小(像素);參見 use_point_size。


float proximity_fade_distance = 1.0 🔗

  • void set_proximity_fade_distance(value: float)

  • float get_proximity_fade_distance()

淡出距離;數值越大,物件完全淡出所需距離越長。


bool proximity_fade_enabled = false 🔗

  • void set_proximity_fade_enabled(value: bool)

  • bool is_proximity_fade_enabled()

若設為 true,啟用近距離淡出效果;圖元會依與指定物件的距離逐漸隱形。


bool refraction_enabled = false 🔗

若設為 true,啟用折射效果,依據物件後方的影像扭曲透明區域。

注意:折射透過螢幕貼圖實作,僅不透明材質會出現在該貼圖中,因此透明材質不會被折射顯示。


float refraction_scale = 0.05 🔗

  • void set_refraction(value: float)

  • float get_refraction()

折射強度。


Texture2D refraction_texture 🔗

控制每圖元折射強度的紋理,會與 refraction_scale 相乘。


TextureChannel refraction_texture_channel = 0 🔗

設定折射資訊位於 refraction_texture 的哪個通道。可將多種資料整合於單張紋理,例如:紅通道折射、藍通道粗糙度、綠通道環境遮蔽,以降低貼圖數量。


float rim = 1.0 🔗

邊緣光強度。


bool rim_enabled = false 🔗

若設為 true,啟用邊緣光效果,使斜視角度下的表面更亮。

注意:當 shading_mode 設為 SHADING_MODE_UNSHADED 時邊緣光不會顯示。


Texture2D rim_texture 🔗

控制每圖元邊緣光強度的紋理,會與 rim 相乘。


float rim_tint = 0.5 🔗

  • void set_rim_tint(value: float)

  • float get_rim_tint()

邊緣光中光源色與反照率混合比率;0 表示完全使用光源色,1 則完全使用反照率,一般取中間值效果最佳。


float roughness = 1.0 🔗

  • void set_roughness(value: float)

  • float get_roughness()

表面粗糙度;0 為完全鏡面, 1 則完全模糊。另見 metallic。


Texture2D roughness_texture 🔗

控制每圖元粗糙度的紋理,會與 roughness 相乘。


TextureChannel roughness_texture_channel = 0 🔗

設定粗糙度資訊位於 roughness_texture 的哪個通道。可將多種資料整合於單張紋理,例如:紅通道金屬度、藍通道粗糙度、綠通道環境遮蔽,以降低貼圖數量。


ShadingMode shading_mode = 1 🔗

設定著色方式:逐圖元、逐頂點或無光照。逐頂點光照較快,適合行動裝置,但品質明顯不如逐圖元;無光照最快,但完全不受光源影響。


bool shadow_to_opacity = false 🔗

若設為 true,啟用「Shadow to Opacity」模式:光照會改寫 Alpha,使陰影區域不透明、其它區域透明。可用於在 AR 畫面上覆蓋陰影。


SpecularMode specular_mode = 0 🔗

鏡面亮斑的繪製方式。

注意:specular_mode 僅影響鏡面亮斑,不會影響天空、螢幕空間反射、VoxelGI、SDFGI 或 ReflectionProbe 的反射;若也需停用那些反射,請將 metallic_specular 設為 0.0。


Color stencil_color = Color(0, 0, 0, 1) 🔗

  • void set_stencil_effect_color(value: Color)

  • Color get_stencil_effect_color()

實驗性: May be affected by future rendering pipeline changes.

範本效果的主顏色。


StencilCompare stencil_compare = 0 🔗

實驗性: May be affected by future rendering pipeline changes.

範本遮罩運算所使用的比較運算符。


int stencil_flags = 0 🔗

  • void set_stencil_flags(value: int)

  • int get_stencil_flags()

實驗性: May be affected by future rendering pipeline changes.

控制範本運算行為的標誌。


StencilMode stencil_mode = 0 🔗

實驗性: May be affected by future rendering pipeline changes.

範本效果模式。


float stencil_outline_thickness = 0.01 🔗

  • void set_stencil_effect_outline_thickness(value: float)

  • float get_stencil_effect_outline_thickness()

實驗性: May be affected by future rendering pipeline changes.

STENCIL_MODE_OUTLINE 的輪廓粗細。


int stencil_reference = 1 🔗

  • void set_stencil_reference(value: int)

  • int get_stencil_reference()

實驗性: May be affected by future rendering pipeline changes.

範本參考值(0-255)。通常是 2 的冪。


bool subsurf_scatter_enabled = false 🔗

如果 true,則啟用次表面散射。模擬光線將穿透物體表面、發生散射並最終逸出的效果。次表面散射品質由 ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality 控制。

注意: 在具有透明背景的視埠(Viewport.transparent_bg 為 true)上不支援次表面散射。


bool subsurf_scatter_skin_mode = false 🔗

若設為 true,次表面散射會啟用專為人類皮膚最佳化的模式,例如增強紅色通道。


float subsurf_scatter_strength = 0.0 🔗

  • void set_subsurface_scattering_strength(value: float)

  • float get_subsurface_scattering_strength()

次表面散射強度;其深度由全域設定 ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale 決定。


Texture2D subsurf_scatter_texture 🔗

控制次表面散射強度的紋理(紅通道),會與 subsurf_scatter_strength 相乘。


float subsurf_scatter_transmittance_boost = 0.0 🔗

  • void set_transmittance_boost(value: float)

  • float get_transmittance_boost()

次表面散射透射強度。


Color subsurf_scatter_transmittance_color = Color(1, 1, 1, 1) 🔗

  • void set_transmittance_color(value: Color)

  • Color get_transmittance_color()

與次表面散射透射效果相乘的顏色;subsurf_scatter_skin_mode 為 true 時忽略。


float subsurf_scatter_transmittance_depth = 0.1 🔗

  • void set_transmittance_depth(value: float)

  • float get_transmittance_depth()

次表面散射透射深度。


bool subsurf_scatter_transmittance_enabled = false 🔗

若設為 true,啟用次表面散射透射;僅在 subsurf_scatter_enabled 為 true 時有效。另見 backlight_enabled。


Texture2D subsurf_scatter_transmittance_texture 🔗

用來乘上次表面散射透射強度的紋理;亦參見 subsurf_scatter_texture。若 subsurf_scatter_skin_mode 為 true 則忽略。


TextureFilter texture_filter = 3 🔗

紋理篩選方式。

注意:heightmap_texture 一律使用線性取樣,即使此處選擇最近鄰。若需更銳利的高度階梯,請在影像編輯器中以最近鄰縮放高度圖。


bool texture_repeat = true 🔗

若設為 true,紋理座標超出範圍時會重複;參見 FLAG_USE_TEXTURE_REPEAT。


Transparency transparency = 0 🔗

材質透明度模式。部分模式會停用投射陰影;除 TRANSPARENCY_DISABLED 外的任何模式都比不透明渲染更耗效能。另見 blend_mode。


bool use_fov_override = false 🔗

若設為 true,使用 fov_override 覆寫 Camera3D 的視野角度。


bool use_particle_trails = false 🔗

若設為 true,啟用 GPUParticles3D 尾跡所需的著色器代碼;需配合 RibbonTrailMesh 或 TubeTrailMesh 等具蒙皮的網格。若在非 GPUParticles3D 網格材質上啟用將導致材質繪製錯誤。


bool use_point_size = false 🔗

若設為 true,允許修改繪製點大小。

注意:僅對以點為單位的幾何(非三角形)有效;另見 point_size。


bool use_z_clip_scale = false 🔗

若設為 true,透過 z_clip_scale 朝鏡頭縮放物體以避免穿牆。


Vector3 uv1_offset = Vector3(0, 0, 0) 🔗

UV 偏移量,於頂點函式加至 UV;可用來移動紋理。Z 分量僅在啟用 uv1_triplanar 時使用。


Vector3 uv1_scale = Vector3(1, 1, 1) 🔗

UV 縮放比例,於頂點函式乘上 UV;Z 分量僅在啟用 uv1_triplanar 時使用。


bool uv1_triplanar = false 🔗

若設為 true,不使用 UV,改以三平面取樣決定貼圖方式。三平面會根據表面法向對三個軸各取紋理一次,並依像素對軸的對齊度混合結果,常用於自然地形以獲得平滑過渡。但因每像素需多次取樣,效能遠低於一般 UV;亦因混合導致邊緣變軟,不適合需要銳利貼圖的場合。


float uv1_triplanar_sharpness = 1.0 🔗

  • void set_uv1_triplanar_blend_sharpness(value: float)

  • float get_uv1_triplanar_blend_sharpness()

數值越低混合越柔和,數值越高混合越銳利。

注意:uv1_triplanar_sharpness 會被限制於 0.0 至 150.0 之間,超出範圍可能導致畫面破損。


bool uv1_world_triplanar = false 🔗

若設為 true,UV 的三平面在世界座標計算;另見 uv1_triplanar。


Vector3 uv2_offset = Vector3(0, 0, 0) 🔗

UV2 偏移量,於頂點函式加至 UV2;可用來移動第二組紋理座標。Z 分量僅在啟用 uv2_triplanar 時使用。


Vector3 uv2_scale = Vector3(1, 1, 1) 🔗

UV2 縮放比例,於頂點函式乘上 UV2;Z 分量僅在啟用 uv2_triplanar 時使用。


bool uv2_triplanar = false 🔗

若設為 true,不使用 UV2,改用三平面取樣。原理與 UV 版本相同,效能成本亦相同,不再贅述。


float uv2_triplanar_sharpness = 1.0 🔗

  • void set_uv2_triplanar_blend_sharpness(value: float)

  • float get_uv2_triplanar_blend_sharpness()

數值越低混合越柔和,數值越高混合越銳利。

注意:uv2_triplanar_sharpness 會被限制於 0.0 至 150.0 之間,超出範圍可能導致畫面破損。


bool uv2_world_triplanar = false 🔗

若設為 true,UV2 的三平面在世界座標計算;另見 uv2_triplanar。


bool vertex_color_is_srgb = false 🔗

如果為 true,則頂點顏色被認為以非線性 sRGB 編碼儲存,並在渲染期間被轉換為線性編碼。如果為 false,則頂點顏色被認為以線性編碼儲存,並按原樣渲染。另見 albedo_texture_force_srgb。

注意:僅在使用 Forward+ 和移動渲染方式時有效,不支援相容模式。


bool vertex_color_use_as_albedo = false 🔗

若設為 true,將頂點色用作反照率。


float z_clip_scale = 1.0 🔗

  • void set_z_clip_scale(value: float)

  • float get_z_clip_scale()

將物件朝鏡頭縮放,以避免近距離穿牆;適用於固定在視角上的物件(例如玩家手臂、工具)。光照與陰影仍能正常運作,但像 SSAO、SSR 等螢幕空間效果在縮放過小時可能失真,因此請盡量接近 1.0。


方法說明

bool get_feature(feature: Feature) const 🔗

如果指定的 feature 已啟用,則回傳 true。


bool get_flag(flag: Flags) const 🔗

如果指定的 flag 已啟用,則回傳 true。


Texture2D get_texture(param: TextureParam) const 🔗

回傳與指定紋理參數 param 關聯的 Texture2D。


void set_feature(feature: Feature, enable: bool) 🔗

如果 enable 設定為 true,則啟用指定的 feature。BaseMaterial3D 中的許多功能都需要在使用前啟用。這樣,僅在指定時才會產生使用該功能的成本。也可以通過將其對應的屬性設定為 true 來啟用功能。


void set_flag(flag: Flags, enable: bool) 🔗

如果 enable 為 true,則啟用指定的 flag。標誌是可以打開和關閉的可選行為。使用該函式一次只能啟用一個標誌,不能將標誌列舉值像位元遮罩一樣進行合併,一次啟用或停用多個標誌。也可以通過將相應屬性設定為 true 來啟用標誌。


void set_texture(param: TextureParam, texture: Texture2D) 🔗

為由 param 指定的槽位設定紋理。