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
基于几何图形的视觉实例的基础节点。
描述
基于几何图形的视觉实例的基础节点。分享一些共同的机制，如可见性和自定义材质。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
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
禁用全局照明模式。用于对全局照明没有贡献的动态对象（例如角色）。使用 VoxelGI 和 SDFGI 时，几何体将接收间接照明和反射，但在 GI 烘焙中不会考虑几何体。
GIMode GI_MODE_STATIC = 1
烘焙全局照明模式。用于有助于全局照明的静态对象（例如关卡几何体）。该 GI 模式在使用 VoxelGI、SDFGI 和 LightmapGI 时有效。
GIMode GI_MODE_DYNAMIC = 2
动态全局照明模式。用于有助于全局照明的动态对象。这种 GI 模式只有在使用 VoxelGI 时才有效，但它对性能的影响，比 GI_MODE_STATIC 更高。当使用其他 GI 方法时，它的作用与 GI_MODE_DISABLED 相同。使用 LightmapGI 时，对象将使用光照贴图探针接收间接光照，而不是使用烘焙的光照贴图纹理。
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
当达到自身可见范围的极限时，会自行淡出。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。
注意：仅支持使用 Forward+ 渲染方法。使用 Mobile 或 Compatibility 渲染方法时，该模式与 VISIBILITY_RANGE_FADE_DISABLED 类似，但会禁用迟滞。
VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DEPENDENCIES = 2
当达到其自身可见性范围的限制时，将淡入其可见性依赖项（见 Node3D.visibility_parent）。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。
注意：仅支持使用 Forward+ 渲染方法。使用 Mobile 或 Compatibility 渲染方法时，该模式与 VISIBILITY_RANGE_FADE_DISABLED 类似，但会禁用迟滞。
属性说明
ShadowCastingSetting cast_shadow = 1 🔗
void set_cast_shadows_setting(value: ShadowCastingSetting)
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(value: LightmapScale)
LightmapScale get_lightmap_scale()
已弃用： Use gi_lightmap_texel_scale instead.
LightmapGI 进行光照贴图时使用的纹素密度。
float gi_lightmap_texel_scale = 1.0 🔗
LightmapGI 中用于光照贴图的纹素密度。较大的缩放值可在光照贴图中提供更高的分辨率，如果灯光同时烘焙了直接光和间接光，阴影就会更加锐利。不过较大的缩放值也会增加网格在光照贴图纹理中占用的空间，导致所需内存、存储空间、烘焙时间的增加。在不同缩放下使用同一个网格时，请考虑调整该值，让光照贴图纹素密度在不同网格之间保持一致。
例如，将 gi_lightmap_texel_scale 翻倍会让物体的光照贴图纹理在每个方向上的分辨率都翻倍，导致纹素数量变为原来的四倍。
用于整个几何体的全局照明模式。为避免结果不一致，请在游戏过程中，使用与网格用途相匹配的模式（静态/动态）。
注意：灯光的烘焙模式，也会影响全局照明渲染。请参阅 Light3D.light_bake_mode。
bool ignore_occlusion_culling = false 🔗
如果为 true，则禁用这个实例的遮挡剔除。可用于即便开启遮挡剔除也必须渲染的小工具。
注意：ignore_occlusion_culling 不会影响视锥剔除（对象因为相机的角度而不可见时触发）。要避免视锥剔除，请将 custom_aabb 设置为很大的 AABB，覆盖住整个游戏世界，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。
改变网格过渡到较低细节级别的速度。值为 0 将强制网格达到最低细节级别，值为 1 将使用默认设置，更大的值将使网格在更远的距离处保持更高的细节级别。
对于测试编辑器中的细节级别的过渡很有用。
整个几何体的材质覆盖层。
如果一个材质被分配给这个属性，它将会被渲染在所有表面的任何其他活动材质之上。
整个几何体的材质覆盖。
如果一个材质被分配给这个属性，它将会被用来代替在网格的任何材质槽中设置的任何材质。
应用于整个几何体的透明度（作为材质现有透明度的乘数）。0.0 是完全不透明的，而 1.0 是完全透明的。大于 0.0（不含）的值将强制几何体的材质通过透明管道，这会导致渲染速度变慢，并且可能会因不正确的透明度排序而出现渲染问题。但是，与使用透明材质不同的是，将 transparency 设置为大于 0.0（不含）的值并不会禁用阴影渲染。
在空间着色器中，1.0 - transparency 被设置为内置 ALPHA 的默认值。
注意：transparency 被钳制在 0.0 和 1.0 之间，所以这个属性不能被用来使透明材质变得比原来更加不透明。
注意：仅在使用 Forward+ 渲染方法时受支持。使用 Mobile 或 Compatibility 渲染方法时，transparency 将被忽略并被视为始终为 0.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(value: VisibilityRangeFadeMode)
VisibilityRangeFadeMode get_visibility_range_fade_mode()
控制在接近可见范围的限制时，哪些实例将被淡化。有关可能的值，请参阅 VisibilityRangeFadeMode。
方法说明
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 着色器中可用，在 Fog、Sky、Particles 着色器中不可用。