@myvillage/cli 2.6.1 → 2.8.0

package/src/assets/templates/arena/src/arena-game.js

@@ -0,0 +1,443 @@
+// The arena: rendering, input and HUD for a live match.
+//
+// Everything multiplayer (prediction, interpolation, lag compensation) lives in
+// the ArenaClient that `mp.connect()` returns; this file only reads controls,
+// hands them to the client, and draws what it reports. Restyle freely.
+
+import * as THREE from 'three';
+import { forwardOf } from './myvillage-realtime.js';
+
+const EYE_HEIGHT = 1.6;
+const LOOK_SENSITIVITY_MOUSE = 0.0025;
+const LOOK_SENSITIVITY_TOUCH = 0.006;
+const TURN_SPEED_KEYS = 2.5; // rad/s for Q/E
+const STICK_RADIUS = 50;
+
+export class ArenaGame {
+  /**
+   * @param {HTMLElement} container element the canvas and HUD go into
+   * @param {object} arena this game's arena config (src/arena.json)
+   */
+  constructor(container, arena) {
+    this.container = container;
+    this.arena = arena;
+    this.net = null;
+    this.handlers = {};
+    this.yaw = 0;
+    this.pitch = 0;
+    this.keys = new Set();
+    this.mouseFire = false;
+    this.touchFire = false;
+    this.stick = { id: -1, ox: 0, oy: 0, x: 0, y: 0 };
+    this.look = { id: -1, x: 0, y: 0 };
+    this.avatars = new Map();
+    this.tracers = [];
+    this.bannerUntil = 0;
+    this.hitUntil = 0;
+
+    this.renderer = new THREE.WebGLRenderer({ antialias: window.devicePixelRatio < 2 });
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    container.prepend(this.renderer.domElement);
+
+    this.scene = new THREE.Scene();
+    this.scene.background = new THREE.Color(0x9fc4e8);
+    this.scene.fog = new THREE.Fog(0x9fc4e8, 30, 70);
+    this.camera = new THREE.PerspectiveCamera(75, 1, 0.05, 200);
+    this.camera.rotation.order = 'YXZ';
+    this.scene.add(new THREE.HemisphereLight(0xffffff, 0x5a6b45, 1.6));
+    const sun = new THREE.DirectionalLight(0xffffff, 1.2);
+    sun.position.set(10, 20, 6);
+    this.scene.add(sun);
+    this.buildMap(arena.map);
+
+    this.hud = this.buildHud();
+    this.bindInput();
+    this.resize();
+    window.addEventListener('resize', () => this.resize());
+
+    this.last = performance.now();
+    requestAnimationFrame((t) => this.frame(t));
+  }
+
+  /** Start playing a connected match. handlers: { code, onLeave, onEnd, onExitResults } */
+  play(net, handlers) {
+    this.net = net;
+    this.handlers = handlers;
+    this.hud.root.hidden = false;
+    this.hud.results.hidden = true;
+    this.hud.fire.hidden = !matchMedia('(pointer: coarse)').matches;
+
+    net.on('event', (e) => this.onEvent(e));
+    net.on('end', (e) => this.onEnd(e));
+    net.on('close', (e) => {
+      if (net.phase !== 'ended' && this.net === net) this.banner('Disconnected (' + (e.reason || e.code) + ')', 60000);
+    });
+  }
+
+  /** Back to the idle fly-over (lobby showing). */
+  stop() {
+    if (this.net) this.net.close();
+    this.net = null;
+    for (const a of this.avatars.values()) this.scene.remove(a.root);
+    this.avatars.clear();
+    this.hud.root.hidden = true;
+    this.hud.fire.hidden = true;
+    document.exitPointerLock?.();
+  }
+
+  // ── scene ────────────────────────────────────────────────────────────────
+
+  buildMap(map) {
+    const outside = new THREE.Mesh(new THREE.PlaneGeometry(400, 400), new THREE.MeshLambertMaterial({ color: 0x5f7d50 }));
+    outside.rotation.x = -Math.PI / 2;
+    outside.position.y = -0.02;
+    this.scene.add(outside);
+    const floor = new THREE.Mesh(new THREE.PlaneGeometry(map.width, map.depth), new THREE.MeshLambertMaterial({ color: 0x7fa36b }));
+    floor.rotation.x = -Math.PI / 2;
+    this.scene.add(floor);
+    const size = Math.max(map.width, map.depth);
+    const grid = new THREE.GridHelper(size, size / 2, 0x5d7f4d, 0x6c9159);
+    grid.position.y = 0.01;
+    this.scene.add(grid);
+
+    const wallMat = new THREE.MeshLambertMaterial({ color: 0xc9b48f });
+    for (const w of map.walls) {
+      const h = w.height ?? 2;
+      const m = new THREE.Mesh(new THREE.BoxGeometry(w.maxX - w.minX, h, w.maxZ - w.minZ), wallMat);
+      m.position.set((w.minX + w.maxX) / 2, h / 2, (w.minZ + w.maxZ) / 2);
+      this.scene.add(m);
+    }
+    const edgeMat = new THREE.MeshLambertMaterial({ color: 0x8a7a5e });
+    for (const [x, z, sx, sz] of [
+      [0, -map.depth / 2, map.width, 0.4],
+      [0, map.depth / 2, map.width, 0.4],
+      [-map.width / 2, 0, 0.4, map.depth],
+      [map.width / 2, 0, 0.4, map.depth],
+    ]) {
+      const m = new THREE.Mesh(new THREE.BoxGeometry(sx, 1, sz), edgeMat);
+      m.position.set(x, 0.5, z);
+      this.scene.add(m);
+    }
+  }
+
+  avatarFor(p) {
+    let a = this.avatars.get(p.id);
+    if (a && a.name !== p.n) {
+      a.root.remove(a.label);
+      a.label = makeLabel(p.n);
+      a.root.add(a.label);
+      a.name = p.n;
+    }
+    if (a) return a;
+    const r = this.net.cfg.playerRadius;
+    const root = new THREE.Group();
+    const body = new THREE.Mesh(new THREE.CapsuleGeometry(r, 1.0, 4, 10), new THREE.MeshLambertMaterial({ color: colorFor(p.id) }));
+    body.position.y = 0.9;
+    const visor = new THREE.Mesh(new THREE.BoxGeometry(r * 1.2, 0.18, 0.2), new THREE.MeshLambertMaterial({ color: 0x1b1f27 }));
+    visor.position.set(0, 1.45, -r);
+    const itMarker = new THREE.Mesh(new THREE.ConeGeometry(0.25, 0.5, 12), new THREE.MeshBasicMaterial({ color: 0xe5484d }));
+    itMarker.rotation.x = Math.PI;
+    itMarker.position.y = 2.75;
+    const label = makeLabel(p.n);
+    root.add(body, visor, itMarker, label);
+    this.scene.add(root);
+    a = { root, itMarker, label, name: p.n };
+    this.avatars.set(p.id, a);
+    return a;
+  }
+
+  addTracer(e) {
+    const f = forwardOf(e.y);
+    const from = new THREE.Vector3(e.x, 1.35, e.z);
+    const to = new THREE.Vector3(e.x + f.x * e.d, 1.35, e.z + f.z * e.d);
+    const color = this.net.cfg.mode === 'tag' ? 0xffffff : e.hit ? 0xff5a5f : 0xffe08a;
+    const line = new THREE.Line(new THREE.BufferGeometry().setFromPoints([from, to]), new THREE.LineBasicMaterial({ color }));
+    this.scene.add(line);
+    this.tracers.push({ line, until: performance.now() + 120 });
+  }
+
+  // ── match events ─────────────────────────────────────────────────────────
+
+  nameOf(id) {
+    return this.net.roster.find((p) => p.id === id)?.n ?? 'someone';
+  }
+
+  onEvent(e) {
+    const you = this.net.you;
+    if (e.k === 'shot') {
+      this.addTracer(e);
+      if (e.a === you && e.hit) this.hitUntil = performance.now() + 150;
+    } else if (e.k === 'elim') {
+      if (e.v === you) this.banner('Blasted by ' + this.nameOf(e.a), this.net.cfg.respawnSec * 1000);
+      else if (e.a === you) this.banner('You got ' + this.nameOf(e.v) + '!');
+    } else if (e.k === 'tag') {
+      if (e.v === you) this.banner("You're it!");
+      else if (e.a === you) this.banner('Tagged ' + this.nameOf(e.v) + '!');
+    } else if (e.k === 'spawn' && e.v === you) {
+      // Face the way the spawn point faces.
+      this.yaw = e.y;
+      this.pitch = 0;
+    }
+  }
+
+  onEnd(end) {
+    document.exitPointerLock?.();
+    const tag = this.net.cfg.mode === 'tag';
+    const list = this.hud.resultsList;
+    list.innerHTML = '';
+    for (const r of end.results) {
+      const li = document.createElement('li');
+      li.textContent = r.name + ' — ' + r.score + (tag ? 's' : '') + (r.id === this.net.you ? ' (you)' : '');
+      list.appendChild(li);
+    }
+    this.hud.resultsTitle.textContent = end.status === 'completed' ? 'Match over' : 'Match abandoned';
+    this.hud.results.hidden = false;
+    this.handlers.onEnd?.(end);
+  }
+
+  banner(text, ms = 1500) {
+    this.hud.banner.textContent = text;
+    this.bannerUntil = performance.now() + ms;
+  }
+
+  // ── HUD ──────────────────────────────────────────────────────────────────
+
+  buildHud() {
+    const root = el('div', 'hud');
+    root.hidden = true;
+    const status = el('div', 'hud-status');
+    const board = el('div', 'hud-board');
+    const leave = el('button', 'hud-leave', 'Leave');
+    const crosshair = el('div', 'hud-crosshair');
+    const banner = el('div', 'hud-banner');
+    const hp = el('div', 'hud-hp');
+    const ping = el('div', 'hud-ping');
+    const results = el('div', 'hud-results');
+    results.hidden = true;
+    const card = el('div', 'card');
+    const resultsTitle = el('h2', '', 'Match over');
+    const resultsList = el('ol');
+    const again = el('button', 'primary', 'Back to lobby');
+    card.append(resultsTitle, resultsList, again);
+    results.append(card);
+    root.append(status, board, leave, crosshair, banner, hp, ping, results);
+    const fire = el('div', 'hud-fire', 'FIRE');
+    fire.hidden = true;
+    const stickEl = el('div', 'hud-stick');
+    stickEl.append(el('i'));
+    stickEl.hidden = true;
+    this.container.append(root, fire, stickEl);
+
+    leave.addEventListener('click', () => this.handlers.onLeave?.());
+    again.addEventListener('click', () => this.handlers.onExitResults?.());
+    return { root, status, board, leave, crosshair, banner, hp, ping, results, resultsTitle, resultsList, fire, stickEl };
+  }
+
+  updateHud(now, me) {
+    const net = this.net;
+    const { hud } = this;
+    const cfg = net.cfg;
+    const code = this.handlers.code ? 'Code ' + this.handlers.code + ' · ' : '';
+    hud.status.textContent =
+      net.phase === 'waiting'
+        ? code + 'Waiting for players (' + net.roster.length + '/' + cfg.minPlayers + ') — warm up!'
+        : net.phase === 'countdown'
+          ? 'Starting in ' + Math.ceil(net.timeLeft)
+          : net.phase === 'playing'
+            ? Math.floor(net.timeLeft / 60) + ':' + String(Math.floor(net.timeLeft % 60)).padStart(2, '0')
+            : 'Match over';
+    hud.board.innerHTML = [...net.roster]
+      .sort((a, b) => b.s - a.s)
+      .map((p) => '<div class="' + (p.id === net.you ? 'me' : '') + '"><span>' + (p.it ? '🔴 ' : '') + escapeHtml(p.n) + '</span><b>' + p.s + '</b></div>')
+      .join('');
+    hud.hp.textContent = cfg.mode === 'tag' ? (me.it ? "You're IT — tag someone!" : 'Run!') : me.alive ? '♥ ' + me.hp : 'Respawning…';
+    hud.ping.textContent = Math.round(net.rttMs) + ' ms';
+    hud.crosshair.classList.toggle('hit', now < this.hitUntil);
+    if (now > this.bannerUntil) hud.banner.textContent = '';
+  }
+
+  // ── input ────────────────────────────────────────────────────────────────
+
+  bindInput() {
+    const canvas = this.renderer.domElement;
+    addEventListener('keydown', (e) => this.keys.add(e.code));
+    addEventListener('keyup', (e) => this.keys.delete(e.code));
+    canvas.addEventListener('mousedown', () => {
+      if (!this.net) return;
+      if (document.pointerLockElement !== canvas) canvas.requestPointerLock();
+      else this.mouseFire = true;
+    });
+    addEventListener('mouseup', () => (this.mouseFire = false));
+    addEventListener('mousemove', (e) => {
+      if (document.pointerLockElement !== canvas) return;
+      this.turn(e.movementX * LOOK_SENSITIVITY_MOUSE, e.movementY * LOOK_SENSITIVITY_MOUSE);
+    });
+
+    // Phones: left half = move stick, right half = drag to look, FIRE button.
+    canvas.addEventListener('touchstart', (e) => {
+      for (const t of Array.from(e.changedTouches)) {
+        if (t.clientX < innerWidth / 2 && this.stick.id < 0) {
+          Object.assign(this.stick, { id: t.identifier, ox: t.clientX, oy: t.clientY, x: 0, y: 0 });
+          const s = this.hud.stickEl;
+          s.style.left = t.clientX + 'px';
+          s.style.top = t.clientY + 'px';
+          s.hidden = !this.net;
+        } else if (this.look.id < 0) {
+          Object.assign(this.look, { id: t.identifier, x: t.clientX, y: t.clientY });
+        }
+      }
+      e.preventDefault();
+    }, { passive: false });
+    canvas.addEventListener('touchmove', (e) => {
+      for (const t of Array.from(e.changedTouches)) {
+        if (t.identifier === this.stick.id) {
+          let dx = t.clientX - this.stick.ox;
+          let dy = t.clientY - this.stick.oy;
+          const len = Math.hypot(dx, dy);
+          if (len > STICK_RADIUS) {
+            dx = (dx / len) * STICK_RADIUS;
+            dy = (dy / len) * STICK_RADIUS;
+          }
+          this.stick.x = dx / STICK_RADIUS;
+          this.stick.y = dy / STICK_RADIUS;
+          this.hud.stickEl.firstElementChild.style.transform = 'translate(' + dx + 'px, ' + dy + 'px)';
+        } else if (t.identifier === this.look.id) {
+          this.turn((t.clientX - this.look.x) * LOOK_SENSITIVITY_TOUCH, (t.clientY - this.look.y) * LOOK_SENSITIVITY_TOUCH);
+          this.look.x = t.clientX;
+          this.look.y = t.clientY;
+        }
+      }
+      e.preventDefault();
+    }, { passive: false });
+    const endTouch = (e) => {
+      for (const t of Array.from(e.changedTouches)) {
+        if (t.identifier === this.stick.id) {
+          Object.assign(this.stick, { id: -1, x: 0, y: 0 });
+          this.hud.stickEl.hidden = true;
+          this.hud.stickEl.firstElementChild.style.transform = '';
+        } else if (t.identifier === this.look.id) this.look.id = -1;
+      }
+    };
+    canvas.addEventListener('touchend', endTouch);
+    canvas.addEventListener('touchcancel', endTouch);
+    const fire = this.hud.fire;
+    fire.addEventListener('touchstart', (e) => { this.touchFire = true; e.preventDefault(); }, { passive: false });
+    fire.addEventListener('touchend', () => (this.touchFire = false));
+    fire.addEventListener('touchcancel', () => (this.touchFire = false));
+  }
+
+  turn(dx, dy) {
+    this.yaw -= dx;
+    this.pitch = Math.max(-1.4, Math.min(1.4, this.pitch - dy));
+  }
+
+  readControls(dt) {
+    const k = this.keys;
+    this.yaw += ((k.has('KeyQ') ? 1 : 0) - (k.has('KeyE') ? 1 : 0)) * TURN_SPEED_KEYS * dt;
+    const kx = (k.has('KeyD') || k.has('ArrowRight') ? 1 : 0) - (k.has('KeyA') || k.has('ArrowLeft') ? 1 : 0);
+    const kz = (k.has('KeyW') || k.has('ArrowUp') ? 1 : 0) - (k.has('KeyS') || k.has('ArrowDown') ? 1 : 0);
+    return {
+      mx: kx || this.stick.x,
+      mz: kz || -this.stick.y,
+      yaw: this.yaw,
+      pitch: this.pitch,
+      fire: this.mouseFire || this.touchFire || k.has('Space'),
+    };
+  }
+
+  // ── loop ─────────────────────────────────────────────────────────────────
+
+  resize() {
+    const w = this.container.clientWidth || innerWidth;
+    const h = this.container.clientHeight || innerHeight;
+    this.renderer.setSize(w, h);
+    this.camera.aspect = w / h;
+    this.camera.updateProjectionMatrix();
+  }
+
+  frame(now) {
+    requestAnimationFrame((t) => this.frame(t));
+    const dt = Math.min(0.1, (now - this.last) / 1000);
+    this.last = now;
+    const net = this.net;
+
+    if (!net || !net.cfg) {
+      // Lobby showing: slow fly-over of the arena.
+      const t = now / 12000;
+      this.camera.position.set(Math.sin(t) * 26, 14, Math.cos(t) * 26);
+      this.camera.lookAt(0, 0, 0);
+      this.renderer.render(this.scene, this.camera);
+      return;
+    }
+
+    net.controls = this.readControls(dt);
+    net.update(dt);
+
+    const me = net.view;
+    this.camera.position.set(me.x, me.alive ? EYE_HEIGHT : 4, me.z);
+    this.camera.rotation.set(this.pitch, this.yaw, 0);
+
+    const seen = new Set();
+    for (const p of net.others(now)) {
+      seen.add(p.id);
+      const a = this.avatarFor(p);
+      a.root.visible = p.a;
+      a.root.position.set(p.x, 0, p.z);
+      a.root.rotation.y = p.y;
+      a.itMarker.visible = !!p.it;
+      a.itMarker.position.y = 2.75 + Math.sin(now / 200) * 0.1;
+    }
+    for (const [id, a] of this.avatars) {
+      if (!seen.has(id)) {
+        this.scene.remove(a.root);
+        this.avatars.delete(id);
+      }
+    }
+    for (let i = this.tracers.length - 1; i >= 0; i--) {
+      if (now > this.tracers[i].until) {
+        this.scene.remove(this.tracers[i].line);
+        this.tracers[i].line.geometry.dispose();
+        this.tracers.splice(i, 1);
+      }
+    }
+
+    this.updateHud(now, me);
+    this.renderer.render(this.scene, this.camera);
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function el(tag, className = '', text = '') {
+  const e = document.createElement(tag);
+  if (className) e.className = className;
+  if (text) e.textContent = text;
+  return e;
+}
+
+function colorFor(id) {
+  return new THREE.Color().setHSL((Number(id) * 0.618) % 1, 0.65, 0.55);
+}
+
+function makeLabel(text) {
+  const c = document.createElement('canvas');
+  c.width = 256;
+  c.height = 64;
+  const g = c.getContext('2d');
+  g.font = 'bold 34px system-ui, sans-serif';
+  g.textAlign = 'center';
+  g.textBaseline = 'middle';
+  g.lineWidth = 6;
+  g.strokeStyle = 'rgba(0,0,0,0.7)';
+  g.strokeText(text, 128, 32);
+  g.fillStyle = '#fff';
+  g.fillText(text, 128, 32);
+  const s = new THREE.Sprite(new THREE.SpriteMaterial({ map: new THREE.CanvasTexture(c), depthWrite: false }));
+  s.scale.set(1.6, 0.4, 1);
+  s.position.y = 2.25;
+  return s;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => '&#' + c.charCodeAt(0) + ';');
+}

package/src/assets/templates/arena/src/arena.json

@@ -0,0 +1,114 @@
+{
+  "mode": "elimination",
+  "minPlayers": 2,
+  "maxPlayers": 8,
+  "durationSec": 180,
+  "countdownSec": 3,
+  "moveSpeed": 6,
+  "playerRadius": 0.4,
+  "maxHp": 100,
+  "damage": 25,
+  "fireCooldownMs": 300,
+  "weaponRange": 40,
+  "respawnSec": 3,
+  "tagRange": 2,
+  "tagCooldownSec": 2,
+  "itSpeedMultiplier": 1.1,
+  "map": {
+    "width": 40,
+    "depth": 40,
+    "walls": [
+      {
+        "minX": -2,
+        "minZ": -2,
+        "maxX": 2,
+        "maxZ": 2,
+        "height": 3
+      },
+      {
+        "minX": -12,
+        "minZ": -12,
+        "maxX": -8,
+        "maxZ": -10,
+        "height": 2
+      },
+      {
+        "minX": 8,
+        "minZ": 10,
+        "maxX": 12,
+        "maxZ": 12,
+        "height": 2
+      },
+      {
+        "minX": -12,
+        "minZ": 8,
+        "maxX": -10,
+        "maxZ": 14,
+        "height": 2
+      },
+      {
+        "minX": 10,
+        "minZ": -14,
+        "maxX": 12,
+        "maxZ": -8,
+        "height": 2
+      },
+      {
+        "minX": -1,
+        "minZ": -16,
+        "maxX": 1,
+        "maxZ": -9,
+        "height": 2.5
+      },
+      {
+        "minX": -1,
+        "minZ": 9,
+        "maxX": 1,
+        "maxZ": 16,
+        "height": 2.5
+      }
+    ],
+    "spawns": [
+      {
+        "x": -16,
+        "z": -16,
+        "yaw": -2.3562
+      },
+      {
+        "x": 16,
+        "z": 16,
+        "yaw": 0.7854
+      },
+      {
+        "x": -16,
+        "z": 16,
+        "yaw": -0.7854
+      },
+      {
+        "x": 16,
+        "z": -16,
+        "yaw": 2.3562
+      },
+      {
+        "x": 0,
+        "z": -18,
+        "yaw": 3.1416
+      },
+      {
+        "x": 0,
+        "z": 18,
+        "yaw": 0
+      },
+      {
+        "x": -18,
+        "z": 0,
+        "yaw": -1.5708
+      },
+      {
+        "x": 18,
+        "z": 0,
+        "yaw": 1.5708
+      }
+    ]
+  }
+}

package/src/assets/templates/arena/src/lobby.js

@@ -0,0 +1,94 @@
+// The lobby — YOUR game's screen for getting players into a match.
+//
+// This is a starting point, not platform UI: restyle it, add teams or a ready
+// check, show open matches with mp.list(), or replace it entirely. It only
+// calls the platform plumbing on `mp` (see src/myvillage-game.js):
+//   mp.quickMatch()          join the fullest open match in your village, or host one
+//   mp.host({ visibility })  host a match; share match.code with friends
+//   mp.join(code)            join a friend's match by code
+// and hands the match to `onEnter`, which connects and starts playing.
+
+export class Lobby {
+  /**
+   * @param {HTMLElement} root element to render into
+   * @param {object} mp the Multiplayer object from MyVillageGame.multiplayer()
+   */
+  constructor(root, mp) {
+    this.root = root;
+    this.mp = mp;
+    /** Called with the match once the player is in one. */
+    this.onEnter = null;
+    this.render();
+  }
+
+  render() {
+    const dev = this.mp.mode === 'dev';
+    this.root.innerHTML = `
+      <div class="card">
+        <h1>Arena</h1>
+        <p class="who">Playing as <b></b></p>
+        <button class="primary" data-action="quick">Quick match</button>
+        <button data-action="host">Host a game</button>
+        <form class="join">
+          <input name="code" placeholder="Friend's code" maxlength="9" autocomplete="off" autocapitalize="characters" />
+          <button type="submit">Join</button>
+        </form>
+        <p class="error" role="alert"></p>
+        ${dev ? '<p class="hint">Dev mode: open this page in a second tab and press Quick match in both (or host in one, join with its code in the other) to play yourself.</p>' : ''}
+      </div>`;
+    this.root.querySelector('.who b').textContent = this.mp.me.displayName;
+    this.root.querySelector('[data-action="quick"]').addEventListener('click', () => this.go(() => this.mp.quickMatch()));
+    this.root.querySelector('[data-action="host"]').addEventListener('click', () => this.go(() => this.mp.host({ visibility: 'private' })));
+    this.root.querySelector('form.join').addEventListener('submit', (e) => {
+      e.preventDefault();
+      const code = new FormData(e.target).get('code');
+      if (String(code).trim()) this.go(() => this.mp.join(code));
+    });
+  }
+
+  async go(action) {
+    this.setBusy(true);
+    this.showError('');
+    try {
+      const match = await action();
+      await this.onEnter?.(match);
+    } catch (err) {
+      this.showError(friendlyError(err));
+    } finally {
+      this.setBusy(false);
+    }
+  }
+
+  setBusy(busy) {
+    for (const b of this.root.querySelectorAll('button, input')) b.disabled = busy;
+  }
+
+  showError(message) {
+    this.root.querySelector('.error').textContent = message;
+  }
+
+  show() {
+    this.root.hidden = false;
+  }
+
+  hide() {
+    this.root.hidden = true;
+  }
+}
+
+function friendlyError(err) {
+  switch (err && err.code) {
+    case 'match_not_found':
+      return 'No match with that code.';
+    case 'match_full':
+      return 'That match is full.';
+    case 'match_closed':
+      return 'That match has already started.';
+    case 'not_in_village':
+      return 'You can only play with people from your village.';
+    case 'no_village':
+      return 'Join a village to play multiplayer — you play with your village.';
+    default:
+      return (err && err.message) || 'Something went wrong. Try again.';
+  }
+}

package/src/assets/templates/arena/src/main.js

@@ -0,0 +1,46 @@
+// Boot: lobby → live match → results → lobby.
+
+import { MyVillageGame } from './myvillage-game.js';
+import arena from './arena.json';
+import { ArenaGame } from './arena-game.js';
+import { Lobby } from './lobby.js';
+
+// Names this game's dev-mode match rooms (standalone `npm run dev` / Studio).
+const GAME_ID = '{{SLUG}}';
+
+async function boot() {
+  const game = new ArenaGame(document.getElementById('game-container'), arena);
+  const mp = await MyVillageGame.multiplayer({ arena, game: GAME_ID });
+  const lobby = new Lobby(document.getElementById('lobby'), mp);
+  MyVillageGame.ready();
+
+  const backToLobby = async () => {
+    game.stop();
+    await mp.leave().catch(() => {});
+    lobby.show();
+  };
+
+  lobby.onEnter = async (match) => {
+    let net;
+    try {
+      net = await mp.connect();
+    } catch (err) {
+      await mp.leave().catch(() => {});
+      throw err;
+    }
+    lobby.hide();
+    // No MyVillageGame.complete() here: in multiplayer the platform records
+    // each player's result and MVT from the match server itself, and hosts
+    // treat complete() as "the game is over" and close it — players should be
+    // able to play again from the results screen.
+    game.play(net, {
+      code: match.code,
+      onLeave: backToLobby,
+      onExitResults: backToLobby,
+    });
+  };
+
+  lobby.show();
+}
+
+boot();