summer-engine 3.0.0 → 3.2.0

package/library/skills/multiplayer-testing/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: multiplayer-testing
+description: "Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_project_setting summer_play summer_stop summer_get_diagnostics summer_get_console summer_screenshot
+paths: ["project.godot", "summer.build.json", "client/**", "authority/**", "network/**"]
+---
+
+# /multiplayer-testing — prove it works before saying it works
+
+Step 4 of the multiplayer sequence (`multiplayer` explains the model).
+
+**Local Play** runs a Summer multiplayer game on one machine. It starts the
+World's authority scene headless and N clients, and each client joins through
+the game's own `Summer.client.join`. No account, server or extra tools are
+needed. It can also make the network bad on purpose, which is where
+multiplayer bugs show.
+
+## 1. Start Local Play
+
+Pick whichever the session has.
+
+**Summer MCP tools** (they set project settings, then play):
+
+```
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+**Editor:** **Debug > Local Multiplayer**, pick the player count, press Play.
+The client windows tile side by side.
+
+**Terminal** (`<summer>` is the Summer editor executable). Import once after
+adding scripts so their classes register:
+
+```sh
+<summer> --headless --path . --import
+<summer> --path . --summer-local-play 2 --summer-local-play-timeout 30
+```
+
+| Setting | Terminal flag | Meaning |
+|---|---|---|
+| `summer/local_play/players` | `--summer-local-play <n>` | Players to start. `-1` uses the queue's `minPlayers`; `0` turns Local Play off |
+| `summer/local_play/queue` | `--summer-local-play-queue <name>` | Which `summer.build.json` queue to stand in for (default: the first) |
+| — | `--summer-local-play-headless` | Run the clients without windows too |
+| — | `--summer-local-play-timeout <s>` | End the session after that many seconds |
+| — | `--summer-local-play-smoke` | Headless clients; exit 0 once every client joined and stayed 3 s |
+| — | `--summer-local-play-spectators <n>` | Also start spectator clients |
+| — | `--summer-local-play-web` | Run the clients in a browser (the game's Web export) |
+
+## 2. Make the network bad
+
+Loopback has no latency, so it hides every timing bug. Always run once with
+these settings; they apply to every client:
+
+```
+summer_project_setting name="summer/local_play/network/round_trip_msec" value=100
+summer_project_setting name="summer/local_play/network/jitter_msec" value=10
+summer_project_setting name="summer/local_play/network/loss_percent" value=1
+```
+
+Or put them in `project.godot` while testing:
+
+```ini
+[summer]
+
+local_play/network/round_trip_msec=100
+local_play/network/jitter_msec=10
+local_play/network/loss_percent=1
+```
+
+Ranges: round trip 0–2000 ms, jitter 0–1000 ms, loss 0–50 %. Each client
+prints `NETWORK_EMULATION round_trip_ms=100 ...` when it applies. Try 200 ms
+too: that is a player on another continent.
+
+## 3. Read the run
+
+Every output line is prefixed by its process: `[authority]`, `[player-1]`,
+`[player-2]`. The last line is the summary:
+
+```text
+SUMMER_LOCAL_PLAY_RESULT {"ok":true,"players":2,"network":{...},"processes":[{"label":"authority","script_errors":0,...},{"label":"player-1","joined":true,"script_errors":0,...}],...}
+```
+
+A run passes only when **all** of these hold:
+
+- [ ] `"ok":true`, and every process has `"script_errors":0`.
+- [ ] The game's own ready lines appear: the authority's, and one per client after its `join` Command (`COURTYARD_AUTHORITY_READY`, `COURTYARD_CLIENT_JOINED` in the Courtyard example). Print one in your game too.
+- [ ] No `[SummerNetworkSpawner] cannot attach` warning on any process.
+- [ ] No `SCRIPT ERROR` lines.
+
+`"ok":true` alone only proves that clients got seats. If the composition is
+invalid, the Spawner logs `cannot attach` as a warning and nothing networked
+works, yet every client still counts as joined. The smoke flag
+(`--summer-local-play-smoke`) proves the same thing and no more.
+
+With MCP, `summer_get_diagnostics` reports runtime errors from the debugger.
+Read it after every play; `summer_get_console` alone misses them.
+
+## 4. Drive the game with bots
+
+To test gameplay without hands, give the game a bot mode. Arguments after
+`--` reach every process, and `{client}` becomes 1, 2, ... for players and 0
+for the authority:
+
+```sh
+<summer> --path . --summer-local-play 2 --summer-local-play-headless --summer-local-play-timeout 20 -- --bot={client}
+```
+
+Put the bot in `client/bot.gd`. It presses the same input actions a player
+does, so it tests the real controls:
+
+```gdscript
+extends Node
+## Test bot for Local Play, enabled with `-- --bot={client}`. It presses the
+## real input actions. Bot 1 walks to the first coin and collects it; every
+## bot prints what it sees, for the test run to check.
+
+const COIN := "0"
+
+var number := 0
+var main: Node
+var elapsed := 0.0
+var step := 0
+
+
+func _process(delta: float) -> void:
+	elapsed += delta
+	var me := _own_player()
+	if me == null:
+		return
+	if number == 1 and step == 0:
+		var at: Array = main.match_doc.get("coins", {}).get(COIN, [])
+		if at.is_empty():
+			return
+		var to_coin := Vector2(at[0] - me.global_position.x, at[2] - me.global_position.z)
+		if to_coin.length() > 0.5:
+			_steer(to_coin.normalized())
+			return
+		_steer(Vector2.ZERO)
+		step = 1
+		print("BOT_MOVED %s" % me.global_position)
+		var collected: Dictionary = await main.collect(COIN)
+		print("BOT_COLLECT %s" % JSON.stringify(collected))
+	if elapsed > 6.0 and step < 2:
+		step = 2
+		for node in main.get_node("Entities").get_children():
+			if node != me:
+				print("BOT_SAW %s" % node.global_position)
+		print("BOT_SCORES %s" % JSON.stringify(main.match_doc.get("scores", {})))
+
+
+func _own_player() -> Node3D:
+	for node in main.get_node("Entities").get_children():
+		if node.get_script() == preload("res://client/player_owner.gd"):
+			return node
+	return null
+
+
+func _steer(direction: Vector2) -> void:
+	for action in [&"ui_left", &"ui_right", &"ui_up", &"ui_down"]:
+		Input.action_release(action)
+	if direction.x > 0.0: Input.action_press(&"ui_right", direction.x)
+	if direction.x < 0.0: Input.action_press(&"ui_left", -direction.x)
+	if direction.y > 0.0: Input.action_press(&"ui_down", direction.y)
+	if direction.y < 0.0: Input.action_press(&"ui_up", -direction.y)
+```
+
+Add it from `client/main.gd` only when the argument is there, after the
+player has joined:
+
+```gdscript
+	# Local Play test bot: `-- --bot={client}` (see multiplayer-testing).
+	for arg in OS.get_cmdline_user_args():
+		if arg.begins_with("--bot="):
+			var bot := preload("res://client/bot.gd").new()
+			bot.number = int(arg.trim_prefix("--bot="))
+			bot.main = self
+			add_child(bot)
+```
+
+Then check the lines it prints. The Courtyard bot walks player 1 to a coin
+and collects it; player 2 watches:
+
+- [ ] `[player-1] BOT_MOVED` and `[player-2] BOT_SAW` report the same position (the observer is up to 100 ms behind while moving, then equal).
+- [ ] `[player-1] BOT_COLLECT {"ok":true...}` and both players print the new score.
+
+Keep bot code in `client/`: files under `test/` or other debug folders are
+left out of the players' pack, so the shipped game could not load them.
+
+Headless clients have no real window. Guard calls that need one (mouse
+capture, window size) with `DisplayServer.get_name() != "headless"`.
+
+## 5. What Local Play cannot show
+
+- **Hosted-only services** answer with an error code locally: parties,
+  friends, World chat, the store, client leaderboards and analytics. Their
+  skills list the codes. Make the UI hide or explain them; never crash on them.
+- **Matchmaking's accept prompt.** Local Play seats players directly: no
+  proposal, one World per queue.
+- **A player leaving for good.** A client that quits or calls
+  `Summer.client.leave()` only disconnects. `session_disconnected` fires and
+  their seat is held. `session_left` arrives when the World ends; hosted, it
+  arrives when Summer ends the Session.
+- **Real devices, real accounts, real distances.** Publish to staging for that
+  (`multiplayer-publish`).
+
+## Checklist for any multiplayer change
+
+- [ ] Ran Local Play with at least 2 players, and once with 100 ms / 10 ms / 1 %.
+- [ ] Every process: no `SCRIPT ERROR`, no `cannot attach`, `script_errors` 0.
+- [ ] The game's own ready lines appear for the authority and every client.
+- [ ] Your own player responds instantly and never snaps while moving normally.
+- [ ] Other players move smoothly and end where their owners are.
+- [ ] Shared state matches on every client; private state reaches only its owner.
+- [ ] A refused Command changes nothing and shows its reason.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Test only on loopback | Add round trip, jitter and loss | Latency bugs are invisible at 0 ms |
+| Read `"ok":true` as success | Also check your ready lines, `cannot attach` and `script_errors` | A broken composition still joins |
+| Read only `summer_get_console` | `summer_get_diagnostics` after each play | Runtime errors live in the debugger |
+| Put bot or test code under `test/` and load it from the game | Keep the bot in `client/`, enabled by `--bot` | Debug folders are left out of the players' pack |
+| Wait for `session_left` in a local test | Watch `session_disconnected` | Local Play ends Sessions only when the World ends |
+| Skip the import pass after adding scripts | `<summer> --headless --path . --import` first | New classes are unknown until imported |
+
+## Next
+
+`multiplayer-publish`: export the summer.games bundle and upload it as a Build.

package/library/skills/multiplayer-testing/resource.yaml

@@ -0,0 +1,39 @@
+id: skill/multiplayer-testing
+kind: skill
+version: 1.0.0
+summary: "Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows."
+use_when:
+  - "running or testing a Summer multiplayer game locally with several players (Local Play)"
+  - "testing multiplayer under latency, jitter or packet loss, or with bots"
+  - "a multiplayer run says ok but nothing networked works, or deciding whether a multiplayer change is done"
+facets:
+  lifecycle:
+    - build
+    - support
+  domains:
+    - multiplayer
+    - playtest
+    - verification
+  modalities:
+    - scripts
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-project
+    - skill/multiplayer-movement
+    - skill/multiplayer-state
+    - skill/multiplayer-publish
+    - skill/summer-friends
+    - skill/summer-match-results
+    - skill/summer-matchmaking
+    - skill/summer-parties
+    - skill/summer-player-data
+    - skill/summer-store
+    - skill/summer-world-chat
+source: official
+license: MIT
+status: stable
+recommended: false

package/library/skills/music-track/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: music-track
-description: Use when generating a looped or cinematic music track. Loops are authored at >=30s with a marked loop point; cinematic tracks at >=60s linear. Trigger on "generate music", "make a calm track", "boss music", "title screen music", "main theme", "exploration loop", "combat track".
+description: "Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/navigate-summer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: navigate-summer
-description: Use when the user wants to SEE, CHECK, or DECIDE something — "show me my billing", "where do I change my plan", "open my games", "let me look at the scene", "open the MCP guide for Cursor". Decides whether to open a Summer web page or editor surface for the user or to act through the API, and lands exactly there with summer_open.
+description: "When to open a Summer web page or editor surface FOR the user (billing, their games, the scene just built) versus acting through the API, using summer_open."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta

package/library/skills/new-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: new-project
-description: Use when the user wants a fresh blank Summer Engine project — not from a template. Asks one question (project name) and runs `summer create empty <name>`. Trigger on "new project", "blank project", "empty project", "from scratch", "start fresh", "create new game", "blank canvas", "scaffold a project".
+description: "Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project

package/library/skills/organic-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: organic-model
-description: Use when generating organic shapes — trees, rocks, mushrooms, coral, bushes, alien plants, vines, crystals, fruit, bones. The "easy mode" of 3D generation; AI artifacts read as natural irregularity. Trigger on "make a tree", "generate rocks", "I need foliage", "mushroom prop", "alien plants", "fill the scene with shrubs", "scatter some boulders".
+description: "Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets

package/library/skills/pixel-art/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixel-art
-description: Use when generating pixel-art assets — sprites, items, tiles, portraits in a pixel style at a specific resolution (32×32, 64×64, 128×128). Pixel-perfect grid, limited palette, retro feel. Trigger on "pixel art", "8-bit art", "16-bit sprite", "pixel sprite", "retro tileset", "pixel icon", "pixel portrait".
+description: "Generate pixel-art assets — sprites, items, tiles, portraits — at a specific resolution with pixel-perfect grid, limited palette, retro feel."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/play/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: play
-description: Use when the user says "play", "run it", "test it", "let me see it", or "start the game". Runs the project in Summer Engine, briefly waits, then reports what's happening — clean run, errors, or warnings.
+description: "Run the project in Summer Engine, wait briefly, then report what's happening — clean run, errors, or warnings."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

package/library/skills/playtesting-a-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playtesting-a-feature
-description: Use when about to claim a gameplay feature is done, shipped, or working — requires actually running the game and walking through the feature before declaring completion. Static diagnostics and type checks do not count as playtesting.
+description: "Before claiming a gameplay feature done: actually run the game and walk through the feature. Static diagnostics and type checks do not count."
 ---
 
 # Playtesting A Feature

package/library/skills/procedural-animation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: procedural-animation
-description: Use when the user needs runtime-driven bone modification on top of clips — head look-at, foot IK on uneven ground, hand-grabs-prop, additive lean, hit-direction recoil. Code-and-modifier patterns, not generation. Trigger on "look at", "IK", "foot placement", "foot IK", "lean", "additive layer", "feet floating", "hand penetration", "head tracks player", "ragdoll".
+description: "Runtime bone modification on top of clips — head look-at, foot IK, hand-grabs-prop, additive lean, recoil. Code-and-modifier patterns, not generation."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
@@ -243,7 +243,7 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 - **Character is mounted (riding a horse).** Disable foot IK on the rider; ride animation already sells the contact. Enable upper-body additive sway driven by horse acceleration.
 - **First-person hands.** Same modifier set, but only the arm chain is visible — disable head/spine modifiers, keep hand-on-prop IK.
 - **Character is a quadruped.** All four legs need foot IK. The bone names are different (`FrontLeftLeg`, `BackRightLeg`, etc.); inspect first.
-- **Network-synced ragdoll.** Don't simulate on every client. Simulate on the host, send bone transforms via `MultiplayerSynchronizer`, blend on receivers. Out of scope; see `setup-multiplayer`.
+- **Network-synced ragdoll.** Don't simulate it on every client and don't sync bones with `MultiplayerSynchronizer`. In a Summer multiplayer game, send the few values that drive the ragdoll (the impulse, the moment it starts) as State or an Event and let each client simulate locally; see `multiplayer-state`.
 
 ## Fallback (no MCP)
 

package/library/skills/procedural-animation/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/procedural-animation
 kind: skill
-version: 1.0.3
+version: 1.0.4
 summary: Runtime bone modification on top of clips — head look-at, foot IK, hand-grabs-prop, additive lean, recoil. Code-and-modifier patterns, not generation.
 use_when:
   - the user needs runtime-driven bone modification on top of clips — head look-at, foot IK on uneven ground, additive lean, hit recoil, ragdoll

package/library/skills/prop-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prop-model
-description: Use when generating a single static 3D prop — sword, barrel, chest, lantern, throne, statue, crate, key, potion, banner. One isolated object, no rigging, wired into the scene as a MeshInstance3D. Trigger on "make a sword", "generate a chest", "I need a barrel", "add a lantern model", "give me a treasure prop", "create a statue".
+description: "Generate a single static 3D prop — sword, barrel, chest, lantern, throne, statue — one isolated object, no rigging, wired as a MeshInstance3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets

package/library/skills/psx-retro-rendering/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: psx-retro-rendering
-description: "Use when building or reviewing a hardware-informed PlayStation 1 rendering pipeline in Godot 4, including low-resolution output, RGB5 color and exact dithering, affine textures, screen-coordinate snapping, draw-order/depth approximation, vertex lighting, PS1 blend modes, and fog — when accuracy and the limits of each Godot approximation matter, not for a generic pixel-art filter."
+description: "Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named."
 license: MIT
 category: shaders
 tags:

package/library/skills/realtime-wet-surfaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: realtime-wet-surfaces
-description: "Use when adding real-time wetness to existing Godot 4 materials while preserving their parameter values, mapping Unity's Lit-preserving wet ShaderGraph swap onto a value-copying shader conversion with a geometry-driven wet mask and instance-uniform control."
+description: "Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount."
 license: MIT
 category: shaders
 tags:
@@ -186,4 +186,4 @@ The source author states heightmap support so wetness flows along map bumps is *
 
 ## Evidence
 
-- [sources/x/tenmomo-unity-realtime-wet/source.md](../../../sources/x/tenmomo-unity-realtime-wet/source.md)
+- Source record `sources/x/tenmomo-unity-realtime-wet/source.md`, kept outside this package (the evidence boundaries above summarise it).

package/library/skills/remote-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remote-deploy
-description: Use when the user wants to run or test the game on a real target instead of the editor — a phone, tablet, or another computer ("deploy to my phone", "run on device", "test on Android/iOS", "remote deploy", "one-click deploy", "play on hardware"). Covers the topnav Remote Deploy button, runnable export presets, export templates, and on-device remote debugging. Use when the Remote Deploy button is greyed out and the user wants to know why.
+description: "Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment

package/library/skills/retarget/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: retarget
-description: Use when the user wants to apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration. Trigger on "retarget", "reuse animation", "apply to other character", "same animations on different model", "share animation library".
+description: "Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

package/library/skills/running-in-the-cloud/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: running-in-the-cloud
-description: Use when Summer Engine runs in a cloud container, CI job, remote agent sandbox, or any Linux box with no desktop — installing the engine there, launching it headless, deciding when xvfb-run and software GL are required, and authenticating without a browser. Also use when a tool reports "engine not running" in an environment that has no display, or when SUMMER_ENGINE_BINARY / SUMMER_TOKEN come up.
+description: "Run Summer Engine on a Linux box with no display — install it, launch headless, know when xvfb + software GL are needed, authenticate without a browser."
 ---
 
 # Running in the Cloud

package/library/skills/save-load/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: save-load
+description: "Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: scripting-patterns
+user-invocable: false
+allowed-tools: Read Grep summer_read_file summer_write_file summer_replace_text summer_project_setting summer_get_script_errors summer_get_diagnostics
+paths: ["**/*.gd", "project.godot"]
+---
+
+# Save / Load
+
+Trigger phrases: "save progress", "settings menu should remember", "high scores",
+"checkpoints", "save slots", "JSON or ConfigFile?", "saves broke after the update".
+
+Save what the player would be angry to lose, and nothing else. Persist DATA
+(numbers, ids, flags), never live nodes or scene references.
+
+## Where saves go
+
+Always `user://` - a writable per-user dir (`res://` is read-only in an export).
+
+- `user://save_0.json` - progress
+- `user://settings.cfg` - options
+
+Never write gameplay saves to `res://`; it fails in the shipped game.
+
+## JSON vs ConfigFile
+
+| Use JSON when | Use ConfigFile when |
+|---------------|---------------------|
+| Nested/structured game state (inventory, quests, world) | Flat key/value settings |
+| One document you load whole | Sectioned options (audio, video, controls) |
+| You want a schema + version field | You want human-editable ini-style |
+
+Default to JSON for game progress, ConfigFile for settings.
+
+## Save schema (version it from day one)
+
+A top-level `version` field is the difference between "old saves still load after
+an update" and "everyone loses their progress on patch day".
+
+```gdscript
+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,
+	}
+```
+
+Serialize Vectors/Colors with `var_to_str()` and restore with `str_to_var()` -
+JSON has no native Vector2/3.
+
+## Write and read
+
+```gdscript
+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)
+
+When the schema changes, bump `SAVE_VERSION` and upgrade old saves instead of
+rejecting them.
+
+```gdscript
+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
+
+```gdscript
+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)
+```
+
+Always pass a default to `get_value` so a missing key never crashes.
+
+## Autosave hooks
+
+- Save on meaningful checkpoints (level end, area transition, shop close), not
+  every frame. Disk writes stutter.
+- Save on quit via `_notification`:
+
+```gdscript
+func _notification(what: int) -> void:
+	if what == NOTIFICATION_WM_CLOSE_REQUEST:
+		save_game()
+		get_tree().quit()
+```
+
+Set `get_tree().set_auto_accept_quit(false)` so you control the 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.

package/library/skills/save-load/resource.yaml

@@ -0,0 +1,27 @@
+id: skill/save-load
+kind: skill
+version: 1.0.0
+summary: "Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks."
+use_when:
+  - 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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scripting
+    - gameplay
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/gdscript-patterns
+    - skill/ui-basics
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: "Use when building or organizing Summer Engine scenes: node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. Trigger on \"scene\", \"sub-scene\", \"instance\", \"prefab\", \"node hierarchy\", \"scene structure\", \"PackedScene\"."
+description: "Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

package/library/skills/scene-hierarchy-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-hierarchy-design
-description: "Use when applying data-oriented hierarchy principles (from Sander Mertens' ECS hierarchies article) to structure Summer Engine scenes: split asset vs. live hierarchies, group by dominant access pattern, use sub-scenes for reuse, and keep logic path-agnostic via MCP scene tools."
+description: "Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic."
 license: MIT
 category: workflow
 tags:

package/library/skills/scene-scripting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-scripting
-description: Use when building or modifying a scene takes more than a couple of node/property calls — scattering instances, procedural meshes, booleans/lathe/sweep geometry, terrain, GridMap fills, lighting rigs, keyframe animation, shader FX, 2D levels (tilemaps, sprites, bodies, cameras, parallax), HUDs and Control trees, persisted signal wiring, attached scripts, prefabs, input actions/autoloads/main scene, or anything with computed placement. Runs one GDScript inside the live editor via summer_run_script instead of long CRUD chains, verifies with summer_snapshot_diff + summer_screenshot, and checks API names with summer_api_docs instead of guessing.
+description: "One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot."
 ---
 
 # Scene Scripting