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() 以取得更可靠的結果。