Skip to main content

Working with data

This page covers how Strata's data model behaves, including nested values, mutations, replication, observations, and session management.

Every example uses the following template:

local Template = {
Coins = 0,
Stats = { Level = 1, Xp = 0 },
Inventory = {} :: { string },
Items = {} :: { [string]: { Damage: number } },
Equipped = nil :: string?,
}

S refers to a player's vault. The server and client expose the same read interface, but the client cannot write to data.

Getting a vault​

There are two ways to retrieve a player's vault:

local S = Data.Server:LoadVault(Player)
local S = Data.Server:GetVault(Player)

LoadVault waits until the player's data is ready. It returns nil if the data cannot be loaded, such as when the player leaves or LoadTimeout expires.

Always check its return value before using the vault:

local S = Data.Server:LoadVault(Player)
if not S then
return
end

GetVault never waits. It returns the existing vault if the player's data is already loaded, otherwise nil. This is useful in code that runs after loading, such as remote handlers.

Non-player sessions​

You can also pass a string key instead of a Player:

local Guild = Data.Server:LoadVault("Guild_42")

This opens a session that isn't tied to a specific player. It can be useful for data shared across a guild, world, or other keyed entity.

Session options​

Both LoadVault and GetVault accept an optional second argument:

export type SessionOptions = {
Incognito: boolean?, -- never save
Key: string?, -- fully override the save key
KeyPrefix: string?, -- override prefix for this load only
}

Incognito (never saves)​

local Ghost = Data.Server:LoadVault(Player, { Incognito = true })

Incognito sessions use a unique throwaway key so the real player profile is never touched. Manual Save, autosave, and end-of-session saves are all skipped. When the session ends, local state is dropped without calling ProfileStore's end-save.

Key override (saves under a fixed key)​

local QA = Data.Server:LoadVault(Player, { Key = "QA_Profile_01" })

Behaves like a normal session, but stores under the key you provide instead of the player's default key.

KeyPrefix override​

local Prefixed = Data.Server:LoadVault(Player, { KeyPrefix = "Test_" })
-- key becomes "Test_<UserId>"

Incognito + Key (load a profile, never write back)​

local Preview = Data.Server:LoadVault(Player, {
Incognito = true,
Key = "Template_Starter",
})

Loads that key's data into memory, then never persists changes. Useful for previews, spectating, or try-before-you-buy flows.

OptionSaves?Key used
(none)YesPlayerKey / KeyPrefix .. UserId or string as-is
Incognito = trueNoUnique incog_<guid> (or explicit Key)
Key = "..."YesExactly that key
Incognito + KeyNoLoads that key, never writes back
KeyPrefix = "..."YesPrefix + UserId (player) or Prefix + string

Reading data​

Every value in the template can be accessed through its corresponding node:

local Coins = S.Coins.Get()
local Level = S.Stats.Level.Get()

local Stats = S.Stats.Get()

You can access nested values by chaining keys. The returned value from Get corresponds to the node you called it on.

Client-side reads​

On the client, tables returned by Get are read-only proxies by default.

You can read and traverse them normally, but attempting to modify them throws an error. This helps prevent accidental local changes from making UI state disagree with the server.

If you need the raw table instead, you can disable this behavior with ClientGuard = "Off".

Writing data​

All writes go through node methods rather than direct assignment.

Set​

Set replaces a node's current value:

S.Coins.Set(50)
S.Stats.Level.Set(2)

It also supports optional fields:

S.Equipped.Set("Wooden Sword")
S.Equipped.Set(nil)

Both calls are valid because Equipped is optional in the template.

Update​

Update receives the current value and returns its replacement:

S.Coins.Update(function(Coins)
return Coins + 10
end)

This is useful when the next value depends on the previous one.

Both Set and Update return the new value.

note

Update always writes the returned value. There is no built-in "skip if unchanged" check. If you only want to write when the value differs, compare first:

if S.Coins.Get() ~= target then
S.Coins.Set(target)
end

Type checks​

Writes are checked against the template. Setting a field to the wrong datatype errors instead of silently storing bad data:

S.Coins.Set("50")
-- error: Strata: type mismatch at Coins — expected number, got string

S.Name.Set(123)
-- error: Strata: type mismatch at Name — expected string, got number

Rules:

  • Primitive leaves (number, string, boolean) must match typeof the template default.
  • Non-empty tables in the template must receive a table.
  • Empty {} collections (open arrays / maps) are not strictly checked.
  • nil optional leaves are not strictly checked.
tip

No direct assignment

S.Coins = 50 -- throws

Error: Strata: assign with .Set(value), not S.Key = value

Data nodes aren't ordinary tables. Writes must go through their methods so Strata can track changes and replicate them correctly.

Mutating tables​

For changes involving multiple fields, use Mutate.

S.Stats.Mutate(function(Stats)
Stats.Level += 1
Stats.Xp = 0
end)

Strata tracks the changes made during the mutation and replicates the resulting changes rather than requiring you to replace the entire table.

Snapshots​

Snapshot returns a deep copy of the current value.

local Before = S.Stats.Snapshot()

Unlike a read-only proxy, a snapshot can be modified freely without changing the actual vault.

This is useful when you need to keep a previous version of some data, prepare changes separately, or pass a copy to another system.

Arrays​

Strata provides methods for common array operations.

S.Inventory.AddNext("Wooden Sword")
S.Inventory.AddNext("Shield")

AddNext adds an item to the end of the array and returns the new length.

S.Inventory.InsertAt(1, "Torch")

InsertAt inserts an item at the specified position, shifting subsequent elements.

local Removed = S.Inventory.RemoveAt(2)
local Last = S.Inventory.RemoveLast()

RemoveAt removes and returns the item at a position. RemoveLast removes and returns the last item.

You can also use Size to retrieve the number of entries:

print(S.Inventory.Size())

Dictionaries​

Dictionaries use the same node API as other tables.

S.Items.Insert("sword_001", {
Damage = 12,
})

You can access individual entries directly:

local Damage = S.Items.sword_001.Damage.Get()

Use Has to check whether an entry exists:

print(S.Items.Has("sword_001"))

Remove deletes an entry and returns its previous value:

local Removed = S.Items.Remove("sword_001")
caution

On array-like tables, numeric indices must use RemoveAt / RemoveLast, not Remove. Calling Remove with a number on an array throws so you don't leave gaps in the sequence.

Shared collection methods​

Arrays and dictionaries also support:

  • Keys — Returns the collection's keys.
  • Values — Returns its values.
  • Size — Returns the number of entries.
  • Clear — Removes all entries.

These methods are available on both collection types.

Observing changes​

Every node has its own Observe, so you watch a field by walking down to it.

local Connection = S.Stats.Level.Observe(function(New, Old)
print("Level is", New, "was", Old)
end)

The listener runs once shortly after you connect, with the current value and nil as the old value. After that it runs whenever the value changes, with the new and old values.

The returned connection can be disconnected when you no longer need the observation:

Connection.Disconnect()

Choosing what to observe​

The node you call Observe on determines which part of the vault you're observing.

S.Coins.Observe(OnCoins)
S.Stats.Observe(OnStats)
S.Observe(OnEntireData)
  • S.Coins observes a single field.
  • S.Stats observes the entire Stats table.
  • S itself observes the entire vault.

Parent and child observations​

Observations account for changes throughout the selected node.

  • Observing a parent fires when one of its descendants changes.
  • Observing a child fires when its parent is replaced.
  • Unchanged values do not trigger another callback.

The listener's value is typed according to the node. For example, observing S.Coins gives the listener a number, while observing S.Stats gives it the corresponding table type. Your editor autocompletes the nodes as you walk down the template.

Changed​

Use Changed when you only want changes and not the current value. It's a signal, so it uses method syntax:

S.Coins.Changed:Connect(function(New, Old)
print(New, "was", Old)
end)

S.Coins.Changed:Once(function(New)
print("First change:", New)
end)

local New, Old = S.Coins.Changed:Wait()

Connect and Once return a connection you can disconnect, and Wait yields until the next change.

Client observations​

The client has the same Observe and Changed on every node:

local C = Data.Client:LoadVault()

if C then
C.Coins.Observe(function(Coins)
CoinLabel.Text = tostring(Coins)
end)
end

There is no separate client observation API. Server-side changes are replicated, and client observations respond to those changes.

Sessions​

Strata manages session loading, saving, and cleanup automatically. You can still interact with a session directly when needed.

S.Save()
S.End()

print(S.IsLoaded())
  • Save requests an immediate save (no-op for Incognito sessions).
  • End ends the session.
  • IsLoaded checks whether the session is still active.

Session information​

Use GetSessionInfo to retrieve information about a session:

local Info = S.GetSessionInfo()

print(Info.UserId)
print(Info.LoadedAt)
print(Info.LastSaveAt)
print(Info.IsActive)

Iterating loaded sessions​

ForEachSession lets you perform an operation on every currently loaded session:

Data.Server:ForEachSession(function(Key, S, Info)
S.Coins.Update(function(Coins)
return Coins + 5
end)
end)

When the server shuts down, active sessions are saved and ended automatically (Incognito sessions are dropped without saving).

To react to sessions starting, ending or saving, see Signals.

Metadata​

Each session has a metadata table alongside its data.

Metadata is stored with the profile, but it isn't part of the template. This makes it useful for bookkeeping values that don't belong in the main data structure.

S.SetMeta("LastDevice", "Mobile")

print(S.GetMeta("LastDevice"))

Replication​

Server-side changes are replicated to the client automatically.

You don't need to create remotes, manually send updates, or request replication after every write.

Strata batches changes made within the same tick. This means multiple writes can be grouped into a single replication update instead of being sent individually.

The client receives a read-only replica. It can read and observe data, but all modifications must happen on the server.

To run code after every update the client receives, connect to Data.Client.OnReplica. See Signals.

Supported values​

Strata supports standard Luau values such as:

  • Numbers
  • Strings
  • Booleans
  • Optional fields
  • Arrays
  • Dictionaries
  • Buffers

It also automatically serializes supported Roblox datatypes, including Vector3, CFrame, Color3, UDim2, EnumItem, and DateTime.

These values are converted for storage and restored when loaded. You can use supported datatypes directly in your template without manually writing serialization logic.

Data limitations​

Strata follows ProfileStore's underlying data restrictions:

  • Arrays cannot contain gaps.
  • Tables cannot mix numeric and string keys.
  • Instances, functions, and threads cannot be saved.

Keep these restrictions in mind when designing your template.