GFSaveDocumentSchema¶
API Reference / Save / 类索引
- 路径：
addons/gf/extensions/save/document/gf_save_document_schema.gd - 模块：
Save - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
9.0.0
项目存档文档的当前版本契约。 项目用该 Resource 声明 schema_id、当前文档版本、已知分区版本和必需分区。 GF 只校验结构与版本，不解释任何业务字段。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | schema_id |
var schema_id: StringName = &"" |
| 属性 | schema_version |
var schema_version: int = 1 |
| 属性 | section_versions |
var section_versions: Dictionary = {} |
| 属性 | required_sections |
var required_sections: PackedStringArray = PackedStringArray() |
| 属性 | allow_unknown_sections |
var allow_unknown_sections: bool = true |
| 方法 | configure |
func configure( p_schema_id: StringName, p_schema_version: int, p_section_versions: Dictionary = {}, options: Dictionary = {} ) -> GFSaveDocumentSchema: |
| 方法 | get_section_version |
func get_section_version(section_id: StringName) -> int: |
| 方法 | has_section |
func has_section(section_id: StringName) -> bool: |
| 方法 | get_section_ids |
func get_section_ids() -> PackedStringArray: |
| 方法 | validate_schema |
func validate_schema() -> Dictionary: |
| 方法 | validate_document |
func validate_document( document: GFSaveDocument, require_current_versions: bool = true ) -> Dictionary: |
| 方法 | to_dict |
func to_dict() -> Dictionary: |
| 方法 | duplicate_schema |
func duplicate_schema() -> GFSaveDocumentSchema: |
| 方法 | from_dict |
static func from_dict(data: Dictionary) -> GFSaveDocumentSchema: |
属性¶
schema_id¶
- API：
public - 首次版本：
9.0.0
项目存档 schema 的稳定 ID。
schema_version¶
- API：
public - 首次版本：
9.0.0
当前文档 schema 版本。
section_versions¶
- API：
public - 首次版本：
9.0.0
已知分区及其当前版本。
结构：
section_versions: Dictionary from non-empty section_id to positive int version.
required_sections¶
- API：
public - 首次版本：
9.0.0
当前 schema 必须存在的分区。
allow_unknown_sections¶
- API：
public - 首次版本：
9.0.0
是否允许并原样保留 schema 未声明的分区。
方法¶
configure¶
- API：
public - 首次版本：
9.0.0
func configure( p_schema_id: StringName, p_schema_version: int, p_section_versions: Dictionary = {}, options: Dictionary = {} ) -> GFSaveDocumentSchema:
配置当前 schema 契约。
参数：
| 名称 | 说明 |
|---|---|
p_schema_id |
稳定 schema ID。 |
p_schema_version |
当前文档版本。 |
p_section_versions |
分区当前版本映射。 |
options |
可包含 required_sections 与 allow_unknown_sections。 |
返回：当前 schema。
结构：
p_section_versions: Dictionary from non-empty section_id to positive int version.options: Dictionary with optional required_sections: PackedStringArray and allow_unknown_sections: bool.
get_section_version¶
- API：
public - 首次版本：
9.0.0
获取指定分区的当前版本。
参数：
| 名称 | 说明 |
|---|---|
section_id |
分区 ID。 |
返回：已声明版本；未知分区返回 0。
has_section¶
- API：
public - 首次版本：
9.0.0
检查是否声明了分区。
参数：
| 名称 | 说明 |
|---|---|
section_id |
分区 ID。 |
返回：已声明时返回 true。
get_section_ids¶
- API：
public - 首次版本：
9.0.0
获取排序后的已知分区 ID。
返回：已知分区 ID。
validate_schema¶
- API：
public - 首次版本：
9.0.0
校验 schema 自身。
返回：结构化校验报告。
结构：
return: GFValidationReportDictionary-compatible report with issues, counts, summary, and next_actions.
validate_document¶
- API：
public - 首次版本：
9.0.0
func validate_document( document: GFSaveDocument, require_current_versions: bool = true ) -> Dictionary:
校验文档是否符合该 schema。
参数：
| 名称 | 说明 |
|---|---|
document |
待校验文档。 |
require_current_versions |
为 true 时要求文档和已知分区恰好为当前版本；为 false 时旧版本仅产生迁移警告。 |
返回：结构化兼容性报告。
结构：
return: GFValidationReportDictionary-compatible report with compatible, migration_required, schema_id, schema_version, issues, counts, summary, and next_actions.
to_dict¶
- API：
public - 首次版本：
9.0.0
转换为字典。
返回：schema 字典。
结构：
return: Dictionary with schema_id, schema_version, section_versions, required_sections, and allow_unknown_sections.
duplicate_schema¶
- API：
public - 首次版本：
9.0.0
创建 schema 副本。
返回：隔离 schema。
from_dict¶
- API：
public - 首次版本：
9.0.0
从字典创建 schema。 该方法执行严格边界检查，不修补非法字段或忽略未知字段。
参数：
| 名称 | 说明 |
|---|---|
data |
schema 字典。 |
返回：新 schema；输入不规范或 schema 自身无效时返回 null。
结构：
data: Dictionary with schema_id, schema_version, section_versions, required_sections, and allow_unknown_sections.