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:
方法	describe_surface_hit	func describe_surface_hit(source: Object, face_index: int) -> Dictionary:
方法	describe_mesh	func describe_mesh(source: Object) -> Dictionary:
方法	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。

describe_surface_hit

• API：public
• 首次版本：7.0.0

func describe_surface_hit(source: Object, face_index: int) -> Dictionary:

描述命中表面的结构化报告。 返回值面向运行时分发、调试面板和日志摘要；GF 只暴露 surface/material 数据， 不解释脚步声、弹孔、地形标签或其它业务语义。

参数：

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

返回：表面命中报告；无法解析时 ok 为 false，并保留 reason。

结构：

• return: Dictionary，包含 ok、reason、face_index、surface_index、base_material、override_material、active_material、has__material 以及对应 _material_name、_material_path、_material_type 字段；material 字段为 JSON-safe 资源摘要，不包含运行时 Object 引用。

describe_mesh

• API：public
• 首次版本：8.0.0

func describe_mesh(source: Object) -> Dictionary:

描述 Mesh 的 surface 布局。 返回值只包含 Mesh、surface、primitive、顶点/索引/面数和材质摘要，适合编辑器工具、 导入预检、调试面板或日志检查 Mesh 结构；不会修改 Mesh、创建碰撞体或生成节点。

参数：

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

返回：Mesh surface 布局报告；无法解析时 ok 为 false，并保留 reason。

结构：

• return: Dictionary，包含 ok、reason、mesh、mesh_name、mesh_path、mesh_type、surface_count、vertex_count、index_count、face_count、aabb_position、aabb_size 和 surfaces；mesh 与 material 字段为 JSON-safe 资源摘要，不包含运行时 Object 引用。

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。