Configuration
Two options are required. Everything else has a default that works, and most games never change any of it.
return Strata.Init({
StoreName = "Players", -- required
Template = Template, -- required
})
Storage
| Option | Default | What it does |
|---|---|---|
StoreName | none | The DataStore name. Change it to start a fresh, separate store. |
Template | none | The shape and default values of a player's data. |
KeyPrefix | "" | Prepended to the player's UserId to build their save key. |
PlayerKey | KeyPrefix .. UserId | A function (Player) -> string for full control over save keys. |
Mock | false | Uses ProfileStore's in-memory storage. Nothing is saved. Good for tests. |
AutoSaveSeconds | unset | Adds a save every N seconds on top of ProfileStore's own auto-saving. |
Per-load key control (Key, KeyPrefix, Incognito) lives on LoadVault / GetVault, not in Init.
Sessions
| Option | Default | What it does |
|---|---|---|
LoadTimeout | 30 | Seconds LoadVault waits before giving up and returning nil. |
KickOnFail | true | Kick a player whose data couldn't load, so they never play on empty data. |
KickOnSessionEnd | true | Kick a player if their session ends while they're still in the server. |
KickMessage | "Could not load your data. Please rejoin." | The message shown when a player is kicked. |
Leave KickOnFail on unless you have a plan for players with no data. With it off, a player whose data failed to load stays in the game with no vault, and LoadVault returns nil for them.
Replication
| Option | Default | What it does |
|---|---|---|
ReplicateMode | "Hybrid" | How changes reach the client. See below. |
MaxPatchesBeforeFull | 24 | Once this many patches queue up in a frame, send a full snapshot instead. |
CollapsePatchesAt | 12 | If one Mutate changes this many keys in a table, send the table as a single patch. |
FlushImmediately | false | Send each change right away instead of batching them. |
ReplicateOnSave | false | Send a full snapshot to the client after every manual Save. |
ReplicateMode takes three values:
"Hybrid"is the default. It sends small patches and switches to a full snapshot when a frame has too many of them."Diff"sends patches."Full"always sends the whole table. It's simpler to reason about, and it costs more bandwidth on large data.
Each replica carries a sequence number. If a patch is ever missed, the client notices and asks the server for a fresh snapshot by itself.
Client
| Option | Default | What it does |
|---|---|---|
ClientGuard | "Proxy" | "Proxy" returns read-only tables from Get on the client. "Off" returns the raw table. |
Leaderstats
Name top-level fields that should appear on the Roblox leaderboard. They must be numbers, strings or booleans.
Strata.Init({
StoreName = "Players",
Template = Template,
Leaderstats = { Coins = true },
})
Strata creates the leaderstats folder and keeps it in sync with the data. You never touch the values yourself.
Private and transient fields
By default, every field in your template is saved and sent to the client. Two options change that.
Strata.Init({
StoreName = "Players",
Template = Template,
Private = {
Stats = { AntiCheat = true }, -- one field inside a table
Secret = true, -- a root field
},
Transient = {
Combo = true, -- a root field only
Cooldowns = true,
},
})
Both mirror your template. Any key you leave out defaults to false, so it's saved and replicated as normal.
Private fields are never sent to the client. They're still saved, and everything on the server works as normal: Get, Set, Observe, signals. They can sit at any depth, and Stats = true hides a whole table. The client never receives them: not in the first snapshot, not in a patch.
Transient fields live in memory only and are never saved. Each session starts them from the template, so they're good for cooldowns, combos and anything that should reset when a player rejoins. They replicate to the client like any other field. They have to be root fields, because the saved data is stored as one profile.
Use both on one field to keep it on the server and out of the save.
The client's types still list private fields, because the client and server share one template type. On the client those fields are nil.
Things to know:
- Root
Get,Set,MutateandSnapshotinclude transient fields. Migrations only see saved data. - A
Privatekey that isn't in the template prints a warning. ATransientkey that isn't in the template throws. Leaderstatsworks on transient fields.
Signals
Strata exposes lifecycle and mutation events as signals, so you can connect from anywhere instead of passing callbacks into Init. A signal is a real object, so it uses method syntax (:Connect). Errors inside a listener are caught and warned, so a bad listener never breaks a write.
local Data = require(ReplicatedStorage.Data)
Data.Server.OnSessionStart:Connect(function(Key, Player, SessionData)
print("Loaded", Key)
end)
Data.Server.OnSessionEnd:Connect(function(Key, Player)
print("Ended", Key)
end)
Data.Server.AfterMutate:Connect(function(Context)
print(Context.Key, "changed", table.concat(Context.Path or {}, "."))
end)
Every signal also has Once and Wait.
Server
| Signal | Listener receives | Fires |
|---|---|---|
OnSessionStart | Key, Player?, Data | After a session loads, before the client is sent its data. |
OnSessionEnd | Key, Player? | Just before a session ends. |
OnSave | Key, Player? | When Strata saves a session: a manual Save, or an AutoSaveSeconds save. |
BeforeMutate | Context | Before every server write. It can't cancel the write. |
AfterMutate | Context | After every server write. |
Context has Key, Player, Data and Path.
Client
| Signal | Listener receives | Fires |
|---|---|---|
OnReplica | Data, Kind | After every update from the server. Kind is "Full" or "Patch". |
Data.Client.OnReplica:Connect(function(ReplicaData, Kind)
print("Received a", Kind, "update")
end)
Each node also has its own Changed signal. See Working with data.
Changing your template later
Adding a field to the template is safe. Existing players get the new field and its default the next time they load, and any field whose type changed is reset to the template's value.
For changes that need real logic, like renaming a field or converting a format, set a SchemaVersion in Init and register a migration on the server with BindToMigrate. It runs once per profile, when that profile's saved version is older than yours.
-- Shared data module
return Strata.Init({
StoreName = "Players",
Template = Template,
SchemaVersion = 2,
})
-- Server script
local Data = require(ReplicatedStorage.Data).Server
Data:BindToMigrate(function(data, fromVersion, toVersion)
-- data is fully typed as your template
if fromVersion < 2 then
data.Stats.Xp = data.Xp or 0
data.Xp = nil
end
end)
Bump SchemaVersion by one each time you ship a migration. The callback always receives the profile's old version, so you can handle players who skipped several updates in a single function.
Call BindToMigrate once, early on the server (before or as players join). Without SchemaVersion in config, migrations never run.
Breaking (1.1.0): Migrate is no longer an Init option. Use Server:BindToMigrate so data stays typed.
Reading settings back
local Settings = Data.Server:GetSettings()
print(Settings.ReplicateMode, Settings.LoadTimeout)
The client has the same method, so shared code can check what it's running under.