API Reference

Overview

Your game runs inside the portal page, but in its own protected box (an <iframe>, a page inside a page). It never touches the portal's data directly. Instead it asks, and the portal decides.

The SDK is how you ask. It gives you a small set of functions plus the <cue-card> element for drawing cards on screen.

Every SDK call returns a 'promise', which basically means the answer arrives a moment later. Put await in front of the call and your code waits for the answer before moving on.

// At a glance
const cue = createCueClient({ gameId: 'my-game' });
await cue.init();                          // connect to the portal. Call this first!
await cue.player.me();                     // who's playing
await cue.player.collection();             // the card IDs they own
await cue.player.decks();                  // the decks they've built
await cue.cards.get(ids);                  // card details and art urls
await cue.storage.get(key) / set(key, val);// save and load your game's state

Asking, not writing

SDK calls are requests, not writes. You are asking the portal to do a thing, and the portal checks its own rules first. Only then does anything change. The upside for you: a bug in your game can never hand out cwhat it shouldn't, so you can experiment freely.

Initialise

import { createCueClient } from '@cue/sdk';

const cue = createCueClient({ gameId: 'tripeaks' });
const { player } = await cue.init();
console.log(`Hello, ${player.name}`);

Identity & collection

Some calls hand back a plain bundle of fields with a name ending in DTO, like PlayerDTO or CardDTO. This refers to the 'shape' of the answer you get back - fields are listed in a table right below it.

PlayerDTO

DeckDTO

Cards

const spaceEpics = await cue.cards.query({ album: 'Space', rarity: 'EPIC' });
const myHighCards = await cue.cards.query({ ownedOnly: true, rankMin: 10 });

Card images normally show the whole card: frame, name, rarity, energy, power and the ability box. If your game draws its own stat display then you can (and should!) ask for images with some parts left off using imageOmit. You can remove 'power', 'energy' and/or 'ability', to make your version of the card that bit easier to parse. NB. frame, name and rarity always stay, for consistency.

// Card images without the stat badges, for a game with its own HUD:
const cards = await cue.cards.get(hand, { imageOmit: ['power', 'energy'] });
// Or from a catalog browse:
const clean = await cue.cards.query({ album: 'Space', imageOmit: ['ability'] });

CardDTO

Tags: ready-made themes

About a third of the catalog carries tags: theme labels like "Octopus", "Winged Mythical" or "Knight of the Round Table". And we plan on adding a load more for the purposes of the portal. They are perfect when you want a card pool that feels hand-picked rather than random. There is no tag filter on cards.query(), but filtering the result yourself is one line:

const all = await cue.cards.query();
const knights = all.filter((c) => c.tags?.includes('Knight of the Round Table'));

A card can have more than one tag, and most cards have none, so always check with ?. like above.

Ability text

abilityText is the wording printed in the card's ability box, with no formatting. A card with more than one ability has one line per clause, so split('\n') gives you each one. Where the card shows an icon, the text has a token instead:

const [card] = await cue.cards.get(['HEV003']);
card.abilityText;
// ":draw: For every Holiday 19 card in your deck, your Holiday 19 cards in-hand gain +2:power: until played.
//  :play: Your Holiday 19 cards gain +5:power: this turn.
//  :return: Your Plant Life cards, wherever they are, gain +5:power: permanently."

Swap the tokens for your own icons or words when you show the text. To make the abilities actually do something in your game, use the rules engine instead of reading the words.

Quiz questions

Most cards carry ready-made trivia questions about their subject, so you can build a quiz game without writing a single question yourself. They arrive on the quiz field of every card from cards.get() and cards.query(). A card has one to three questions; some cards have none, so deal from cards.query({ hasQuiz: true }) when your game needs them.

QuizQuestion

const pool = await cue.cards.query({ album: 'Space', hasQuiz: true });
const card = pool[Math.floor(Math.random() * pool.length)];
const q = card.quiz[0];
ask(q.question, q.randomize ? shuffle(q.options) : q.options);
// the right answer is q.options[q.answer], so remember it BEFORE you shuffle

Rendering cards with <cue-card>

The card renderer is a custom HTML element and will look like a CUE card in every game. Register with defineCueCard(), then create and place it like any other element. It works with any framework (or none!) because it is just part of the page.

import { defineCueCard } from '@cue/sdk';
defineCueCard();

const [card] = await cue.cards.get(['EAG001']);
const el = document.createElement('cue-card');
el.card = card;             // fills the art, name and foil from the card in one line
document.body.append(el);

el.card = card is the easy way: hand it a card from cue.cards.get() and it shows the art, name and foil. The art is the full card face, with the energy, power and ability text printed on it, so there is nothing extra to draw. If you want finer control you can still set each attribute yourself (see the table below). cue.cards.get() remembers the cards you ask for, so you can call it on each redraw without slowing down, meaning there is no need to keep your own list of cards.

Try it, live

The last three buttons are imageOmit (see Cards) in action.

Attributes

What it looks like

If you're building without being able to see it live (using an AI assistant, for example), this is a description of what you'd be seeing...

The card is a rounded rectangle (default width 92px, always 5:7) with the art filling it edge to edge over a near-black backing. The art is the finished card face with the name, energy number, power and ability text as part of the image itself. A face-up card is fully readable with no overlays. Face-down shows the back image (if you do not set one, it falls back to the default CUE card back). <cue-card face="down"> always looks right with no extra work. While a face-up card's art is still downloading the card shows a soft grey shimmer in its place, not the back, so a table of loading cards should not look like a deck being turned over. foil is a diagonal glint that slides across the art. selected lifts the card slightly and gives a violet glow, matchable adds a green glow, disabled greys it out, and playable gives it a pointer cursor and a hover lift.

Save state

await cue.storage.set('save', JSON.stringify(state));
const raw = await cue.storage.get('save');
const state = raw ? JSON.parse(raw) : newGame();

Multiplayer

A real-time match server. The platform handles rooms, seats and matchmaking; your game decides what a "turn" or a "move" means.

The easy way is one call. cue.match.lobby() shows a ready-made lobby (a Play button, a "Play with a friend" code screen, and a waiting screen) and hands your game a live match once it starts. You write no menu of your own.

const match = await cue.match.lobby();
if (!match) return showMyTitleScreen(); // the player closed the lobby without starting

// match.room is your live Room. match.seat is your own seat number.
// match.roster is every player's name, in seat order.
startPlaying(match);

The lobby's waiting screen shows the room code and an Invite portal friends button. The portal draws the friend list and sends the invites itself (your game doesn't get the data directly). An invited friend gets a notification with a Join button, and when they tap it your game opens with the lobby already joining that room. You get all of this for free by using lobby(); if you build your own menu with the calls below, invited players still land in your game, they just start from your menu like anyone else.

You can make the lobby your game's whole front screen so a player is one tap from playing, with no menu in front of it. Pass actions to add your own buttons (a practice mode, a tutorial) beside Play, and set dismissable: false since there is nowhere to close to. If the player taps one of your buttons, lobby() resolves with { action: 'the-id-you-gave' } instead of a match, and you do whatever that button means:

const r = await cue.match.lobby({
  title: 'Card Runner',
  dismissable: false,
  actions: [{ id: 'practice', label: 'Practice run' }],
});
if (r.action === 'practice') startPractice(); // your own button
else startMatch(r);                            // r is a Match: r.room, r.seat, r.roster …

Set your game's Max players (and, if you like, Min players) in Studio → Details. Max is how many seats a room has. Set Min below it and a match can start early once that many people have joined. The player who opened the room gets a Start button, and a short countdown starts it for them if they wait too long. Leave Min the same as Max to always wait for a full room.

Build the lobby yourself

Want your own menu and waiting screen instead? The lobby is built on these four calls:

Room

const { code, room } = await cue.match.host();
showCode(code); // share this with the other player(s)

room.on('start', (m) => {
  // m.seat is your seat index. m.roster is one entry per SEAT, in order, with null for
  // every empty one — so m.roster.length is the seat COUNT, not the player count. To
  // count players: m.roster.filter(Boolean).length
  // m.avatarUrls, m.cardBacks and m.sleeves are each seat's chosen look, in the
  // same order (null where a player uses the defaults). The portal fills these
  // from each player's account, so nobody can wear someone else's look.
  // Example: show the other player's card back on their face-down cards:
  //   oppCardEl.setAttribute('back', m.cardBacks[oppSeat] ?? '');
  // m.decks is each seat's main deck (card ids), or null if that player has no
  // playable deck.
  // m.seed is the match seed: a server-made random number, the SAME for every
  // player in this match and different next match. Feed it to a seeded random
  // function and every client deals the same shuffle with no messages needed:
  //   let s = m.seed;
  //   const rand = () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
});
room.on('peer-action', (m) => {
  // m.from is the seat that sent it; m.type / m.data are whatever they sent
});
room.on('seat-left', (m) => { /* m.seat left the game - everyone else plays on */ });
room.on('ended', (m) => { /* the match itself stopped - too many players left (m.reason) */ });
room.on('disconnected', (m) => { /* YOUR connection dropped (network/server), m.reason */ });

room.send('move', { x: 1, y: 2 }); // every OTHER seat gets a peer-action for this

These events (start, peer-action, seat-left, ended, disconnected) are received by all games, and they're typed.

Streaming positions: room.state()

room.send() delivers every message you give it, to every other seat. That is what you want for events: a goal, a pickup, a hit, a score. It is the wrong tool for something you send over and over, like where your player is standing, because in a big room the messages multiply: with 32 players each sending 15 times a second, the room has to push more than 14,000 messages a second and it falls over.

For that, use room.state(). You hand it your latest state, as often as you like. The portal keeps only the newest one per player and sends everybody's together, about 30 times a second, as a single states event:

// Every player publishes where they are, 15 times a second.
setInterval(() => room.state({ x: me.x, y: me.y, facing: me.facing }), 66);

// Everyone else's latest state, all in one go. Keyed by seat number.
room.on('states', (m) => {
  for (const seat in m.seats) {
    if (Number(seat) === mySeat) continue; // your own is in there too, skip it
    const s = m.seats[seat];
    others[seat].moveTo(s.x, s.y, s.facing);
  }
});

If a newer frame turns up before the old one has gone out, the old one is dropped, which is exactly right for a position (you only ever want the current one) - so use state() for that. It's exactly wrong for a score, so for that you'd use send().

A seat that has not published since the last tick is simply missing from m.seats. Keep showing its last known state.

Turn-based matches

Multiplayer where nobody has to be online at the same time. A player asks for a match, the portal pairs them with the next players who ask, and everyone takes turns over hours or days. When you finish your turn, the portal sends the next player a notification with a Play button that opens your game right back on that match. Think chess by post, with CUE cards.

Turn it on in Studio → Details: switch on Turn-based matches, pick Players per turn match (2 to 8) and a Turn time (1 hour to 2 weeks, 72 hours by default). A player who runs out of turn time is out of the match, and the last player left standing wins.

The whole loop looks like this:

import { createCueClient } from '@cue/sdk';
const cue = createCueClient({ gameId: 'my-game' });
await cue.init();

// Did a notification bring the player here? Then resume that match.
const ctx = await cue.turn.context();
if (ctx) {
  showMatch(await cue.turn.get(ctx.matchId));
} else {
  showMenu(await cue.turn.matches()); // their matches, active first
}

// Your menu's Play button:
const res = await cue.turn.play();
if (res.status === 'matched') showMatch(res.match); // someone was waiting
else tellThem("You're in the queue. We'll send a notification when an opponent turns up.");

// Taking a turn:
const updated = await cue.turn.submit(match.matchId, {
  state: JSON.stringify(myGameState), // your own data, up to 64KB
  move: cardId,                       // what you did, shown to the next player
}, match.turn);
showMatch(updated);

The portal stores your match between turns and tells the next player it is their move. It never looks inside state or checks that a move is legal. That is your game's job, the same deal as room.send() in a live match.

Shared docs

Save state (cue.storage) is private, so each player sees only their own. Shared docs are the opposite. A player makes something in your game (a tier list, a bracket, a level), publishes it, and every other player can open it. The portal stores it, so it survives reloads, works on any device, and never has to be squeezed into a share code.

A doc starts private: only its author can read it, so it works as a draft. Publish it with visibility: 'public' and anyone signed in can open it. Each player can keep up to 20 docs per game, each up to 64KB of JSON.

// Save the player's tier list as a draft, then make it public.
let saved = await cue.docs.publish({ title: 'Best dinosaurs', doc: myList });
saved = await cue.docs.publish({
  docId: saved.docId,
  title: saved.title,
  doc: myList,
  version: saved.version,
  visibility: 'public',
});

// Get a link the player can send to a friend.
const url = await cue.docs.link(saved.docId);

The link looks like .../#/play/your-game/abc123.... When someone opens it, the portal launches your game and hands you the doc's id. Check for it at boot, before showing your menu:

const ctx = await cue.docs.context();
if (ctx) {
  const doc = await cue.docs.get(ctx.docId);
  showTierList(doc); // straight to the shared thing, no menu
}

Errors

When the portal says no to a request, the call throws a CueRequestError with a .code:

Under the hood

You don't need this to build a game, but here is how the boundary works. The SDK and the portal pass small messages to each other (the browser's postMessage mechanism), and both sides check exactly who they are talking to before trusting anything:

// request (game -> portal)
{ cue: '1', dir: 'req', id: 'c-42', method: 'player.me', params: {} }
// response (portal -> game)
{ cue: '1', dir: 'res', id: 'c-42', ok: true, result: { /* ... */ } }

• Your game only ever trusts messages from the portal; the portal only trusts your game's own address and the exact frame it launched.
• Every message names its intended receiver explicitly. Nothing is broadcast.
• Save data lives with the player's account on the portal's server (a sandboxed game can't keep its own browser storage), which is why cue.storage is the only way to persist anything.