Area2D

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

2D 空間中的一個區域，能夠偵測到其他 CollisionObject2D 的進入或退出。

說明

Area2D 是 2D 空間中的一個區域，由一個或多個 CollisionShape2D 或 CollisionPolygon2D 子節點定義，能夠偵測其他 CollisionObject2D 進入或離開，並持續追蹤尚未離開的碰撞物件（亦即仍與其重疊的物件）。

此節點亦可在區域內局部調整或覆寫物理參數（重力、阻尼），並將音訊導向自訂音訊匯流排。

注意： 以 PhysicsServer2D 建立的 Area 或剛體可能無法與 Area2D 如預期互動，亦可能無法正確發出訊號或追蹤物件。

教學

屬性

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`

方法

Array[Area2D]	get_overlapping_areas() const
Array[Node2D]	get_overlapping_bodies() const
bool	has_overlapping_areas() const
bool	has_overlapping_bodies() const
bool	overlaps_area(area: Node) const
bool	overlaps_body(body: Node) const

訊號

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 節點：

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 節點：

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 與本區域相交或重疊則回傳 true，否則回傳 false。

注意： 測試結果並非物件移動後立即更新。基於效能，本區域的重疊清單於每影格且物理步驟之前僅更新一次。建議改用訊號。

bool overlaps_body(body: Node) const 🔗

若指定的物理物件與本區域相交或重疊則回傳 true，否則回傳 false。

注意： 測試結果並非物件移動後立即更新。基於效能，重疊清單於每影格且物理步驟之前僅更新一次。建議改用訊號。

body 可為 PhysicsBody2D 或 TileMap 實例。雖然 TileMap 本身不是物理物件，但其含碰撞形狀的圖塊會註冊為虛擬物理物件。