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...

AABB

3D 軸對齊邊界框。

說明

The AABB built-in Variant type represents an axis-aligned bounding box in a 3D space. It is defined by its position and size, which are Vector3. It is frequently used for fast overlap tests (see intersects()). Although AABB itself is axis-aligned, it can be combined with Transform3D to represent a rotated or skewed bounding box.

It uses floating-point coordinates. The 2D counterpart to AABB is Rect2. There is no version of AABB that uses integer coordinates.

Note: Negative values for size are not supported. With negative size, most AABB methods do not work correctly. Use abs() to get an equivalent AABB with a non-negative size.

Note: In a boolean context, an AABB evaluates to false if both position and size are zero (equal to Vector3.ZERO). Otherwise, it always evaluates to true.

備註

使用 C# 操作此 API 時有顯著差異，詳見 C# API 與 GDScript 的不同。

教學

屬性

Vector3

end

Vector3(0, 0, 0)

Vector3

position

Vector3(0, 0, 0)

Vector3

size

Vector3(0, 0, 0)

建構子

AABB

AABB()

AABB

AABB(from: AABB)

AABB

AABB(position: Vector3, size: Vector3)

方法

AABB

abs() const

bool

encloses(with: AABB) const

AABB

expand(to_point: Vector3) const

Vector3

get_center() const

Vector3

get_endpoint(idx: int) const

Vector3

get_longest_axis() const

int

get_longest_axis_index() const

float

get_longest_axis_size() const

Vector3

get_shortest_axis() const

int

get_shortest_axis_index() const

float

get_shortest_axis_size() const

Vector3

get_support(direction: Vector3) const

float

get_volume() const

AABB

grow(by: float) const

bool

has_point(point: Vector3) const

bool

has_surface() const

bool

has_volume() const

AABB

intersection(with: AABB) const

bool

intersects(with: AABB) const

bool

intersects_plane(plane: Plane) const

Variant

intersects_ray(from: Vector3, dir: Vector3) const

Variant

intersects_segment(from: Vector3, to: Vector3) const

bool

is_equal_approx(aabb: AABB) const

bool

is_finite() const

AABB

merge(with: AABB) const

運算子

bool

operator !=(right: AABB)

AABB

operator *(right: Transform3D)

bool

operator ==(right: AABB)

屬性說明

Vector3 end = Vector3(0, 0, 0) 🔗

結束點。通常為邊界框右上後方的角點，等同於 position + size。設定此值會改變 size。

Vector3 position = Vector3(0, 0, 0) 🔗

起始點。通常為邊界框左下前方的角點。

Vector3 size = Vector3(0, 0, 0) 🔗

邊界框自 position 起的寬度、高度與深度。設定此值同時會影響 end。

注意： 建議將寬、高、深設為非負值，因為 Godot 多數方法假設 position 為左下前角， end 為右上後角。若需取得大小為非負的等效邊界框，請使用 abs()。

建構子說明

AABB AABB() 🔗

預設建構 AABB，其 position 與 size 皆為 Vector3.ZERO。

AABB AABB(from: AABB)

建構給定 AABB 的副本。

AABB AABB(position: Vector3, size: Vector3)

以指定的 position 與 size 建立 AABB。

方法說明

AABB abs() const 🔗

傳回與此邊界框等效、且寬度、高度與深度皆為非負值的 AABB。

var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
var absolute = box.abs()
print(absolute.position) # 輸出 (-15.0, -10.0, 0.0)
print(absolute.size)     # 輸出 (20.0, 10.0, 5.0)

注意： 當 size 為負值時，建議先呼叫本方法，因為 Godot 其他方法通常假設 size 的各分量皆大於 0。

bool encloses(with: AABB) const 🔗

若此邊界框可完全包覆 with，則回傳 true。兩者邊緣亦被計入。

var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4))
var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3))
var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8))

print(a.encloses(a)) # Prints true
print(a.encloses(b)) # Prints true
print(a.encloses(c)) # Prints false

AABB expand(to_point: Vector3) const 🔗

傳回此邊界框的副本；如有需要，會擴張至其邊緣與給定的 to_point 對齊。

var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))

box = box.expand(Vector3(10, 0, 0))
print(box.position) # Prints (0.0, 0.0, 0.0)
print(box.size)     # Prints (10.0, 2.0, 5.0)

box = box.expand(Vector3(-5, 0, 5))
print(box.position) # Prints (-5.0, 0.0, 0.0)
print(box.size)     # Prints (15.0, 2.0, 5.0)

Vector3 get_center() const 🔗

傳回此邊界框的中心點。等同於 position + (size / 2.0)。

Vector3 get_endpoint(idx: int) const 🔗

Returns the position of one of the 8 vertices that compose this bounding box. With an idx of 0 this is the same as position, and an idx of 7 is the same as end.

Vector3 get_longest_axis() const 🔗

傳回此邊界框 size 最長軸向的單位向量，為 Vector3（可能為 Vector3.RIGHT、Vector3.UP 或 Vector3.BACK）。

var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))

print(box.get_longest_axis())       # Prints (0.0, 0.0, 1.0)
print(box.get_longest_axis_index()) # Prints 2
print(box.get_longest_axis_size())  # Prints 8.0

另請參閱 get_longest_axis_index() 與 get_longest_axis_size()。

int get_longest_axis_index() const 🔗

傳回此邊界框 size 最長軸的索引（參見 Vector3.AXIS_X、Vector3.AXIS_Y、Vector3.AXIS_Z）。

範例請見 get_longest_axis()。

float get_longest_axis_size() const 🔗

傳回此邊界框 size 最長的尺寸。

範例請見 get_longest_axis()。

Vector3 get_shortest_axis() const 🔗

傳回此邊界框 size 最短軸向的單位向量，為 Vector3（可能為 Vector3.RIGHT、Vector3.UP 或 Vector3.BACK）。

var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))

print(box.get_shortest_axis())       # Prints (1.0, 0.0, 0.0)
print(box.get_shortest_axis_index()) # Prints 0
print(box.get_shortest_axis_size())  # Prints 2.0

另請參閱 get_shortest_axis_index() 與 get_shortest_axis_size()。

int get_shortest_axis_index() const 🔗

傳回此邊界框 size 最短軸的索引（參見 Vector3.AXIS_X、Vector3.AXIS_Y、Vector3.AXIS_Z）。

範例請見 get_shortest_axis()。

float get_shortest_axis_size() const 🔗

傳回此邊界框 size 最短的尺寸。

範例請見 get_shortest_axis()。

Vector3 get_support(direction: Vector3) const 🔗

回傳在指定方向上距離最遠的頂點位置（支援點），常用於碰撞偵測演算法。

float get_volume() const 🔗

傳回此邊界框的體積。等同於 size.x * size.y * size.z。另請參閱 has_volume()。

AABB grow(by: float) const 🔗

傳回在所有方向上以 by 數值擴張後的此邊界框副本。若 by 為負，則改為收縮。

var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
print(a.position) # Prints (0.0, 0.0, 0.0)
print(a.size)     # Prints (16.0, 16.0, 16.0)

var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2)
print(b.position) # Prints (-2.0, -2.0, -2.0)
print(b.size)     # Prints (12.0, 8.0, 6.0)

bool has_point(point: Vector3) const 🔗

若此邊界框包含給定的 point，則回傳 true。依慣例，恰位於右側、上側與後側邊緣的點不會被計入。

注意： 對於大小為負值的 AABB，此方法不可靠；請先使用 abs() 取得有效的邊界框。

bool has_surface() const 🔗

若此邊界框具備面積或長度（至少有一個 size 分量大於 0），則回傳 true；否則為 false。

bool has_volume() const 🔗

若此邊界框的寬度、高度與深度皆為正值，則回傳 true。另請參閱 get_volume()。

AABB intersection(with: AABB) const 🔗

傳回此邊界框與 with 的交集。如果兩框不相交，則回傳空的 AABB。若僅於邊緣相交，則回傳沒有體積的扁平 AABB（參見 has_surface() 與 has_volume()）。

var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8))
var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))

var intersection = box1.intersection(box2)
print(intersection.position) # Prints (2.0, 0.0, 2.0)
print(intersection.size)     # Prints (3.0, 2.0, 4.0)

注意： 若僅需判斷兩邊界框是否相交，請改用 intersects()。

bool intersects(with: AABB) const 🔗

若此邊界框與 with 發生重疊，則回傳 true。兩者邊緣皆被排除。

bool intersects_plane(plane: Plane) const 🔗

若此邊界框同時位於指定 plane 的兩側，則回傳 true。

Variant intersects_ray(from: Vector3, dir: Vector3) const 🔗

回傳此邊界框與指定射線的第一個交點，型別為 Vector3；若無交點則回傳 null。

射線從 from 出發，方向為 dir，並延伸至無限遠。

Variant intersects_segment(from: Vector3, to: Vector3) const 🔗

回傳此邊界框與指定線段的第一個交點，型別為 Vector3；若無交點則回傳 null。

線段起於 from，止於 to。

bool is_equal_approx(aabb: AABB) const 🔗

若此邊界框與 aabb 近似相等（透過分別對 position 與 size 呼叫 Vector3.is_equal_approx()），則回傳 true。

bool is_finite() const 🔗

若此邊界框的值皆為有限數（透過對 position 與 size 呼叫 Vector3.is_finite()），則回傳 true。

AABB merge(with: AABB) const 🔗

傳回同時包覆此邊界框與 with 的 AABB。另請參閱 encloses()。

運算子說明

bool operator !=(right: AABB) 🔗

若兩邊界框的 position 或 size 不相等，則回傳 true。

注意： 由於浮點誤差，建議改用 is_equal_approx() 以取得更可靠的結果。

AABB operator *(right: Transform3D) 🔗

將此 AABB 以給定的 Transform3D 逆向變換（乘法）並回傳結果，前提為該變換基底為正交單位矩陣（可含旋轉／鏡射，但不含縮放／斜切）。

aabb * transform 等價於 transform.inverse() * aabb。詳見 Transform3D.inverse()。

若需對仿射變換（包含縮放）的逆變換，可使用 transform.affine_inverse() * aabb。詳見 Transform3D.affine_inverse()。

bool operator ==(right: AABB) 🔗

若兩邊界框的 position 與 size 完全相等，則回傳 true。

注意： 由於浮點誤差，建議改用 is_equal_approx() 以取得更可靠的結果。