GFStorageUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/storage/gf_storage_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
基于 user:// 的轻量存档系统。 支持槽位存档、元数据分离读取、Resource 存取， 以及可配置 codec、完整性校验、版本迁移和简单混淆，适合通用本地持久化场景。 该混淆不提供安全加密能力，请勿用于保护敏感数据。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | data_integrity_failed |
signal data_integrity_failed(file_name: String, error: String) |
| 信号 | data_migrated |
signal data_migrated(file_name: String, from_version: int, to_version: int) |
| 信号 | save_completed |
signal save_completed(file_name: String, error: Error) |
| 信号 | load_completed |
signal load_completed(file_name: String, result: Dictionary) |
| 常量 | DEFAULT_MAX_LIST_DEPTH |
const DEFAULT_MAX_LIST_DEPTH: int = 32 |
| 常量 | DEFAULT_MAX_LISTED_FILES |
const DEFAULT_MAX_LISTED_FILES: int = 10000 |
| 属性 | encrypt_key |
var encrypt_key: int = 42 |
| 属性 | save_dir_name |
var save_dir_name: String = "saves" |
| 属性 | codec |
var codec: GFStorageCodec = GFStorageCodec.new() |
| 属性 | file_format |
var file_format: GFStorageCodec.Format = GFStorageCodec.Format.JSON |
| 属性 | use_compression |
var use_compression: bool = false |
| 属性 | allow_legacy_plain_json_fallback |
var allow_legacy_plain_json_fallback: bool = false |
| 属性 | normalize_json_numbers |
var normalize_json_numbers: bool = false |
| 属性 | use_integrity_checksum |
var use_integrity_checksum: bool = false |
| 属性 | strict_integrity |
var strict_integrity: bool = true |
| 属性 | require_integrity_checksum |
var require_integrity_checksum: bool = true |
| 属性 | include_storage_metadata |
var include_storage_metadata: bool = false |
| 属性 | allow_absolute_paths |
var allow_absolute_paths: bool = false |
| 属性 | create_directories_for_nested_paths |
var create_directories_for_nested_paths: bool = true |
| 属性 | max_async_thread_count |
var max_async_thread_count: int = 4: |
| 属性 | save_version |
var save_version: int = 1: |
| 属性 | strict_schema_migrations |
var strict_schema_migrations: bool = false |
| 属性 | default_values_for_new_keys |
var default_values_for_new_keys: Dictionary = {} |
| 属性 | last_load_result |
var last_load_result: Dictionary = {} |
| 方法 | init |
func init() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | tick |
func tick(_delta: float = 0.0) -> void: |
| 方法 | save_resource |
func save_resource(file_name: String, resource: Resource) -> Error: |
| 方法 | load_resource |
func load_resource(file_name: String, type_hint: String = "") -> Resource: |
| 方法 | ensure_directory |
func ensure_directory(directory_name: String = "") -> Error: |
| 方法 | list_files |
func list_files( directory_name: String = "", extension_filter: String = "", recursive: bool = false, options: Dictionary = {} ) -> PackedStringArray: |
| 方法 | delete_file |
func delete_file(file_name: String) -> Error: |
| 方法 | save_slot |
func save_slot(slot_id: int, data: Dictionary, metadata: Dictionary = {}) -> Error: |
| 方法 | load_slot |
func load_slot(slot_id: int) -> Dictionary: |
| 方法 | load_slot_result |
func load_slot_result(slot_id: int) -> Dictionary: |
| 方法 | load_slot_meta |
func load_slot_meta(slot_id: int) -> Dictionary: |
| 方法 | load_slot_meta_result |
func load_slot_meta_result(slot_id: int) -> Dictionary: |
| 方法 | has_slot |
func has_slot(slot_id: int) -> bool: |
| 方法 | list_slots |
func list_slots() -> Array[Dictionary]: |
| 方法 | delete_slot |
func delete_slot(slot_id: int) -> void: |
| 方法 | save_data |
func save_data(file_name: String, data: Dictionary) -> Error: |
| 方法 | load_data |
func load_data(file_name: String) -> Dictionary: |
| 方法 | load_data_result |
func load_data_result(file_name: String) -> Dictionary: |
| 方法 | save_data_async |
func save_data_async(file_name: String, data: Dictionary) -> Error: |
| 方法 | load_data_async |
func load_data_async(file_name: String) -> Error: |
| 方法 | wait_for_async_tasks |
func wait_for_async_tasks() -> void: |
| 方法 | migrate_data |
func migrate_data(data: Dictionary, _from_version: int, _to_version: int) -> Dictionary: |
| 方法 | register_migration |
func register_migration(from_version: int, to_version: int, callback: Callable) -> bool: |
| 方法 | unregister_migration |
func unregister_migration(from_version: int, to_version: int) -> void: |
| 方法 | clear_migrations |
func clear_migrations() -> void: |
| 方法 | get_registered_migrations |
func get_registered_migrations() -> Array[Dictionary]: |
信号¶
data_integrity_failed¶
- API：
public
解码数据失败或发现完整性校验失败后发出。
参数：
| 名称 | 说明 |
|---|---|
file_name |
文件名。 |
error |
错误描述。 |
data_migrated¶
- API：
public
数据版本迁移后发出。
参数：
| 名称 | 说明 |
|---|---|
file_name |
文件名。 |
from_version |
原版本。 |
to_version |
目标版本。 |
save_completed¶
- API：
public
异步保存完成后发出。
参数：
| 名称 | 说明 |
|---|---|
file_name |
文件名。 |
error |
Godot 的 Error 结果码。 |
load_completed¶
- API：
public
异步读取完成后发出。
参数：
| 名称 | 说明 |
|---|---|
file_name |
文件名。 |
result |
读取结果，包含 ok、data、metadata、integrity_valid、error。 |
结构：
result: Dictionary，包含 ok: bool、data: Dictionary、metadata: Dictionary、integrity_valid: bool 和 error: String。
常量¶
DEFAULT_MAX_LIST_DEPTH¶
- API：
public
递归枚举文件时默认允许进入的最大目录深度。
DEFAULT_MAX_LISTED_FILES¶
- API：
public
单次文件枚举默认最多返回的文件数量。
属性¶
encrypt_key¶
- API：
public
用于简单 XOR + Base64 混淆的密钥；为 0 时直接保存明文 JSON。该字段不是安全加密密钥。
save_dir_name¶
- API：
public
保存子目录名；为空时直接写入 user://。
codec¶
- API：
public
存档 codec。为 null 时会自动创建默认 GFStorageCodec。
file_format¶
- API：
public
数据序列化格式。
use_compression¶
- API：
public
是否压缩存档载荷。
allow_legacy_plain_json_fallback¶
- API：
public
解码失败时是否尝试按旧版未压缩、未混淆 JSON 读取原始 bytes。
normalize_json_numbers¶
- API：
public
JSON 读取时是否把接近整数的 float 归一为 int。Binary 格式不受影响。
use_integrity_checksum¶
- API：
public
是否写入并校验 SHA-256 完整性校验。
strict_integrity¶
- API：
public
完整性校验失败时是否拒绝读取。
require_integrity_checksum¶
- API：
public
启用完整性校验时，是否要求载荷必须包含 _meta.checksum。
include_storage_metadata¶
- API：
public
是否写入 _meta.version、_meta.timestamp 等通用元信息。
allow_absolute_paths¶
- API：
public
是否允许传入绝对路径。关闭后绝对路径会被收敛到存档目录下的同名文件。
create_directories_for_nested_paths¶
- API：
public
写入嵌套相对路径时是否自动创建目录。
max_async_thread_count¶
- API：
public
同时运行的异步存取线程数量。小于 1 时会被钳制为 1。
save_version¶
- API：
public
当前存档数据版本。小于 1 会被钳制为 1。
strict_schema_migrations¶
- API：
public
为 true 时，读取旧版本存档必须存在完整迁移链，不能仅更新 _meta.version。
default_values_for_new_keys¶
- API：
public
读取旧版本数据时需要补齐的新字段默认值。
结构：
default_values_for_new_keys: Dictionary，包含迁移旧存档时合并进去的新字段默认值。
last_load_result¶
- API：
public
迁移后的最近一次读取结果，包含 ok、data、metadata、integrity_valid、error。
结构：
last_load_result: Dictionary，包含 ok: bool、data: Dictionary、metadata: Dictionary、integrity_valid: bool 和 error: String。
方法¶
init¶
- API：
public
初始化存储目录和内部帮助器。
dispose¶
- API：
public
等待并清理异步存取任务。
tick¶
- API：
public
驱动异步存档任务完成检查。
参数：
| 名称 | 说明 |
|---|---|
_delta |
本帧时间增量（秒），默认实现不直接使用。 |
save_resource¶
- API：
public
保存一个 Resource 文件。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
resource |
要保存的资源实例。 |
返回：Godot 的 Error 结果码。
load_resource¶
- API：
public
读取一个 Resource 文件。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
type_hint |
可选类型提示。 |
返回：读取到的资源实例；不存在时返回 null。
ensure_directory¶
- API：
public
确保存储相对目录存在。
参数：
| 名称 | 说明 |
|---|---|
directory_name |
相对存储目录；为空时只确保根存储目录存在。 |
返回：Godot 的 Error 结果码。
list_files¶
- API：
public
func list_files( directory_name: String = "", extension_filter: String = "", recursive: bool = false, options: Dictionary = {} ) -> PackedStringArray:
枚举指定存储目录下的文件。
参数：
| 名称 | 说明 |
|---|---|
directory_name |
相对存储目录；为空时枚举根存储目录。 |
extension_filter |
可选扩展名过滤，允许传入 "json" 或 ".json"。 |
recursive |
是否递归枚举子目录。 |
options |
可选参数，支持 max_scan_depth 与 max_file_count。 |
返回：存储相对文件路径数组；若传入允许的绝对目录，则返回绝对文件路径。
结构：
options: Dictionary，包含 max_scan_depth: int 和 max_file_count: int。
delete_file¶
- API：
public
删除一个存储文件。
参数：
| 名称 | 说明 |
|---|---|
file_name |
存储相对文件路径。 |
返回：Godot 的 Error 结果码；文件不存在时返回 ERR_FILE_NOT_FOUND。
save_slot¶
- API：
public
保存一个槽位存档。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
data |
核心存档数据。 |
metadata |
展示用元数据。 |
返回：Godot 的 Error 结果码。
结构：
data: Dictionary，作为存档槽主要数据保存的载荷。metadata: Dictionary，作为存档槽展示元数据保存。
load_slot¶
- API：
public
读取槽位核心数据。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
返回：反序列化后的核心数据字典。
结构：
return: Dictionary，作为存档槽主要数据保存的载荷。
load_slot_result¶
- API：
public
读取槽位核心数据并返回 codec 结果。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
返回：结果字典，包含 ok、data、metadata、integrity_valid、error。
结构：
return: Dictionary，包含 ok: bool、data: Dictionary、metadata: Dictionary、integrity_valid: bool 和 error: String。
load_slot_meta¶
- API：
public
读取槽位元数据。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
返回：反序列化后的元数据字典。
结构：
return: Dictionary，作为存档槽展示元数据保存。
load_slot_meta_result¶
- API：
public
读取槽位元数据并返回 codec 结果。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
返回：结果字典，包含 ok、data、metadata、integrity_valid、error。
结构：
return: Dictionary，包含 ok: bool、data: Dictionary、metadata: Dictionary、integrity_valid: bool 和 error: String。
has_slot¶
- API：
public
检查槽位是否存在有效存档。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
返回：核心数据与元数据文件都存在时返回 true。
list_slots¶
- API：
public
枚举所有有效槽位。
返回：槽位信息数组，元素包含 slot_id、metadata 与 modified_time。
结构：
return: Array，包含 slot_id: int、metadata: Dictionary 和 modified_time: int 的 Dictionary 条目。
delete_slot¶
- API：
public
删除指定槽位的数据与元数据。
参数：
| 名称 | 说明 |
|---|---|
slot_id |
槽位 ID。 |
save_data¶
- API：
public
保存纯字典数据。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
data |
要保存的字典。 |
返回：Godot 的 Error 结果码。
结构：
data: Dictionary，要序列化并保存的数据载荷。
load_data¶
- API：
public
读取纯字典数据。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
返回：反序列化后的字典数据。
结构：
return: Dictionary，从存储读取的数据载荷；读取失败时为空字典。
load_data_result¶
- API：
public
读取纯字典数据并返回 codec 结果。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
返回：结果字典，包含 ok、data、metadata、integrity_valid、error。
结构：
return: Dictionary，包含 ok: bool、data: Dictionary、metadata: Dictionary、integrity_valid: bool 和 error: String。
save_data_async¶
- API：
public
在线程中异步保存纯字典数据。完成后从主线程发出 save_completed。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
data |
要保存的字典。 |
返回：启动线程的 Error 结果码。
结构：
data: Dictionary，要序列化并保存的数据载荷。
load_data_async¶
- API：
public
在线程中异步读取纯字典数据。完成后从主线程发出 load_completed。
参数：
| 名称 | 说明 |
|---|---|
file_name |
目标文件名。 |
返回：启动线程的 Error 结果码。
wait_for_async_tasks¶
- API：
public
等待已经入队和正在执行的异步纯数据任务全部完成。 需要在同一路径上混合同步与异步读写时，可先调用该方法收敛顺序。
migrate_data¶
- API：
public
迁移存档数据。项目可继承 GFStorageUtility 并重写该方法。
参数：
| 名称 | 说明 |
|---|---|
data |
已读取的数据副本。 |
_from_version |
原版本。 |
_to_version |
目标版本。 |
返回：迁移后的数据。
结构：
data: Dictionary，在存档 schema 版本之间迁移的数据载荷。return: Dictionary，应用已注册迁移和默认值后的数据载荷。
register_migration¶
- API：
public
注册一个版本迁移步骤。
参数：
| 名称 | 说明 |
|---|---|
from_version |
来源版本。 |
to_version |
目标版本，必须大于来源版本。 |
callback |
迁移回调，签名为 func(data: Dictionary, from_version: int, to_version: int) -> Dictionary。 |
返回：注册成功时返回 true。
unregister_migration¶
- API：
public
注销一个版本迁移步骤。
参数：
| 名称 | 说明 |
|---|---|
from_version |
来源版本。 |
to_version |
目标版本。 |
clear_migrations¶
- API：
public
清空所有注册的版本迁移步骤。
get_registered_migrations¶
- API：
public
获取已注册迁移步骤。
返回：迁移步骤摘要数组。
结构：
return: Array，包含 from_version: int 和 to_version: int 的 Dictionary 条目。