AABB

3D 轴对齐边界框。

描述

AABB 内置 Variant 类型表示 3D 空间中的轴对齐边界框。它由其 position 和 size 定义，皆为 Vector3 类型。它经常被用于快速重叠测试（参见 intersects()）。虽然 AABB 本身是轴对齐的，但它可以与 Transform3D 组合来表示旋转或倾斜的边界框。

它使用浮点坐标。AABB 的 2D 等效体是 Rect2。没有使用整数坐标的 AABB 版本。

注意：不支持负的 size。对于负大小，大多数 AABB 方法都无法正常工作。使用 abs() 获取具有非负大小的等效 AABB。

注意：在布尔上下文中，如果 position 和 size 均为零（等于 Vector3.ZERO），则 AABB 的计算结果为 false。否则，它的计算结果始终为 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，其宽度、高度和深度被修改为非负值。

GDScriptC#

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。两个框的边都包括在内。

GDScriptC#

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)) # 打印 true
print(a.encloses(b)) # 打印 true
print(a.encloses(c)) # 打印 false

---

AABB expand(to_point: Vector3) const 🔗

返回该边界框的副本，如有必要，该边界框被扩展为将边与给定的 to_point 对齐。

GDScriptC#

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

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

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

---

Vector3 get_center() const 🔗

返回该边界框的中心点。这与 position + (size / 2.0) 相同。

---

Vector3 get_endpoint(idx: int) const 🔗

返回组成该边界框的 8 个顶点之一的位置。当 idx 为 0 时，这与 position 相同；idx 为 7 时，与 end 相同。

---

Vector3 get_longest_axis() const 🔗

返回该边界框的 size 的最长归一化轴，作为 Vector3（Vector3.RIGHT、Vector3.UP 或 Vector3.BACK）。

GDScriptC#

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

print(box.get_longest_axis())       # 输出 (0.0, 0.0, 1.0)
print(box.get_longest_axis_index()) # 输出 2
print(box.get_longest_axis_size())  # 输出 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）。

GDScriptC#

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

print(box.get_shortest_axis())       # 输出 (1.0, 0.0, 0.0)
print(box.get_shortest_axis_index()) # 输出 0
print(box.get_shortest_axis_size())  # 输出 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。负数会缩小该框。

GDScriptC#

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

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

---

bool has_point(point: Vector3) const 🔗

如果该边界框包含给定的 point，则返回 true。依照惯例，不包括正好位于右侧、顶部和前侧的点。

注意：对于具有负 size 的 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()）。

GDScriptC#

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) # 输出 (2.0, 0.0, 2.0)
print(intersection.size)     # 输出 (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 近似相等，则返回 true，判断方法是通过在 position 和 size 上调用 Vector3.is_equal_approx()。

---

bool is_finite() const 🔗

如果该边界框的值是有限的，则返回 true，判断方法是通过在 position 和 size 上调用 Vector3.is_finite()。

---

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()，会更可靠。