Skip to content

Shared documents

A profile belongs to one server at a time. Some data belongs to no server: a guild’s bank, a clan’s member list, a global counter. Any server may change it at any time. KeepBlox.shared opens a store of such documents.

const guilds = KeepBlox.shared("Guilds", { template = { members = {}, bank = 0 } })
const result = guilds:update(guildId, function(data)
data.bank += 50
end)
guilds:watch(guildId, function(data)
refreshGuildUi(data)
end)

KeepBlox.shared(name, options) takes the data store name and:

Option Meaning
template The data a document starts with. Give this or schema, not both.
schema The shape of the data (see Schema and migrations). New documents start from its defaults, and every update is checked against it.
config Overrides for the defaults (see Config). A shared store uses loadTimeout, callTimeout, backoffMin and backoffMax.
mock Keep the documents in memory: true, or the name of a scratch set (see Studio and testing).
services The engine services; tests pass fakes.
guilds.onError:connect(function(key, message)
warn(`[KeepBlox] {key}: {message}`)
end)

onError fires (key, message, kind) as a store’s does. A shared store reports one thing through it: in Studio, a place that cannot reach live data (never published, or without API access) keeps the documents in memory for the play test, and says so once, with the key "" and the kind "studio", on the first read, update or watch. See Studio and testing. A failed read or update is not reported here: its result carries the reason.

A shared store never claims a key. There is no load and no release, and no server holds a document between calls. Every update reads and writes the document in one UpdateAsync, so updates from many servers at once never overwrite each other.

Documents are stored in the same record format as profiles, with the data under Data.

const result = guilds:read(guildId)
if result.ok then
print(result.data.bank)
end

read(key) returns a copy of the document’s data. A document that does not exist yet reads as a copy of the template. With a schema, missing fields are filled from its defaults. A failed call is retried with backoff until loadTimeout passes.

update(key, change) runs change(data) inside one UpdateAsync, on the value the store holds at that moment, and returns the data it stored as { ok = true, data = ... }.

That gives change a strict contract:

  • It must not yield. It runs inside the engine’s transform function.
  • It may run more than once. The engine calls the transform again when another server wrote in between, and KeepBlox retries a failed call with backoff until loadTimeout. Do not count calls, send messages or grant anything from inside change; only change data.

After change returns, the data is checked as a profile’s is before a save: every value must be storable, and with a schema it must fit the schema. A refusal writes nothing, and the message names the path of the bad value.

A data store call that fails or times out may still have gone through: Roblox warns that a failed write “does not always guarantee that the backend write did not occur”, and a call KeepBlox stops waiting for keeps running in the engine. Retried blindly, data.bank += 100 would then land twice.

So every update takes one id, the same for all its tries, and stores it in the document by the same write that stores the change. A try that finds its id already there changes nothing and returns the data as stored. A try also checks its own clock: one that runs more than loadTimeout + callTimeout seconds (140 s by default) after the update started changes nothing. A call that answers reason = "failed" may still have landed, but only once.

The ids live in MetaData.KeepBlox.applied, as { id, os.time() } pairs, beside the data the game sees. A document keeps the newest 100, and forgets each one 600 s after its update could last have landed (the 600 s cover servers whose clocks disagree). So an update lands once as long as fewer than 100 other updates of the same document land while it is still being tried.

An update that answers "error" or "refused" never lands later. The risk is the same late try: the first try waits past its deadline, the retry finds a bank of 50 and change refuses to spend 100, the game is told no, then another server adds 100 and the first try runs on 150. So a refusal found by a retry is stored with the update’s id, in MetaData.KeepBlox.refused with its reason and the first 200 characters of its message, and an earlier try that lands later finds it and changes nothing. A refusal on the first try is not stored, and costs no write: no earlier try exists.

A transform that throws inside UpdateAsync does not fail the call on Roblox: the engine logs “Transform function error” and answers as if nothing were to be written (checked live, 2026-10-16). KeepBlox checks that each of its transforms finished, and treats one that did not as a failed write, tried again.

watch(key, handler) calls handler(data) after each update of key made through a shared store, from any server. It returns a connection with Disconnect().

Each successful update publishes a notice on the MessagingService topic KB_<name>/<key>. A watcher that hears it reads the document again and passes the fresh data to handler. The notice carries no data, so a watcher always sees what the store holds. MessagingService is best effort: a notice can be lost, so treat watch as a hint to refresh, not as a log of every change.

A topic may be at most 80 characters. A store name and key that make a longer topic raise an error when the topic is built.

read and update return { ok = true, data = ... } or { ok = false, reason = ..., message = ... }.

Reason From When
"error" update change threw. message holds the error. Nothing is written.
"refused" update The changed data cannot be stored, or breaks the schema. message names the path. Nothing is written.
"foreign" read, update The key holds a value that is not a KeepBlox or ProfileStore record. It is left untouched.
"locked" update A session holds the key: it is a profile, not a shared document. Nothing is written.
"failed" read, update The data store kept failing until loadTimeout passed.

Profile keys are session-locked, and update refuses a key that a session holds ("locked"). Keep shared documents in their own data store, never in the data store of a profile store, so a document key and a profile key can never meet.