Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Area2D

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

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

描述

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

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

教程

属性

float

angular_damp

1.0

SpaceOverride

angular_damp_space_override

0

StringName

audio_bus_name

&"Master"

bool

audio_bus_override

false

float

gravity

980.0

Vector2

gravity_direction

Vector2(0, 1)

bool

gravity_point

false

Vector2

gravity_point_center

Vector2(0, 1)

float

gravity_point_unit_distance

0.0

SpaceOverride

gravity_space_override

0

float

linear_damp

0.1

SpaceOverride

linear_damp_space_override

0

bool

monitorable

true

bool

monitoring

true

int

priority

0

方法

Area2D[]

get_overlapping_areas ( ) const

Node2D[]

get_overlapping_bodies ( ) const

bool

has_overlapping_areas ( ) const

bool

has_overlapping_bodies ( ) const

bool

overlaps_area ( Node area ) const

bool

overlaps_body ( Node body ) const


信号

area_entered ( Area2D area )

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


area_exited ( Area2D area )

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


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

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

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

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

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

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

另见 area_shape_entered


body_entered ( Node2D body )

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


body_exited ( Node2D body )

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


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

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

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

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

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

当收到的 bodyShape2D 退出这个区域的形状时发出。body 可以是一个 PhysicsBody2D 或一个 TileMap。如果 TileMapTileSet 配置了碰撞形状,则会被检测到。要求 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 ( float value )

  • float get_angular_damp ( )

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

关于阻尼的更多细节见 ProjectSettings.physics/2d/default_angular_damp


SpaceOverride angular_damp_space_override = 0

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


StringName audio_bus_name = &"Master"

该区域音频总线的名称。


bool audio_bus_override = false

  • void set_audio_bus_override ( bool value )

  • bool is_overriding_audio_bus ( )

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


float gravity = 980.0

  • void set_gravity ( float value )

  • float get_gravity ( )

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


Vector2 gravity_direction = Vector2(0, 1)

  • void set_gravity_direction ( Vector2 value )

  • Vector2 get_gravity_direction ( )

该区域的重力向量(未归一化)。


bool gravity_point = false

  • void set_gravity_is_point ( bool value )

  • bool is_gravity_a_point ( )

如果为 true,则从一个点(通过 gravity_point_center 设置)计算重力。参阅 gravity_space_override


Vector2 gravity_point_center = Vector2(0, 1)

  • void set_gravity_point_center ( Vector2 value )

  • Vector2 get_gravity_point_center ( )

如果重力是一个点(参见 gravity_point),这将是吸引力点。


float gravity_point_unit_distance = 0.0

  • void set_gravity_point_unit_distance ( float value )

  • 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

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


float linear_damp = 0.1

  • void set_linear_damp ( float value )

  • float get_linear_damp ( )

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

关于阻尼的更多细节见 ProjectSettings.physics/2d/default_linear_damp


SpaceOverride linear_damp_space_override = 0

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


bool monitorable = true

  • void set_monitorable ( bool value )

  • bool is_monitorable ( )

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


bool monitoring = true

  • void set_monitoring ( bool value )

  • bool is_monitoring ( )

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


int priority = 0

  • void set_priority ( int value )

  • int get_priority ( )

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


方法说明

Area2D[] get_overlapping_areas ( ) const

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

出于性能的考虑(所有碰撞都是一起处理的),这个列表会在物理步骤中进行一次修改,而不是在物体被移动后立即修改。可考虑改用信号。


Node2D[] get_overlapping_bodies ( ) const

返回相交的 PhysicsBody2DTileMap。重叠物体的 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

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

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


bool overlaps_area ( Node area ) const

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

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


bool overlaps_body ( Node body ) const

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

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

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