Skip to main content

Invite links

A player in a multiplayer deck can make an invite link and send it to a friend. A friend who opens it on castle.xyz is placed in the public session the player who sent it is in, when there's room. If both players are 13 or older and neither follows the other yet, they also follow each other on Castle.

Invite links are experimental, and the API may still change.

Turn them on​

Invite links need a multiplayer server. Opt the deck in under server in castle.json:

{
"server": {
"main": "server/index.js",
"invites": true
}
}

Save the deck with castle-web 0.4.248 or later. A deck last saved with an older version can't make or use links: its calls answer { status: "unavailable", reason: "DOCUMENT_MISMATCH" }. To fix that, update the CLI and its base kit, then save again:

npm install -g castle-web-cli@latest
castle-web update-import
castle-web save-deck

Join a public session first, then call DeckInvites.invite():

import { DeckInvites, Multiplayer } from "castle-web-sdk";

const conn = await Multiplayer.join({ mode: "public" });

const result = await DeckInvites.invite();
if (result.status === "ok") {
// result.url looks like https://castle.xyz/d/<deckId>?deckInvite=...
// result.expiresAt is an ISO 8601 time.
showShareButton(result.url);
} else {
// result.reason says why, when Castle gives one.
}

Castle makes the link; your deck doesn't pass a session id or token. The link carries the inviter, not a fixed session: when the friend joins, Castle looks for the public session the inviter is in at that moment. If the inviter has left, or that session is full or can't be joined, the friend joins a public session the usual way. The URL contains the link's secret, so treat it as private to the player: show it to them or hand it to a share button, but don't send it to your server or log it.

When a friend arrives​

The friend's Multiplayer.join({ mode: "public" }) puts them in the inviter's session when it can; you don't pass anything. Once they've joined, call DeckInvites.inviteArrival(). It completes the invite: it makes the two players follow each other (when they qualify, see below) and tells you who invited them. A deck that never calls it still brings the players together, but no follow is made:

const arrival = await DeckInvites.inviteArrival();
if (arrival.status === "ok") {
// arrival.inviter is { userId, username } or null.
// arrival.friends: players from the invite who follow this player and are followed back.
welcome(arrival.inviter);
}

inviteArrival() is unavailable when the player didn't open the deck from a link. It is also unavailable until they're in the session, so call it after the join. You can call it more than once.

Limits​

  • A link works for 24 hours and can be used 5 times.
  • One player can make 12 links an hour.
  • Links work only for public sessions on castle.xyz, not for named or party joins, and not in the Castle app yet.
  • A link never works on a private deck: a private deck always plays solo.
  • Only a signed-in player who is 13 or older can make a link.
  • Anyone who can play the deck can open a link. The two players follow each other only when both are signed-in accounts that are 13 or older, and only if neither follows the other yet. If one already follows the other, Castle adds nothing, so a one-way follow stays one-way. Castle doesn't send a follow notification for it.
  • Castle refuses a link for blocked players, suspended accounts and players who can't use multiplayer. invite() answers unavailable with Castle's reason, and a refused friend plays the deck without being placed in the inviter's session.
  • There's no way to undo the follow from the deck. Players can unfollow each other on Castle as usual.