Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
GeometryInstance3D¶
继承： VisualInstance3D < Node3D < Node < Object
派生： CPUParticles3D, CSGShape3D, GPUParticles3D, Label3D, MeshInstance3D, MultiMeshInstance3D, SpriteBase3D
基于几何图形的视觉实例的基础节点。
描述¶
基于几何图形的视觉实例的基础节点。分享一些共同的机制，如可见性和自定义材质。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法¶
get_instance_shader_parameter ( StringName name ) const |
|
void |
set_instance_shader_parameter ( StringName name, Variant value ) |
枚举¶
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
禁用全局照明模式。用于对全局照明没有贡献的动态对象（例如角色）。使用 VoxelGI 和 SDFGI 时，几何体将接收间接照明和反射，但在 GI 烘焙中不会考虑几何体。使用 LightmapGI 时，对象将使用光照贴图探针接收间接光照，而不是使用烘焙的光照贴图纹理。
GIMode GI_MODE_STATIC = 1
烘焙全局照明模式。用于有助于全局照明的静态对象（例如关卡几何体）。该 GI 模式在使用 VoxelGI、SDFGI 和 LightmapGI 时有效。
GIMode GI_MODE_DYNAMIC = 2
动态全局照明模式。用于有助于全局照明的动态对象。这种 GI 模式只有在使用 VoxelGI 时才有效，但它对性能的影响，比 GI_MODE_STATIC 更高。当使用其他 GI 方法时，它的作用与 GI_MODE_DISABLED 相同。
enum LightmapScale:
LightmapScale LIGHTMAP_SCALE_1X = 0
使用 LightmapGI 进行光照贴图的标准纹素密度。
LightmapScale LIGHTMAP_SCALE_2X = 1
使用 LightmapGI 进行光照贴图时，将纹素密度乘以 2 倍。为确保纹素密度的一致性，请在按 1.5 到 3.0 之间的系数缩放网格时，使用该选项。
LightmapScale LIGHTMAP_SCALE_4X = 2
使用 LightmapGI 进行光照贴图时，将纹素密度乘以 4 倍。为确保纹素密度的一致性，请在按 3.0 到 6.0 之间的系数缩放网格时，使用该选项。
LightmapScale LIGHTMAP_SCALE_8X = 3
使用 LightmapGI 进行光照贴图时，将纹素密度乘以 8 倍。为确保纹素密度的一致性，请在以大于 6.0 的系数缩放网格时，使用该选项。
LightmapScale LIGHTMAP_SCALE_MAX = 4
代表 LightmapScale 枚举的大小。
enum VisibilityRangeFadeMode:
VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DISABLED = 0
不会自行淡化，也不会淡化其可见性依赖项，而是使用滞后。这是手动 LOD 的最快方法，但它可能会导致明显的 LOD 过渡，具体取决于 LOD 网格的创作方式。有关更多信息，请参阅 visibility_range_begin 和 Node3D.visibility_parent。
VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_SELF = 1
当达到自身可见范围的极限时，会自行淡出。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。
VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DEPENDENCIES = 2
当达到其自身可见性范围的限制时，将淡入其可见性依赖项（参见 Node3D.visibility_parent）。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。
属性说明¶
ShadowCastingSetting cast_shadow = 1
void set_cast_shadows_setting ( ShadowCastingSetting value )
ShadowCastingSetting get_cast_shadows_setting ( )
选择的阴影投射标志。可能的取值见 ShadowCastingSetting。
AABB custom_aabb = AABB(0, 0, 0, 0, 0, 0)
使用自定义边界框覆盖该节点的边界框。骨架使用 MeshInstance3D 时可以避免重新计算 AABB 节省性能，也可以用来对 MeshInstance3D 的边界框进行精确控制。要使用默认的 AABB，请将其设为所有字段均为 0.0 的 AABB。要避免视锥剔除，请将 custom_aabb 设为大到能够覆盖整个游戏世界的 AABB，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。要禁用所有形式的剔除（包括遮挡剔除），请使用该 GeometryInstance3D 的 RID 调用 RenderingServer.instance_set_ignore_culling。
float extra_cull_margin = 0.0
添加到 GeometryInstance3D 的边界框（AABB），以增加其剔除框的额外距离。
LightmapScale gi_lightmap_scale = 0
void set_lightmap_scale ( LightmapScale value )
LightmapScale get_lightmap_scale ( )
LightmapGI 中用于光照贴图的纹素密度。较大的缩放值可在光照贴图中提供更高的分辨率，这可以为同时烘焙了直接光和间接光的灯光，生成更清晰的阴影。但是，更大的缩放值也会增加光照贴图纹理中网格占用的空间，从而增加需要的内存、存储空间、和烘焙时间。在不同缩放下使用单个网格时，请考虑调整该值，以保持光照贴图纹素密度在网格之间保持一致。
GIMode gi_mode = 1
用于整个几何体的全局照明模式。为避免结果不一致，请在游戏过程中，使用与网格用途相匹配的模式（静态/动态）。
注意：灯光的烘焙模式，也会影响全局照明渲染。请参阅 Light3D.light_bake_mode。
bool ignore_occlusion_culling = false
如果为 true，则禁用这个实例的遮挡剔除。可用于即便开启遮挡剔除也必须渲染的小工具。
注意：ignore_occlusion_culling 不会影响视锥剔除（对象因为相机的角度而不可见时触发）。要避免视锥剔除，请将 custom_aabb 设置为很大的 AABB，覆盖住整个游戏世界，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。
float lod_bias = 1.0
改变网格过渡到较低细节级别的速度。值为 0 将强制网格达到最低细节级别，值为 1 将使用默认设置，更大的值将使网格在更远的距离处保持更高的细节级别。
对于测试编辑器中的细节级别的过渡很有用。
Material material_overlay
整个几何体的材质覆盖层。
如果一个材质被分配给这个属性，它将会被渲染在所有表面的任何其他活动材质之上。
Material material_override
整个几何体的材质覆盖。
如果一个材质被分配给这个属性，它将会被用来代替在网格的任何材质槽中设置的任何材质。
float transparency = 0.0
应用于整个几何体的透明度（作为材质现有透明度的乘数）。0.0 是完全不透明的，而 1.0 是完全透明的。大于 0.0（不含）的值将强制几何体的材质通过透明管道，这会导致渲染速度变慢，并且可能会因不正确的透明度排序而出现渲染问题。但是，与使用透明材质不同的是，将 transparency 设置为大于 0.0（不含）的值并不会禁用阴影渲染。
在空间着色器中，1.0 - transparency 被设置为内置 ALPHA 的默认值。
注意：transparency 被钳制在 0.0 和 1.0 之间，所以这个属性不能被用来使透明材质变得比原来更加不透明。
float visibility_range_begin = 0.0
GeometryInstance3D 可见的起始距离，同时考虑 visibility_range_begin_margin。默认值 0 用于禁用范围检查。
float visibility_range_begin_margin = 0.0
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
GeometryInstance3D 将被隐藏的距离，同时考虑 visibility_range_end_margin。默认值 0 用于禁用范围检查。
float visibility_range_end_margin = 0.0
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 ( VisibilityRangeFadeMode value )
VisibilityRangeFadeMode get_visibility_range_fade_mode ( )
控制在接近可见范围的限制时，哪些实例将被淡化。有关可能的值，请参阅 VisibilityRangeFadeMode。
方法说明¶
Variant get_instance_shader_parameter ( StringName name ) const
获取在该实例上设置的着色器参数值。
void set_instance_shader_parameter ( StringName name, Variant value )
仅为该实例设置一个着色器 uniform 值（每实例 uniform） 。另请参阅 ShaderMaterial.set_shader_parameter 以使用相同的 ShaderMaterial 在所有实例上分配一个 uniform。
注意：要在每个实例的基础上分配一个着色器 uniform，则必须在着色器代码中，使用 instance uniform ...，而不是 uniform ... 来定义。
注意：name 是区分大小写的，并且必须与代码中的 uniform 名称完全匹配（而不是检查器中大写的名称）。
注意：逐实例着色器 uniform 目前仅在 3D 中可用，因此没有该方法的 2D 等效方法。