Godot Save Load Systems

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

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).

Encrypted elite paths still use false unless the payload is explicitly trusted-local and non-user-editable.