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 索引， 不负责物理碰撞、可见性或玩法规则。

成员概览

类型	名称	签名
属性	cell_size	var cell_size: float:
方法	configure	func configure(p_cell_size: float) -> void:
方法	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:
方法	query_aabb	func query_aabb(area: AABB) -> Array[Variant]:
方法	query_radius	func query_radius(center: Vector3, radius: float) -> Array[Variant]:
方法	prune_invalid_entities	func prune_invalid_entities() -> void:
方法	clear	func clear() -> void:

属性

cell_size

• API：public

var cell_size: float:

单个哈希格子的世界尺寸。

方法

configure

• API：public

func configure(p_cell_size: float) -> void:

配置格子尺寸并清空索引。

参数：

名称	说明
p_cell_size	单格世界尺寸。

insert

• API：public

func insert(entity: Variant, bounds: AABB) -> bool:

插入实体。

参数：

名称	说明
entity	实体标识或 Object。
bounds	实体 AABB。

返回：成功时返回 true。

结构：

• entity: Variant entity identity stored by value or weak Object reference.

remove

• API：public

func remove(entity: Variant) -> void:

移除实体。

参数：

名称	说明
entity	实体标识或 Object。

结构：

• entity: Variant entity identity stored by value or weak Object reference.

update

• API：public

func update(entity: Variant, bounds: AABB) -> bool:

更新实体 AABB。

参数：

名称	说明
entity	实体标识或 Object。
bounds	新 AABB。

返回：成功时返回 true。

结构：

• entity: Variant entity identity stored by value or weak Object reference.

has_entity

• API：public

func has_entity(entity: Variant) -> bool:

检查实体是否存在。

参数：

名称	说明
entity	实体标识或 Object。

返回：存在时返回 true。

结构：

• entity: Variant entity identity stored by value or weak Object reference.

get_entity_count

• API：public

func get_entity_count() -> int:

获取实体数量。

返回：实体数量。

query_aabb

• API：public

func query_aabb(area: AABB) -> Array[Variant]:

查询与 AABB 相交的实体。

参数：

名称	说明
area	查询 AABB。

返回：实体数组。

结构：

• return: Array entity values restored from spatial hash records.

query_radius

• API：public

func query_radius(center: Vector3, radius: float) -> Array[Variant]:

查询与球体相交的实体。

参数：

名称	说明
center	球心。
radius	半径。

返回：实体数组。

结构：

• return: Array entity values restored from spatial hash records.

prune_invalid_entities

• API：public

func prune_invalid_entities() -> void:

清理已释放 Object 实体。

clear

• API：public

func clear() -> void:

清空索引。