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 += 50end)
guilds:watch(guildId, function(data) refreshGuildUi(data)end)Options
Section titled “Options”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. |
onError
Section titled “onError”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.
No session lock
Section titled “No session lock”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)endread(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
Section titled “update”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 insidechange; only changedata.
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.
Each update lands once
Section titled “Each update lands once”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.
A refusal stays a refusal
Section titled “A refusal stays a refusal”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.
Result reasons
Section titled “Result reasons”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. |
Use a data store of its own
Section titled “Use a data store of its own”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.
