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 建立的 Area 與剛體可能與 Area3D 的互動不如預期，亦可能無法正確發送訊號或追蹤物件。

警告： 若在本節點的 CollisionShape3D 子節點中使用 ConcavePolygonShape3D（例如在選取 MeshInstance3D 後於 Mesh 功能表選擇 Create Trimesh Collision Sibling 建立），因為該碰撞形狀為中空，可能產生非預期結果。如不希望如此，請將其拆分為多個 ConvexPolygonShape3D 或 BoxShape3D 等基礎形狀；某些情況下亦可改用 CollisionPolygon3D。

教學

屬性

float	angular_damp	`0.1`
SpaceOverride	angular_damp_space_override	`0`
StringName	audio_bus_name	`&"Master"`
bool	audio_bus_override	`false`
float	gravity	`9.8`
Vector3	gravity_direction	`Vector3(0, -1, 0)`
bool	gravity_point	`false`
Vector3	gravity_point_center	`Vector3(0, -1, 0)`
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`
float	reverb_bus_amount	`0.0`
bool	reverb_bus_enabled	`false`
StringName	reverb_bus_name	`&"Master"`
float	reverb_bus_uniformity	`0.0`
float	wind_attenuation_factor	`0.0`
float	wind_force_magnitude	`0.0`
NodePath	wind_source_path	`NodePath("")`

方法

Array[Area3D]	get_overlapping_areas() const
Array[Node3D]	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: Area3D) 🔗

當接收到的 area 進入此區域時發出。需將 monitoring 設為 true 才能觸發。

area_exited(area: Area3D) 🔗

當接收到的 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。

另見 area_shape_entered。

body_entered(body: Node3D) 🔗

Emitted when the received body enters this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

body_exited(body: Node3D) 🔗

Emitted when the received body exits this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

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

Emitted when a Shape3D of the received body enters a shape of this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

local_shape_index and body_shape_index contain indices of the interacting shapes from this area and the interacting body, respectively. body_rid contains the RID of the body. These values can be used with the PhysicsServer3D.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

Example: Get the CollisionShape3D node from the shape index:

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) 🔗

Emitted when a Shape3D of the received body exits a shape of this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to 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 🔗

void set_angular_damp(value: float)
float get_angular_damp()

物體在此區域停止旋轉的速度。代表每秒損失的角速度.

關於阻尼的更多細節，見 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()

此區域內角阻尼計算的覆寫模式。可用值請參閱 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 = 9.8 🔗

void set_gravity(value: float)
float get_gravity()

該區域的重力強度（以米每平方秒為單位）。這個值是重力向量的倍數。這對於改變重力大小而不改變其方向很有用。

Vector3 gravity_direction = Vector3(0, -1, 0) 🔗

void set_gravity_direction(value: Vector3)
Vector3 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。

Vector3 gravity_point_center = Vector3(0, -1, 0) 🔗

void set_gravity_point_center(value: Vector3)
Vector3 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 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()

此區域內重力計算的覆寫模式。可用值請參閱 SpaceOverride。

float linear_damp = 0.1 🔗

void set_linear_damp(value: float)
float get_linear_damp()

實體在此區域減速的速率。代表每秒損失的線速度。

關於阻尼的更多細節，見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()

此區域內線性阻尼計算的覆寫模式。可用值請參閱 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()

該區域的優先順序。將優先處理優先順序較高的區域。World3D 的物理始終在所有區域之後處理。

float reverb_bus_amount = 0.0 🔗

void set_reverb_amount(value: float)
float get_reverb_amount()

該區域對其相關音訊套用混響的程度。範圍從 0 到 1，精度為 0.1。

bool reverb_bus_enabled = false 🔗

void set_use_reverb_bus(value: bool)
bool is_using_reverb_bus()

如果為 true，該區域會將混響套用於其關聯音訊。

StringName reverb_bus_name = &"Master" 🔗

void set_reverb_bus_name(value: StringName)
StringName get_reverb_bus_name()

用於該區域關聯音訊的混響匯流排的名稱。

float reverb_bus_uniformity = 0.0 🔗

void set_reverb_uniformity(value: float)
float get_reverb_uniformity()

該區域的混響效果均勻的程度。範圍從 0 到 1，精度為 0.1。

float wind_attenuation_factor = 0.0 🔗

void set_wind_attenuation_factor(value: float)
float get_wind_attenuation_factor()

風力隨與源點距離增加而呈指數遞減的速率。

注意： 風力僅作用於 SoftBody3D 節點，其他物理物體目前不受影響。

float wind_force_magnitude = 0.0 🔗

void set_wind_force_magnitude(value: float)
float get_wind_force_magnitude()

此區域專屬風力的強度大小。

注意： 風力僅作用於 SoftBody3D 節點，其他物理物體目前不受影響。

NodePath wind_source_path = NodePath("") 🔗

void set_wind_source_path(value: NodePath)
NodePath get_wind_source_path()

用以指定此區域風力方向與來源的 Node3D。風向與該節點局部轉換的 z 軸相反，風源則位於其局部原點。

注意： 風力僅作用於 SoftBody3D 節點，其他物理物體目前不受影響。

方法說明

Array[Area3D] get_overlapping_areas() const 🔗

返回相交的 Area3D 的列表。重疊區域的 CollisionObject3D.collision_layer 必須是該區域的 CollisionObject3D.collision_mask 的一部分才能被偵測到。

出於性能原因（同時處理所有碰撞），此列表在物理步驟期間修改一次，而不是在實體被移動後立即修改。可考慮改用訊號。

Array[Node3D] get_overlapping_bodies() const 🔗

Returns a list of intersecting PhysicsBody3Ds, SoftBody3Ds, and GridMaps. The overlapping body's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not return any such bodies.

bool has_overlapping_areas() const 🔗

如果與其他 Area3D 相交，則返回 true，否則返回 false。重疊區域的 CollisionObject3D.collision_layer 必須是該區域 CollisionObject3D.collision_mask 的一部分，才能被偵測到。

出於性能原因（所有碰撞都是一起處理的），重疊區域的列表只會在每次物理反覆運算時發生一次更改，不會在對象移動後立即更改。請考慮使用訊號。

bool has_overlapping_bodies() const 🔗

Returns true if intersecting any PhysicsBody3Ds, SoftBody3Ds, or GridMaps, otherwise returns false. The overlapping body's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not consider such bodies.

bool overlaps_area(area: Node) const 🔗

如果給定的 Area3D 與此 Area3D 相交或重疊，則返回 true，否則返回 false。

注意：測試結果不反映物件移動後的即時狀態。出於性能原因，重疊列表每影格只會在物理反覆運算前更新一次。請考慮使用訊號。

bool overlaps_body(body: Node) const 🔗

Returns true if the given physics body intersects or overlaps this Area3D, false otherwise.

body argument can either be a PhysicsBody3D, SoftBody3D, or a GridMap instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body.

Note: The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will return false in such cases.