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...
Area3D
继承： CollisionObject3D < Node3D < Node < Object
3D 空间中的一个区域，能够检测到其他 CollisionObject3D 的进入或退出。
描述
Area3D 是 3D 空间中的一个区域，由一个或多个 CollisionShape3D 或 CollisionPolygon3D 子节点定义，能够检测到其他 CollisionObject3D 进入或退出该区域，同时也会记录哪些碰撞对象尚未退出（即哪些对象与其存在重叠）。
这个节点也可以在局部修改或覆盖物理参数（重力、阻尼），将音频引导至自定义音频总线。
注意：使用 PhysicsServer3D 创建的区域和物体可能无法按预期与 Area3D 交互，并且可能无法正确发出信号或跟踪对象。
警告：在这个节点的 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(area: Node) const |
|
overlaps_body(body: Node) const |
信号
当接收的 area 进入此区域时发出。需要 monitoring 被设置为 true。
当接收的 area 退出此区域时发出。需要 monitoring 被设置为 true。
area_shape_entered(area_rid: RID, area: Area3D, area_shape_index: int, local_shape_index: int) 🔗
当收到的 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(area_rid: RID, area: Area3D, area_shape_index: int, local_shape_index: int) 🔗
当接收的 area 的 Shape3D 退出此区域的形状时发出。需要 monitoring 被设置为 true。
当接收到的 body（物体）进入该区域时，将会发出此信号。body 可以是一个 PhysicsBody3D（3D物理刚体）、SoftBody3D（3D软体）或 GridMap（3D网格地图）。如果 GridMap 的 MeshLibrary（网格库）中配置了碰撞形状，它也能被检测到。此功能需要将 monitoring（监控）属性设为 true 才会生效。
注意： Godot Physics（Godot 自带的物理引擎）不支持报告与 SoftBody3D 的重叠状态，因此在这种情况下不会发出此信号。
当接收到的 body 离开该区域时触发（发射）此信号。body 可以是 PhysicsBody3D、SoftBody3D 或 GridMap。如果 GridMap 的 MeshLibrary 配置了碰撞形状，它们也会被检测到。需要将 monitoring 属性设置为 true 才能生效。
注意： Godot Physics（Godot自带的物理引擎）不支持报告与 SoftBody3D 的重叠情况，因此在这种情况下不会触发此信号。
body_shape_entered(body_rid: RID, body: Node3D, body_shape_index: int, local_shape_index: int) 🔗
当接收到的 body（物体）的某个 Shape3D（3D碰撞形状）进入该区域的某个形状时，将会发出此信号。body 可以是一个 PhysicsBody3D（3D物理刚体）、SoftBody3D（3D软体）或 GridMap（3D网格地图）。如果 GridMap 的 MeshLibrary（网格库）中配置了碰撞形状，它也能被检测到。此功能需要将 monitoring（监控）属性设为 true 才会生效。
local_shape_index 和 body_shape_index 分别包含了该区域与发生交互的物体之间，互相碰撞的碰撞形状的索引。body_rid 包含了该物体的 RID（资源ID）。这些值可以配合 PhysicsServer3D（3D物理服务器）来使用。
注意： Godot Physics（Godot 自带的物理引擎）不支持报告与 SoftBody3D 的重叠状态，因此在这种情况下不会发出此信号。
示例： 通过形状索引获取对应的 CollisionShape3D（3D碰撞形状）节点：
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(body_rid: RID, body: Node3D, body_shape_index: int, local_shape_index: int) 🔗
当接收到的 body 的某个 Shape3D（3D形状）离开该区域的一个形状时，触发（发射）此信号。body 可以是 PhysicsBody3D、SoftBody3D 或 GridMap。如果 GridMap 的 MeshLibrary 配置了碰撞形状，它们也会被检测到。需要将 monitoring 属性设置为 true 才能生效。
另请参阅 body_shape_entered（即刚才那个信号）。
注意： Godot Physics（Godot自带的物理引擎）不支持报告与 SoftBody3D 的重叠情况，因此在这种情况下不会触发此信号。
枚举
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 顺序），但仍将继续计算其余区域。
属性说明
物体在此区域停止旋转的速度。代表每秒损失的角速度.
关于阻尼的更多细节，见 ProjectSettings.physics/3d/default_angular_damp。
SpaceOverride angular_damp_space_override = 0 🔗
void set_angular_damp_space_override_mode(value: SpaceOverride)
SpaceOverride get_angular_damp_space_override_mode()
此区域内的角阻尼计算的覆盖模式。
StringName audio_bus_name = &"Master" 🔗
void set_audio_bus_name(value: StringName)
StringName get_audio_bus_name()
该区域音频总线的名称。
bool audio_bus_override = false 🔗
如果为 true，该区域的音频总线将覆盖默认的音频总线。
该区域的重力强度（以米每平方秒为单位）。这个值是重力向量的倍数。这对于改变重力大小而不改变其方向很有用。
Vector3 gravity_direction = Vector3(0, -1, 0) 🔗
该区域的重力向量（未归一化）。
如果为 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(value: SpaceOverride)
SpaceOverride get_gravity_space_override_mode()
该区域内重力计算的覆盖模式。
实体在此区域减速的速率。代表每秒损失的线速度。
关于阻尼的更多细节，见ProjectSettings.physics/3d/default_linear_damp。
SpaceOverride linear_damp_space_override = 0 🔗
void set_linear_damp_space_override_mode(value: SpaceOverride)
SpaceOverride get_linear_damp_space_override_mode()
该区域内线性阻尼计算的覆盖模式。
如果为 true，其他监测区域可以检测到这个区域。
为 true 时，该区域能够检测到进入和退出该区域的实体或区域。
该区域的优先级。将优先处理优先级较高的区域。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(value: StringName)
StringName get_reverb_bus_name()
用于该区域关联音频的混响总线的名称。
float reverb_bus_uniformity = 0.0 🔗
该区域的混响效果均匀的程度。范围从 0 到 1，精度为 0.1。
float wind_attenuation_factor = 0.0 🔗
风力随距离原点的距离而减小的指数速率。
注意：风力仅适用于 SoftBody3D 节点。其他物理体目前不受风的影响。
float wind_force_magnitude = 0.0 🔗
特定区域风力的大小。
注意：风力仅适用于 SoftBody3D 节点。其他物理体目前不受风的影响。
NodePath wind_source_path = NodePath("") 🔗
指定区域风力方向和原点的 Node3D。方向与 Node3D 本地变换的 Z 轴相反，原点为 Node3D 本地变换的原点。
注意：这种风力只适用于 SoftBody3D 节点。其他物理体目前不受风力影响。
方法说明
Array[Area3D] get_overlapping_areas() const 🔗
返回相交的 Area3D 的列表。重叠区域的 CollisionObject3D.collision_layer 必须是该区域的 CollisionObject3D.collision_mask 的一部分才能被检测到。
出于性能的考虑（所有碰撞都是一起处理的），这个列表会在物理迭代时进行一次修改，而不是在实体被移动后立即修改。可考虑改用信号。
Array[Node3D] get_overlapping_bodies() const 🔗
返回一个包含与之相交的 PhysicsBody3D（3D物理刚体）、SoftBody3D（3D软体）和 GridMap（网格地图）的列表。只有当重叠物体的 CollisionObject3D.collision_layer（碰撞层）属于该区域的 CollisionObject3D.collision_mask（碰撞掩码）时，才能被检测到。
出于性能考虑（所有碰撞都在同一时间统一处理），这个列表每帧只会在物理步骤中更新一次，而不会在物体移动后立即更新。因此，建议考虑使用信号（signals）来代替。
注意： Godot Physics（Godot自带的物理引擎）不支持报告与 SoftBody3D 的重叠情况，因此不会返回任何此类物体。
bool has_overlapping_areas() const 🔗
如果与其他 Area3D 相交，则返回 true，否则返回 false。重叠区域的 CollisionObject3D.collision_layer 必须是该区域 CollisionObject3D.collision_mask 的一部分，才能被检测到。
出于性能原因（所有碰撞都是一起处理的），重叠区域的列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。
bool has_overlapping_bodies() const 🔗
如果与任意 PhysicsBody3D（3D物理刚体）、SoftBody3D（3D软体）或 GridMap（3D网格地图）发生重叠，则返回 true，否则返回 false。只有当发生重叠的物体的 CollisionObject3D.collision_layer（碰撞层）包含在该区域的 CollisionObject3D.collision_mask（碰撞掩码）范围内时，才会被检测到。
出于性能原因（所有的碰撞都会在同一个时间点统一处理），重叠物体的列表是在物理帧（physics step）中统一更新一次的，而不是在物体移动后立刻更新。因此，建议考虑使用信号（signals）来替代轮询。
注意： Godot Physics（Godot 自带的物理引擎）不支持报告与 SoftBody3D 的重叠状态，因此不会将软体纳入检测范围。
bool overlaps_area(area: Node) const 🔗
如果给定的 Area3D 与此 Area3D 相交或重叠，则返回 true，否则返回 false。
注意：测试结果不反映对象移动后的即时状态。出于性能原因，重叠列表每帧只会在物理迭代前更新一次。请考虑使用信号。
bool overlaps_body(body: Node) const 🔗
如果指定的物理刚体与该 Area3D 相交或重叠，则返回 true，否则返回 false。
body 参数可以是 PhysicsBody3D、SoftBody3D 或 GridMap 的实例。虽然 GridMap 本身不是物理刚体，但它会将自己带有碰撞形状的图块作为一个虚拟的物理刚体进行注册。
注意： 在移动物体后，此测试的结果不会立即更新。出于性能考虑，重叠列表每帧更新一次，并且是在物理步骤之前。因此，建议考虑使用信号（signals）来代替。
注意： Godot Physics（Godot自带的物理引擎）不支持报告与 SoftBody3D 的重叠情况，因此在这种情况下会返回 false。