Skip to main content

arcadible.wires

Live messages between the players of your game. A wire is a place players are on together: what one sends, everyone on it gets at once, in one order, and your game's function can speak on it as the server. Nothing is kept. It's in the Arcadible SDK, the package and the hosted script alike. How to use it: Live Play.

interface Wires {
open(): Promise<Wire>;
join(wire: { readonly id: string }): Promise<Wire>;
}

interface Wire {
readonly id: string;
readonly members: readonly Member[];
send(data: unknown): Promise<void>;
on(name: "message", listener: (message: Message) => void): () => void;
on(name: "join" | "leave", listener: (member: Member) => void): () => void;
on(name: "end", listener: (error: ArcadibleError) => void): () => void;
leave(): void;
}

type Member = { id: string; guest: boolean; name: string | null };
type Message = { data: unknown; from: Member | null; server: boolean; at: string };

Members​

MemberDescription
wires.open()A new wire, with this player on it
wires.join(wire)A wire someone made, with this player on it
wire.idThe wire's id, to hand to whoever should join
wire.membersWho's on the wire now
wire.send(data)Sends a message to everyone on the wire
wire.on(name, listener)A message arrived, a member came on or went, or the wire ended
wire.leave()Takes this player off the wire

Two players on a wire​

Sam's game opens a wire, and gets its id to Alex's, here in a link:

const wire = await arcadible.wires.open();
wire.on("message", ({ data, from }) => {
// { data: { x: 3, y: 4 }, from: { id: "9c1e…", guest: false, name: "Alex" }, server: false, at: "2026-11-18T19:00:00.000Z" }
// … draw the move in data, by from …
});
await arcadible.links.share({ data: { wire: wire.id } });

Alex's game joins it, and sends:

const wire = await arcadible.wires.join({ id: arcadible.context.link.data.wire });
wire.members; // [{ id: "3f2b…", guest: false, name: "Sam" }, { id: "9c1e…", guest: false, name: "Alex" }]
await wire.send({ x: 3, y: 4 });

A wire​

  • Everyone on a wire gets each message once, in the same order, the sender too. So two players who press at once agree on who was first, and your game draws what came back, not what it sent.
  • Nothing is kept. A message sent while a player is off the wire is gone for them. Keep your game's state in values, and use the wire to say it changed.
  • Arcadible makes every wire's id. It's opaque: your game hands it on as it came, in a link's data, in a value, in its function's answer.
  • Anyone with a wire's id can join it, and send on it. A wire is as private as its id, which is random and long, so no one guesses one; one that leaks can't be taken back. Keep an id where only those meant to have it can find it, and don't send on a wire what a player on it mustn't see.
  • A wire's id never expires. A wire with no one on it simply waits.
  • A wire is for the channel it was made on. One made on a staging build isn't production's, nor another game's.
  • A member is a player, not a window: the same player in two windows is one member, who leaves when their last window does, and each window gets every message.
  • A guest is a member too, with guest: true and no name.
  • While Arcadible pauses your game, a wire stays connected, and its listeners still run: decide what to do with a move that arrives while your game is held.

wires.open()​

open(): Promise<Wire>

A new wire, with this player on it.

const wire = await arcadible.wires.open();
  • Resolves once the player is on it, with members holding them alone.
  • It takes nothing: no name, and no options.
  • Your game's function can open one too, with no one on it, and hand its id only to the players it has checked (the Function SDK's wires.open()).
  • Fails with full when this player is on 4 wires already; denied for a guest Arcadible has given no id, which is rare; busy when the game has opened too many in a minute; unavailable when a wire can't be reached now, such as offline; and unsupported off Arcadible, or on a play page with no wires.

wires.join(wire)​

join(wire: { readonly id: string }): Promise<Wire>

A wire someone made, with this player on it: anything with its id, such as { id } from a link's data, or what your function's wires.open() gave.

const wire = await arcadible.wires.join({ id });
  • Resolves once the player is on it: members is filled, and events follow.
  • A connection that can't be made now is tried again, as a dropped one is: offline, or Arcadible not answering, join waits and tries again by itself, longer after each failure, and resolves once the player is on. A refusal (an id that isn't one, a full wire, wires not being there at all) fails at once.
  • Read first, then listen. A wire tells of what happens after you join, so read your game's state from values, then take what the wire says after. A message that names a revision lets your game tell what it already has.
  • Joining a wire this player is already on, from another window or device, adds a connection, not a member, up to 8 connections; the next fails with full.
  • Fails with invalid for what isn't a wire, or isn't one of this game's on this channel; full when the wire is full, or this player is on 4 wires already; busy past a player's joins a minute; and denied and unsupported as open() does.

wire.id​

readonly id: string

The wire's id, Arcadible's: opaque, and passed on as it came. Hand it to whoever should join.

wire.members​

readonly members: readonly Member[]

Who's on the wire now, this player included, in the order they came on.

FieldValue
idThe member's id in your game, the one players.primary.id is for them
guestWhether they're logged out
nameTheir name, as players see it; null for a guest, with none, or when it can't be read in time
  • It's Arcadible's word, read as each member connects: no player says their own name or id.
  • It's a new array at each change, so keep it and compare, or read it again in a join or leave listener.
  • It's empty while this player is off the wire: after their own leave, until their own join.
  • A member is a player, and may gain properties: compare and keep the id.
  • The others are those whose id isn't yours: wire.members.filter((m) => m.id !== arcadible.players.primary.id), or find for the other player of two.

wire.send(data)​

send(data: unknown): Promise<void>

Sends a message to everyone on the wire, this player included.

await wire.send({ x: 3, y: 4 });
  • data is anything JSON, up to 1 KB, by JSON's own rules: what's sent is what JSON.stringify makes of it, and only what it can't make text of at all (undefined, a function, a cycle) fails with invalid. A snapshot of a whole world is a value; a message says what changed.
  • Resolves once the message is handed to the connection, not when anyone got it. A game that needs to know asks its function.
  • Everyone gets it as a message, with from this player. Your game gets its own back, in the wire's order.
  • Sent as fast as the wire takes them, in order. A player sends up to 20 messages a second; past it, the SDK holds a message until the wire takes it, and sends it then, so a burst arrives late rather than lost. Send the latest state at a steady rate, not every frame.
  • Fails with invalid for data that isn't JSON, and on a wire this game left or that ended, and a message still held when the game left (one held when the wire ended fails with the error end carries); too_large past the wire's size; and unavailable while this player is off the wire, which the SDK is mending.

wire.on(name, listener)​

on(name: "message", listener: (message: Message) => void): () => void
on(name: "join" | "leave", listener: (member: Member) => void): () => void
on(name: "end", listener: (error: ArcadibleError) => void): () => void

Hears what happens on the wire. Returns a function that unsubscribes.

const off = wire.on("message", ({ data, from, server }) => {
if (server) {
// … your function's word: apply data …
}
});
wire.on("join", (member) => {
// … show member as here …
});
wire.on("leave", (member) => {
// … show member as away …
});
EventThe listener gets
messageA message: its data, who it's from, whether it's the server's, and at, when the wire took it, an ISO time in UTC
joinThe member who came on
leaveThe member who went
endThe ArcadibleError that ended the wire for this player (A wire's end)
  • server is true for your game's function, by Arcadible's word. Trust server, never from === null: from is null for anything that isn't a player, which may one day be more than your function.
  • from is the member who sent it, by Arcadible's word, or null for what isn't a player. No player can send as another, or as the server.
  • data is whatever the sender's game sent, and a player can send from a changed game: read a player's message as input, and check it. Only a message with server: true is your function's word.
  • A join or leave for this player is the connection's own: leave says it dropped, and join that it's back. Compare member.id with players.primary.id.
  • Several listeners each get it, and one that throws stops none of the others.
  • Throws an ArcadibleError with invalid for a name that isn't one of the four, or a listener that isn't a function.

wire.leave()​

leave(): void

Takes this player off the wire, for good. The wire goes on for the rest, who hear the leave.

  • Nothing follows it: no event reaches your game after, not even end, members is empty, and send fails with invalid.
  • To come back, join again with the wire.
  • A game that closes leaves by itself.

A dropped connection​

A network drops, a phone sleeps, a browser freezes a tab. The SDK mends it: it connects again by itself, waiting longer after each failure, for as long as it takes. A join that can't connect at first, such as offline as the game starts, is tried again the same way.

wire.on("leave", (member) => {
if (member.id === arcadible.players.primary.id) showReconnecting();
});
wire.on("join", async (member) => {
if (member.id === arcadible.players.primary.id) {
await readState(); // what was sent meanwhile is gone: read the state again
hideReconnecting();
}
});
  • Your game hears its own leave, then its own join. Its join is the cue to read its state again, since nothing sent meanwhile was kept.
  • Before its own join, who went and who came while it was off: a leave for each who went, then a join for each who came, with members already as it is now, so your join and leave listeners hear every change in who's on. One who was on before and after hears nothing.
  • While it's off, members is empty and send fails with unavailable.
  • The others see the player leave and come back. To forgive a brief drop, wait a few seconds before acting on a leave, and before showing as away a player who's only just been given the wire: a player your function has just seated takes a moment to come on.
  • A player who never comes back leaves within 4 minutes at most, when their connection is found dead.
  • A wire that won't have the player back is over: your game hears its own leave, then end, and no join.

A wire's end​

A wire can be over for this player without their leaving it: the wire won't have them back, such as a guest whose id is gone. The SDK says so with end, the last event the wire sends.

wire.on("end", (error) => {
// … the wire is over for this player: error.code says why; open or join another …
});
  • It's the error that ended it: a close whose retry is "no". Any other close is a drop, which the SDK mends (A dropped connection), so a close it has never heard of is handled right.
  • Nothing follows it: members is empty, and send fails with invalid. To try again, join again.
  • Your own leave() isn't an end, and has no end event.

Codes​

A call that fails rejects with an ArcadibleError: act on its code, and on its retry for a code you don't handle. An end carries one too.

CodeMeansretryWhat to do
invalidNot a wire, or not one of this game's; data that isn't JSON; a send on a wire it left, or that endednoPass a wire as it was given; send JSON
too_largeA message past the wire's size, 1 KBnoSend less: what changed, not the whole state
fullThe wire is full, or this player is on 4 wires alreadylaterLeave a wire first; split players across wires
busyOpening too many wires, or joining too oftenyesSlow down, and try again after a moment
deniedA guest Arcadible has given no idnoSay live play isn't available right now, and play on
unavailableA wire can't be reached now: offline, or off the wire for a momentyesSay so, and play on; the SDK reconnects a wire it's on
unsupportedOff Arcadible, or on a play page with no wiresnoPlay on without live play

New codes may be added, each with its retry.

Limits​

LimitValueWhen you reach itWhat to do
A message1 KB, as JSONThe send fails as too_largeSend what changed; keep the rest in values
A player's sends on a wire20 a second, 40 at onceThe SDK holds the message until the wire takes itSend the latest state, at a steady rate
A wire's messages, all players200 a secondPlayers' messages past it are droppedSplit players across wires
Members on a wire100The next to join fails as fullOpen another wire
A player's connections to a wire8, from their windows and devicesThe next fails as fullClose a window
Wires a player is on at once4 in a game, on each channelThe next fails as fullLeave one first
A player's joins60 a minute, every wire of the game on a channel togetherThe join fails as busyJoin once, and stay on
Wires a game opens600 a minuteopen() fails as busyOpen a wire for a match, not for a message
A connection with nothing heardClosed within 4 minutesThe member leavesNothing: the SDK keeps a live one alive

Every limit is also in Limits.

Under arc serve​

arc serve runs wires itself, with the same rules, and nothing reaches Arcadible.

  • Open a second window as another player with ?player=<name>, such as http://localhost:4100/?player=Alex, or ?player= for a guest. Two windows on one wire are two players.
  • A wire's id made in an earlier run still works, so a match kept in values is still joined after a restart.
  • To try a rejoin, start it with --wires-drop <seconds>: each connection is cut that long after it comes on, and your game hears its own leave, then its own join.
  • Wires a game opens, a player's joins, and a function's sends, aren't counted, so those are never busy there. A player's own rate of sending is.
  • With --url, wires need your game to have a function: without one, open() fails with unavailable, and join() waits, as it does offline.