- name
>
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill save-systems -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill save-systems -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill save-systems -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill save-systems -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/HEAD/skills/disciplines/save-systemsFrom the publisher
A save file is a serialized snapshot of game state that must survive crashes, restarts and patches. The hard parts are choosing what to save, writing it so a crash mid-save cannot destroy it, and reading old saves after an update. This skill owns the file: format, writes, versioning, slots and location. Genre skills decide what goes in it.
Not this skill: Roblox cloud persistence (roblox-datastores), the data model itself
(godot-resources, unity-scriptableobjects), rebinding data shape (input-systems), save
screens and rollback in a visual novel (visual-novel).
FileAccess, ConfigFile,
ResourceSaver, PlayerPrefs, SaveGameToSlot, persistentDataPath) and any shipped
saves. If players already have saves, every change below needs a migration.version in every save from the first release..bak, rename into place.func capture_state() -> Dictionary:
return {
"version": SAVE_VERSION,
"player": { "hp": player.hp, "pos": [player.position.x, player.position.y] },
"inventory": player.inventory.to_array(), # ids + counts, not Item nodes
"flags": world.flags,
"seed": world.seed, # regenerate procedural content
}
func apply_state(data: Dictionary) -> void: # rebuild from data; no live references
player.hp = int(data["player"]["hp"])
player.position = Vector2(data["player"]["pos"][0], data["player"]["pos"][1])
player.inventory.from_array(data["inventory"])
world.flags = data["flags"]
# Godot 4.7. Write a temp file, keep the previous save as .bak, then rename.
func save_atomic(path: String, data: Dictionary) -> Error:
var tmp := path + ".tmp"
var f := FileAccess.open(tmp, FileAccess.WRITE)
if f == null:
return FileAccess.get_open_error() # disk full, read-only, no permission...
if not f.store_string(JSON.stringify(data)):
return ERR_FILE_CANT_WRITE
f.close() # flushes Godot's buffer to the OS
if FileAccess.file_exists(path):
DirAccess.rename_absolute(path, path + ".bak") # keep the last good save
return DirAccess.rename_absolute(tmp, path)
func load_save(path: String) -> Dictionary: # empty = nothing loadable
for p in [path, path + ".bak"]: # .bak covers a crash between renames
if FileAccess.file_exists(p):
var data = JSON.parse_string(FileAccess.get_file_as_string(p))
if data is Dictionary and data.has("version"):
data["version"] = int(data["version"]) # JSON numbers load as float
return data
return {}
# WRONG: opening `path` directly and writing in place — a crash mid-write leaves a
# truncated, unloadable save and destroys the player's progress.
A crash leaves the old save, the new one, or (between the two renames) only the .bak, which
the loader tries next. rename() replaces the target atomically on POSIX within one volume, but
Godot's Windows rename_absolute deletes the target and then moves, so Windows relies on the
.bak as well. Neither flush() nor close() calls fsync, so a power cut right after a save
can still lose the newest file. Check every returned Error and tell the player when a save
fails.
SAVE_VERSION = 3
def load_save(raw_bytes):
data = parse(raw_bytes) # JSON/binary -> dict
v = int(data.get("version", 1)) # no field = the first shipped schema
if v > SAVE_VERSION:
raise NewerSaveError(v) # save is from a newer build; refuse
while v < SAVE_VERSION: # apply migrations in order, v -> v+1
data = MIGRATIONS[v](data)
v += 1
data["version"] = v
validate(data) # check required keys / ranges
return data
# Each migration is a pure function from one version's shape to the next.
def migrate_1_to_2(d):
d["flags"] = {k: True for k in d.pop("completed_quests", [])} # list -> set-map
return d
def migrate_2_to_3(d):
d.setdefault("difficulty", "normal") # new field: old saves get the default
return d
MIGRATIONS = {1: migrate_1_to_2, 2: migrate_2_to_3}
Keep every migration forever; deleting one strands every save of that version.
const SLOT_PATH := "user://save_%d.json" # manual slots 0..N
const AUTOSAVE_PATH := "user://autosave.json" # separate file: never clobbers a slot
var _autosave_cooldown := 0.0
func autosave_if_due(dt: float) -> void:
_autosave_cooldown -= dt
if _autosave_cooldown <= 0.0:
save_atomic(AUTOSAVE_PATH, capture_state())
_autosave_cooldown = 60.0 # at most once a minute; also save on checkpoints
# tools/save_roundtrip_test.gd: godot --headless --path . --script res://tools/save_roundtrip_test.gd
extends SceneTree
const PATH := "user://test_save.json"
func _initialize() -> void:
var saver = load("res://save.gd").new() # the game's save_atomic / load_save
var ok := true
var first := {"version": 3, "player": {"hp": 7, "pos": [1.5, -2.0]}, "flags": {"met_guard": true}}
var second := first.duplicate(true)
second["player"]["hp"] = 4
ok = ok and saver.save_atomic(PATH, first) == OK
ok = ok and saver.save_atomic(PATH, second) == OK # first is now the .bak
var loaded: Dictionary = saver.load_save(PATH)
# Compare fields, not whole Dictionaries: JSON turned hp 4 into 4.0, and 4 != 4.0 there.
ok = ok and loaded.get("version") is int and loaded["player"]["hp"] == 4
ok = ok and loaded["player"]["pos"] == [1.5, -2.0] and loaded["flags"] == second["flags"]
var f := FileAccess.open(PATH, FileAccess.WRITE) # simulate a truncated primary
f.store_string("{\"version\": 3, \"pla")
f.close()
ok = ok and saver.load_save(PATH)["player"]["hp"] == 7 # fell back to .bak
for p in [PATH, PATH + ".bak", PATH + ".tmp"]:
DirAccess.remove_absolute(ProjectSettings.globalize_path(p))
print("SAVE_ROUNDTRIP ", "ok" if ok else "FAIL")
quit(0 if ok else 1)
Point res://save.gd at the game's own save script. The truncated file makes Godot print
Parse JSON failed; that line is expected here, and the test passes only if the .bak loads.
SAVE_ROUNDTRIP ok.Node, Resource, var_to_str, store_var with
objects allowed); there should be none..bak.version 3 loads as 3.0, so
MIGRATIONS.has(data["version"]) is false, whole-Dictionary == against the original fails,
and integers above 2^53 (64-bit ids, big seeds) lose digits. Convert with int(), store big ids
as strings, or wrap the state with JSON.from_native() / JSON.to_native().JSON.parse_string on a corrupt file logs an engine error and returns null. Use a
JSON instance and parse() when you need the error line and message for the player or log.str_to_var or get_var with objects allowed, a
ConfigFile holding objects, or ResourceLoader on a .tres the player can swap will create
an object whose script runs during the load. Saves get shared online; keep them plain data.references/versioning-and-migration.md: read when evolving a schema (additive, rename and
removal migrations), keeping a save corpus, rotating backups, choosing JSON vs binary,
writing load-time validation, finding where saves live per engine, or setting up Steam Cloud.roblox-datastores: cloud persistence, request limits, session locking.godot-resources, unity-scriptableobjects: the data model you serialize.procedural-gen: saving the seed and generator version instead of the world.rpg, survival-crafting, visual-novel: what each genre puts in the save.steam-publish: the Steamworks app admin pages where Steam Cloud is configured.Last verified: 2026-11-11.
FileAccess.store_string returns bool; JSON.from_native/to_native exist;
Windows DirAccess.rename deletes the target before moving
(drivers/windows/dir_access_windows.cpp). The round-trip test above ran on 4.7.2 headless.© 2026 Skills Rack.
---name: save-systemsdescription: >---# skills/disciplines/save-systems/SKILL.mdFAQ
Download skills/disciplines/save-systems/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/gamedev-skills/awesome-gamedev-agent-skills.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.