@myvillage/cli 1.62.0 → 1.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.62.0",
+  "version": "1.63.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/create-game.js

@@ -87,10 +87,9 @@ export async function createGameCommand(options = {}) {
       name: 'ageGroup',
       message: 'Target age group:',
       choices: [
-        { name: '5-8 years', value: '5-8' },
-        { name: '9-12 years', value: '9-12' },
-        { name: '13-15 years', value: '13-15' },
-        { name: '16-18 years', value: '16-18' },
+        { name: 'Under 5', value: 'under-5' },
+        { name: '6-12', value: '6-12' },
+        { name: '13 and Over', value: '13-and-over' },
       ],
     },
   ]);
@@ -129,6 +128,7 @@ export async function createGameCommand(options = {}) {
     console.log(brand.teal('  Next steps:'));
     console.log();
     console.log(`    ${brand.gold('cd')} ${slug}`);
+    console.log(`    ${brand.gold('npm install')}      ${brand.teal('- Install dependencies (already run for you; re-run after cloning)')}`);
     console.log(`    ${brand.gold('npm run dev')}      ${brand.teal('- Start development server')}`);
     console.log(`    ${brand.gold('npm run build')}    ${brand.teal('- Build for production')}`);
     console.log(`    ${brand.gold('myvillage deploy')} ${brand.teal('- Deploy to MyVillageOS')}`);
@@ -182,10 +182,9 @@ async function createUnityGame(options = {}) {
       name: 'ageGroup',
       message: 'Target age group:',
       choices: [
-        { name: '5-8 years', value: '5-8' },
-        { name: '9-12 years', value: '9-12' },
-        { name: '13-15 years', value: '13-15' },
-        { name: '16-18 years', value: '16-18' },
+        { name: 'Under 5', value: 'under-5' },
+        { name: '6-12', value: '6-12' },
+        { name: '13 and Over', value: '13-and-over' },
       ],
     },
   ]);

package/src/utils/templates.js

@@ -1,7 +1,13 @@
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { mkdirSync, writeFileSync, copyFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { randomUUID } from 'crypto';
 
+// Bundled starter cover art lives at src/assets/game-art/ (this file is at
+// src/utils/). Resolved from the module path so it also works once the CLI is
+// installed globally via npm.
+const GAME_ART_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'game-art');
+
 // 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.4';
@@ -77,6 +83,7 @@ export function createGameProject(targetDir, options) {
   writeFileSync(join(targetDir, 'README.md'), generateReadme(name, description, type, ageGroup));
   writeFileSync(join(targetDir, 'index.html'), generateIndexHtml(name, orientation));
   writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
+  copyTemplateArt(targetDir, type, orientation);
 
   // Write base source files
   writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
@@ -180,6 +187,9 @@ export async function createUnityGameProject(targetDir, options) {
   writeFileSync(join(targetDir, 'Assets/Editor/MyVillageOrientation.cs.meta'), generateUnityScriptMeta());
 
   writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
+  // Unity has no quiz/exploration/narrative type — categories fall back to the
+  // generic "custom" starter art inside copyTemplateArt.
+  copyTemplateArt(targetDir, type, orientation);
   writeFileSync(join(targetDir, '.gitignore'), generateUnityGitignore());
   writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, orientation, unityVersion));
 
@@ -456,6 +466,30 @@ function generatePackageJson(name, description, slug, type, ageGroup, orientatio
 }
 
 // Drop-zone guidance for cover art that ships with the submission.
+// Copy the bundled starter cover art for this template into the scaffold's
+// assets/ folder as thumbnail.png + banner.png — the paths declared in the
+// myvillage.assets block, so `myvillage deploy` ships them out of the box.
+// Devs replace these with their own before deploying. The thumbnail is always
+// square; the banner matches orientation (9:16 portrait / 16:9 landscape).
+// Unknown types (e.g. Unity categories like "puzzle") fall back to the generic
+// "custom" art. Missing source files are skipped silently so a packaging gap
+// never breaks scaffolding.
+function copyTemplateArt(targetDir, type, orientation) {
+  const KNOWN_TYPES = ['quiz', 'exploration', 'narrative', 'custom'];
+  const artType = KNOWN_TYPES.includes(type) ? type : 'custom';
+  const bannerVariant = orientation === 'portrait' ? 'portrait' : 'landscape';
+  const copies = [
+    [`${artType}-thumbnail.png`, 'thumbnail.png'],
+    [`${artType}-${bannerVariant}.png`, 'banner.png'],
+  ];
+  for (const [src, dest] of copies) {
+    const srcPath = join(GAME_ART_DIR, src);
+    if (existsSync(srcPath)) {
+      copyFileSync(srcPath, join(targetDir, 'assets', dest));
+    }
+  }
+}
+
 function generateAssetsReadme(orientation) {
   const thumb = orientation === 'portrait'
     ? 'Square (1:1, e.g. 512×512) — shown on game cards in muni and on the web.'
@@ -465,13 +499,18 @@ function generateAssetsReadme(orientation) {
     : 'Landscape hero (16:9, e.g. 1920×1080) — featured banner on the web.';
   return `# Submission art
 
-These files ship with \`myvillage deploy\` (declared in the \`myvillage.assets\` block of package.json).
+This template ships with starter **thumbnail.png** and **banner.png** so your
+game has cover art the moment you deploy. They're declared in the
+\`myvillage.assets\` block and uploaded by \`myvillage deploy\`. Swap them for your
+own art before launch — keep the same filenames (or update the paths in the
+config) and these dimensions:
 
 - **thumbnail.png** — ${thumb}
 - **banner.png** — ${banner}
 
-Replace the placeholders before deploying. The CLI checks aspect ratio against
-this game's orientation (\`${orientation}\`) and warns on a mismatch.
+The CLI checks each image's aspect ratio against this game's orientation
+(\`${orientation}\`) and warns on a mismatch — it never blocks, so the sizes above
+are recommended targets, not hard limits.
 `;
 }
 
@@ -607,8 +646,9 @@ function generateIndexHtml(name, orientation = 'landscape') {
       width: min(100vw, calc(100vh * 9 / 16));
       height: min(100vh, calc(100vw * 16 / 9));
       margin: 0 auto;
+      overflow: hidden;
     }`
-    : `#game-container { width: 100%; height: 100%; position: relative; }`;
+    : `#game-container { width: 100%; height: 100%; position: relative; overflow: hidden; }`;
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -697,9 +737,12 @@ class Game {
   }
 
   init() {
-    // Set up renderer with responsive canvas
+    // Set up renderer with responsive canvas. Size to the #game-container, not
+    // the window: portrait games are framed in a centered 9:16 box that is much
+    // narrower than a landscape desktop window. Measuring the window would make
+    // the canvas overflow the frame and render in the wrong aspect ratio.
     this.renderer = new THREE.WebGLRenderer({ antialias: true });
-    this.renderer.setSize(window.innerWidth, window.innerHeight);
+    this.renderer.setSize(this.container.clientWidth, this.container.clientHeight);
     this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
     this.renderer.shadowMap.enabled = true;
     this.container.appendChild(this.renderer.domElement);
@@ -711,8 +754,10 @@ class Game {
     this.gameLogic = new GameLogic(this);
     this.ui = new UI(this);
 
-    // Handle window resize
+    // Handle window resize, and sync the camera/renderer to the container size
+    // once now (the container's final size is known after the canvas is added).
     window.addEventListener('resize', () => this.onResize());
+    this.onResize();
 
     // Simulate asset loading (replace with real asset loading in your game)
     this.loadAssets().then(() => {
@@ -747,8 +792,10 @@ class Game {
   }
 
   onResize() {
-    const width = window.innerWidth;
-    const height = window.innerHeight;
+    // Match the container (the 9:16 frame for portrait, full viewport for
+    // landscape) rather than the raw window.
+    const width = this.container.clientWidth;
+    const height = this.container.clientHeight;
 
     this.scene.camera.aspect = width / height;
     this.scene.camera.updateProjectionMatrix();
@@ -902,12 +949,14 @@ export class MainScene {
     this.scene = new THREE.Scene();
     this.scene.background = new THREE.Color(0x87CEEB); // Sky blue
 
-    // Camera setup with perspective projection
+    // Camera setup with perspective projection. The aspect is a placeholder —
+    // Game.onResize() sets the real value from the #game-container the moment
+    // the renderer is attached (and on every resize after).
     this.camera = new THREE.PerspectiveCamera(
-      60,                                     // FOV
-      window.innerWidth / window.innerHeight, // Aspect ratio
-      0.1,                                    // Near plane
-      1000                                    // Far plane
+      60,    // FOV
+      1,     // Aspect ratio (corrected by Game.onResize)
+      0.1,   // Near plane
+      1000   // Far plane
     );
     this.camera.position.set(0, 5, 10);
     this.camera.lookAt(0, 0, 0);
@@ -991,6 +1040,11 @@ export class InputManager {
     this.touches = [];
     this.isTouchDevice = 'ontouchstart' in window;
 
+    // Virtual joystick state for mobile movement. { x, z } in the range -1..1,
+    // with active === true while a finger is on the stick. Stays null until a
+    // movement-based game calls enableJoystick(), and on desktop.
+    this.joystick = null;
+
     this.setupEventListeners();
   }
 
@@ -1007,11 +1061,23 @@ export class InputManager {
       this.keys[e.code] = false;
     });
 
+    // Normalized device coordinates (-1 to +1), relative to the canvas rect.
+    // The canvas may be a centered 9:16 frame inside a larger window (portrait
+    // games), so pointer math must be canvas-relative, not window-relative, or
+    // raycasting/picking will be offset.
+    const toNDC = (clientX, clientY) => {
+      const rect = this.canvas.getBoundingClientRect();
+      return {
+        x: ((clientX - rect.left) / rect.width) * 2 - 1,
+        y: -((clientY - rect.top) / rect.height) * 2 + 1,
+      };
+    };
+
     // Mouse events
     this.canvas.addEventListener('mousemove', (e) => {
-      // Normalized device coordinates (-1 to +1)
-      this.mouse.x = (e.clientX / window.innerWidth) * 2 - 1;
-      this.mouse.y = -(e.clientY / window.innerHeight) * 2 + 1;
+      const { x, y } = toNDC(e.clientX, e.clientY);
+      this.mouse.x = x;
+      this.mouse.y = y;
     });
 
     this.canvas.addEventListener('mousedown', () => {
@@ -1023,32 +1089,129 @@ export class InputManager {
     });
 
     // Touch events
-    this.canvas.addEventListener('touchstart', (e) => {
-      this.touches = Array.from(e.touches).map((t) => ({
-        x: (t.clientX / window.innerWidth) * 2 - 1,
-        y: -(t.clientY / window.innerHeight) * 2 + 1,
+    const mapTouches = (touchList) =>
+      Array.from(touchList).map((t) => ({
+        ...toNDC(t.clientX, t.clientY),
         id: t.identifier,
       }));
+
+    this.canvas.addEventListener('touchstart', (e) => {
+      this.touches = mapTouches(e.touches);
     });
 
     this.canvas.addEventListener('touchmove', (e) => {
       e.preventDefault();
-      this.touches = Array.from(e.touches).map((t) => ({
-        x: (t.clientX / window.innerWidth) * 2 - 1,
-        y: -(t.clientY / window.innerHeight) * 2 + 1,
-        id: t.identifier,
-      }));
+      this.touches = mapTouches(e.touches);
     }, { passive: false });
 
     this.canvas.addEventListener('touchend', (e) => {
-      this.touches = Array.from(e.touches).map((t) => ({
-        x: (t.clientX / window.innerWidth) * 2 - 1,
-        y: -(t.clientY / window.innerHeight) * 2 + 1,
-        id: t.identifier,
-      }));
+      this.touches = mapTouches(e.touches);
     });
   }
 
+  // Add an on-screen thumbstick for movement, for games that use
+  // getMovementVector(). Call this from your GameLogic.start() — the
+  // exploration template already does. No-op on desktop and if already enabled.
+  //
+  // The stick is a DOM overlay (not drawn in the 3D scene), so it survives any
+  // camera/render changes; it's anchored bottom-left inside #game-container,
+  // clear of iOS safe-area insets. Pointer Events drive it, so it also works in
+  // a desktop browser's mobile emulation for testing.
+  enableJoystick() {
+    if (!this.isTouchDevice || this.joystick) return;
+
+    const container = this.canvas.parentElement || document.body;
+
+    const base = document.createElement('div');
+    Object.assign(base.style, {
+      position: 'absolute',
+      left: 'calc(24px + env(safe-area-inset-left, 0px))',
+      bottom: 'calc(24px + env(safe-area-inset-bottom, 0px))',
+      width: '120px',
+      height: '120px',
+      borderRadius: '50%',
+      background: 'rgba(255, 255, 255, 0.15)',
+      border: '2px solid rgba(255, 255, 255, 0.4)',
+      touchAction: 'none',
+      pointerEvents: 'auto',
+      zIndex: '50',
+      userSelect: 'none',
+      webkitUserSelect: 'none',
+    });
+
+    const knob = document.createElement('div');
+    Object.assign(knob.style, {
+      position: 'absolute',
+      left: '50%',
+      top: '50%',
+      width: '56px',
+      height: '56px',
+      marginLeft: '-28px',
+      marginTop: '-28px',
+      borderRadius: '50%',
+      background: 'rgba(255, 215, 0, 0.85)',
+      boxShadow: '0 2px 8px rgba(0, 0, 0, 0.4)',
+      pointerEvents: 'none',
+    });
+    base.appendChild(knob);
+    container.appendChild(base);
+
+    const state = { x: 0, z: 0, active: false };
+    this.joystick = state;
+
+    const maxDist = 60; // how far (px) the knob travels from center
+    let center = { x: 0, y: 0 };
+    let pointerId = null;
+
+    const recenter = () => {
+      const r = base.getBoundingClientRect();
+      center = { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+    };
+
+    const setKnob = (dx, dy) => {
+      knob.style.transform = 'translate(' + dx + 'px, ' + dy + 'px)';
+    };
+
+    base.addEventListener('pointerdown', (e) => {
+      pointerId = e.pointerId;
+      base.setPointerCapture(pointerId);
+      recenter();
+      state.active = true;
+      e.preventDefault();
+    });
+
+    base.addEventListener('pointermove', (e) => {
+      if (!state.active || e.pointerId !== pointerId) return;
+      let dx = e.clientX - center.x;
+      let dy = e.clientY - center.y;
+      const dist = Math.hypot(dx, dy);
+      if (dist > maxDist) {
+        dx = (dx / dist) * maxDist;
+        dy = (dy / dist) * maxDist;
+      }
+      setKnob(dx, dy);
+      // Screen up (dy < 0) maps to forward (-z) and screen right (dx > 0) to
+      // +x — the same axes the keyboard uses, so movement feels identical.
+      state.x = dx / maxDist;
+      state.z = dy / maxDist;
+      e.preventDefault();
+    });
+
+    const release = (e) => {
+      if (e.pointerId !== pointerId) return;
+      state.active = false;
+      state.x = 0;
+      state.z = 0;
+      pointerId = null;
+      setKnob(0, 0);
+    };
+    base.addEventListener('pointerup', release);
+    base.addEventListener('pointercancel', release);
+
+    // Keep the cached center correct if the frame is resized/rotated.
+    window.addEventListener('resize', recenter);
+  }
+
   // Check if a key is currently held down
   isKeyDown(code) {
     return !!this.keys[code];
@@ -1059,8 +1222,15 @@ export class InputManager {
     return !!this.keysJustPressed[code];
   }
 
-  // Get WASD / arrow key movement vector
+  // Movement vector for the game loop. Mobile virtual joystick takes priority
+  // when engaged; otherwise falls back to WASD / arrow keys on desktop.
   getMovementVector() {
+    // The joystick vector is already analog (magnitude <= 1), so return it as-is
+    // for smooth, speed-proportional movement.
+    if (this.joystick && this.joystick.active) {
+      return { x: this.joystick.x, z: this.joystick.z };
+    }
+
     let x = 0;
     let z = 0;
 
@@ -1613,6 +1783,9 @@ export class GameLogic {
     this.collectedItems = [];
     this.setupPlayer();
     this.spawnCollectibles();
+
+    // Show the on-screen movement joystick on touch devices (no-op on desktop).
+    this.game.input.enableJoystick();
   }
 
   reset() {