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.

Checking the stable version of the documentation...

GeometryInstance3D

繼承： VisualInstance3D < Node3D < Node < Object

被繼承： CPUParticles3D, CSGShape3D, GPUParticles3D, Label3D, MeshInstance3D, MultiMeshInstance3D, SpriteBase3D

基於幾何圖形的視覺實例的基礎節點。

說明

基於幾何圖形的視覺實例的基礎節點。分享一些共同的機制，如可見性和自訂材質。

教學

可見範圍（HLOD）

屬性

ShadowCastingSetting	cast_shadow	`1`
AABB	custom_aabb	`AABB(0, 0, 0, 0, 0, 0)`
float	extra_cull_margin	`0.0`
LightmapScale	gi_lightmap_scale	`0`
float	gi_lightmap_texel_scale	`1.0`
GIMode	gi_mode	`1`
bool	ignore_occlusion_culling	`false`
float	lod_bias	`1.0`
Material	material_overlay
Material	material_override
float	transparency	`0.0`
float	visibility_range_begin	`0.0`
float	visibility_range_begin_margin	`0.0`
float	visibility_range_end	`0.0`
float	visibility_range_end_margin	`0.0`
VisibilityRangeFadeMode	visibility_range_fade_mode	`0`

方法

Variant	get_instance_shader_parameter(name: StringName) const
void	set_instance_shader_parameter(name: StringName, value: Variant)

列舉

enum ShadowCastingSetting: 🔗

ShadowCastingSetting SHADOW_CASTING_SETTING_OFF = 0

不會投射任何陰影。使用該選項，可提高不太可能投射明顯陰影的小型幾何體（例如碎片）的性能。

ShadowCastingSetting SHADOW_CASTING_SETTING_ON = 1

將從 GeometryInstance3D 中的所有可見面投射陰影。

將考慮剔除，因此在陰影投射時，不會考慮那些不會被算繪的面。

ShadowCastingSetting SHADOW_CASTING_SETTING_DOUBLE_SIDED = 2

將從 GeometryInstance3D 中的所有可見面投射陰影。

不會考慮剔除，因此在陰影投射時，將考慮所有面。

ShadowCastingSetting SHADOW_CASTING_SETTING_SHADOWS_ONLY = 3

只顯示從這個物體投射出來的陰影。

換句話說，實際的網格將不可見，只有網格投影可見。

enum GIMode: 🔗

GIMode GI_MODE_DISABLED = 0

Disabled global illumination mode. Use for dynamic objects that do not contribute to global illumination (such as characters). When using VoxelGI and SDFGI, the geometry will receive indirect lighting and reflections but the geometry will not be considered in GI baking.

GIMode GI_MODE_STATIC = 1

烘焙全域照明模式。用於有助於全域照明的靜態物件（例如關卡幾何體）。該 GI 模式在使用 VoxelGI、SDFGI 和 LightmapGI 時有效。

GIMode GI_MODE_DYNAMIC = 2

Dynamic global illumination mode. Use for dynamic objects that contribute to global illumination. This GI mode is only effective when using VoxelGI, but it has a higher performance impact than GI_MODE_STATIC. When using other GI methods, this will act the same as GI_MODE_DISABLED. When using LightmapGI, the object will receive indirect lighting using lightmap probes instead of using the baked lightmap texture.

enum LightmapScale: 🔗

LightmapScale LIGHTMAP_SCALE_1X = 0

已棄用： Use gi_lightmap_texel_scale instead.

使用 LightmapGI 進行光照貼圖的標準紋素密度。

LightmapScale LIGHTMAP_SCALE_2X = 1

已棄用： Use gi_lightmap_texel_scale instead.

使用 LightmapGI 進行光照貼圖時，將紋素密度乘以 2 倍。為確保紋素密度的一致性，請在按 1.5 到 3.0 之間的係數縮放網格時，使用該選項。

LightmapScale LIGHTMAP_SCALE_4X = 2

已棄用： Use gi_lightmap_texel_scale instead.

使用 LightmapGI 進行光照貼圖時，將紋素密度乘以 4 倍。為確保紋素密度的一致性，請在按 3.0 到 6.0 之間的係數縮放網格時，使用該選項。

LightmapScale LIGHTMAP_SCALE_8X = 3

已棄用： Use gi_lightmap_texel_scale instead.

使用 LightmapGI 進行光照貼圖時，將紋素密度乘以 8 倍。為確保紋素密度的一致性，請在以大於 6.0 的係數縮放網格時，使用該選項。

LightmapScale LIGHTMAP_SCALE_MAX = 4

已棄用： Use gi_lightmap_texel_scale instead.

代表 LightmapScale 列舉的大小。

enum VisibilityRangeFadeMode: 🔗

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DISABLED = 0

不會自行淡化，也不會淡化其可見性依賴項，而是使用滯後。這是手動 LOD 的最快方法，但它可能會導致明顯的 LOD 過渡，具體取決於 LOD 網格的創作方式。有關更多信息，請參閱 visibility_range_begin 和 Node3D.visibility_parent。

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_SELF = 1

Will fade-out itself when reaching the limits of its own visibility range. This is slower than VISIBILITY_RANGE_FADE_DISABLED, but it can provide smoother transitions. The fading range is determined by visibility_range_begin_margin and visibility_range_end_margin.

Note: Only supported when using the Forward+ rendering method. When using the Mobile or Compatibility rendering method, this mode acts like VISIBILITY_RANGE_FADE_DISABLED but with hysteresis disabled.

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DEPENDENCIES = 2

Will fade-in its visibility dependencies (see Node3D.visibility_parent) when reaching the limits of its own visibility range. This is slower than VISIBILITY_RANGE_FADE_DISABLED, but it can provide smoother transitions. The fading range is determined by visibility_range_begin_margin and visibility_range_end_margin.

Note: Only supported when using the Forward+ rendering method. When using the Mobile or Compatibility rendering method, this mode acts like VISIBILITY_RANGE_FADE_DISABLED but with hysteresis disabled.

屬性說明

ShadowCastingSetting cast_shadow = 1 🔗

void set_cast_shadows_setting(value: ShadowCastingSetting)
ShadowCastingSetting get_cast_shadows_setting()

The mode used to cast shadows from this instance.

AABB custom_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

void set_custom_aabb(value: AABB)
AABB get_custom_aabb()

Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive AABB recalculation that happens when a skeleton is used with a MeshInstance3D or to have precise control over the MeshInstance3D's bounding box. To use the default AABB, set value to an AABB with all fields set to 0.0. To avoid frustum culling, set custom_aabb to a very large AABB that covers your entire game world such as AABB(-10000, -10000, -10000, 20000, 20000, 20000). To disable all forms of culling (including occlusion and layer culling), call RenderingServer.instance_set_ignore_culling() on the GeometryInstance3D's RID.

float extra_cull_margin = 0.0 🔗

void set_extra_cull_margin(value: float)
float get_extra_cull_margin()

新增到 GeometryInstance3D 的邊界框（AABB），以增加其剔除框的額外距離。

LightmapScale gi_lightmap_scale = 0 🔗

void set_lightmap_scale(value: LightmapScale)
LightmapScale get_lightmap_scale()

已棄用： Use gi_lightmap_texel_scale instead.

The texel density to use for lightmapping in LightmapGI.

float gi_lightmap_texel_scale = 1.0 🔗

void set_lightmap_texel_scale(value: float)
float get_lightmap_texel_scale()

The texel density to use for lightmapping in LightmapGI. Greater scale values provide higher resolution in the lightmap, which can result in sharper shadows for lights that have both direct and indirect light baked. However, greater scale values will also increase the space taken by the mesh in the lightmap texture, which increases the memory, storage, and bake time requirements. When using a single mesh at different scales, consider adjusting this value to keep the lightmap texel density consistent across meshes.

For example, doubling gi_lightmap_texel_scale doubles the lightmap texture resolution for this object on each axis, so it will quadruple the texel count.

GIMode gi_mode = 1 🔗

void set_gi_mode(value: GIMode)
GIMode get_gi_mode()

用於整個幾何體的全域照明模式。為避免結果不一致，請在遊戲過程中，使用與網格用途相配對的模式（靜態/動態）。

注意：燈光的烘焙模式，也會影響全域照明算繪。請參閱 Light3D.light_bake_mode。

bool ignore_occlusion_culling = false 🔗

void set_ignore_occlusion_culling(value: bool)
bool is_ignoring_occlusion_culling()

如果為 true，則禁用這個實例的遮擋剔除。可用於即便開啟遮擋剔除也必須算繪的小工具。

注意：ignore_occlusion_culling 不會影響視錐剔除（物件因為相機的角度而不可見時觸發）。要避免視錐剔除，請將 custom_aabb 設定為很大的 AABB，覆蓋住整個遊戲世界，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。

float lod_bias = 1.0 🔗

void set_lod_bias(value: float)
float get_lod_bias()

改變網格過渡到較低細節級別的速度。值為 0 將強制網格達到最低細節級別，值為 1 將使用預設設定，更大的值將使網格在更遠的距離處保持更高的細節級別。

對於測試編輯器中的細節級別的過渡很有用。

Material material_overlay 🔗

void set_material_overlay(value: Material)
Material get_material_overlay()

整個幾何體的材質覆蓋層。

如果一個材質被分配給這個屬性，它將會被算繪在所有表面的任何其他活動材質之上。

Material material_override 🔗

void set_material_override(value: Material)
Material get_material_override()

整個幾何體的材質覆蓋。

如果一個材質被分配給這個屬性，它將會被用來代替在網格的任何材質槽中設定的任何材質。

float transparency = 0.0 🔗

void set_transparency(value: float)
float get_transparency()

The transparency applied to the whole geometry (as a multiplier of the materials' existing transparency). 0.0 is fully opaque, while 1.0 is fully transparent. Values greater than 0.0 (exclusive) will force the geometry's materials to go through the transparent pipeline, which is slower to render and can exhibit rendering issues due to incorrect transparency sorting. However, unlike using a transparent material, setting transparency to a value greater than 0.0 (exclusive) will not disable shadow rendering.

In spatial shaders, 1.0 - transparency is set as the default value of the ALPHA built-in.

Note: transparency is clamped between 0.0 and 1.0, so this property cannot be used to make transparent materials more opaque than they originally are.

Note: Only supported when using the Forward+ rendering method. When using the Mobile or Compatibility rendering method, transparency is ignored and is considered as always being 0.0.

float visibility_range_begin = 0.0 🔗

void set_visibility_range_begin(value: float)
float get_visibility_range_begin()

GeometryInstance3D 可見的起始距離，同時考慮 visibility_range_begin_margin。預設值 0 用於禁用範圍檢查。

float visibility_range_begin_margin = 0.0 🔗

void set_visibility_range_begin_margin(value: float)
float get_visibility_range_begin_margin()

visibility_range_begin 閾值的邊距。GeometryInstance3D 只有在超出或低於 visibility_range_begin 閾值達到這個量時，才會更改其可見性狀態。

如果 visibility_range_fade_mode 為 VISIBILITY_RANGE_FADE_DISABLED，這將作為滯後距離。如果 visibility_range_fade_mode 為 VISIBILITY_RANGE_FADE_SELF 或 VISIBILITY_RANGE_FADE_DEPENDENCIES，這將作為淡入淡出過渡距離，並且必須被設定為大於 0.0 的值，才能使效果顯眼。

float visibility_range_end = 0.0 🔗

void set_visibility_range_end(value: float)
float get_visibility_range_end()

GeometryInstance3D 將被隱藏的距離，同時考慮 visibility_range_end_margin。預設值 0 用於禁用範圍檢查。

float visibility_range_end_margin = 0.0 🔗

void set_visibility_range_end_margin(value: float)
float get_visibility_range_end_margin()

visibility_range_end 閾值的邊距。GeometryInstance3D 只有在超出或低於 visibility_range_end 閾值達到這個量時，才會更改其可見性狀態。

如果 visibility_range_fade_mode 為 VISIBILITY_RANGE_FADE_DISABLED，這將作為滯後距離。如果 visibility_range_fade_mode 為 VISIBILITY_RANGE_FADE_SELF 或 VISIBILITY_RANGE_FADE_DEPENDENCIES，這將作為淡入淡出過渡距離，並且必須被設定為大於 0.0 的值，才能使效果顯眼。

VisibilityRangeFadeMode visibility_range_fade_mode = 0 🔗

void set_visibility_range_fade_mode(value: VisibilityRangeFadeMode)
VisibilityRangeFadeMode get_visibility_range_fade_mode()

Controls which instances will be faded when approaching the limits of the visibility range.

方法說明

Variant get_instance_shader_parameter(name: StringName) const 🔗

獲取在該實例上設定的著色器參數值。

void set_instance_shader_parameter(name: StringName, value: Variant) 🔗

設定著色器 Uniform 的值，僅限此實例 (每實例 Uniform)。另請參閱 ShaderMaterial.set_shader_parameter()，以在使用相同 ShaderMaterial 的所有實例上指派 Uniform。

注意： 著色器 Uniform 若要能夠按每個實例指派，它在著色器程式碼中必須定義為 instance uniform ...，而非 uniform ...。

注意： name 區分大小寫，且必須與程式碼中 Uniform 的名稱完全相符 (而非屬性檢視器中大寫的名稱)。

注意： 每實例著色器 Uniform 僅在 Spatial 和 CanvasItem 著色器中可用，但不適用於霧、天空或粒子著色器。