Save systems

Where this conflicts with the roblox-lessons skill, roblox-lessons wins. Read roblox-lessons references/data.md first.

A save is a serialized snapshot of authoritative state that outlives the code that wrote it. The hard parts are choosing what to save, never losing it to a bad write, and loading old saves after you ship an update.

On Roblox

• No files: DataStores, through ProfileStore. Session locking stops two servers overwriting each other during fast server hops. ProfileStore auto-saves, saves on leave and on shutdown, and does the atomic read-modify-write for you. Don't hand-roll GetAsync/SetAsync.
• One table per player (profile.Data), mutated only by the server through one service API. The client never writes saves; it only displays what the server sends.
• Never rename the DataStore to change the format. A new name is a new, empty store, and everyone loses their progress. Migrate instead.
• Studio uses its own store (NAME .. "_Studio"), so playtests never touch live players. Guard Studio conveniences with RunService:IsStudio().
• Format limits: values must be JSON-encodable.
  • No Instances, Vector3, CFrame or Color3: store numbers and strings.
  • No tables mixing array and string keys, and no sparse arrays.
  • No NaN or infinity.
  • There is a per-key size limit of about 4 MB.
• Backups: DataStores keep previous versions of a key for a limited time (ListVersionsAsync, GetVersionAsync), which is your rollback path. The Open Cloud API can read a live entry to confirm what was really saved.

Workflow

1. Decide the authoritative state. Save data (ids, counts, levels, flags), never Instances or object references. Rebuild the world from data on load.
2. Stamp dataVersion in the template from day one.
3. Load pipeline:
   • Run Migrate(data, DATA_VERSION) on a deep copy. Steps[v] upgrades v to v+1; run each in pcall.
   • Replace the live data only if every step succeeds.
   • Then Reconcile() to fill new template fields.
   • Then validate (ids still exist in content, numbers sane).
4. Outcomes:
   • current or migrated: load normally.
   • newer (an old server during a rolling update), missingStep or failed: leave the save untouched, end the session and kick with "please rejoin".
   • Reset only pre-launch dev saves below a declared baseline, never live ones.
5. Bump DATA_VERSION together with Steps[old]. A spec should fail until every version from the baseline up has a step. Keep old steps forever.
6. Store, don't derive. Save choices and progress, and recompute derived values (income totals, multipliers) on load, so a formula change in a patch can't desync saves.
7. Verify:
   • Spec the migration chain against fixture saves from each shipped version.
   • Playtest with Studio API access on: save, rejoin, and confirm the state matches.

local function Migrate(data, target, steps)
	local v = data.dataVersion or 0
	if v > target then return "newer", data end
	if v == target then return "current", data end
	if v < BASELINE then return "reset", nil end
	local copy = deepCopy(data)
	while v < target do
		local step = steps[v]
		if not step then return "missingStep", data end
		if not pcall(step, copy) then return "failed", data end
		v += 1
		copy.dataVersion = v
	end
	return "migrated", copy
end

Pitfalls

• Renaming the store, or wiping on a version mismatch.
• Loading a newer save with older code, which silently drops unknown fields on the next write.
• Migrations that mutate the live table and fail halfway.
• Saving Roblox datatypes or Instances, which are dropped or rejected on write.
• Mixed or sparse tables. Key by tostring(id).
• Content removed in a patch (an item id) that crashes the load. Drop or substitute it during validation.
• Trusting the client with any saved value.
• Studio playtests writing to the live store.

References

• references/versioning-and-migration.md: the version field, the migration chain and its rules, backups and rollback, format constraints, a load-time validation checklist, and store vs recompute.

Related: roblox-lessons (data.md, monetization.md for purchase-receipt dedupe stored in the save).

Adapted from awesome-gamedev-agent-skills (Apache-2.0). Modified; see SOURCE.md.