Skip to main content

players

Your game's players, as your function reaches them: who sent a request, and players' names. The package is the Arcadible Function SDK. Each code a call fails with is in Codes, and the limits are in Limits.

import { players } from "@arcadible/function-sdk";

interface Players {
primary(request: Request): TicketPlayer | null;
read(players: readonly ({ readonly id: string } | null | undefined)[]): Promise<(Player | null)[]>;
}

type TicketPlayer = { id: string; guest: boolean };
type Player = { id: string; guest: boolean; name: string | null };

Members​

MemberDescription
primary(request)Who sent a request
read(players)Players' names

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 request's ticket says who.

  • A call that takes a player reads only its id, so anything with one passes: what players.primary(request) gives, an entry of players.read, or a { id } your function kept in a value.
  • 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: 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, such as a place on a leaderboard.
  • 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.primary(request)​

primary(request: Request): TicketPlayer | null

Who sent a request to your function: the player, { id, guest }, with guest saying whether they're logged out, or null for no one. A request's ticket carries no name: read one with players.read, which takes what this gives as it is.

const me = players.primary(request);
if (me === null) return Response.json({ code: "no_player" }, { status: 403 });
  • It's Arcadible's word. Arcadible checks each request's ticket before your code runs, and a request with none never reaches it, so there's nothing for your function to check.
  • null is no one: a guest whose device has no id from Arcadible yet, such as one that was offline when it first played. It's rare, and passes: the next time they play, they have one. Refuse what needs to know who's asking.
  • Under arc serve, a guest is named by the id their browser keeps, and a player by --player or ?player=.
  • Returns at once: it asks nothing of Arcadible.
  • Throws an ArcadibleError with invalid outside a function, where nobody checked the request.

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([me]);
  • 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: 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 busy or unavailable, as every call does.