Skip to main content

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​

MemberDescription
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's player, an entry of players.read or players.deleted, or a { id } your server kept.
  • An id is the player's in your game: the same every time they play it, and the one your game's own players.primary has. 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: true in a ticket's player: someone playing logged out. Arcadible gives their device the id and vouches for it, so it's the one your game's own players.primary has, 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: check guest before giving what should take an account.
  • A guest has no name and no values: players.read gives null for one, and a guest as a value's scope fails with denied.

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 }, with guest always false, or null for a player who deleted their account, an id that's no one's in your game, a guest, and a missing player, null or undefined, which isn't asked for.
  • A name is the player's own, as they've set it on Arcadible, or null when 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, take read[i] ?? { ...seat, name: null }, with guest saying 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, when players isn't a list or an entry isn't a player, an id alone included; too_many for more than 50, as Arcadible says; and invalid, unauthorized, busy, or unavailable, 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: next is where to go on from, the last entry's place, whether or not more follow. Keep it, and pass it as after on your next read, however much later. A read has caught up when it comes back with no items, and its next is the after you gave. Never loop until next is null: it isn't, once anything has been listed.
  • since is 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, with Z or an offset such as +02:00; a date alone, a time with no zone, a number, or a Date fails with invalid. Between reads, after alone.
  • Kept 30 days: with neither, it's everyone from the last 30 days.
  • limit is how many entries a read gives at most, 1 to 1000, and 1000 unless you ask; one past either fails with invalid.
  • Each entry is a player, { id }. players.read answers null for them.
  • Fails with invalid for a since or an after that isn't one, and invalid, unauthorized, busy, or unavailable, as every call with a key does.