Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
Area3D¶
继承： CollisionObject3D < Node3D < Node < Object
3D 空间中的一个区域，能够检测到其他 CollisionObject3D 的进入或退出。
描述¶
Area3D 是 3D 空间中的一个区域，由一个或多个 CollisionShape3D 或 CollisionPolygon3D 子节点定义，能够检测到其他 CollisionObject3D 进入或退出该区域，同时也会记录哪些碰撞对象尚未退出（即哪些对象与其存在重叠）。
这个节点也可以在局部修改或覆盖物理参数（重力、阻尼），将音频引导至自定义音频总线。
警告：在这个节点的 CollisionShape3D 子节点中使用 ConcavePolygonShape3D（创建方法是在选中 MeshInstance3D 节点后，在出现的 Mesh 菜单中选择创建三角网格碰撞同级选项）可能得到意外的结果，因为碰撞形状是空心的。如果不想要这种行为，则应该将其拆分为多个 ConvexPolygonShape3D 或 BoxShape3D 等基础网格，有些情况下也可以用 CollisionPolygon3D 代替。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法¶
get_overlapping_areas ( ) const |
|
get_overlapping_bodies ( ) const |
|
has_overlapping_areas ( ) const |
|
has_overlapping_bodies ( ) const |
|
overlaps_area ( Node area ) const |
|
overlaps_body ( Node body ) const |
信号¶
area_entered ( Area3D area )
当接收的 area 进入此区域时发出。需要 monitoring 被设置为 true。
area_exited ( Area3D area )
当接收的 area 退出此区域时发出。需要 monitoring 被设置为 true。
area_shape_entered ( RID area_rid, Area3D area, int area_shape_index, int local_shape_index )
当收到的 area 的 Shape3D 进入这个区域的形状时发出。要求 monitoring 被设置为 true 。
local_shape_index 和 area_shape_index 分别包含来自这个区域和另一个区域的交互形状的索引。area_rid 包含另一个区域的 RID。这些值可以与 PhysicsServer3D 一起使用。
从形状索引中获取 CollisionShape3D 节点的例子。
var other_shape_owner = area.shape_find_owner( area_shape_index)
var other_shape_node = area.shape_owner_get_owner(other_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
area_shape_exited ( RID area_rid, Area3D area, int area_shape_index, int local_shape_index )
当接收的 area 的 Shape3D 退出此区域的形状时发出。需要 monitoring 被设置为 true。
body_entered ( Node3D body )
当接收到的 body 进入这个区域时发出。body 可以是一个 PhysicsBody3D 或一个 GridMap。如果 GridMap 的 MeshLibrary 配置了碰撞形状就会被检测到。需要将 monitoring 设置为 true 。
body_exited ( Node3D body )
当接收到的 body 离开这个区域时发出的。body 可以是一个 PhysicsBody3D 或一个 GridMap。如果 GridMap 的 MeshLibrary 配置了碰撞形状，就会被检测到。要求 monitoring 被设置为 true 。
body_shape_entered ( RID body_rid, Node3D body, int body_shape_index, int local_shape_index )
当接收到的物体 body 中的某个 Shape3D 进入此区域中的某个形状时发出。body 可以是 PhysicsBody3D 或 GridMap。GridMap 的 MeshLibrary 配置有碰撞形状时才能够被检测到。要求将 monitoring 设置为 true。
local_shape_index 和 body_shape_index 分别对应此区域中以及交互物体中正在进行交互的形状的索引。body_rid 包含该物体的 RID。这些值可以在 PhysicsServer3D 中使用。
根据形状索引获取 CollisionShape3D 节点的示例：
var body_shape_owner = body.shape_find_owner(body_shape_index)
var body_shape_node = body.shape_owner_get_owner(body_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
body_shape_exited ( RID body_rid, Node3D body, int body_shape_index, int local_shape_index )
当接收到的物体 body 中的某个 Shape3D 离开此区域中的某个形状时发出。body 可以是 PhysicsBody3D 或 GridMap。GridMap 的 MeshLibrary 配置有碰撞形状时才能够被检测到。要求将 monitoring 设置为 true。
枚举¶
enum SpaceOverride:
SpaceOverride SPACE_OVERRIDE_DISABLED = 0
这个区域不影响重力/阻尼。
SpaceOverride SPACE_OVERRIDE_COMBINE = 1
该区域将其重力/阻尼值加到迄今为止计算出的任何值上（按 priority 排序）。
SpaceOverride SPACE_OVERRIDE_COMBINE_REPLACE = 2
该区域将其重力/阻尼值添加到到目前为止已计算的任何内容（按 priority 顺序），而忽略任何较低优先级的区域。
SpaceOverride SPACE_OVERRIDE_REPLACE = 3
该区域将替换所有重力/阻尼，甚至是默认值，而忽略任何较低优先级的区域。
SpaceOverride SPACE_OVERRIDE_REPLACE_COMBINE = 4
这个区域取代了到目前为止计算出的任何重力/阻尼（按 priority 顺序），但继续计算其余的区域。
属性说明¶
float angular_damp = 0.1
物体在此区域停止旋转的速度。代表每秒损失的角速度.
关于阻尼的更多细节，见 ProjectSettings.physics/3d/default_angular_damp。
SpaceOverride angular_damp_space_override = 0
void set_angular_damp_space_override_mode ( SpaceOverride value )
SpaceOverride get_angular_damp_space_override_mode ( )
此区域内的角阻尼计算的覆盖模式。有关可能的值，请参阅 SpaceOverride。
StringName audio_bus_name = &"Master"
void set_audio_bus_name ( StringName value )
StringName get_audio_bus_name ( )
该区域音频总线的名称。
bool audio_bus_override = false
如果为 true，该区域的音频总线将覆盖默认的音频总线。
float gravity = 9.8
该区域的重力强度（以米每平方秒为单位）。这个值是重力向量的倍数。这对于改变重力大小而不改变其方向很有用。
Vector3 gravity_direction = Vector3(0, -1, 0)
该区域的重力向量（未归一化）。
bool gravity_point = false
如果为 true，则从一个点（通过 gravity_point_center 设置）计算重力。参阅 gravity_space_override。
Vector3 gravity_point_center = Vector3(0, -1, 0)
如果重力是一个点（参见 gravity_point），这将是吸引力点。
float gravity_point_unit_distance = 0.0
重力强度等于 gravity 的距离。例如，在一个半径为 100 米、表面重力为 4.0 m/s² 的行星上，将 gravity 设置为 4.0，将单位距离设置为 100.0。重力会根据平方反比定律衰减，因此在该示例中，距中心 200 米处的重力将为 1.0 m/s²（距离的两倍，重力的 1/4），在 50 米处为 16.0 m/s²（距离的一半，重力的 4 倍），依此类推。
仅当单位距离为正数时，上述情况才成立。当该属性被设置为 0.0 时，无论距离如何，重力都将保持不变。
SpaceOverride gravity_space_override = 0
void set_gravity_space_override_mode ( SpaceOverride value )
SpaceOverride get_gravity_space_override_mode ( )
该区域内重力计算的覆盖模式。有关可能的值，请参阅 SpaceOverride。
float linear_damp = 0.1
实体在此区域减速的速率。代表每秒损失的线速度。
关于阻尼的更多细节，见ProjectSettings.physics/3d/default_linear_damp。
SpaceOverride linear_damp_space_override = 0
void set_linear_damp_space_override_mode ( SpaceOverride value )
SpaceOverride get_linear_damp_space_override_mode ( )
该区域内线性阻尼计算的覆盖模式。可取的值见 SpaceOverride。
bool monitorable = true
如果为 true，其他监测区域可以检测到这个区域。
bool monitoring = true
为 true 时，该区域能够检测到进入和退出该区域的实体或区域。
int priority = 0
该区域的优先级。将优先处理优先级较高的区域。World3D 的物理始终在所有区域之后处理。
float reverb_bus_amount = 0.0
该区域对其相关音频应用混响的程度。范围从 0 到 1，精度为 0.1。
bool reverb_bus_enabled = false
如果为 true，该区域会将混响应用于其关联音频。
StringName reverb_bus_name = &"Master"
void set_reverb_bus_name ( StringName value )
StringName get_reverb_bus_name ( )
用于该区域关联音频的混响总线的名称。
float reverb_bus_uniformity = 0.0
该区域的混响效果均匀的程度。范围从 0 到 1，精度为 0.1。
float wind_attenuation_factor = 0.0
风力随着距其原点的距离而衰减的指数速率。
float wind_force_magnitude = 0.0
特定区域风力的大小。
NodePath wind_source_path = NodePath("")
Node3D 用于指定特定区域风力的方向和原点。方向与 Node3D 局部变换的 z 轴相反，其原点为 Node3D 局部变换的原点。
方法说明¶
Area3D[] get_overlapping_areas ( ) const
返回相交的 Area3D 的列表。重叠区域的 CollisionObject3D.collision_layer 必须是该区域的 CollisionObject3D.collision_mask 的一部分才能被检测到。
出于性能原因（同时处理所有碰撞），此列表在物理步骤期间修改一次，而不是在实体被移动后立即修改。可考虑改用信号。
Node3D[] get_overlapping_bodies ( ) const
返回相交的 PhysicsBody3D 和 GridMap。重叠物体的 CollisionObject3D.collision_layer 必须是该区域 CollisionObject3D.collision_mask 的一部分，才能被检测到。
出于性能原因（所有碰撞都是一起处理的），这个列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。
bool has_overlapping_areas ( ) const
如果与其他 Area3D 相交，则返回 true，否则返回 false。重叠区域的 CollisionObject3D.collision_layer 必须是该区域 CollisionObject3D.collision_mask 的一部分，才能被检测到。
出于性能原因（所有碰撞都是一起处理的），重叠区域的列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。
bool has_overlapping_bodies ( ) const
如果与其他 PhysicsBody3D 或 GridMap 相交，则返回 true，否则返回 false。重叠物体的 CollisionObject3D.collision_layer 必须是该区域 CollisionObject3D.collision_mask 的一部分，才能被检测到。
出于性能原因（所有碰撞都是一起处理的），重叠物体的列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。
bool overlaps_area ( Node area ) const
如果给定的 Area3D 与此 Area3D 相交或重叠，则返回 true，否则返回 false。
注意：测试结果不反映对象移动后的即时状态。出于性能原因，重叠列表每帧只会在物理迭代前更新一次。请考虑使用信号。
bool overlaps_body ( Node body ) const
如果给定的物理物体与此 Area3D 相交或重叠，则返回 true，否则返回 false。
注意：测试结果不反映对象移动后的即时状态。出于性能原因，重叠列表每帧只会在物理迭代前更新一次。请考虑使用信号。
参数 body 可以是 PhysicsBody3D 实例，也可以是 GridMap 实例。GridMap 虽然不是物理物体，但会把图块的碰撞形状注册为虚拟物理物体。