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
| Member | Description |
|---|---|
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: whatplayers.primary(request)gives, an entry ofplayers.read, or a{ id }your function kept in a value. - 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: true: 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, such as a place on a leaderboard. - A guest has no name and no values:
players.readgivesnullfor one, and a guest as a value's scope fails withdenied.
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.
nullis 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--playeror?player=. - Returns at once: it asks nothing of Arcadible.
- Throws an
ArcadibleErrorwithinvalidoutside 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 }, 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: 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; andbusyorunavailable, as every call does.