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
| Member | Description |
|---|---|
wires.open() | A new wire, with this player on it |
wires.join(wire) | A wire someone made, with this player on it |
wire.id | The wire's id, to hand to whoever should join |
wire.members | Who'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: trueand 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
membersholding 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
fullwhen this player is on 4 wires already;deniedfor a guest Arcadible has given no id, which is rare;busywhen the game has opened too many in a minute;unavailablewhen a wire can't be reached now, such as offline; andunsupportedoff 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:
membersis 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,
joinwaits 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
invalidfor what isn't a wire, or isn't one of this game's on this channel;fullwhen the wire is full, or this player is on 4 wires already;busypast a player's joins a minute; anddeniedandunsupportedasopen()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.
| Field | Value |
|---|---|
id | The member's id in your game, the one players.primary.id is for them |
guest | Whether they're logged out |
name | Their 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
joinorleavelistener. - It's empty while this player is off the wire: after their own
leave, until their ownjoin. - A member is a player, and may gain properties: compare and keep the
id. - The others are those whose
idisn't yours:wire.members.filter((m) => m.id !== arcadible.players.primary.id), orfindfor 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 });
datais anything JSON, up to 1 KB, by JSON's own rules: what's sent is whatJSON.stringifymakes of it, and only what it can't make text of at all (undefined, a function, a cycle) fails withinvalid. 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, withfromthis 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
invalidfordatathat 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 errorendcarries);too_largepast the wire's size; andunavailablewhile 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 …
});
| Event | The listener gets |
|---|---|
message | A 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 |
join | The member who came on |
leave | The member who went |
end | The ArcadibleError that ended the wire for this player (A wire's end) |
serveristruefor your game's function, by Arcadible's word. Trustserver, neverfrom === null:fromisnullfor anything that isn't a player, which may one day be more than your function.fromis the member who sent it, by Arcadible's word, ornullfor what isn't a player. No player can send as another, or as the server.datais 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 withserver: trueis your function's word.- A
joinorleavefor this player is the connection's own:leavesays it dropped, andjointhat it's back. Comparemember.idwithplayers.primary.id. - Several listeners each get it, and one that throws stops none of the others.
- Throws an
ArcadibleErrorwithinvalidfor 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,membersis empty, andsendfails withinvalid. - 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 ownjoin. Itsjoinis 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: aleavefor each who went, then ajoinfor each who came, withmembersalready as it is now, so yourjoinandleavelisteners hear every change in who's on. One who was on before and after hears nothing. - While it's off,
membersis empty andsendfails withunavailable. - 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, thenend, and nojoin.
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
retryis"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:
membersis empty, andsendfails withinvalid. To try again, join again. - Your own
leave()isn't an end, and has noendevent.
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.
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | Not a wire, or not one of this game's; data that isn't JSON; a send on a wire it left, or that ended | no | Pass a wire as it was given; send JSON |
too_large | A message past the wire's size, 1 KB | no | Send less: what changed, not the whole state |
full | The wire is full, or this player is on 4 wires already | later | Leave a wire first; split players across wires |
busy | Opening too many wires, or joining too often | yes | Slow down, and try again after a moment |
denied | A guest Arcadible has given no id | no | Say live play isn't available right now, and play on |
unavailable | A wire can't be reached now: offline, or off the wire for a moment | yes | Say so, and play on; the SDK reconnects a wire it's on |
unsupported | Off Arcadible, or on a play page with no wires | no | Play on without live play |
New codes may be added, each with its retry.
Limits
| Limit | Value | When you reach it | What to do |
|---|---|---|---|
| A message | 1 KB, as JSON | The send fails as too_large | Send what changed; keep the rest in values |
| A player's sends on a wire | 20 a second, 40 at once | The SDK holds the message until the wire takes it | Send the latest state, at a steady rate |
| A wire's messages, all players | 200 a second | Players' messages past it are dropped | Split players across wires |
| Members on a wire | 100 | The next to join fails as full | Open another wire |
| A player's connections to a wire | 8, from their windows and devices | The next fails as full | Close a window |
| Wires a player is on at once | 4 in a game, on each channel | The next fails as full | Leave one first |
| A player's joins | 60 a minute, every wire of the game on a channel together | The join fails as busy | Join once, and stay on |
| Wires a game opens | 600 a minute | open() fails as busy | Open a wire for a match, not for a message |
| A connection with nothing heard | Closed within 4 minutes | The member leaves | Nothing: 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 ashttp://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 ownleave, then its ownjoin. - Wires a game opens, a player's joins, and a function's sends, aren't counted, so those are never
busythere. A player's own rate of sending is. - With
--url, wires need your game to have a function: without one,open()fails withunavailable, andjoin()waits, as it does offline.