Make a 3D game

const river = world.addZone({ position: [0, -4, 0], size: [50, 2, 50], kills: true });

const goal = world.addZone({ position: [10, 0, 0], size: [3, 3, 3] });
goal.on('enter', (thing) => {
  console.log('something reached the goal');
});

Cards

const catalog = await cue.cards.query({});
catalog.slice(0, 5).forEach((c, i) => world.addCard(c.id, { position: [i * 2 - 4, 2, 5] }));

The player picks up the nearest card (or any carriable block) with E, and drops it with E again. A carried card rides on the avatar's back, facing outward, so from the chase camera behind the player you see its front. It turns with the avatar. A carried thing still collides with the world and other players, just not with the person carrying it.

A common pattern: a delivery pad is a visible part plus an invisible trigger zone, and you deliver by running over it while carrying a card.

const pad = world.addPart({ size: [1.5, 0.1, 1.5], position: [x, 0.05, z], color: '#a16207' });
const slot = world.addZone({ position: [x, 0.9, z], size: [1.6, 1.8, 1.6] });
slot.on('enter', (who) => {
  if (who !== me) return;                     // only react to the player
  const card = me.carryingCard;               // are they carrying one?
  if (!card) return;
  pad.setColor('#16a34a');                    // orange -> green
  world.placeCard(card, { position: [x, 0.6, z] }); // lock it centered in the pad
});

Floating labels

const board = world.addLabel({ text: 'Ada · 0', position: [0, 5, 25], size: 1.6, readable: true });
// later, when the score changes:
board.setText(`Ada · ${score}`);

The player

The controls are fixed and are part of the package:

Your character emits events you can listen to:

const { player } = await cue.init();
const me = world.spawnPlayer({ avatar: player.avatar3d, spawn: [0, 2, 6] });
me.on('death', () => me.respawn());
me.on('drop', (card) => {
  // e.g. did they drop it on the goal? check card.position against your goal
});

First person

By default the camera watches your player from behind. Switch it to first person and it sits at their eyes instead, so they see the world the way they would really see it.

const me = world.spawnPlayer({ avatar: player.avatar3d, view: 'first' });

Let players choose, if you like. Nothing in the engine claims a key for it, so pick your own:

addEventListener('keydown', (e) => {
  if (e.code === 'KeyV') world.setView(world.view === 'first' ? 'third' : 'first');
});

Three things change when you go first person:

• You can look nearly straight up and down. The chase camera only tilts a little, because it swings around the player.
• Their body turns to face wherever they are looking. Walking sideways now looks like walking sideways to everyone else in the game, instead of like turning to walk that way.
• Picking things up needs you to be looking at them. E still takes the nearest thing in reach, but only from the ones roughly in front of you. Standing next to a card with your back to it will not pick it up, which is what a player expects when they can see where they aim.

Your player cannot see their own carried card in first person, because it rides on their back where everyone else can see it. If it matters which card they are holding, put it in your HUD using the pickup and drop events.

me.on('pickup', (card) => { held.textContent = `Holding ${card.id}`; });
me.on('drop', () => { held.textContent = ''; });

Pointing at things

Often you want to know what the player is aiming at: the block under their crosshair, the card they are about to grab, whether a door is in front of them. Ask.

It measures from the player's eyes, so it works in both cameras.

// Highlight whatever they are looking at, within reach
setInterval(() => {
  const hit = world.lookingAt(4);
  prompt.textContent = hit ? `Press E to take it` : '';
}, 100);

Use it for a turret's line of fire, or to check whether one thing can see another:

const canSee = (a, b) => {
  const dir = [b.position[0] - a.position[0], b.position[1] - a.position[1], b.position[2] - a.position[2]];
  return world.raycast(a.position, dir, 100, { ignore: a })?.entity === b;
};

Run it

Keeping it smooth

The engine is pretty happy with a big world - so roughly a thousand static blocks is fine, because anything that never moves costs almost nothing once it is placed. What you pay for is things that move or load:

So: build as much scenery as you like, but keep the moving parts and the cards to the ones your game actually uses, and size the world to the number of players rather than to the maximum your game allows.

A HUD over the top

A HUD (heads-up display) is the score, timer or menu you lay over the game. The 3D view is a normal <canvas>, so you can put ordinary HTML on top of it for a score, a timer, or a menu. Position it over the canvas and it just works. A tip: while the mouse is captured for looking, buttons are not clickable, so show menus when the game is not in look mode.

Playing together

You can make a game that several people share, from two players up to the Max players you set on your game's Details tab (up to 32). Use cue.match.lobby() (see the Multiplayer section of the API reference) to show a ready-made lobby and get a room once a match starts, then hand that room to the world:

roster.length is not your player count

This one catches people out. roster has one entry per SEAT, not one per player. A game that allows up to 32 gets a 32-long roster every time, with null wherever nobody is sitting:

// Three people playing a game that allows 32:
roster = ["Ellie", "Sam", "Ada", null, null, ... ]   // length 32, three real names

Build your level from roster.length and you make a world for 32 when three turned up. It looks fine and it runs horribly. Count the names instead:

const { seat, roster, seed } = await net.started;
const players = roster.filter(Boolean).length;   // <- the real number
buildMyLevel(players, seed);

Keep your own per-player things keyed by seat number, though, because that is what messages carry (m.from) and what roster is keyed by.

When someone leaves

People quit, and their internet drops. Yeah it's disappointing, but here's how you deal with it:

• One player goes, the rest play on. You get room.on('seat-left', m => ...) with their seat number. Their character disappears from the world for you automatically. Take them off your scoreboard and carry on.
• Too many go and there is no match left. Once the room falls below the Min players you set on Details, the portal ends the match and everyone gets room.on('ended', ...). Show your result screen. This is a normal ending, not an error, and it is not the same as room.on('disconnected', ...), which means your own connection dropped. Gulp.

match.room.on('seat-left', (m) => {
  scores.delete(m.seat);          // they are gone; the world already removed their character
  refreshScoreboard();
});
match.room.on('ended', () => {
  world.stop();
  showResults('Not enough players left.');
});

The match seed, and how everyone looks

seed is the match seed: a random number made by the server, the SAME for every player in this match and different next match. Every client must build an identical world, so any randomness in your level (which cards spawn, layouts) should come from this seed through a seeded random function, never from Math.random():

const { seat, roster, seed } = await net.started;
let s = seed;
const rand = () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296); // 0..1, same on every client
const pick = catalog[Math.floor(rand() * catalog.length)]; // everyone picks the same card

started also tells you how each player likes to look, in seat order: avatarUrls (their little portrait, nice on a scoreboard), cardBacks and sleeves (art URLs). A null entry means that player just uses the normal look. The portal fills these in from each player's own account, so nobody can wear someone else's. Cards in a shared world don't belong to anyone, so it's your call whether one shows a player's back: pass it when you create the card, like world.addCard(id, { back: started.cardBacks[seat] ?? undefined }) for cards on that player's side.

const match = await cue.match.lobby();          // the ready-made lobby handles Play, codes, waiting
if (!match) return showMyMenu();                // the player closed the lobby without starting
const net = world.connectNet(match.room);
try {
  const { seat, roster, seed } = await net.started;  // the match has begun
  const players = roster.filter(Boolean).length;    // how many actually turned up
  buildMyLevel(players, seed);                      // a world sized to them, the same on every client
  const me = world.spawnPlayer({ avatar: player.avatar3d, spawn: spawnPoints[seat] });
  world.start();
} catch (err) {
  // the match ended before it got going; show your menu again
}

Your own messages still work the same way: anything you room.send() reaches every other player as a peer-action (a score update, a rematch offer). Four rules keep the sharing working:

• Don't attach your own room.on('start') listener; use net.started instead.
• The send names state and anything starting with card: belong to the engine. Pick other names for your own messages.
• room.state() belongs to the engine too. That is how it streams everyone's position, and the portal keeps only the newest one per player, so calling it yourself would throw your own character's position away. In a 3D game you never need it: positions are already handled. Use room.send() for your own messages.
• Never remove() a card in a connected game. Send it home with resetCard or lock it down with placeCard instead, so every world keeps the same card list.

Why it works this way

Your game runs in its own protected box, separate from the portal, and asks the portal for anything real (a card's art, who is playing, a reward) through the SDK. @cue/3d is just a library that runs inside that box with you. It cannot mint cards or currency any more than your own code can. The one thing to remember: like every CUE game, it only runs inside the portal (use the Test button), because it needs the portal on the other side to answer.