Skip to main content

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​

OptionDefaultWhat it does
StoreNamenoneThe DataStore name. Change it to start a fresh, separate store.
TemplatenoneThe shape and default values of a player's data.
KeyPrefix""Prepended to the player's UserId to build their save key.
PlayerKeyKeyPrefix .. UserIdA function (Player) -> string for full control over save keys.
MockfalseUses ProfileStore's in-memory storage. Nothing is saved. Good for tests.
AutoSaveSecondsunsetAdds 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​

OptionDefaultWhat it does
LoadTimeout30Seconds LoadVault waits before giving up and returning nil.
KickOnFailtrueKick a player whose data couldn't load, so they never play on empty data.
KickOnSessionEndtrueKick 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.
caution

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​

OptionDefaultWhat it does
ReplicateMode"Hybrid"How changes reach the client. See below.
MaxPatchesBeforeFull24Once this many patches queue up in a frame, send a full snapshot instead.
CollapsePatchesAt12If one Mutate changes this many keys in a table, send the table as a single patch.
FlushImmediatelyfalseSend each change right away instead of batching them.
ReplicateOnSavefalseSend 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​

OptionDefaultWhat 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.

note

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, Mutate and Snapshot include transient fields. Migrations only see saved data.
  • A Private key that isn't in the template prints a warning. A Transient key that isn't in the template throws.
  • Leaderstats works 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

SignalListener receivesFires
OnSessionStartKey, Player?, DataAfter a session loads, before the client is sent its data.
OnSessionEndKey, Player?Just before a session ends.
OnSaveKey, Player?When Strata saves a session: a manual Save, or an AutoSaveSeconds save.
BeforeMutateContextBefore every server write. It can't cancel the write.
AfterMutateContextAfter every server write.

Context has Key, Player, Data and Path.

Client

SignalListener receivesFires
OnReplicaData, KindAfter 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)
tip

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.

caution

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.