GFQuadTreeUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/spatial/gf_quad_tree_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
纯逻辑 2D 四叉树空间划分工具。 继承自 GFUtility，提供不依赖引擎物理节点的 2D 空间划分和范围查询能力。 适用于模拟经营、RTS 等需要对海量实体进行高效范围检索的场景。 用法： 1. 调用 setup(bounds, max_depth, max_entities) 初始化树的参数。 2. 调用 insert(entity_id, rect) 将实体插入四叉树。 3. 调用 query_rect(rect)、query_radius(center, radius) 或 query_point(point) 查询。 4. 调用 update(entity_id, rect) 更新实体位置（内部先移除再插入）。 5. 调用 remove(entity_id) 移除实体。 注意：entity_id 为 int，由调用方自行管理 ID 映射。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | DEFAULT_MAX_DEPTH |
const DEFAULT_MAX_DEPTH: int = 8 |
| 常量 | DEFAULT_MAX_ENTITIES |
const DEFAULT_MAX_ENTITIES: int = 8 |
| 属性 | bounds |
var bounds: Rect2 = Rect2() |
| 属性 | max_depth |
var max_depth: int = DEFAULT_MAX_DEPTH |
| 属性 | max_entities_per_node |
var max_entities_per_node: int = DEFAULT_MAX_ENTITIES |
| 方法 | init |
func init() -> void: |
| 方法 | setup |
func setup(world_bounds: Rect2, depth: int = DEFAULT_MAX_DEPTH, entities_per_node: int = DEFAULT_MAX_ENTITIES) -> void: |
| 方法 | insert |
func insert(entity_id: int, rect: Rect2) -> void: |
| 方法 | insert_with_hit_test |
func insert_with_hit_test(entity_id: int, rect: Rect2, hit_test: Callable) -> void: |
| 方法 | remove |
func remove(entity_id: int) -> void: |
| 方法 | update |
func update(entity_id: int, new_rect: Rect2) -> void: |
| 方法 | set_entity_hit_test |
func set_entity_hit_test(entity_id: int, hit_test: Callable) -> bool: |
| 方法 | clear_entity_hit_test |
func clear_entity_hit_test(entity_id: int) -> bool: |
| 方法 | get_entity_rect |
func get_entity_rect(entity_id: int) -> Rect2: |
| 方法 | query_rect |
func query_rect(area: Rect2) -> Array[int]: |
| 方法 | query_radius |
func query_radius(center: Vector2, radius: float) -> Array[int]: |
| 方法 | query_point |
func query_point(point: Vector2, use_exact_hit_tests: bool = true) -> Array[int]: |
| 方法 | query_first_point |
func query_first_point(point: Vector2, use_exact_hit_tests: bool = true) -> int: |
| 方法 | compact |
func compact() -> void: |
| 方法 | clear |
func clear() -> void: |
| 方法 | get_entity_count |
func get_entity_count() -> int: |
| 方法 | has_entity |
func has_entity(entity_id: int) -> bool: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
常量¶
DEFAULT_MAX_DEPTH¶
- API：
public
默认最大树深度。
DEFAULT_MAX_ENTITIES¶
- API：
public
默认每节点最大实体数（超过后分裂）。
属性¶
bounds¶
- API：
public
四叉树覆盖的世界边界。
max_depth¶
- API：
public
最大递归深度。
max_entities_per_node¶
- API：
public
每个节点在分裂前允许的最大实体数。
方法¶
init¶
- API：
public
第一阶段初始化：创建空根节点。
setup¶
- API：
public
func setup(world_bounds: Rect2, depth: int = DEFAULT_MAX_DEPTH, entities_per_node: int = DEFAULT_MAX_ENTITIES) -> void:
配置四叉树参数并重建。应在 init() 之前或之后调用。
参数：
| 名称 | 说明 |
|---|---|
world_bounds |
世界边界矩形。 |
depth |
最大递归深度。 |
entities_per_node |
每节点最大实体数。 |
insert¶
- API：
public
将实体插入四叉树。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体唯一标识。 |
rect |
实体的轴对齐包围矩形。 |
insert_with_hit_test¶
- API：
public
将带精确点命中测试的实体插入四叉树。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体唯一标识。 |
rect |
实体的轴对齐包围矩形。 |
hit_test |
可选精确命中测试，签名为 (entity_id, point, rect) -> bool。 |
remove¶
- API：
public
从四叉树中移除实体。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
要移除的实体标识。 |
update¶
- API：
public
更新实体的位置（先移除再插入）。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体标识。 |
new_rect |
新的包围矩形。 |
set_entity_hit_test¶
- API：
public
设置实体的精确点命中测试。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体标识。 |
hit_test |
命中测试 Callable，签名为 (entity_id, point, rect) -> bool。 |
返回：设置成功返回 true。
clear_entity_hit_test¶
- API：
public
清除实体的精确点命中测试。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体标识。 |
返回：清除成功返回 true。
get_entity_rect¶
- API：
public
获取实体矩形。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体标识。 |
返回：实体矩形；不存在时返回空 Rect2。
query_rect¶
- API：
public
矩形范围查询：返回与查询区域有交集的所有实体 ID。
参数：
| 名称 | 说明 |
|---|---|
area |
查询矩形。 |
返回：匹配的实体 ID 数组。
query_radius¶
- API：
public
圆形范围查询：返回包围矩形与圆有交集的所有实体 ID。
参数：
| 名称 | 说明 |
|---|---|
center |
圆心坐标。 |
radius |
查询半径。 |
返回：匹配的实体 ID 数组。
query_point¶
- API：
public
点查询：返回包含该点的实体 ID，可选执行精确命中测试。
参数：
| 名称 | 说明 |
|---|---|
point |
查询点。 |
use_exact_hit_tests |
是否执行通过 set_entity_hit_test() 注册的精确命中测试。 |
返回：匹配的实体 ID 数组。
query_first_point¶
- API：
public
点查询：返回第一个包含该点的实体 ID，不存在时返回 -1。
参数：
| 名称 | 说明 |
|---|---|
point |
查询点。 |
use_exact_hit_tests |
是否执行精确命中测试。 |
返回：第一个实体 ID；不存在时返回 -1。
compact¶
- API：
public
重建四叉树节点结构，保留实体、矩形和命中测试。
clear¶
- API：
public
清空四叉树中的所有实体并重建根节点。
get_entity_count¶
- API：
public
获取当前存储的实体总数。
返回：实体数量。
has_entity¶
- API：
public
检查实体是否存在于四叉树中。
参数：
| 名称 | 说明 |
|---|---|
entity_id |
实体标识。 |
返回：是否存在。
get_debug_snapshot¶
- API：
public
获取调试快照。
返回：四叉树状态。
结构：
return: Dictionary withbounds: Rect2,entity_count: int,hit_test_count: int,max_depth: int,max_entities_per_node: int, andnode_count: int.