GFSpatialHash3D¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/foundation/math/gf_spatial_hash_3d.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
纯逻辑 3D 空间哈希。 适用于大量动态 3D 实体的粗粒度范围查询。它只维护 AABB 索引， 不负责物理碰撞、可见性或玩法规则。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | DEFAULT_MAX_COVERED_CELLS |
const DEFAULT_MAX_COVERED_CELLS: int = 262144 |
| 属性 | cell_size |
var cell_size: float: |
| 属性 | max_covered_cells |
var max_covered_cells: int: |
| 方法 | configure |
func configure(p_cell_size: float) -> void: |
| 方法 | get_cell_for_position |
func get_cell_for_position(position: Vector3) -> Vector3i: |
| 方法 | insert |
func insert(entity: Variant, bounds: AABB) -> bool: |
| 方法 | remove |
func remove(entity: Variant) -> void: |
| 方法 | update |
func update(entity: Variant, bounds: AABB) -> bool: |
| 方法 | has_entity |
func has_entity(entity: Variant) -> bool: |
| 方法 | get_entity_count |
func get_entity_count() -> int: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
| 方法 | query_aabb |
func query_aabb(area: AABB) -> Array[Variant]: |
| 方法 | query_radius |
func query_radius(center: Vector3, radius: float) -> Array[Variant]: |
| 方法 | query_cell |
func query_cell(cell: Vector3i) -> Array[Variant]: |
| 方法 | query_cell_range |
func query_cell_range(center_cell: Vector3i, radius: Vector3i = Vector3i.ZERO) -> Array[Variant]: |
| 方法 | prune_invalid_entities |
func prune_invalid_entities() -> void: |
| 方法 | clear |
func clear() -> void: |
常量¶
DEFAULT_MAX_COVERED_CELLS¶
- API：
public - 首次版本：
7.0.0
单次插入或查询允许覆盖的默认最大哈希格子数。
属性¶
cell_size¶
- API：
public
单个哈希格子的世界尺寸。
max_covered_cells¶
- API：
public - 首次版本：
7.0.0
单个 AABB 或格子范围允许覆盖的最大哈希格子数。 超过上限的插入会返回 false；超过上限的查询会返回空结果，避免误用超大范围导致 一帧内分配海量中间数组。
方法¶
configure¶
- API：
public
配置格子尺寸并清空索引。
参数：
| 名称 | 说明 |
|---|---|
p_cell_size |
单格世界尺寸。 |
get_cell_for_position¶
- API：
public - 首次版本：
6.0.0
获取世界坐标所在的哈希格子。
参数：
| 名称 | 说明 |
|---|---|
position |
世界坐标。 |
返回：哈希格子坐标。
insert¶
- API：
public - 首次版本：
3.17.0
插入实体。
参数：
| 名称 | 说明 |
|---|---|
entity |
实体标识或 Object。 |
bounds |
实体 AABB。 |
返回：成功时返回 true。
结构：
entity: Object, StringName, String, or int identity stored by value or weak Object reference.
remove¶
- API：
public - 首次版本：
3.17.0
移除实体。
参数：
| 名称 | 说明 |
|---|---|
entity |
实体标识或 Object。 |
结构：
entity: Object, StringName, String, or int identity stored by value or weak Object reference.
update¶
- API：
public - 首次版本：
3.17.0
更新实体 AABB。
参数：
| 名称 | 说明 |
|---|---|
entity |
实体标识或 Object。 |
bounds |
新 AABB。 |
返回：成功时返回 true。
结构：
entity: Object, StringName, String, or int identity stored by value or weak Object reference.
has_entity¶
- API：
public - 首次版本：
3.17.0
检查实体是否存在。
参数：
| 名称 | 说明 |
|---|---|
entity |
实体标识或 Object。 |
返回：存在时返回 true。
结构：
entity: Object, StringName, String, or int identity stored by value or weak Object reference.
get_entity_count¶
- API：
public
获取实体数量。
返回：实体数量。
get_debug_snapshot¶
- API：
public - 首次版本：
6.0.0
获取空间哈希调试快照。
返回：调试快照。
结构：
return: Dictionary with cell_size, max_covered_cells, entity_count, bucket_count, max_bucket_size, and average_bucket_size.
query_aabb¶
- API：
public
查询与 AABB 相交的实体。
参数：
| 名称 | 说明 |
|---|---|
area |
查询 AABB。 |
返回：实体数组。
结构：
return: Array entity values restored from spatial hash records.
query_radius¶
- API：
public
查询与球体相交的实体。
参数：
| 名称 | 说明 |
|---|---|
center |
球心。 |
radius |
半径。 |
返回：实体数组。
结构：
return: Array entity values restored from spatial hash records.
query_cell¶
- API：
public - 首次版本：
6.0.0
查询指定哈希格子中的候选实体。 返回值是该格子桶内的粗筛候选，调用方如需精确几何或玩法规则过滤，应继续使用自己的规则处理。
参数：
| 名称 | 说明 |
|---|---|
cell |
哈希格子坐标。 |
返回：实体数组。
结构：
return: Array entity values restored from spatial hash records.
query_cell_range¶
- API：
public - 首次版本：
6.0.0
查询以中心格子为基准的哈希格子范围。 radius 按轴表示要向外扩展的格子数；例如 Vector3i(2, 0, 2) 会查询同一 Y 层上 X/Z 各扩展 2 格的区域。
参数：
| 名称 | 说明 |
|---|---|
center_cell |
中心哈希格子。 |
radius |
各轴扩展格子数，负数会按绝对值处理。 |
返回：去重后的实体数组。
结构：
return: Array entity values restored from spatial hash records.
prune_invalid_entities¶
- API：
public
清理已释放 Object 实体。
clear¶
- API：
public
清空索引。