roblox data persistence

When to Load

Load when designing player saves, schema migrations, retries, shutdown handling, or session ownership. Use roblox-server-data for ordered leaderboards, messaging, and global world data; roblox-cloud for Open Cloud and external API access.

Quick Reference

• Define a serializable template and a version field before storing player state. Deep-copy templates so nested defaults are not shared between profiles, and run migrations before stamping the version.
• Use UpdateAsync for read-modify-write operations and handle throttling or transient errors.
• Prevent two servers from mutating the same player's profile at once, either with a well-understood wrapper or an equivalent session protocol.
• If using ProfileStore, use StartSessionAsync, Profile.OnSessionEnd, and EndSession as documented. Do not use its Steal option for normal player loading.
• Use ProfileStore.Mock for Studio tests that must not write live DataStore keys.
• Save on meaningful changes and on lifecycle boundaries, but do not assume PlayerRemoving alone is sufficient.
• Use BindToClose to finish pending work within Roblox's shutdown window.
• Store primitives, arrays, and dictionaries. Convert Instances, userdata, functions, and cyclic tables first. Before persisting client-influenced values: numbers must not be NaN or infinity, strings must pass utf8.len, and any nested table must be re-validated, since one unsaveable value fails the whole key write.

Need the details? Load references/full.md for a framework-neutral persistence design.