GFSurfaceUtility

API Reference / Standard / 类索引

• 路径：addons/gf/standard/utilities/display/gf_surface_utility.gd
• 模块：Standard
• 继承：GFUtility
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

3D 表面材质查询工具。 根据碰撞命中的 face index 推导 MeshInstance3D surface，并返回基础材质、 覆盖材质或最终 active material。框架只负责几何到材质的映射，不解释材质语义。

成员概览

类型	名称	签名
枚举	CacheMode	enum CacheMode
常量	DEFAULT_AUTO_CACHE_SIZE	const DEFAULT_AUTO_CACHE_SIZE: int = 8
属性	cache_mode	var cache_mode: CacheMode = CacheMode.AUTOMATIC
属性	auto_cache_size	var auto_cache_size: int = DEFAULT_AUTO_CACHE_SIZE
方法	dispose	func dispose() -> void:
方法	get_active_material	func get_active_material(source: Object, face_index: int) -> Material:
方法	get_surface_override_material	func get_surface_override_material(source: Object, face_index: int) -> Material:
方法	get_base_material	func get_base_material(source: Object, face_index: int) -> Material:
方法	get_surface_index	func get_surface_index(source: Object, face_index: int) -> int:
方法	clear_cache	func clear_cache() -> void:
方法	cache_mesh_surface	func cache_mesh_surface(source: Object) -> bool:
方法	erase_cached_mesh	func erase_cached_mesh(source: Object) -> bool:
方法	set_auto_cache_size	func set_auto_cache_size(size: int) -> void:
方法	get_debug_snapshot	func get_debug_snapshot() -> Dictionary:

枚举

CacheMode

• API：public

enum CacheMode { ## 不读写缓存，每次查询都重新计算。 DISABLED, ## 只使用显式预热写入的缓存。 MANUAL, ## 查询时自动缓存，并按 auto_cache_size 控制容量。 AUTOMATIC, }

Mesh surface face count 缓存策略。

常量

DEFAULT_AUTO_CACHE_SIZE

• API：public

const DEFAULT_AUTO_CACHE_SIZE: int = 8

自动缓存默认容量。

属性

cache_mode

• API：public

var cache_mode: CacheMode = CacheMode.AUTOMATIC

当前缓存策略。

auto_cache_size

• API：public

var auto_cache_size: int = DEFAULT_AUTO_CACHE_SIZE

自动缓存容量。小于 1 时会被归一化为 1。

方法

dispose

• API：public

func dispose() -> void:

释放工具时清空 Mesh surface face count 缓存。

get_active_material

• API：public

func get_active_material(source: Object, face_index: int) -> Material:

获取命中表面最终渲染使用的材质。

参数：

名称	说明
source	MeshInstance3D、CollisionObject3D 或其相邻节点。
face_index	RayCast3D.get_collision_face_index() 返回的面索引。

返回：命中材质；无法解析时返回 null。

get_surface_override_material

• API：public

func get_surface_override_material(source: Object, face_index: int) -> Material:

获取 MeshInstance3D surface override 材质。

参数：

名称	说明
source	MeshInstance3D、CollisionObject3D 或其相邻节点。
face_index	RayCast3D.get_collision_face_index() 返回的面索引。

返回：覆盖材质；未设置或无法解析时返回 null。

get_base_material

• API：public

func get_base_material(source: Object, face_index: int) -> Material:

获取 Mesh 资源自身的 surface 材质。

参数：

名称	说明
source	MeshInstance3D、CollisionObject3D 或其相邻节点。
face_index	RayCast3D.get_collision_face_index() 返回的面索引。

返回：基础材质；无法解析时返回 null。

get_surface_index

• API：public

func get_surface_index(source: Object, face_index: int) -> int:

获取 face index 所属的 Mesh surface 索引。

参数：

名称	说明
source	MeshInstance3D、CollisionObject3D 或其相邻节点。
face_index	RayCast3D.get_collision_face_index() 返回的面索引。

返回：surface 索引；无法解析时返回 -1。

clear_cache

• API：public

func clear_cache() -> void:

清空 Mesh surface face count 缓存。

cache_mesh_surface

• API：public

func cache_mesh_surface(source: Object) -> bool:

预热指定 Mesh 或 MeshInstance3D 的 surface face count 缓存。

参数：

名称	说明
source	Mesh、MeshInstance3D、CollisionObject3D 或其相邻节点。

返回：缓存成功返回 true。

erase_cached_mesh

• API：public

func erase_cached_mesh(source: Object) -> bool:

移除指定 Mesh 或 MeshInstance3D 的 surface face count 缓存。

参数：

名称	说明
source	Mesh、MeshInstance3D、CollisionObject3D 或其相邻节点。

返回：移除成功返回 true。

set_auto_cache_size

• API：public

func set_auto_cache_size(size: int) -> void:

设置自动缓存容量。

参数：

名称	说明
size	自动缓存容量；小于 1 时按 1 处理。

get_debug_snapshot

• API：public

func get_debug_snapshot() -> Dictionary:

获取调试快照。

返回：缓存状态。

结构：

• return: Dictionary，包含 cached_meshes、cache_mode 和 auto_cache_size。