godot-save-load-systems

name	godot-save-load-systems
description	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://, serialization, version migration, PERSIST group.

Godot 4.7 Baseline

• Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
• Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
• NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

Save/Load Systems

JSON serialization, version migration, and PERSIST group patterns define robust data persistence.

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

MANDATORY for JSON / binary / PERSIST collect — patterns default store_var(..., false).

save_migration_manager.gd

MANDATORY when any save has a version field that can lag the build.

save_system_encryption.gd

MANDATORY before encrypted slots — password from secure storage / user secret, never hardcoded in examples.

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. 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).
• 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
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
Schema evolved	Migrate then load	save_migration_manager.gd
Anti-tamper / sensitive fields	Encrypted FileAccess	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 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 — Persist group serialization, JSON line format, and the canonical save/load loop this skill builds on.
• File paths in Godot — user:// vs res:// mapping across OS app-data folders; never hardcode absolute paths.
• Binary serialization API — store_var/get_var Variant encoding, type fidelity, and why allow_objects is unsafe for untrusted saves.
• Background loading — ResourceLoader.load_threaded_request for hitch-free level/resource loads after a save restore.
• File system — FileAccess/DirAccess workflow for existence checks, backups, and safe overwrite patterns.
• Resources — Resource vs Dictionary persistence, duplicate(true), and when .tres/.res beats hand-rolled JSON.
• Groups — SceneTree group membership used by the Persist/PERSIST auto-collect pattern.
• FileAccess — Open modes, encrypted-with-pass AES helpers, SHA-256, compression flags, and buffer I/O.
• JSON — stringify/parse/parse_string for human-readable saves and validation of parse errors.
• ConfigFile — INI-style settings (user://settings.cfg) separate from full game-state saves.
• ResourceSaver — Persist typed Resources/custom Resource trees when JSON type loss is unacceptable.
• AESContext — Low-level AES block encrypt/decrypt used by custom compressed encrypted save pipelines.

Related Skills

Prerequisites

• godot-project-foundations — ProjectSettings, Autoload registration, and user:// project identity must exist before a SaveManager can own paths.
• godot-gdscript-mastery — Typed Dictionaries, Resources, and error-handling patterns for versioned serialize/deserialize code.
• godot-autoload-architecture — SaveManager is almost always an Autoload; use this for singleton ownership, boot order, and scene-change survival.

Complements

• godot-resource-data-patterns — Custom Resource schemas and .tres workflows that pair with ResourceSaver instead of flattening everything to JSON.
• godot-scene-management — Threaded scene swaps and wipe/rebuild Persist nodes after load without leaking old world state.
• godot-signal-architecture — game_saved / game_loaded event buses so UI and systems react without hard-wiring SaveManager.
• godot-ui-containers — Settings menus that write ConfigFile/volume keys this skill persists separately from run progress.
• godot-inventory-system — Item stacks and equipment dictionaries are the heaviest Persist payloads; share ID schemes with save migration.
• godot-quest-system — Quest flags/stage IDs must round-trip through versioned saves without breaking journal UI.
• godot-economy-system — Currency wallets and shop unlocks need the same version field and validation as player progress.

Downstream / consumers

• godot-adapt-single-to-multiplayer — Local save patterns become host-authoritative state sync; never trust client-edited JSON in multiplayer.
• godot-monte-carlo-balancer — Use when progression/economy curves stored in saves need simulated balance passes against migration defaults.
• godot-multiplayer-networking — Server-side validation and snapshot formats that replace plaintext user:// saves for competitive modes.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns persistence vs content systems.