[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CS1X5RVG8Q9R12CV1AXJG5":3,"skill-same:01M7CS1X5RVG8Q9R12CV1AXJG5":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":32,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M7CS1X5RVG8Q9R12CV1AXJG5","game-save-and-persistence",null,"Use when adding or changing save games, settings or progression storage - a versioned save format with a tested migration chain, atomic writes with backup and checksum, per-engine storage locations, safe serializers, and the round-trip\u002Fmigration\u002Fcorruption tests.","makifbaysal\u002Ftasktrooper","makifbaysal","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F25031940?v=4","01M7CRG3ZCSYZSSEVDMW3DEYC8","Mehmet Akif Baysal","01M7CRG401FJ8YAXH5ER730XYV",122,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fgame-developer\u002Fskills\u002Fgame-save-and-persistence\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: game-save-and-persistence\ncategory: gameplay\ndescription: Use when adding or changing save games, settings or progression storage - a versioned save format with a tested migration chain, atomic writes with backup and checksum, per-engine storage locations, safe serializers, and the round-trip\u002Fmigration\u002Fcorruption tests.\ntech_stack: Game core\nsource: informed by the Unity, Godot, Unreal and MDN storage docs and the .NET BinaryFormatter security guidance; own wording\n---\n# Game Save and Persistence\n\n## Overview\n\nA save file outlives the code that wrote it. Players carry saves across updates, crashes happen mid-write, and a lost 40-hour save is the bug players remember. Every save has a version, every older version has a tested migration, and a write never destroys the last good save.\n\n**Core principle:** Versioned, migrated, written atomically, checked on load — and never deserialized with a format that can execute code.\n\n## The format\n\n```json\n{\n  \"version\": 3,\n  \"savedAtUtc\": \"2026-10-08T12:00:00Z\",\n  \"player\": { \"levelId\": \"forest_02\", \"position\": [12.5, 0, -4.0], \"hp\": 72 },\n  \"inventory\": [{ \"itemId\": \"sword_iron\", \"count\": 1 }],\n  \"flags\": [\"met_blacksmith\", \"boss_forest_defeated\"]\n}\n```\n\n- A plain DTO, separate from engine objects: no `GameObject`, `Node` or `AActor` references, no array indices into data tables — stable IDs only (data-driven-gameplay-design).\n- Settings (volume, bindings, accessibility) in a separate file from progress, so resetting one never touches the other.\n- JSON is readable and diff-able; a compact binary format (MessagePack, protobuf, Godot's `store_var` without objects) is fine when size matters — the version field stays first.\n\n## Migrations\n\n```ts\ntype Migration = (save: any) => any;\nconst migrations: Record\u003Cnumber, Migration> = {\n  1: (s) => ({ ...s, version: 2, inventory: s.items.map((id: string) => ({ itemId: id, count: 1 })) }),\n  2: (s) => ({ ...s, version: 3, flags: Object.keys(s.questState ?? {}).filter((k) => s.questState[k] === \"done\") }),\n};\n\nexport function upgrade(raw: any): SaveV3 {\n  if (typeof raw?.version !== \"number\") throw new SaveError(\"unversioned\");\n  if (raw.version > CURRENT) throw new SaveError(\"from a newer game version\");  \u002F\u002F refuse, never guess\n  let s = raw;\n  while (s.version \u003C CURRENT) s = migrations[s.version](s);\n  return SaveV3Schema.parse(s);\n}\n```\n\n- One migration per version step, never edited after release; each tested with a fixture file captured from that version (`tests\u002Ffixtures\u002Fsaves\u002Fv1.json`, `v2.json`).\n- A save from a newer version is refused with a clear message, not loaded and overwritten.\n- Changing a saved field's meaning without bumping the version is the bug this exists to prevent.\n\n## Writing safely\n\n1. Serialize to bytes in memory.\n2. Write to `save.json.tmp`, flush to disk.\n3. Keep the previous file as `save.json.bak`.\n4. Rename the temp file over `save.json` (atomic on the same volume).\n5. Store a checksum (CRC32 or SHA-256 of the payload) in a header or a sidecar.\n\nOn load: verify the checksum and parse; on failure fall back to `.bak`, tell the player, and never crash or silently start a new game over the old one.\n\nSerialize on the main thread if the engine requires it, but do file I\u002FO off it (or between frames at a checkpoint) — a save must not hitch gameplay. Autosave at checkpoints, not every frame.\n\n## Where saves live\n\n| Engine | Location \u002F API |\n|---|---|\n| Unity | `Application.persistentDataPath` + `System.IO`; `PlayerPrefs` only for tiny settings |\n| Godot | `user:\u002F\u002F` with `FileAccess`; `ConfigFile` for settings |\n| Unreal | `USaveGame` subclass + `UGameplayStatics::AsyncSaveGameToSlot` \u002F `LoadGameFromSlot`; keep a version `UPROPERTY` in it |\n| Web | IndexedDB for saves (async, larger; e.g. `idb-keyval`), `localStorage` only for small settings — it is synchronous, ~5 MB and can throw in private mode or when full |\n| Bevy \u002F Rust | `serde` to the platform data dir (`directories` crate) |\n| pygame \u002F MonoGame | the OS user data directory, never the install folder |\n\nConsoles and some stores impose their own save APIs and size limits — follow the platform layer the repository already has.\n\n## Serializers that execute code — never for save data\n\n- .NET `BinaryFormatter`: obsolete and insecure; do not use it in Unity, MonoGame or Godot C#.\n- Godot: `bytes_to_var_with_objects` \u002F `str_to_var` on untrusted data, and loading a user-supplied `.tres`\u002F`.res`, can instantiate scripts — use `JSON`, `ConfigFile`, or `FileAccess.get_var(false)` (objects disallowed).\n- Python `pickle` for pygame saves: a shared or downloaded save becomes code execution — use JSON.\n- Treat every save file as untrusted input: players edit them, and mods share them.\n\n## Tests\n\n- **Round trip:** state → save → load → equal state.\n- **Migration:** each fixture `vN.json` → `upgrade` → matches the expected current-version object.\n- **Corruption:** truncated file, bad checksum, garbage bytes → falls back to `.bak` and reports; no exception escapes.\n- **Newer version:** refused, original file untouched.\n- **Atomicity:** the write path is tested with a fake file system that fails between steps — the previous save is still loadable.\n\n## Common Mistakes\n\n- Serializing engine objects or private implementation classes directly, so every refactor breaks old saves.\n- No version field; \"we'll add one when we need it\".\n- Writing in place over the only copy.\n- Saving inventory by data-table index; reordering the table corrupts every save.\n- Blocking the main thread with file I\u002FO mid-gameplay.\n\n## Red Flags\n\n- A change to a saved type with no version bump and no migration test.\n- `BinaryFormatter`, `pickle`, or object-enabled Godot variant decoding in a save path.\n- A load path with no fallback when parsing fails.\n","# Game Save and Persistence\n\n## Overview\n\nA save file outlives the code that wrote it. Players carry saves across updates, crashes happen mid-write, and a lost 40-hour save is the bug players remember. Every save has a version, every older version has a tested migration, and a write never destroys the last good save.\n\n**Core principle:** Versioned, migrated, written atomically, checked on load — and never deserialized with a format that can execute code.\n\n## The format\n\n```json\n{\n  \"version\": 3,\n  \"savedAtUtc\": \"2026-10-08T12:00:00Z\",\n  \"player\": { \"levelId\": \"forest_02\", \"position\": [12.5, 0, -4.0], \"hp\": 72 },\n  \"inventory\": [{ \"itemId\": \"sword_iron\", \"count\": 1 }],\n  \"flags\": [\"met_blacksmith\", \"boss_forest_defeated\"]\n}\n```\n\n- A plain DTO, separate from engine objects: no `GameObject`, `Node` or `AActor` references, no array indices into data tables — stable IDs only (data-driven-gameplay-design).\n- Settings (volume, bindings, accessibility) in a separate file from progress, so resetting one never touches the other.\n- JSON is readable and diff-able; a compact binary format (MessagePack, protobuf, Godot's `store_var` without objects) is fine when size matters — the version field stays first.\n\n## Migrations\n\n```ts\ntype Migration = (save: any) => any;\nconst migrations: Record\u003Cnumber, Migration> = {\n  1: (s) => ({ ...s, version: 2, inventory: s.items.map((id: string) => ({ itemId: id, count: 1 })) }),\n  2: (s) => ({ ...s, version: 3, flags: Object.keys(s.questState ?? {}).filter((k) => s.questState[k] === \"done\") }),\n};\n\nexport function upgrade(raw: any): SaveV3 {\n  if (typeof raw?.version !== \"number\") throw new SaveError(\"unversioned\");\n  if (raw.version > CURRENT) throw new SaveError(\"from a newer game version\");  \u002F\u002F refuse, never guess\n  let s = raw;\n  while (s.version \u003C CURRENT) s = migrations[s.version](s);\n  return SaveV3Schema.parse(s);\n}\n```\n\n- One migration per version step, never edited after release; each tested with a fixture file captured from that version (`tests\u002Ffixtures\u002Fsaves\u002Fv1.json`, `v2.json`).\n- A save from a newer version is refused with a clear message, not loaded and overwritten.\n- Changing a saved field's meaning without bumping the version is the bug this exists to prevent.\n\n## Writing safely\n\n1. Serialize to bytes in memory.\n2. Write to `save.json.tmp`, flush to disk.\n3. Keep the previous file as `save.json.bak`.\n4. Rename the temp file over `save.json` (atomic on the same volume).\n5. Store a checksum (CRC32 or SHA-256 of the payload) in a header or a sidecar.\n\nOn load: verify the checksum and parse; on failure fall back to `.bak`, tell the player, and never crash or silently start a new game over the old one.\n\nSerialize on the main thread if the engine requires it, but do file I\u002FO off it (or between frames at a checkpoint) — a save must not hitch gameplay. Autosave at checkpoints, not every frame.\n\n## Where saves live\n\n| Engine | Location \u002F API |\n|---|---|\n| Unity | `Application.persistentDataPath` + `System.IO`; `PlayerPrefs` only for tiny settings |\n| Godot | `user:\u002F\u002F` with `FileAccess`; `ConfigFile` for settings |\n| Unreal | `USaveGame` subclass + `UGameplayStatics::AsyncSaveGameToSlot` \u002F `LoadGameFromSlot`; keep a version `UPROPERTY` in it |\n| Web | IndexedDB for saves (async, larger; e.g. `idb-keyval`), `localStorage` only for small settings — it is synchronous, ~5 MB and can throw in private mode or when full |\n| Bevy \u002F Rust | `serde` to the platform data dir (`directories` crate) |\n| pygame \u002F MonoGame | the OS user data directory, never the install folder |\n\nConsoles and some stores impose their own save APIs and size limits — follow the platform layer the repository already has.\n\n## Serializers that execute code — never for save data\n\n- .NET `BinaryFormatter`: obsolete and insecure; do not use it in Unity, MonoGame or Godot C#.\n- Godot: `bytes_to_var_with_objects` \u002F `str_to_var` on untrusted data, and loading a user-supplied `.tres`\u002F`.res`, can instantiate scripts — use `JSON`, `ConfigFile`, or `FileAccess.get_var(false)` (objects disallowed).\n- Python `pickle` for pygame saves: a shared or downloaded save becomes code execution — use JSON.\n- Treat every save file as untrusted input: players edit them, and mods share them.\n\n## Tests\n\n- **Round trip:** state → save → load → equal state.\n- **Migration:** each fixture `vN.json` → `upgrade` → matches the expected current-version object.\n- **Corruption:** truncated file, bad checksum, garbage bytes → falls back to `.bak` and reports; no exception escapes.\n- **Newer version:** refused, original file untouched.\n- **Atomicity:** the write path is tested with a fake file system that fails between steps — the previous save is still loadable.\n\n## Common Mistakes\n\n- Serializing engine objects or private implementation classes directly, so every refactor breaks old saves.\n- No version field; \"we'll add one when we need it\".\n- Writing in place over the only copy.\n- Saving inventory by data-table index; reordering the table corrupts every save.\n- Blocking the main thread with file I\u002FO mid-gameplay.\n\n## Red Flags\n\n- A change to a saved type with no version bump and no migration test.\n- `BinaryFormatter`, `pickle`, or object-enabled Godot variant decoding in a save path.\n- A load path with no fallback when parsing fails.\n",{"name":5,"source":24,"category":25,"tech_stack":26,"description":7},"informed by the Unity, Godot, Unreal and MDN storage docs and the .NET BinaryFormatter security guidance; own wording","gameplay","Game core","main","910394a0b6db9fc8c9a8f36328ec421d3ebd8b38","catalog\u002Fagents\u002Fgame-developer\u002Fskills\u002Fgame-save-and-persistence",18,"https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper","https:\u002F\u002Ftasktrooper.ai","https:\u002F\u002Fgithub.com\u002Fmakifbaysal","Senior Software Developer","2026-11-15 04:50:29",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add makifbaysal\u002Ftasktrooper --skill game-save-and-persistence",{"tool":42,"command":43},"bunx","bunx skills add makifbaysal\u002Ftasktrooper --skill game-save-and-persistence",{"tool":45,"command":46},"pnpm","pnpm dlx skills add makifbaysal\u002Ftasktrooper --skill game-save-and-persistence","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fgame-developer\u002Fskills\u002Fgame-save-and-persistence\u002FSKILL.md",true,[],[51,57,64,71,78,85],{"skillNo":52,"name":53,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M7CSVEPQW6J6TD6CS2T5FPNZ","visual-craft","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fvisual-craft\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M7CSVAQG91ETHQ0HBNZDG5FR","ux-copy","Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fux-copy\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7CSV6H0J38659NDXHJQ8396","screen-mockup-html","Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fscreen-mockup-html\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7CSV3JFRF3BM3XK52M7YEYR","performance-awareness","How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fperformance-awareness\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7CSTZDH00YRF5SCT7BRT9QD","design-variants","Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-variants\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7CSTV6P3SM3PAE28DB0RF77","design-system-authoring","Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-system-authoring\u002FSKILL.md",[],[]]