@myvillage/cli 2.7.0 → 2.8.0

package/src/commands/create-game.js

@@ -24,7 +24,7 @@ function normEngine(v) {
 function normType(v) {
   if (!v) return null;
   v = String(v).toLowerCase();
-  return ['quiz', 'exploration', 'narrative', 'custom'].includes(v) ? v : null;
+  return ['quiz', 'exploration', 'narrative', 'custom', 'arena'].includes(v) ? v : null;
 }
 function normAge(v) {
   if (!v) return null;
@@ -127,6 +127,7 @@ export async function createGameCommand(options = {}) {
         { name: 'Exploration Game - Navigate and discover', value: 'exploration' },
         { name: 'Narrative Game - Story-driven experience', value: 'narrative' },
         { name: 'Custom - Start with base Three.js template', value: 'custom' },
+        { name: 'Arena (multiplayer) - Real-time first-person tag / blaster matches', value: 'arena' },
       ],
     });
   if (needName)
@@ -213,6 +214,10 @@ export async function createGameCommand(options = {}) {
     console.log(`    ${brand.gold('myvillage deploy')} ${brand.teal('- Deploy to MyVillageOS')}`);
     console.log();
     console.log(brand.teal(`  Game type: ${game.type} | Orientation: ${orientation} | Age group: ${game.ageGroup}`));
+    if (game.type === 'arena') {
+      console.log(brand.teal('  Multiplayer: open the dev server in two browser tabs and press Quick match in both.'));
+      console.log(brand.teal('  Match rules + map: src/arena.json (sent with every deploy).'));
+    }
     console.log(brand.teal(`  Cover art: drop thumbnail.png / banner.png in ${slug}/assets/ before deploy.`));
     console.log();
   } catch (err) {

package/src/commands/deploy.js

@@ -22,6 +22,42 @@ function readPackageJson(dir) {
   }
 }
 
+const MAX_MULTIPLAYER_BYTES = 64 * 1024;
+
+/**
+ * The game's real-time multiplayer config for the deploy metadata, from
+ * `myvillage.multiplayer` in package.json: `{ arena: 'src/arena.json' }` (a
+ * path) or `{ arena: {...} }` (inline). Returns undefined when the game doesn't
+ * declare one (the platform keeps its current setting), null to turn it off.
+ * Throws a readable error for a missing or malformed config.
+ */
+export function readMultiplayerConfig(dir, mv) {
+  const setting = mv?.multiplayer;
+  if (setting === undefined) return undefined;
+  if (setting === null || setting === false) return null;
+  if (typeof setting !== 'object' || Array.isArray(setting)) {
+    throw new Error('myvillage.multiplayer must be an object like { "arena": "src/arena.json" }');
+  }
+  let arena = setting.arena ?? {};
+  if (typeof arena === 'string') {
+    const file = join(dir, arena);
+    if (!existsSync(file)) throw new Error(`myvillage.multiplayer.arena points to ${arena}, which doesn't exist`);
+    try {
+      arena = JSON.parse(readFileSync(file, 'utf-8'));
+    } catch (err) {
+      throw new Error(`${arena} is not valid JSON: ${err.message}`);
+    }
+  }
+  if (typeof arena !== 'object' || arena === null || Array.isArray(arena)) {
+    throw new Error('myvillage.multiplayer.arena must be a JSON object (or a path to one)');
+  }
+  const config = { arena };
+  if (JSON.stringify(config).length > MAX_MULTIPLAYER_BYTES) {
+    throw new Error('Multiplayer config is larger than 64 KB — simplify the map');
+  }
+  return config;
+}
+
 function readMyVillageJson(dir) {
   const configPath = join(dir, 'myvillage.json');
   if (!existsSync(configPath)) return null;
@@ -217,6 +253,17 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
   // If this game is already live, confirm + unpublish before we rebuild/upload.
   if (!(await confirmRedeployIfPublished(pkg.myvillage.gameId, options))) return;
 
+  // Multiplayer rules + map ship with the deploy; a broken config should fail
+  // before anything is built or uploaded.
+  let multiplayer;
+  try {
+    multiplayer = readMultiplayerConfig(projectDir, pkg.myvillage);
+  } catch (err) {
+    if (json) console.log(JSON.stringify({ ok: false, error: err.message }));
+    else console.log(chalk.red(`\n  ✗ ${err.message}`));
+    return;
+  }
+
   // Village visibility is part of the submission — gather it up front (before
   // the build) so it travels in the deploy metadata.
   const villageIds = await gatherVillages(pkg.myvillage.villages || [], options);
@@ -263,6 +310,7 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
       orientation: pkg.myvillage.orientation || 'landscape',
       entryFile: 'index.html',
       villageIds,
+      ...(multiplayer !== undefined && { multiplayer }),
     };
     formData.append('metadata', JSON.stringify(metadata));
 

package/src/index.js

@@ -215,7 +215,7 @@ export function run() {
     .option('--description <text>', 'Game description')
     .option('--engine <engine>', 'Engine: threejs | unity')
     .option('--orientation <orientation>', 'portrait | landscape')
-    .option('--type <type>', 'Three.js type: quiz | exploration | narrative | custom')
+    .option('--type <type>', 'Three.js type: quiz | exploration | narrative | custom | arena (multiplayer)')
     .option('--category <category>', 'Unity category: education | action | adventure | puzzle | other')
     .option('--target-age <age>', 'Target age: under-5 | 6-12 | 13-and-over')
     .option('--dir <path>', 'Parent directory to scaffold into (defaults to cwd)')

package/src/utils/templates.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from 'fs';
+import { mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { tmpdir } from 'os';
 import { fileURLToPath } from 'url';
@@ -10,6 +10,13 @@ import * as tar from 'tar';
 // installed globally via npm.
 const GAME_ART_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'game-art');
 
+// Real source files (not strings) for the game toolkit and the arena template,
+// so they can be linted and tested: src/assets/game-toolkit, src/assets/templates.
+const ASSETS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+// Multiplayer netcode, built from the myvillage-realtime repo
+// (scripts/sync-realtime-client.sh refreshes it).
+const REALTIME_CLIENT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vendor', 'realtime', 'myvillage-realtime-client.js');
+
 // GameKit SDK version that scaffolded Unity projects pin to.
 // Bump alongside CLI minor releases as the SDK contract evolves.
 const GAMEKIT_SDK_VERSION = '1.1.0-alpha.5';
@@ -109,6 +116,11 @@ export function createGameProject(targetDir, options) {
     createNarrativeProject(targetDir, options);
     return;
   }
+  // Real-time multiplayer arena: its own scaffold (lobby + live match).
+  if (type === 'arena') {
+    createArenaProject(targetDir, options);
+    return;
+  }
 
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 
@@ -142,7 +154,7 @@ export function createGameProject(targetDir, options) {
   copyTemplateArt(targetDir, type, orientation);
 
   // Write base source files
-  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
+  writeGameToolkit(targetDir);
   writeFileSync(join(targetDir, 'src/main.js'), generateMainJs(type));
   writeFileSync(join(targetDir, 'src/scenes/MainScene.js'), generateMainScene(type));
   writeFileSync(join(targetDir, 'src/utils/InputManager.js'), generateInputManager());
@@ -188,7 +200,7 @@ function createQuizProject(targetDir, options) {
   writeFileSync(join(targetDir, 'src/main.js'), generateQuizApp());
   writeFileSync(join(targetDir, 'src/questions.js'), generateQuizQuestions(name));
   writeFileSync(join(targetDir, 'src/styles.css'), generateQuizStyles());
-  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
+  writeGameToolkit(targetDir);
 
   writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
   copyTemplateArt(targetDir, 'quiz', orientation);
@@ -673,12 +685,61 @@ function createNarrativeProject(targetDir, options) {
   writeFileSync(join(targetDir, 'src/main.js'), generateNarrativeApp());
   writeFileSync(join(targetDir, 'src/story.js'), generateNarrativeStory(name));
   writeFileSync(join(targetDir, 'src/styles.css'), generateNarrativeStyles());
-  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
+  writeGameToolkit(targetDir);
 
   writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
   copyTemplateArt(targetDir, 'narrative', orientation);
 }
 
+// ── Arena Project (real-time multiplayer) ──────────────────────────
+// A first-person arena that plays live matches on MyVillage's match servers.
+// The game owns its lobby (src/lobby.js); the platform plumbing lives in the
+// toolkit. src/arena.json holds the match rules + map, which the game renders
+// and `myvillage deploy` sends to the platform (myvillage.multiplayer.arena).
+// Source files live in src/assets/templates/arena with {{PLACEHOLDERS}}.
+function createArenaProject(targetDir, options) {
+  const { name, description, ageGroup, orientation = 'landscape' } = options;
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+  const src = join(ASSETS_DIR, 'templates', 'arena');
+  const vars = {
+    NAME: name,
+    SLUG: slug,
+    DESCRIPTION: description || 'A real-time multiplayer arena game.',
+    ORIENTATION: orientation,
+    GOLD: BRAND.gold,
+    DARK: BRAND.darkBrown,
+    CONTAINER_CSS: orientation === 'portrait'
+      ? `#game-container { position: relative; width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; }
+    @media (min-aspect-ratio: 3/4) { #game-container { width: min(100vw, calc(100dvh * 9 / 16)); margin: 0 auto; } }`
+      : '#game-container { position: relative; width: 100%; height: 100%; overflow: hidden; }',
+  };
+  const fill = (file) => readFileSync(join(src, file), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+
+  for (const dir of ['', 'src', 'assets', 'public']) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+
+  writeFileSync(join(targetDir, 'package.json'), generateArenaPackageJson(name, description, slug, ageGroup, orientation));
+  writeFileSync(join(targetDir, 'vite.config.js'), generateViteConfig());
+  writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
+  for (const file of ['index.html', 'README.md', 'AGENTS.md', 'src/main.js', 'src/lobby.js', 'src/arena-game.js', 'src/arena.json']) {
+    writeFileSync(join(targetDir, file), fill(file));
+  }
+  writeGameToolkit(targetDir);
+
+  writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
+  copyTemplateArt(targetDir, 'arena', orientation);
+}
+
+function generateArenaPackageJson(name, description, slug, ageGroup, orientation) {
+  const pkg = JSON.parse(generatePackageJson(name, description || 'A real-time multiplayer arena game.', slug, 'arena', ageGroup, orientation));
+  pkg.myvillage.category = 'action';
+  // Real-time multiplayer: the match rules + map `myvillage deploy` sends to
+  // the platform. A path to a JSON file, or the config inline.
+  pkg.myvillage.multiplayer = { arena: 'src/arena.json' };
+  return JSON.stringify(pkg, null, 2) + '\n';
+}
+
 function generateNarrativeApp() {
   return `// Narrative Game — an interactive, choice-driven story.
 //
@@ -1059,6 +1120,7 @@ function generate2DGameAgents(name, gameType, orientation) {
     '| `' + contentFile + '` | **The content** — edit this first for content changes. |',
     '| `src/styles.css` | Styling (CSS variables in `:root`). |',
     '| `src/myvillage-game.js` | Host bridge — **do not edit.** |',
+    '| `src/myvillage-realtime.js` | Multiplayer netcode (unused unless the game calls `MyVillageGame.multiplayer()`) — **do not edit.** |',
     '| `assets/` | Cover art shipped on deploy. |',
     '| `package.json` | The `myvillage` block holds metadata `myvillage deploy` reads. |',
     '',
@@ -1137,6 +1199,7 @@ function generate3DGameAgents(name, type, orientation) {
     '| `src/utils/InputManager.js` | Keyboard / mouse / touch + mobile joystick. |',
     '| `src/utils/AudioManager.js` | Sound effects + music (Web Audio). |',
     '| `src/myvillage-game.js` | Host bridge — **do not edit.** |',
+    '| `src/myvillage-realtime.js` | Multiplayer netcode (unused unless the game calls `MyVillageGame.multiplayer()`) — **do not edit.** |',
     '| `assets/` | Cover art shipped on deploy. |',
     '| `public/assets/` | Drop 3D models / textures / audio here. |',
     '',
@@ -2100,87 +2163,16 @@ window.game = game;
 // The universal MyVillage game contract (the "mvgame" protocol). Every
 // scaffolded game ships this verbatim so completion + exit behave identically
 // across the muni mobile app, the web (mvp-video-games), and standalone dev.
+// The game toolkit every JS game gets: src/myvillage-game.js (the mvgame host
+// bridge + multiplayer plumbing) and src/myvillage-realtime.js (match netcode,
+// only loaded by games that call MyVillageGame.multiplayer()).
 function generateMyVillageGameSdk() {
-  return `// MyVillage Game Bridge — the "mvgame" protocol (v1).
-//
-// ONE contract for every MyVillage game, on every surface:
-//   - muni mobile app  (React Native WebView)
-//   - the web          (mvp-video-games, in an iframe)
-//   - standalone dev   (logs to the console)
-//
-// Two calls every game makes:
-//   MyVillageGame.ready()                // once, when your game is interactive
-//   MyVillageGame.complete({ score })    // when the game is finished / won / over
-//
-// One the host ALWAYS provides, but you can trigger too:
-//   MyVillageGame.exit()                 // leave the game
-//
-// The host always renders an Exit control, so a player can leave ANY game at
-// any time even if the game never calls exit() itself. Mirrors the native Unity
-// contract (CompleteMission / abort) so there is a single mental model.
-
-const PROTOCOL = 'mvgame';
-const VERSION = 1;
-
-function now() {
-  return typeof performance !== 'undefined' ? performance.now() : Date.now();
-}
-
-function post(message) {
-  const payload = { source: PROTOCOL, version: VERSION, ...message };
-  const json = JSON.stringify(payload);
-  try {
-    // React Native WebView (muni mobile app)
-    if (typeof window !== 'undefined' && window.ReactNativeWebView) {
-      window.ReactNativeWebView.postMessage(json);
-    }
-    // Iframe parent (mvp-video-games web host) — only if actually embedded
-    if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
-      window.parent.postMessage(payload, '*');
-    }
-    // Standalone dev: nothing is listening, so surface it for debugging.
-    if (typeof window !== 'undefined' && !window.ReactNativeWebView && window.parent === window) {
-      console.info('[mvgame] (no host attached) ' + json);
-    }
-  } catch (e) {
-    console.warn('[mvgame] postMessage failed', e);
-  }
-}
-
-let readySent = false;
-let startedAt = now();
-
-export const MyVillageGame = {
-  /** Call once when the game has loaded and is interactive. */
-  ready() {
-    if (readySent) return;
-    readySent = true;
-    startedAt = now();
-    post({ type: 'ready' });
-  },
-
-  /**
-   * Call when the game is finished. \`result\` is optional:
-   *   { score?: number, rewards?: number, won?: boolean, custom?: object }
-   * \`durationMs\` is added automatically.
-   */
-  complete(result = {}) {
-    post({ type: 'complete', durationMs: Math.round(now() - startedAt), ...result });
-  },
-
-  /** Request to leave the game. The host also always offers an Exit control. */
-  exit() {
-    post({ type: 'exit' });
-  },
-};
-
-// Expose globally too, for non-module games and quick debugging.
-if (typeof window !== 'undefined') {
-  window.MyVillageGame = MyVillageGame;
+  return readFileSync(join(ASSETS_DIR, 'game-toolkit', 'myvillage-game.js'), 'utf8');
 }
 
-export default MyVillageGame;
-`;
+function writeGameToolkit(targetDir) {
+  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
+  writeFileSync(join(targetDir, 'src/myvillage-realtime.js'), readFileSync(REALTIME_CLIENT_PATH, 'utf8'));
 }
 
 function generateMainScene(type) {