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 轴对齐边界框。

描述

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，其宽度、高度和深度被修改为非负值。

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

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）。

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。负数会缩小该框。

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()）。

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