Expert blueprint for save/load systems using JSON/binary serialization, PERSIST group pattern, versioning, and migration. Covers player progress, settings, game state persistence, and error recovery. Use when implementing save systems OR data persistence. Keywords save, load, JSON, FileAccess, user:

NEVER Do NEVER save without a version field — When you update your game's data structure, old saves will break. Always include a "version": "1.0.0" field and implement migration logic. NEVER use absolute OS paths — Hardcoding C:/Users/... will break on every other machine. Always use the user:// protocol, which Godot maps to the correct OS specific app data folder. NEVER attempt to save Node references directly — Nodes are objects, not raw data. Extract the necessary primitive data (positions, health, levels) into a Dictionary or Resource instead. NEVER forget to close FileAccess handles — Leaving a file open can lead to handle leaks and save file corruption. In Godot 4, files auto close when the variable goes out of scope, but explicit close() is safer for long running logic. NEVER use JSON for very large binary data — Storing 10MB of texture data as Base64 in JSON is slow and bloats file size. Use binary store var() or separate dedicated asset files. NEVER trust loaded data without validation — Users can edit save files. Always use data.get("field", default value) and validate that numbers are within expected ranges to prevent crashes. NEVER trigger a save during high frequency physics or animation updates — A crash mid write will corrupt the file. Save only on explicit game events like entering a menu, finishing a level, or at a checkpoint. NEVER modify a save Dictionary while iterating over its keys — Calling erase() or add() inside a loop over the same dictionary causes iteration errors. Use data.duplicate() to iterate safely. NEVER store raw passwords or sensitive credentials in unencrypted JSON — If you have sensitive data, use FileAccess.open encrypted with pass() to secure it. NEVER use ResourceLoader.load() for massive scenes on the main thread — It causes a visible freeze. Use ResourceLoader.load threaded request() to load levels in the background. NEVER rely on get instance id() for cross session identification — These IDs are assigned at runtime and change every time the game restarts. Generate your own persistent String UUIDs for game objects. NEVER forget to call duplicate(true) on a loaded Resource stats block — If multiple enemies load the same "goblin stats.tres", they will all share the same health pool unless duplicated. NEVER use the "allow objects" flag in store var/get var for untrusted data — Setting this to true allows full object decoding, which is a major security risk for saves downloaded from the web. NEVER use JSON for data requiring strict type preservation — JSON converts Vector3 to a string or dictionary. For strict data types, use var to bytes() or a binary format. NEVER leave internal metadata (set meta) in persistent dictionaries — This unnecessarily inflates save file size. Clean your dictionaries before serialization. Available Scripts MANDATORY : Read the script for the chosen format before writing SaveManager code. [save load patterns.gd](scripts/save load patterns.gd) MANDATORY for JSON / binary / PERSIST collect — patterns default store var(..., false) . [save migration manager.gd](scripts/save migration manager.gd) MANDATORY when any save has a version field that can lag the build. [save system encryption.gd](scripts/save system encryption.gd) MANDATORY before encrypted slots — password from secure storage / user secret, never hardcoded in examples. [save integrity validator.gd](scripts/save integrity validator.gd) Rolling .bak + SHA 256 verify before trusting a slot; fall back to backup on mismatch. Deep dive (load on demand) MANDATORY for JSON/PERSIST walkthroughs, binary examples, gotchas, and elite encrypted paths — [references/save patterns deep.md](references/save patterns deep.md). Do not paste Step 1–3 Autoload tutorials into scenes. Expert WHY (critical) CAUTION: Baseline tutorials used store var(data, true) . Untrusted user:// saves must allow objects=false — RCE risk on modded/workshop files. Vectors in JSON — store {x,y,z} components; JSON does not round trip Vector3 faithfully. Rolling backup — crash mid write corrupts primary; copy to .bak before overwrite ([save integrity validator.gd](scripts/save integrity validator.gd)). When to save — menu/checkpoint/level complete only — never per physics frame. Decision Tree: Pick a Persistence Shape Need Format MANDATORY Human readable, small/medium progress JSON + version [save load patterns.gd](scripts/save load patterns.gd) Type faithful Variants / larger blobs Binary store var with allow objects=false same Typed Resource trees / inspector schemas ResourceSaver / .tres / .res Peer godot resource data patterns Many scene nodes auto collect PERSIST group + save() / load() [save load patterns.gd](scripts/save load patterns.gd) Schema evolved Migrate then load [save migration manager.gd](scripts/save migration manager.gd) Anti tamper / sensitive fields Encrypted FileAccess [save system encryption.gd](scripts/save system encryption.gd) Do not paste Step 1–3 JSON Autoload tutorials here — implement from the scripts. allow objects Trust Boundary Default always store var(data, false) / get var(false) . Case allow objects Rule Player user:// saves, workshop mods, downloads false NEVER true — RCE risk Trusted local only (your own tooling, offline debug fixtures you control) true only if unavoidable Document why; never ship as default; prefer Resources / Dictionaries of primitives Encrypted elite paths still use false unless the payload is explicitly trusted local and non user editable. Golden Path (version → migrate → backup → atomic write) 1. Version field on every save blob. 2. Migrate via [save migration manager.gd](scripts/save migration manager.gd) when versions differ. 3. Backup existing file ( DirAccess.copy absolute to .bak ) before overwrite. 4. Write to temp then rename, or write after backup; validate open errors. 5. Integrity optional: FileAccess.get sha256 compare; fall back to backup on mismatch. 6. Paths only user:// — never absolute OS paths. 7. When to save — menu, checkpoint, level complete — never per physics frame. Settings may use ConfigFile separately from run progress JSON/binary. Reference Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice. Official Documentation [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving games.html) — Persist group serialization, JSON line format, and the canonical save/load loop this skill builds on. [File paths in Godot](https://docs.godotengine.org/en/stable/tutorials/io/data paths.html) — user:// vs res:// mapping across OS app data folders; never hardcode absolute paths. [Binary serialization API](https://docs.godotengine.org/en/stable/tutorials/io/binary serialization api.html) — store var / get var Variant encoding, type fidelity, and why allow objects is unsafe for untrusted saves. [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background loading.html) — ResourceLoader.load threaded request for hitch free level/resource loads after a save restore. [File system](https://docs.godotengine.org/en/stable/tutorials/scripting/filesystem.html) — FileAccess/DirAccess workflow for existence checks, backups, and safe overwrite patterns. [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Resource vs Dictionary persistence, duplicate(true) , and when .tres / .res beats hand rolled JSON. [Groups](https://docs.godotengine.org/en/stable/tutorials/scripting/groups.html) — SceneTree group membership used by the Persist/PERSIST auto collect pattern. [FileAccess](https://docs.godotengine.org/en/stable/classes/class fileaccess.html) — Open modes, encrypted with pass AES helpers, SHA 256, compression flags, and buffer I/O. [JSON](https://docs.godotengine.org/en/stable/classes/class json.html) — stringify / parse / parse string for human readable saves and validation of parse errors. [ConfigFile](https://docs.godotengine.org/en/stable/classes/class configfile.html) — INI style settings ( user://settings.cfg ) separate from full game state saves. [ResourceSaver](https://docs.godotengine.org/en/stable/classes/class resourcesaver.html) — Persist typed Resources/custom Resource trees when JSON type loss is unacceptable. [AESContext](https://docs.godotengine.org/en/stable/classes/class aescontext.html) — Low level AES block encrypt/decrypt used by custom compressed encrypted save pipelines. Related Skills Prerequisites [godot project foundations](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot project foundations/SKILL.md) — ProjectSettings, Autoload registration, and user:// project identity must exist before a SaveManager can own paths. [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md) — Typed Dictionaries, Resources, and error handling patterns for versioned serialize/deserialize code. [godot autoload architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot autoload architecture/SKILL.md) — SaveManager is almost always an Autoload; use this for singleton ownership, boot order, and scene change survival. Complements [godot resource data patterns](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot resource data patterns/SKILL.md) — Custom Resource schemas and .tres workflows that pair with ResourceSaver instead of flattening everything to JSON. [godot scene management](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot scene management/SKILL.md) — Threaded scene swaps and wipe/rebuild Persist nodes after load without leaking old world state. [godot signal architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot signal architecture/SKILL.md) — game saved / game loaded event buses so UI and systems react without hard wiring SaveManager. [godot ui containers](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot ui containers/SKILL.md) — Settings menus that write ConfigFile/volume keys this skill persists separately from run progress. [godot inventory system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot inventory system/SKILL.md) — Item stacks and equipment dictionaries are the heaviest Persist payloads; share ID schemes with save migration. [godot quest system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot quest system/SKILL.md) — Quest flags/stage IDs must round trip through versioned saves without breaking journal UI. [godot economy system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot economy system/SKILL.md) — Currency wallets and shop unlocks need the same version field and validation as player progress. Downstream / consumers [godot adapt single to multiplayer](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot adapt single to multiplayer/SKILL.md) — Local save patterns become host authoritative state sync; never trust client edited JSON in multiplayer. [godot monte carlo balancer](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot monte carlo balancer/SKILL.md) — Use when progression/economy curves stored in saves need simulated balance passes against migration defaults. [godot multiplayer networking](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot multiplayer networking/SKILL.md) — Server side validation and snapshot for

godot-save-load-systems