arcadible.values
The game's data kept on Arcadible, as your game reaches it: JSON under a key, in a scope, for one game and one channel. A game reads what you publish and what the game shares, and reads and writes its own player's, wherever they play. It's in the Arcadible SDK, the package and the hosted script alike, and a call is allowed by the player who's playing.
interface Values {
read<T extends ReadItem>(items: readonly T[]): Promise<(Value | UnchangedFor<T> | null)[]>;
write(items: readonly WriteItem[]): Promise<Written[]>;
remove(items: readonly RemoveItem[], options?: RemoveOptions): Promise<void>;
list(scope: Scope, options?: ListOptions): Promise<Page<Entry>>;
}
type Scope = "developer" | "game" | { readonly id: string };
type ReadItem = { scope: Scope; key: string; since?: number };
type WriteItem = { scope: { readonly id: string }; key: string; value: unknown; revision?: number };
type RemoveItem = { scope: { readonly id: string }; key: string; revision?: number };
type RemoveOptions = { onConflict?: "reject" | "skip" };
type Value = { scope: Scope; key: string; value: unknown; revision: number; updatedAt: string };
type Unchanged = { scope: Scope; key: string; revision: number; unchanged: true };
type Written = { scope: Scope; key: string; revision: number; updatedAt: string };
type UnchangedFor<T> = T extends { key: string; since?: undefined } ? never : Unchanged;
type Conflict = { scope: Scope; key: string };
type ListOptions = { prefix?: string; after?: string | null; limit?: number };
type Page<T> = { items: T[]; next: string | null };
type Entry = { key: string; revision: number; updatedAt: string; size: number | null };
Members
| Member | Description |
|---|---|
read(items) | Values, across scopes, in one snapshot |
write(items) | Replaces the player's own values |
remove(items, options) | Removes the player's own values |
list(scope, options) | A scope's keys, without their values |
Access
A game's calls are allowed by the player it runs for, arcadible.players.primary: the play page asks Arcadible for the game, as that player, and your game holds no key and no token.
- The values a call reaches are your game's, on the channel of the build that's running: staging's build reaches staging's values, and production's, production's.
- A player's values are for a player logged in. A guest has none: a call on a player's values while a guest plays fails with
denied. A guest reads the developer's and the game's like anyone. To offer a guest a log-in, callplayers.logIn(). - A game reaches only its own player's. Another player's fails with
denied. - What a game may do is the scopes' (below): read the developer's and the game's, and read and write its player's.
- On Arcadible only, and under
arc serve. Off Arcadible, such as on your dev server, or on a play page from before values, every call fails withunsupported.
Scopes
A scope says whose a value is. A game reads three of the four, and writes only its player's.
| Scope | Whose | Your game, for its player | Your function, or a server of your own |
|---|---|---|---|
"developer" | Yours: what you publish for the game | Reads | Reads |
"game" | The game's, shared by every player | Reads | Reads and writes |
"server" | Your function's and your servers' | Nothing | Reads and writes |
| A player | One player's, in this game | Reads and writes its own | Reads and writes |
- A player's values are on Arcadible, and follow the account to any device. Saves are on the device, and work offline and for guests.
- What your game writes, a player can. A player's values are written by your game's code, on the player's device, so treat them as the player's own word: a value that must be true, such as a score or a balance, is for your function to write.
- The game's values are written by your function or a server of your own, never by a game, so no player can change what the others see. A game that wants a player to change one asks its function.
- A scope a game can't reach, such as
"server", fails withinvalid.
A player
A player's scope is the player: arcadible.players.primary, or anything with their id, such as a link's by or a wire's member. Only the id is read. An id alone, null, or anything else fails with invalid.
const me = arcadible.players.primary;
if (!me.guest) {
await arcadible.values.write([{ scope: me, key: "progress", value: { level: 3 } }]);
}
Keys, values, and revisions
- A key is 1 to 128 letters, digits,
-,_,., and/. A/is a character like the rest, whichlist'sprefixmakes use of:daily/2026-11-12. - A value is anything JSON holds, up to 64 KB, by JSON's own rules: what's kept is what
JSON.stringifymakes of it, soNaNis kept asnull, and a property that'sundefinedis left out. Only what it can't make text of at all,undefineditself, a function, aBigInt, or a cycle, fails withinvalid. - A value's size is counted as Arcadible keeps it: its JSON with a space after each
:and,, so one a little under 64 KB asJSON.stringifywrites it may still betoo_large. The totals of a write and a scope are counted the same way. - A
revisionis a number that changes each time a value is written, and is never0for a value that exists. Don't read anything else into it. - A time,
updatedAt, is an ISO time, in UTC, to the millisecond:2026-11-10T03:12:00.000Z.
Revisions and conflict
A write or a remove that names a revision is made only if it's still the value's, so a player's two devices never overwrite each other unseen.
- Read, then write with the revision you read. When the value was written in between, such as from the player's other device, the call fails with
conflict, and nothing in it is written: read again, and decide again. - The error names the items that conflicted: its
conflictsis a list of{ scope, key }, one for each item whoserevisionwasn't the value's, in the call's order, with thescopeas you gave it. An item with norevisionis never in it. revision: 0writes only if there's no value yet.- Without a revision, the last write wins.
- A write that fails with
unavailablemay have been kept: Arcadible may have written it before the answer was lost. Trying again with the samerevisionthen fails withconflict, since the value moved on to your own write. So afterunavailable, read again before you write again.
const values = arcadible.values;
const [progress] = await values.read([{ scope: me, key: "progress" }]);
try {
await values.write([{ scope: me, key: "progress", value: next, revision: progress?.revision ?? 0 }]);
} catch (err) {
if (err.code !== "conflict") throw err;
// … written meanwhile, on another device: read it again, and decide again …
}
read(items)
read<T extends ReadItem>(items: readonly T[]): Promise<(Value | UnchangedFor<T> | null)[]>
The values of the items, across scopes, in one request and one snapshot.
const [puzzle, match] = await arcadible.values.read([
{ scope: "developer", key: "daily/2026-11-12" },
{ scope: "game", key: "match/4821" },
]);
- Resolves with a list as long as the one given, in its order: for each, the value, with the
scopeas it was given, ornullfor a key with none. sinceon an item, a revision you have: when the value is still at it, the entry is{ scope, key, revision, unchanged: true }, without its value. A read whose every item is unchanged isn't counted toward your game's calls a day, which makes watching a value cheap.- In TypeScript, an entry is typed
Value | nullwhen no item can namesince, andValue | Unchanged | nullwhen one can: a read with nosinceneeds no check forunchanged. That's whatUnchangedForsays, of the items' type. - An empty list resolves with
[], and asks nothing. - Fails with
invalidfor an item that isn't one, a key or a scope that isn't one, or a key named twice in a scope;too_manyfor more than 32 items;too_largewhen the values together are past 1 MB;deniedfor a player's values while a guest plays, or a player who isn't the one playing.
write(items)
write(items: readonly WriteItem[]): Promise<Written[]>
Replaces each item's value, whole, in the player's own values: all of them, or none.
await arcadible.values.write([
{ scope: me, key: "progress", value: { level: 5 } },
{ scope: me, key: "settings", value: { sound: false } },
]);
- Resolves with each item's
{ scope, key, revision, updatedAt }, in the order given: the value's new revision. - With
revision, an item is written only if that's still the value's revision;0means only if there's no value. Otherwise the whole call fails withconflict, itsconflictsnaming the items, and nothing is written (Revisions andconflict). - Every item or none, always: a write has no way to skip an item, since what's written together is meant to agree. Write what's independent in calls of its own.
- Without
revision, the value is replaced whatever it was. - An empty list resolves with
[], and asks nothing. - Fails with
invalidandtoo_manyasreaddoes, and for a value that isn't JSON;deniedfor the developer's or the game's scope, a player's values while a guest plays, or a player who isn't the one playing;too_largefor a value past 64 KB, or the call's values together past 256 KB;fullwhen the player's storage is used up;limit_reachedonce your game's calls a day are spent. - A write that fails with
unavailablemay have landed, since Arcadible may have acted before its answer was lost: try it again, which is safe, since the same write twice ends the same. One that names arevisionreads first: if the first try landed, the revision moved on, and a retry is refused withconflict(Revisions andconflict).
remove(items, options)
remove(items: readonly RemoveItem[], options?: RemoveOptions): Promise<void>
Removes what each item holds in the player's own values: all of them, or none.
await arcadible.values.remove([{ scope: me, key: "settings" }]);
| Option | Value | Default |
|---|---|---|
onConflict | "reject": a conflict fails the call. "skip": it leaves that item, and the rest go | "reject" |
-
Resolves with nothing. Removing a key with no value does nothing.
-
With
revision, an item is removed only if that's still the value's revision; otherwise the whole call fails withconflict, itsconflictsnaming the items, and nothing is removed. -
With
{ onConflict: "skip" }, each item is on its own: one whoserevisionisn't the value's any more is left as it is, the rest are removed, and the call resolves, never failing withconflict. It's for clearing many values at once, where one that changed since you listed it shouldn't keep the rest. -
An empty list asks nothing.
-
Fails with
invalid,too_many,denied, andlimit_reachedaswritedoes. -
A remove that fails with
unavailablemay have landed, since Arcadible may have acted before its answer was lost: try it again, which is safe, since removing twice ends the same. One that names arevisionreads first: if the first try landed, the revision moved on, and a retry is refused withconflict.
list(scope, options)
list(scope: Scope, options?: ListOptions): Promise<Page<Entry>>
One scope's keys, in order, by byte, each with its revision, time, and size, and never its value.
const { items, next } = await arcadible.values.list("developer", { prefix: "daily/" });
| Option | Value | Default |
|---|---|---|
prefix | Only the keys that start with it | Every key |
after | Where to go on from: the last page's next, as it came | The first key |
limit | How many keys, 1 to 100 | 50 |
- No options, or
null, is every key, 50 at a time. - Resolves with
{ items, next }: each item is{ key, revision, updatedAt, size }, withsizethe value's, in bytes, ornullwhere Arcadible doesn't say;nextgoes back asafterfor the following page, as it came, and isnullat the end. - It isn't a snapshot: a value written between pages may show, or not.
- Fails with
invalidfor a scope, aprefix, anafter, or alimitthat isn't one, anddeniedfor a player's values while a guest plays, or a player who isn't the one playing.
Codes
Every call that fails rejects with an ArcadibleError: act on its code, a string such as "conflict", and on its retry for a code you don't handle.
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | A scope, a key, a value, an item, or an option that isn't one | no | Pass what the call takes |
too_many | More than 32 items in a call | no | Make more than one call |
denied | Arcadible doesn't allow it: writing the developer's or the game's values, a guest's call on a player's, or a player not the one playing | no | Write only the player's own; offer a guest a log-in |
conflict | A value was written since the revision the call named. Nothing was written, and conflicts names the items | later | Read the value again, then write |
too_large | A value past 64 KB, a write's values together past 256 KB, or a read's past 1 MB | no | Keep less in one value, or in one call |
full | The player's storage is used up | later | Remove values first |
busy | Too many calls in a minute, or waiting at once | yes | Slow down, and try again |
limit_reached | For a write or a remove, your account's calls for the month, or the game's for the day, are spent; reads go on | later | Keep what the player did, and write it once the day turns (UTC) |
unavailable | Arcadible couldn't be reached, or didn't answer | yes | Try again; keep what the player did, and write it then |
unsupported | Off Arcadible, or on a play page from before values | no | Play on without them |
New codes may be added, each with its retry. The SDK's other calls are in its reference.
Limits
For each game and channel:
| Limit | Value | When you reach it | What to do |
|---|---|---|---|
| A key | 1 to 128 letters, digits, -, _, ., or / | The call fails as invalid | Rename it |
| A value | 64 KB, as JSON | The write fails as too_large | Split it across keys |
| Items in a call | 32 | The call fails as too_many | Make more than one call |
| A write's values together | 256 KB | The write fails as too_large | Write fewer at once |
| A read's values together | 1 MB | The read fails as too_large | Read fewer at once |
| Keys in a list | 100 a page, 50 unless you ask | A limit past it is invalid | Go on from next |
| A player's | 256 keys and 1 MB, each player | The write fails as full | Remove values first |
| The developer's and the game's | 10,000 keys and 64 MB, each scope | A write to it fails as full | Remove values first |
| Calls a minute | 60 reads or lists, and 30 writes or removes, for a player's address, and for their account | The call fails as busy | Read less often; write at checkpoints |
| Calls a month | 3 million, every game of your account and every player together, by the calendar month in UTC | A write or a remove fails as limit_reached; reads go on | Write less often |
| Calls a day | 500,000 for a game, every player's together, both channels, by the day in UTC | A write or a remove fails as limit_reached; reads go on | Write less often |
A call is counted once, however many items it names. A read whose every item is unchanged (since) isn't counted toward the month or the day, but is toward the minute. You're emailed as your games near the month's calls and when they're spent, and the day a game makes its own, once each. Every limit is also in Limits.
Examples
Today's puzzle, which you publish, and the player's progress, in one call:
const values = arcadible.values;
const me = arcadible.players.primary;
const day = new Date(Date.parse(arcadible.context.launch.at)).toISOString().slice(0, 10);
const [puzzle, solved] = await values.read([{ scope: "developer", key: `daily/${day}` }, ...(me.guest ? [] : [{ scope: me, key: `solved/${day}` }])]);
A match your game's function keeps, watched every few seconds, read again only when it's changed:
let match = null;
setInterval(async () => {
const [seen] = await arcadible.values.read([{ scope: "game", key: "match/4821", ...(match ? { since: match.revision } : {}) }]);
if (seen && !seen.unchanged) {
match = seen;
// … draw the match from match.value …
}
}, 2000);
Under arc serve
arc serve keeps a game's values itself, as channel local, so the game, its function, and a server of your own beside it reach the same ones, and nothing reaches Arcadible.
- The player is a guest, with no values of their own, until your game calls
players.logIn()and the offer is taken: then a local player, "Player", untilarc servestops. Started with--player <name>, or opened as/?player=<name>, the run is that local player from the start, with values of their own. - The developer's values are files in your project, in
.arcadible-data/values/, one a value, as JSON, read as they change:.arcadible-data/values/daily/2026-11-12.jsonisdaily/2026-11-12. - The rest are kept in
.arc/values/local.json, so a match survives a restart. Delete it to start over. - The limits on what a value and a scope hold apply there too; the limits on how often you call don't.