players
Your game's players, as your server reaches them with one of your game's keys: their names, and who deleted their account. The package is the Arcadible Server SDK. Each code a call fails with is in Codes, and the limits are in Limits.
import { players } from "@arcadible/server-sdk";
interface Players {
read(players: readonly ({ readonly id: string } | null | undefined)[]): Promise<(Player | null)[]>;
deleted(options?: { after?: string | null; limit?: number; since?: string }): Promise<Feed<DeletedPlayer>>;
}
type Player = { id: string; guest: boolean; name: string | null };
type DeletedPlayer = { id: string };
type Feed<T> = { items: T[]; next: string | null };
Members
| Member | Description |
|---|---|
read(players) | Players' names |
deleted(options) | The players who deleted their accounts |
A player
A player is an object, in every call and every answer, never an id alone, and the same shape in a game, a function, and a server: a Player, { id, guest, name }, where the name is known, and a TicketPlayer, { id, guest }, the same object a field short, where only a ticket says who.
- A call that takes a player reads only its
id, so anything with one passes: a ticket'splayer, an entry ofplayers.readorplayers.deleted, or a{ id }your server kept. - An
idis the player's in your game: the same every time they play it, and the one your game's ownplayers.primaryhas. It's different in every game. It's opaque: keep it and compare it, and read nothing into its form. - A player may gain properties. Arcadible may add to a player in a later version. Don't depend on a player's exact shape, such as by comparing whole objects or expecting the same properties back: compare and keep the
id. - A guest has an id too, with
guest: truein a ticket'splayer: someone playing logged out. Arcadible gives their device the id and vouches for it, so it's the one your game's ownplayers.primaryhas, and the same each time that device plays. It proves it's the same device as before, and nothing more: another browser, or cleared data, is another guest. That's enough to hold a seat in a match. What else a guest may have is yours to choose: checkguestbefore giving what should take an account. - A guest has no name and no values:
players.readgivesnullfor one, and a guest as a value's scope fails withdenied.
players.read(players)
read(players: readonly ({ readonly id: string } | null | undefined)[]): Promise<(Player | null)[]>
Each player as they are now, with their name, in the order given.
const [sam] = await players.read([ticket.player]);
- Resolves with a list as long as the one given, in its order: for each, a
Player,{ id, guest, name }, withguestalwaysfalse, ornullfor a player who deleted their account, anidthat's no one's in your game, a guest, and a missing player,nullorundefined, which isn't asked for. - A
nameis the player's own, as they've set it on Arcadible, ornullwhen they've set none: have a word of your own for a player with no name. Show it as text, never as HTML. It can change, which is why a ticket doesn't carry it: read it when you show it. - A guest is
null, as a player who's gone is: Arcadible keeps nothing of a guest to answer with. To show a seat you hold either way, a player or a guest, takeread[i] ?? { ...seat, name: null }, withguestsaying which. - A player named twice is asked for once, and answered in both places. An empty list resolves with
[], and asks nothing. - Fails with
invalid, before anything is asked, whenplayersisn't a list or an entry isn't a player, an id alone included;too_manyfor more than 50, as Arcadible says; andinvalid,unauthorized,busy, orunavailable, as every call with a key does.
players.deleted(options)
deleted(options?: { after?: string | null; limit?: number; since?: string }): Promise<Feed<DeletedPlayer>>
The players who deleted their Arcadible accounts, oldest first, a feed your server follows.
// from the `next` your server kept last time (or, the first time, `since`)
let read = await players.deleted({ after: kept });
while (read.items.length > 0) {
// … delete what your server keeps for each …
kept = read.next; // keep it, for the next read
read = await players.deleted({ after: kept });
}
- Read it on a schedule, and delete what your server keeps for each player. A player who deletes their account leaves your server no other sign.
- A feed, not a list that ends:
nextis where to go on from, the last entry's place, whether or not more follow. Keep it, and pass it asafteron your next read, however much later. A read has caught up when it comes back with no items, and itsnextis theafteryou gave. Never loop untilnextisnull: it isn't, once anything has been listed. sinceis for a first read, or one after your server lost what it kept: those deleted after a time, within the last 30 days. It's an ISO time that says its zone, withZor an offset such as+02:00; a date alone, a time with no zone, a number, or aDatefails withinvalid. Between reads,afteralone.- Kept 30 days: with neither, it's everyone from the last 30 days.
limitis how many entries a read gives at most, 1 to 1000, and 1000 unless you ask; one past either fails withinvalid.- Each entry is a player,
{ id }.players.readanswersnullfor them. - Fails with
invalidfor asinceor anafterthat isn't one, andinvalid,unauthorized,busy, orunavailable, as every call with a key does.