Area2D

继承： CollisionObject2D < Node2D < CanvasItem < Node < Object

2D 空间中的一个区域，能够检测到其他 CollisionObject2D 的进入或退出。

描述

Area2D 是 2D 空间中的一个区域，由一个或多个 CollisionShape2D 或 CollisionPolygon2D 子节点定义，能够检测到其他 CollisionObject2D 进入或退出该区域，同时也会记录哪些碰撞对象尚未退出（即哪些对象与其存在重叠）。

这个节点也可以在局部修改或覆盖物理参数（重力、阻尼），将音频引导至自定义音频总线。

注意：使用 PhysicsServer2D 创建的区域和物体可能无法按预期与 Area2D 交互，并且可能无法正确发出信号或跟踪对象。

教程

• 使用 Area2D

• 2D Dodge The Creeps 演示

• 2D Pong 演示

• 2D 平台跳跃演示

属性

方法

信号

area_entered(area: Area2D) 🔗

当接收的 area 进入此区域时发出。需要 monitoring 被设置为 true。

area_exited(area: Area2D) 🔗

当接收的 area 退出此区域时发出。需要 monitoring 被设置为 true。

area_shape_entered(area_rid: RID, area: Area2D, area_shape_index: int, local_shape_index: int) 🔗

当收到的 area 的 Shape2D 进入这个区域的形状时发出。要求 monitoring 被设置为 true 。

local_shape_index 和 area_shape_index 分别包含来自这个区域和另一个区域的交互形状的索引。area_rid 包含另一个区域的 RID。这些值可以与 PhysicsServer2D 一起使用。

从形状索引中获取 CollisionShape2D节点的例子：

GDScript

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: Area2D, area_shape_index: int, local_shape_index: int) 🔗

当接收的 area 的 Shape2D 退出此区域的形状时发出。需要 monitoring 被设置为 true。

另见 area_shape_entered。

body_entered(body: Node2D) 🔗

当接收到的 body 进入这个区域时发出的。body 可以是一个 PhysicsBody2D 或一个 TileMap。如果 TileMap 的 TileSet 配置了碰撞形状，就会被检测到。需要将 monitoring 设置为 true 。

body_exited(body: Node2D) 🔗

当接收到的 body 离开这个区域时发出的。body 可以是一个 PhysicsBody2D 或一个 TileMap。如果 TileMap 的 TileSet 配置了碰撞形状，就会被检测到。要求 monitoring 被设置为 true 。

body_shape_entered(body_rid: RID, body: Node2D, body_shape_index: int, local_shape_index: int) 🔗

当收到的 body 的 Shape2D 进入这个区域的形状时发出。body 可以是一个 PhysicsBody2D 或一个 TileMap。如果 TileMap 的 TileSet 配置了碰撞形状，则会被检测到。要求 monitoring 被设置为 true 。

local_shape_index 和 body_shape_index 分别包含来自这个区域和交互体的交互形状的指数。body_rid 包含体的 RID。这些值可以与 PhysicsServer2D 一起使用。

从形状索引中获取 CollisionShape2D 节点的例子。

GDScript

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: Node2D, body_shape_index: int, local_shape_index: int) 🔗

当收到的 body 的 Shape2D 退出这个区域的形状时发出。body 可以是一个 PhysicsBody2D 或一个 TileMap。如果 TileMap 的 TileSet 配置了碰撞形状，则会被检测到。要求 monitoring 被设置为 true 。

另请参阅 body_shape_entered。

枚举

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 = 1.0 🔗

• void set_angular_damp(value: float)

• float get_angular_damp()

物体在此区域停止旋转的速度。代表每秒损失的角速度。

关于阻尼的更多细节见 ProjectSettings.physics/2d/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()

此区域内的角阻尼计算的覆盖模式。有关可能的值，请参阅 SpaceOverride。

StringName audio_bus_name = &"Master" 🔗

• void set_audio_bus_name(value: StringName)

• StringName get_audio_bus_name()

该区域音频总线的名称。

bool audio_bus_override = false 🔗

• void set_audio_bus_override(value: bool)

• bool is_overriding_audio_bus()

如果为 true，该区域的音频总线将覆盖默认的音频总线。

float gravity = 980.0 🔗

• void set_gravity(value: float)

• float get_gravity()

该区域的重力强度（以像素每平方秒为单位）。这个值是重力向量的倍数。这对于改变重力大小而不改变其方向很有用。

Vector2 gravity_direction = Vector2(0, 1) 🔗

• void set_gravity_direction(value: Vector2)

• Vector2 get_gravity_direction()

该区域的重力向量（未归一化）。

bool gravity_point = false 🔗

• void set_gravity_is_point(value: bool)

• bool is_gravity_a_point()

如果为 true，则从一个点（通过 gravity_point_center 设置）计算重力。参阅 gravity_space_override。

Vector2 gravity_point_center = Vector2(0, 1) 🔗

• void set_gravity_point_center(value: Vector2)

• Vector2 get_gravity_point_center()

如果重力是一个点（参见 gravity_point），这将是吸引力点。

float gravity_point_unit_distance = 0.0 🔗

• void set_gravity_point_unit_distance(value: float)

• float get_gravity_point_unit_distance()

重力强度等于 gravity 的距离。例如，在一个半径为 100 像素、表面重力为 4.0 px/s² 的行星上，将 gravity 设置为 4.0，将单位距离设置为 100.0。重力将根据平方反比定律衰减，因此在该示例中，距离中心 200 像素处的重力将为 1.0 px/s²（距离的两倍，重力的 1/4），距离 50 像素处为 16.0 px/s²（距离的一半，重力的 4 倍），依此类推。

仅当单位距离为正数时，上述情况才成立。当该属性被设置为 0.0 时，无论距离如何，重力都将保持不变。

SpaceOverride gravity_space_override = 0 🔗

• void set_gravity_space_override_mode(value: SpaceOverride)

• SpaceOverride get_gravity_space_override_mode()

该区域内重力计算的覆盖模式。有关可能的值，请参阅 SpaceOverride。

float linear_damp = 0.1 🔗

• void set_linear_damp(value: float)

• float get_linear_damp()

物体在此区域停止运动的速度。代表每秒损失的线速度。

关于阻尼的更多细节见 ProjectSettings.physics/2d/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()

该区域内线性阻尼计算的覆盖模式。可取的值见 SpaceOverride。

bool monitorable = true 🔗

• void set_monitorable(value: bool)

• bool is_monitorable()

如果为 true，其他监测区域可以检测到这个区域。

bool monitoring = true 🔗

• void set_monitoring(value: bool)

• bool is_monitoring()

为 true 时，该区域能够检测到进入和退出该区域的实体或区域。

int priority = 0 🔗

• void set_priority(value: int)

• int get_priority()

该区域的优先级。将优先处理优先级较高的区域。World2D 的物理始终在所有区域之后处理。

方法说明

Array[Area2D] get_overlapping_areas() const 🔗

返回相交的 Area2D 的列表。重叠区域的 CollisionObject2D.collision_layer 必须是这个区域 CollisionObject2D.collision_mask 的一部分，这样才能被检测到。

出于性能的考虑（所有碰撞都是一起处理的），这个列表会在物理迭代时进行一次修改，而不是在物体被移动后立即修改。可考虑改用信号。

Array[Node2D] get_overlapping_bodies() const 🔗

返回相交的 PhysicsBody2D 和 TileMap。重叠物体的 CollisionObject2D.collision_layer 必须是该区域 CollisionObject2D.collision_mask 的一部分，才能被检测到。

出于性能原因（所有碰撞都是一起处理的），这个列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。

bool has_overlapping_areas() const 🔗

如果与其他 Area2D 相交，则返回 true，否则返回 false。重叠区域的 CollisionObject2D.collision_layer 必须是该区域 CollisionObject2D.collision_mask 的一部分，才能被检测到。

出于性能原因（所有碰撞都是一起处理的），重叠区域的列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。

bool has_overlapping_bodies() const 🔗

如果与其他 PhysicsBody2D 或 TileMap 相交，则返回 true，否则返回 false。重叠物体的 CollisionObject2D.collision_layer 必须是该区域 CollisionObject2D.collision_mask 的一部分，才能被检测到。

出于性能原因（所有碰撞都是一起处理的），重叠物体的列表只会在每次物理迭代时发生一次更改，不会在对象移动后立即更改。请考虑使用信号。

bool overlaps_area(area: Node) const 🔗

如果给定的 Area2D 与此 Area2D 相交或重叠，则返回 true，否则返回 false。

注意：测试结果不反映对象移动后的即时状态。出于性能原因，重叠列表每帧只会在物理迭代前更新一次。请考虑使用信号。

bool overlaps_body(body: Node) const 🔗

如果给定的物理物体与此 Area2D 相交或重叠，则返回 true，否则返回 false。

注意：测试结果不反映对象移动后的即时状态。出于性能原因，重叠列表每帧只会在物理迭代前更新一次。请考虑使用信号。

参数 body 可以是 PhysicsBody2D 实例，也可以是 TileMap 实例。TileMap 虽然不是物理物体，但会把图块的碰撞形状注册为虚拟物理物体。