GFSaveGraphUtility

API Reference / Save / 类索引

• 路径：addons/gf/extensions/save/graph/gf_save_graph_utility.gd
• 模块：Save
• 继承：GFUtility
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

通用节点存档图编排工具。 负责遍历 GFSaveScope/GFSaveSource，采集、应用和落盘存档图。具体数据结构 由 Source、Serializer 或项目继承类决定，Utility 本身不绑定业务字段。

成员概览

类型	名称	签名
常量	FORMAT_ID	const FORMAT_ID: String = "gf_save_graph"
常量	FORMAT_VERSION	const FORMAT_VERSION: int = 1
属性	serializer_registry	var serializer_registry: GFNodeSerializerRegistry = GFNodeSerializerRegistry.new()
属性	pipeline_steps	var pipeline_steps: Array[GFSavePipelineStep] = []
方法	register_entity_factory	func register_entity_factory(factory: GFSaveEntityFactory) -> void:
方法	unregister_entity_factory	func unregister_entity_factory(type_key: StringName) -> void:
方法	clear_entity_factories	func clear_entity_factories() -> void:
方法	add_pipeline_step	func add_pipeline_step(step: GFSavePipelineStep) -> void:
方法	remove_pipeline_step	func remove_pipeline_step(step: GFSavePipelineStep) -> void:
方法	clear_pipeline_steps	func clear_pipeline_steps() -> void:
方法	create_pipeline_context	func create_pipeline_context( operation: StringName, scope: GFSaveScope = null, shared: Dictionary = {} ) -> GFSavePipelineContext:
方法	inspect_scope	func inspect_scope(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:
方法	build_scope_health_report	func build_scope_health_report(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:
方法	validate_payload_for_scope	func validate_payload_for_scope(scope: GFSaveScope, payload: Dictionary, strict: bool = false) -> Dictionary:
方法	build_payload_health_report	func build_payload_health_report(scope: GFSaveScope, payload: Dictionary, strict: bool = false) -> Dictionary:
方法	gather_scope	func gather_scope(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:
方法	apply_scope	func apply_scope( scope: GFSaveScope, payload: Dictionary, context: Dictionary = {}, strict: bool = false ) -> Dictionary:
方法	save_scope	func save_scope( file_name: String, scope: GFSaveScope, metadata: Dictionary = {}, context: Dictionary = {} ) -> Error:
方法	load_scope	func load_scope( file_name: String, scope: GFSaveScope, context: Dictionary = {}, strict: bool = false ) -> Dictionary:

常量

FORMAT_ID

• API：public

const FORMAT_ID: String = "gf_save_graph"

存档图载荷格式标识。

FORMAT_VERSION

• API：public

const FORMAT_VERSION: int = 1

当前存档图载荷格式版本。

属性

serializer_registry

• API：public

var serializer_registry: GFNodeSerializerRegistry = GFNodeSerializerRegistry.new()

节点序列化器注册表。

pipeline_steps

• API：public

var pipeline_steps: Array[GFSavePipelineStep] = []

存档图流程步骤。按数组顺序执行，适合压缩前校验、调试标记、版本适配等通用处理。

方法

register_entity_factory

• API：public

func register_entity_factory(factory: GFSaveEntityFactory) -> void:

注册实体工厂。

参数：

名称	说明
factory	实体工厂。

unregister_entity_factory

• API：public

func unregister_entity_factory(type_key: StringName) -> void:

注销实体工厂。

参数：

名称	说明
type_key	实体类型键。

clear_entity_factories

• API：public

func clear_entity_factories() -> void:

清空实体工厂。

add_pipeline_step

• API：public

func add_pipeline_step(step: GFSavePipelineStep) -> void:

添加存档流程步骤。

参数：

名称	说明
step	流程步骤。

remove_pipeline_step

• API：public

func remove_pipeline_step(step: GFSavePipelineStep) -> void:

移除存档流程步骤。

参数：

名称	说明
step	流程步骤。

clear_pipeline_steps

• API：public

func clear_pipeline_steps() -> void:

清空存档流程步骤。

create_pipeline_context

• API：public

func create_pipeline_context( operation: StringName, scope: GFSaveScope = null, shared: Dictionary = {} ) -> GFSavePipelineContext:

创建存档流程上下文。

参数：

名称	说明
operation	操作类型。
scope	可选根 Scope。
shared	初始共享数据。

返回：新上下文。

结构：

• shared: Dictionary，流程共享数据，可由步骤写入调试标记、迁移状态或项目自定义键。

inspect_scope

• API：public

func inspect_scope(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:

检查 Scope 树的可保存结构。

参数：

名称	说明
scope	根 Scope。
context	调用上下文字典。

返回：诊断报告。

结构：

• context: Dictionary，可包含诊断调用方自定义键，不会被 Utility 写入私有状态。
• return: Dictionary，包含 ok、healthy、scope_key、计数字段、issue_counts_by_kind、summary、next_action、scopes、sources 与 issues。

build_scope_health_report

• API：public

func build_scope_health_report(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:

构建 Scope 健康报告。

参数：

名称	说明
scope	根 Scope。
context	调用上下文字典。

返回：含 summary、next_action 与 issue 统计的诊断报告。

结构：

• context: Dictionary，可包含诊断调用方自定义键，不会被 Utility 写入私有状态。
• return: Dictionary，结构与 inspect_scope 的返回诊断报告一致。

validate_payload_for_scope

• API：public

func validate_payload_for_scope(scope: GFSaveScope, payload: Dictionary, strict: bool = false) -> Dictionary:

校验载荷是否能匹配当前 Scope 树。

参数：

名称	说明
scope	根 Scope。
payload	待校验载荷。
strict	为 true 时把缺失 Source/Scope 视为错误；否则视为警告。

返回：诊断报告。

结构：

• payload: Dictionary，存档图载荷，包含 format、format_version、scope、sources、scopes，可选 metadata 与 pipeline_trace。
• return: Dictionary，包含 ok、healthy、scope_key、checked_source_count、checked_scope_count、missing、issues、summary 与 next_action。

build_payload_health_report

• API：public

func build_payload_health_report(scope: GFSaveScope, payload: Dictionary, strict: bool = false) -> Dictionary:

构建载荷匹配健康报告。

参数：

名称	说明
scope	根 Scope。
payload	待校验载荷。
strict	为 true 时把缺失 Source/Scope 视为错误；否则视为警告。

返回：含 summary、next_action 与 issue 统计的诊断报告。

结构：

• payload: Dictionary，存档图载荷，包含 format、format_version、scope、sources、scopes，可选 metadata 与 pipeline_trace。
• return: Dictionary，结构与 validate_payload_for_scope 的返回诊断报告一致。

gather_scope

• API：public

func gather_scope(scope: GFSaveScope, context: Dictionary = {}) -> Dictionary:

采集 Scope 存档图。

参数：

名称	说明
scope	根 Scope。
context	调用上下文字典。

返回：存档载荷。

结构：

• context: Dictionary，可包含 pipeline_context、pipeline_shared、include_pipeline_trace、transactional_apply 及项目自定义键。
• return: Dictionary，存档图载荷，包含 format、format_version、scope、sources、scopes，可选 metadata 与 pipeline_trace。

apply_scope

• API：public

func apply_scope( scope: GFSaveScope, payload: Dictionary, context: Dictionary = {}, strict: bool = false ) -> Dictionary:

应用 Scope 存档图。

参数：

名称	说明
scope	根 Scope。
payload	存档载荷。
context	调用上下文字典。
strict	为 true 时缺失 Source/Scope 会记录错误。

返回：结果字典。

结构：

• payload: Dictionary，存档图载荷，包含 format、format_version、scope、sources、scopes，可选 metadata 与 pipeline_trace。
• context: Dictionary，可包含 pipeline_context、pipeline_shared、include_pipeline_trace、transactional_apply 及项目自定义键。
• return: Dictionary，包含 ok、applied、errors、missing，可选 pipeline_trace。

save_scope

• API：public

func save_scope( file_name: String, scope: GFSaveScope, metadata: Dictionary = {}, context: Dictionary = {} ) -> Error:

采集并保存 Scope。

参数：

名称	说明
file_name	目标文件名。
scope	根 Scope。
metadata	附加元信息。
context	调用上下文字典。

返回：Godot 错误码。

结构：

• metadata: Dictionary，写入载荷 metadata 字段的项目元信息。
• context: Dictionary，可包含 pipeline_context、pipeline_shared、include_pipeline_trace 及项目自定义键。

load_scope

• API：public

func load_scope( file_name: String, scope: GFSaveScope, context: Dictionary = {}, strict: bool = false ) -> Dictionary:

从文件读取并应用 Scope。

参数：

名称	说明
file_name	目标文件名。
scope	根 Scope。
context	调用上下文字典。
strict	为 true 时缺失 Source/Scope 会记录错误。

返回：结果字典。

结构：

• context: Dictionary，可包含 pipeline_context、pipeline_shared、include_pipeline_trace、transactional_apply 及项目自定义键。
• return: Dictionary，包含 ok、applied、errors、missing，可选 pipeline_trace。