$npx -y skills add TabooHarmony/roblox-brain --skill roblox-dataUse when implementing player data persistence with DataStore, session ownership, schemas, migrations, or save and load flows.
| 1 | # roblox data persistence |
| 2 | |
| 3 | ## When to Load |
| 4 | |
| 5 | Load when designing player saves, schema migrations, retries, shutdown handling, session ownership, or cross-server state. Use `roblox-server-data` for ordered leaderboards, messaging, and global world data. |
| 6 | |
| 7 | ## Quick Reference |
| 8 | |
| 9 | - Define a serializable template and a version field before storing player state. |
| 10 | - Use `UpdateAsync` for read-modify-write operations and handle throttling or transient errors. |
| 11 | - Prevent two servers from mutating the same player's profile at once, either with a well-understood wrapper or an equivalent session protocol. |
| 12 | - If using ProfileStore, use `StartSessionAsync`, `Profile.OnSessionEnd`, and `EndSession` as documented. Do not use its `Steal` option for normal player loading. |
| 13 | - Use `ProfileStore.Mock` for Studio tests that must not write live DataStore keys. |
| 14 | - Save on meaningful changes and on lifecycle boundaries, but do not assume `PlayerRemoving` alone is sufficient. |
| 15 | - Use `BindToClose` to finish pending work within Roblox's shutdown window. |
| 16 | - Store primitives, arrays, and dictionaries. Convert Instances, userdata, functions, and cyclic tables first. |
| 17 | |
| 18 | **Need the details?** Load `references/full.md` for a framework-neutral persistence design. |