Make a 2D game

These all chain, so a rare card can be one line:

card.glow({ color: '#ffd166', strength: 2 }).holo({ strength: 1.2 });

// A card leaving play, and its exit
const sparks = card.sparks();
await card.moveTo({ x: 900, ms: 600 });
sparks.stop();
await card.dissolve();

Shapes, text and pictures

Everything you add, cards included, can be moved (thing.x, thing.y), turned (thing.angle, in degrees), faded (thing.alpha), scaled (thing.scale), hidden (thing.visible), stacked (thing.depth, higher is nearer the front), resized (thing.setSize(w, h)), recoloured (thing.setColor()) and removed (thing.remove()).

// A timer bar that drains. Two things matter here. setSize, not scale: the WIDTH is the
// information, and scaling would stretch the rounded ends with it. And setOrigin(0, 0.5),
// which pins the LEFT edge, so it shrinks towards the right instead of closing in from both sides.
const bar = stage
  .addRect({ x: 24, y: 158, w: 672, h: 8, color: '#64e0a0', radius: 4 })
  .setOrigin(0, 0.5);
bar.setSize(672 * fractionLeft);

Looks

Every card, sprite, rectangle and line can carry 'looks'. They are per-pixel work on the thing itself, so a glow is shaped by the artwork rather than by the box. Clear a look by passing null or 0.

They chain, so a styled panel can be achieved in one statement:

const panel = stage.addRect({ x: 360, y: 500, w: 460, h: 300, color: '#141a26', radius: 20 });
panel.shadow({ y: 10 }).glow({ color: '#8b7bff', strength: 1.5 });

// Grade the whole board while a dialog is up, then put it back.
board.forEach((c) => c.blur(1.2).grade('night'));

Effects

This is what a canvas is for. Start with a ready-made effect, change any part of it, or describe your own from scratch.

Make it yours

The eight above are a starting point. You can avoid effects looking 'stock' by using your your own picture, eg:

// Your uploaded art, thrown like a sparkle.
stage.burst({ x, y, kind: 'sparkle', texture: 'my-star.png' });

// Or describe one from nothing.
stage.effect({
  texture: 'petal.png',
  count: 30,
  from: { shape: 'rect', w: 200, h: 20 },  // born across a strip
  speed: [40, 140],
  angle: [-100, -80],                      // upward
  gravity: 120,
  drag: 1.5,
  spin: [-180, 180],
  life: [1, 2.2],
  size: { from: 18, to: 6 },               // ramps over its life
  fade: { from: 1, to: 0, ease: 'in' },
  colors: ['#ffd166', '#ff8fab'],          // walks the list as it ages
  blend: 'add',
}, x, y);

The fields, all optional:

stage.tween(button, { scale: 1.08, ms: 700, repeat: 'forever', yoyo: true });

await stage.tweenValue(0, score, { ms: 900, onUpdate: (v) => label.setText(String(Math.round(v))) });

Put together, a celebration can be a handful of lines:

async function celebrate(a, b) {
  stage.burst({ x: a.x, y: a.y, kind: 'sparkle', power: 1.4 });
  stage.burst({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2, kind: 'ring' });
  stage.shake({ ms: 140 });
  await Promise.all([stage.tween(a, { scale: 1.12, ms: 130 }), stage.tween(b, { scale: 1.12, ms: 130 })]);
  await Promise.all([
    stage.tween(a, { y: a.y - 40, scale: 0.4, alpha: 0, ms: 260, ease: 'in' }),
    stage.tween(b, { y: b.y - 40, scale: 0.4, alpha: 0, ms: 260, ease: 'in' }),
  ]);
}

Input

A tap is not the only thing a player does, and for a card game dragging is the main one.

for (const card of cards) {
  card.onTap(() => {
    pick(card);          // your own function
  });
}

card.drag({
  onDrop: () => {
    const overSlot = Math.abs(card.x - slot.x) < 60;
    if (overSlot) card.moveTo({ x: slot.x, y: slot.y });
    else card.moveTo({ x: home.x, y: home.y });   // send it back
  },
});

A thing's tap area survives being rotated, so (for example) a hand of cards fanned by a few degrees has no awkward dead spots.

Groups

const hand = stage.addGroup({ x: 360, y: 900 });
cards.forEach((card, i) => {
  card.x = (i - 2) * 40;      // positions are now relative to the group
  card.setParent(hand);
});
await stage.tween(hand, { y: 700, angle: 4 });   // the whole hand rises and tilts

Tap targets follow the group too, so a card inside a moved group is hit where you can see it.

The camera

Your board can be bigger than the screen.

Sprites and animation

const coin = stage.addSprite('coin.png', { w: 48, h: 48, sheet: { w: 32, h: 32 } });
coin.play({ frames: [0, 7], fps: 14 });          // spins forever
await explosion.play({ frames: [0, 15], fps: 24, repeat: 0 });   // once, then carry on

Layout and blending

const bar = stage.addRect({ x: 40, y: 60, w: 600, h: 12, color: '#64e0a0' }).setOrigin(0, 0.5);
bar.setSize(600 * fractionLeft);     // shrinks from the right, left edge stays put

An additive circle over a board:

stage.addCircle({ x: 360, y: 400, radius: 120, color: '#ffb457' }).setBlend('add');

A clock, or anything per frame

It runs on the stage's own loop, so it stops when you stop the game:

const clock = stage.addText('60', { x: 360, y: 1100, size: 34, bold: true });
let timeLeft = 60_000;   // milliseconds
let running = true;

stage.on('frame', ({ dt }) => {
  if (!running) return;
  timeLeft = Math.max(0, timeLeft - dt * 1000);
  clock.setText(String(Math.ceil(timeLeft / 1000)));
  if (timeLeft === 0) {
    running = false;
    clock.setColor('#f87171');
  }
});

Sound

await stage.loadSound('flip', 'flip.mp3');
stage.playSound('flip', { volume: 0.6 });

Browsers will not play sound until the player has touched the page, which usually means on the first tap. Nothing to do here, just do not expect noise before then.

Run it

Call stop() when a game has finished. A results screen left running keeps a full loop going for as long as the player leaves it open.

There is also stage.dispose(), which throws the whole stage away but you rarely need it as the portal automatically tidies up when a player closes your game.

Keeping it smooth

Keep an eye on the number of cards you're using at once as each downloads its own art. (The engine shrinks that art to the size you actually draw it, so a small card does cost much less memory than a large one.)

A board of a few dozen cards with effects is fine. Hundreds of cards on screen at once is not, so it's best to select a pool.

Putting it together

Here's a tiny - but complete - game: turn two cards, keep them if they match. So, Snap basically. (But not that Snap. :))

import { createCueClient } from '@cue/sdk';
import { createStage } from '@cue/2d';

const cue = createCueClient({ gameId: 'my-pairs' });
await cue.init();

const stage = await createStage({ cue, canvas: document.querySelector('#scene'), width: 720, height: 1180 });
const score = stage.addText('0', { x: 360, y: 80, size: 40, bold: true });

const pool = await cue.cards.query({ album: 'Space' });
const six = pool.slice(0, 6).map((c) => c.id);
const seats = shuffle([...six, ...six]);

// Cards are off the top of the screen to start with, so they can drop into place.
const cards = await stage.addCards(seats, { w: 132, faceDown: true, y: -200 });
cards.forEach((card, i) => {
  card.x = 130 + (i % 4) * 166;
  card.onTap(() => {
    pick(card);
  });
});

// The board is built so we can 'start'. Do this BEFORE the deal below: an animation needs
// the loop running in order to work.
stage.start();

await Promise.all(
  cards.map((card, i) => card.moveTo({ y: 320 + Math.floor(i / 4) * 210, delay: i * 55 })),
);

let picked = [];
let busy = false;
let points = 0;

async function pick(card) {
  if (busy || !card.faceDown) return;
  busy = true;
  await card.flip();
  picked.push(card);

  if (picked.length === 2) {
    const [a, b] = picked;
    picked = [];
    if (a.id === b.id) {
      points += 100;
      score.setText(String(points));
      a.set({ matchable: true });
      b.set({ matchable: true });
      stage.burst({ x: a.x, y: a.y, kind: 'sparkle' });
      stage.burst({ x: b.x, y: b.y, kind: 'sparkle' });
      await Promise.all([stage.tween(a, { alpha: 0, ms: 300 }), stage.tween(b, { alpha: 0, ms: 300 })]);
      a.visible = false;
      b.visible = false;
    } else {
      await stage.wait(400);
      await Promise.all([a.shake(), b.shake()]);
      await Promise.all([a.flip(), b.flip()]);
    }
  }
  busy = false;
}

// A fair shuffle. Do not be tempted by `list.sort(() => Math.random() - 0.5)`: it looks
// too neat and it does not shuffle evenly.
function shuffle(list) {
  const out = [...list];
  for (let i = out.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [out[i], out[j]] = [out[j], out[i]];
  }
  return out;
}

The busy flag is worth noting here. Without it a fast player can tap a third card while two are still being judged, and your game ends up counting cards that weren't actually displayed!

Why it works this way

Your game runs in its own protected box, separate from the portal, and asks the portal for Info (a card's art, who is playing) via the SDK. @cue/2d is a library that runs inside the box with the game. Like every CUE game it only runs inside the portal.