save-load
Use when building or replacing a save/load system — ConfigFile, JSON, Resource serialization, and save game architecture
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 964
- Forks
- 63
01 前言 Front Matter
- name
- save-load
- description
- Use when building or replacing a save/load system — ConfigFile, JSON, Resource serialization, and save game architecture
02 资源文件 4
- 参考文档references/configfile.md3.5 KB
- 参考文档references/json-saves.md12.5 KB
- 参考文档references/save-architecture.md4.1 KB
- 参考文档references/version-migration.md2.3 KB
03 SKILL.md 正文
Save / Load Systems in Godot 4.3+
Choose the right serialization strategy for your data type. All examples target Godot 4.3+ with no deprecated APIs.
Related skills: resource-pattern for custom Resource data containers, inventory-system for inventory serialization patterns, godot-project-setup for SaveManager autoload setup, popochiu for adventure-framework saves.
1. Strategy Comparison
| Strategy | Best For | Readable | Editor Support | Notes |
|---|---|---|---|---|
| ConfigFile | Settings, simple key-value data | Yes | No | Built-in INI-style, no extra deps |
| JSON | Game saves, flexible structures | Yes | No | Cross-platform, version-migratable |
| Resource .tres | Editor-integrated data | Yes | Yes | NOT secure — never load untrusted files |
| Resource .res | Fast binary data | No | Yes | NOT secure — never load untrusted files |
When you recommend a strategy, name the one you rejected and the factor that decided it — "JSON, not Resource files, because saves are user-writable and loading a Resource can run code". A format picked without a named alternative cannot be overruled.
Security warning: Loading
.tresor.resfiles executes arbitrary GDScript embedded in the resource. Never load Resource files from untrusted sources (user-uploaded files, downloaded mods). Use ConfigFile or JSON for user-generated save data.
2. ConfigFile — Settings
ConfigFile writes INI-style sections — ideal for audio / video / controls settings (small, designer-debuggable). Use set_value(section, key, value) then save(path); load with load(path) and get_value(section, key, default).
See references/configfile.md for the full GDScript + C# settings save/load + typical settings-menu wiring.
3. JSON — Game Saves
JSON.stringify(dict) to serialize, JSON.parse_string(text) to deserialize. Read/write through FileAccess. Best for game saves where you want human-readable files. Build a Dictionary that captures all gameplay state (player position, inventory, world flags), serialize, write to user://save_<slot>.json.
See references/json-saves.md for the full GDScript + C# save/load implementation, including FileAccess wrapping and error handling.
⚠️ Changed in Godot 4.7:
JSON.stringify(data, indent = "", sort_keys = true, full_precision = false)now serializes an emptyDictionarycompactly as{}even when anindentis passed (GH-115883). Save files written with an indent change formatting for empty-dict fields after upgrading — anything that diffs or hashes save output byte-for-byte must tolerate the new form. Parsing is unaffected.
4. Save Architecture Pattern
For larger games, attach a SaveableComponent to each persistent node. Each component holds a stable save_id and two callables, serialize and deserialize, and joins the saveable group. The save manager walks that group, calls each serialize, and builds a master Dictionary keyed by save_id.
See references/save-architecture.md for the full
SaveableComponent+ save-manager implementation.
5. Save File Locations
user:// resolves to a platform-specific writable directory outside the project folder.
| Platform | Path |
|---|---|
| Windows | %APPDATA%\Godot\app_userdata\<project-name>\ |
| macOS | ~/Library/Application Support/Godot/app_userdata/<project-name>/ |
| Linux | ~/.local/share/godot/app_userdata/<project-name>/ |
Always use
user://for save data, neverres://. Theres://path is read-only in exported builds.
6. Version Migration
Save files outlive the schema that wrote them. Always include "version": <int> at the top of the saved Dictionary; on load, switch on the version and migrate older saves forward incrementally (v1 → v2 → v3 → current). Never break old saves — always migrate.
See references/version-migration.md for the full migration helper pattern.
7. Implementation Checklist
- [ ] Use ConfigFile for settings, JSON for game saves (not Resources)
- [ ] Every save file includes a
versioninteger field - [ ] Save path uses
user://, neverres:// - [ ] Call
DirAccess.make_dir_recursive_absolute()before writing saves - [ ] Vector2/Vector3 serialized as separate
x/y/zfloats (JSON has no Vector type) - [ ] All file operations check return codes and call
push_error()on failure - [ ]
_migrate()handles every version from 0 to current, applied incrementally - [ ] Resource files (.tres/.res) are never used for player-controlled save data
- [ ]
get_save_slots()anddelete_save()helpers exist for UI slot management - [ ] Saveable nodes use stable IDs that do not change between sessions
04 同仓库更多 Skills
xr-development
Use when building VR/AR/XR applications — OpenXR setup, XROrigin3D, hand tracking, controllers, passthrough, and Meta Quest deployment in Godot 4.3+
web-services
Use when a Godot game calls a web server — HTTPRequest, downloads, REST/JSON APIs, auth headers, WebSocketPeer clients, TLS, retries, and keeping secrets out of the build. Not for game networking/RPCs (multiplayer-basics) or browser export (web-export)
web-export
Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP/COEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:// persistence, audio and input limits, and load size
using-godot-prompter
Bootstrap skill — establishes how to find and use GodotPrompter skills, with platform-specific tool mapping
tween-animation
Use when implementing tweens — property animation, method tweening, chaining, parallel sequences, easing, and common UI/gameplay motion recipes
state-machine
Use when building a state machine or refactoring logic into one — enum, node, and resource-based FSM patterns with trade-offs. Not for adding states to an existing one