Skip to main content

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​

MemberDescription
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, call players.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 with unsupported.

Scopes​

A scope says whose a value is. A game reads three of the four, and writes only its player's.

ScopeWhoseYour game, for its playerYour function, or a server of your own
"developer"Yours: what you publish for the gameReadsReads
"game"The game's, shared by every playerReadsReads and writes
"server"Your function's and your servers'NothingReads and writes
A playerOne player's, in this gameReads and writes its ownReads 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 with invalid.

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, which list's prefix makes 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.stringify makes of it, so NaN is kept as null, and a property that's undefined is left out. Only what it can't make text of at all, undefined itself, a function, a BigInt, or a cycle, fails with invalid.
  • 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 as JSON.stringify writes it may still be too_large. The totals of a write and a scope are counted the same way.
  • A revision is a number that changes each time a value is written, and is never 0 for 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 conflicts is a list of { scope, key }, one for each item whose revision wasn't the value's, in the call's order, with the scope as you gave it. An item with no revision is never in it.
  • revision: 0 writes only if there's no value yet.
  • Without a revision, the last write wins.
  • A write that fails with unavailable may have been kept: Arcadible may have written it before the answer was lost. Trying again with the same revision then fails with conflict, since the value moved on to your own write. So after unavailable, 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 scope as it was given, or null for a key with none.
  • since on 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 | null when no item can name since, and Value | Unchanged | null when one can: a read with no since needs no check for unchanged. That's what UnchangedFor says, of the items' type.
  • An empty list resolves with [], and asks nothing.
  • Fails with invalid for an item that isn't one, a key or a scope that isn't one, or a key named twice in a scope; too_many for more than 32 items; too_large when the values together are past 1 MB; denied for 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; 0 means only if there's no value. Otherwise the whole call fails with conflict, its conflicts naming the items, and nothing is written (Revisions and conflict).
  • 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 invalid and too_many as read does, and for a value that isn't JSON; denied for 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_large for a value past 64 KB, or the call's values together past 256 KB; full when the player's storage is used up; limit_reached once your game's calls a day are spent.
  • A write that fails with unavailable may 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 a revision reads first: if the first try landed, the revision moved on, and a retry is refused with conflict (Revisions and conflict).

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" }]);
OptionValueDefault
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 with conflict, its conflicts naming the items, and nothing is removed.

  • With { onConflict: "skip" }, each item is on its own: one whose revision isn't the value's any more is left as it is, the rest are removed, and the call resolves, never failing with conflict. 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, and limit_reached as write does.

  • A remove that fails with unavailable may 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 a revision reads first: if the first try landed, the revision moved on, and a retry is refused with conflict.

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/" });
OptionValueDefault
prefixOnly the keys that start with itEvery key
afterWhere to go on from: the last page's next, as it cameThe first key
limitHow many keys, 1 to 10050
  • No options, or null, is every key, 50 at a time.
  • Resolves with { items, next }: each item is { key, revision, updatedAt, size }, with size the value's, in bytes, or null where Arcadible doesn't say; next goes back as after for the following page, as it came, and is null at the end.
  • It isn't a snapshot: a value written between pages may show, or not.
  • Fails with invalid for a scope, a prefix, an after, or a limit that isn't one, and denied for 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.

CodeMeansretryWhat to do
invalidA scope, a key, a value, an item, or an option that isn't onenoPass what the call takes
too_manyMore than 32 items in a callnoMake more than one call
deniedArcadible 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 playingnoWrite only the player's own; offer a guest a log-in
conflictA value was written since the revision the call named. Nothing was written, and conflicts names the itemslaterRead the value again, then write
too_largeA value past 64 KB, a write's values together past 256 KB, or a read's past 1 MBnoKeep less in one value, or in one call
fullThe player's storage is used uplaterRemove values first
busyToo many calls in a minute, or waiting at onceyesSlow down, and try again
limit_reachedFor a write or a remove, your account's calls for the month, or the game's for the day, are spent; reads go onlaterKeep what the player did, and write it once the day turns (UTC)
unavailableArcadible couldn't be reached, or didn't answeryesTry again; keep what the player did, and write it then
unsupportedOff Arcadible, or on a play page from before valuesnoPlay 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:

LimitValueWhen you reach itWhat to do
A key1 to 128 letters, digits, -, _, ., or /The call fails as invalidRename it
A value64 KB, as JSONThe write fails as too_largeSplit it across keys
Items in a call32The call fails as too_manyMake more than one call
A write's values together256 KBThe write fails as too_largeWrite fewer at once
A read's values together1 MBThe read fails as too_largeRead fewer at once
Keys in a list100 a page, 50 unless you askA limit past it is invalidGo on from next
A player's256 keys and 1 MB, each playerThe write fails as fullRemove values first
The developer's and the game's10,000 keys and 64 MB, each scopeA write to it fails as fullRemove values first
Calls a minute60 reads or lists, and 30 writes or removes, for a player's address, and for their accountThe call fails as busyRead less often; write at checkpoints
Calls a month3 million, every game of your account and every player together, by the calendar month in UTCA write or a remove fails as limit_reached; reads go onWrite less often
Calls a day500,000 for a game, every player's together, both channels, by the day in UTCA write or a remove fails as limit_reached; reads go onWrite 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", until arc serve stops. 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.json is daily/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.