Save load skill for AI agents

​

When your agent uses it

• Persisting progress, settings, high scores, checkpoints, or save slots
• Deciding between JSON and ConfigFile for a save or settings file
• Making saves survive game updates with a schema version and migration

​

Install

npx -y summer-engine@latest skills install save-load --agent claude-code

​

The skill

​

Where saves go

• user://save_0.json - progress
• user://settings.cfg - options

​

JSON vs ConfigFile

​

Save schema (version it from day one)

const SAVE_PATH := "user://save_0.json"
const SAVE_VERSION := 1

func build_save() -> Dictionary:
	return {
		"version": SAVE_VERSION,
		"level": GameManager.current_level,
		"player": {
			"hp": GameManager.player_health,
			"gold": GameManager.player_gold,
			"pos": var_to_str(player.global_position),  # Vector serialized as string
		},
		"inventory": GameManager.inventory,   # array of item ids, not item nodes
		"flags": GameManager.story_flags,
	}

​

Write and read

func save_game() -> void:
	var f := FileAccess.open(SAVE_PATH, FileAccess.WRITE)
	if f == null:
		push_error("save failed: %s" % FileAccess.get_open_error())
		return
	f.store_string(JSON.stringify(build_save(), "\t"))   # tab-indented, readable
	f.close()

func load_game() -> bool:
	if not FileAccess.file_exists(SAVE_PATH):
		return false
	var f := FileAccess.open(SAVE_PATH, FileAccess.READ)
	var data: Variant = JSON.parse_string(f.get_as_text())
	f.close()
	if typeof(data) != TYPE_DICTIONARY:
		return false                       # corrupt/partial file
	data = _migrate(data)                  # bring old versions up to current
	_apply_save(data)
	return true

​

Migration (do not skip)

func _migrate(data: Dictionary) -> Dictionary:
	var v: int = data.get("version", 0)
	if v < 1:
		data["flags"] = data.get("flags", {})   # field added in v1
		data["version"] = 1
	return data

​

Settings with ConfigFile

func save_settings() -> void:
	var cfg := ConfigFile.new()
	cfg.set_value("audio", "master", master_volume)
	cfg.set_value("video", "fullscreen", is_fullscreen)
	cfg.save("user://settings.cfg")

func load_settings() -> void:
	var cfg := ConfigFile.new()
	if cfg.load("user://settings.cfg") != OK:
		return                              # first run, use defaults
	master_volume = cfg.get_value("audio", "master", 1.0)

​

Autosave hooks

• Save on meaningful checkpoints (level end, area transition, shop close), not every frame. Disk writes stutter.
• Save on quit via _notification:

func _notification(what: int) -> void:
	if what == NOTIFICATION_WM_CLOSE_REQUEST:
		save_game()
		get_tree().quit()

​

Traps

• Storing a node/PackedScene/callable in the save = unserializable or huge. Store ids and rebuild.
• Writing to res:// - read-only in exports; silently fails or errors.
• No version field - the first schema change wipes every player’s save.
• JSON.parse_string returns null on bad input; type-check before using it.
• Floats round-trip fine; ints may load back as floats from JSON - cast on read (int(data["gold"])).

​

Applying it in Summer Engine

• The save code is a script, usually an autoload (res://scripts/autoloads/save_manager.gd): create it with summer_write_file(path=..., content=..., create_only=true), then register it with summer_project_setting(key="autoload/SaveManager", value="*res://scripts/autoloads/save_manager.gd") (the leading * makes it a singleton). Check it with summer_get_script_errors.
• user:// is the per-user data dir, outside the project, so do not expect summer_read_file (a project-file reader) to show a save file. Prove a round trip from inside the game instead: a RunVerification probe (see playtesting-a-feature) that calls save_game(), changes a value, calls load_game(), and report()s the restored value.

​

From a shell

​

Related skills

• make-game: Orchestrate ‘make me a game’: brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship.
• gdscript-patterns: GDScript conventions: type hints, signals, exports, onready, lifecycle methods, node paths, naming.
• ui-basics: Build UI: HUDs, menus, health bars, dialogue boxes, Control trees, anchors, containers and themes.