@myvillage/cli 1.62.1 → 1.64.1

package/package.json

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

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';
@@ -49,6 +55,15 @@ const BRAND = {
 
 export function createGameProject(targetDir, options) {
   const { name, description, type, ageGroup, orientation = 'landscape' } = options;
+
+  // A quiz is a 2D UI experience, not a 3D world — it gets a dedicated DOM/CSS
+  // scaffold (no Three.js, no renderer, no game loop) instead of the shared
+  // 3D shell the exploration/narrative/custom types use.
+  if (type === 'quiz') {
+    createQuizProject(targetDir, options);
+    return;
+  }
+
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 
   // Create directory structure
@@ -77,6 +92,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());
@@ -103,6 +119,480 @@ export function createGameProject(targetDir, options) {
   }
 }
 
+// ── Quiz Game Project (2D) ─────────────────────────────────────────
+// A quiz is a UI experience, so this scaffold is plain DOM/CSS — no Three.js,
+// no renderer, no game loop. Two files hold everything a developer edits:
+//   src/questions.js  - the questions + quiz settings (content)
+//   src/styles.css    - the look
+// src/main.js runs the quiz lifecycle (start → questions → results) and reports
+// the result through the shared MyVillage game contract.
+function createQuizProject(targetDir, options) {
+  const { name, description, ageGroup, orientation = 'portrait' } = options;
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+
+  const dirs = ['', 'src', 'assets', 'public'];
+  for (const dir of dirs) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+
+  writeFileSync(join(targetDir, 'package.json'), generateQuizPackageJson(name, description, slug, ageGroup, orientation));
+  writeFileSync(join(targetDir, 'vite.config.js'), generateViteConfig());
+  writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
+  writeFileSync(join(targetDir, 'index.html'), generateQuizIndexHtml(name, orientation));
+  writeFileSync(join(targetDir, 'README.md'), generateQuizReadme(name, description, ageGroup));
+
+  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());
+
+  writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
+  copyTemplateArt(targetDir, 'quiz', orientation);
+}
+
+function generateQuizPackageJson(name, description, slug, ageGroup, orientation) {
+  return JSON.stringify({
+    name: slug,
+    version: '1.0.0',
+    description,
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'vite build',
+      preview: 'vite preview',
+    },
+    // No Three.js — a quiz is pure DOM/CSS.
+    devDependencies: {
+      vite: '^5.0.0',
+    },
+    myvillage: {
+      name: name,
+      gameId: null,
+      gameType: 'quiz',
+      targetAge: ageGroup,
+      orientation,
+      aspectRatio: orientation === 'portrait' ? '9:16' : '16:9',
+      assets: {
+        thumbnail: 'assets/thumbnail.png',
+        banner: 'assets/banner.png',
+      },
+      villages: [],
+      lastDeployed: null,
+    },
+  }, null, 2) + '\n';
+}
+
+function generateQuizIndexHtml(name, orientation) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+  <!-- orientation: ${orientation} -->
+  <title>${name}</title>
+  <link rel="stylesheet" href="/src/styles.css" />
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>
+`;
+}
+
+function generateQuizQuestions(name) {
+  return `// Quiz content — edit this file to make the quiz your own.
+//
+// Each question has the prompt, a list of choices, and \`correct\`: the index of
+// the right choice, starting at 0. Add or remove questions freely.
+
+export const quizConfig = {
+  // Shown on the start screen.
+  title: ${JSON.stringify(name)},
+  intro: 'Answer the questions and see how many you get right!',
+  // Fraction of questions you must get right to "win" (0.6 = 60%).
+  passThreshold: 0.6,
+  // Briefly highlight the correct / incorrect answer after each pick.
+  showFeedback: true,
+};
+
+export const questions = [
+  {
+    question: 'What is 2 + 2?',
+    choices: ['3', '4', '5', '6'],
+    correct: 1,
+  },
+  {
+    question: 'What is the capital of France?',
+    choices: ['London', 'Berlin', 'Paris', 'Madrid'],
+    correct: 2,
+  },
+  {
+    question: 'Which planet is closest to the Sun?',
+    choices: ['Venus', 'Mercury', 'Earth', 'Mars'],
+    correct: 1,
+  },
+];
+`;
+}
+
+function generateQuizApp() {
+  return `// Quiz Game — a 2D question/answer game.
+//
+// Edit your questions and settings in src/questions.js, and the look in
+// src/styles.css. This file runs the quiz: it renders the start screen, each
+// question (with a progress bar + score), instant right/wrong feedback, and a
+// results screen — then reports the result to the MyVillage host.
+
+import { MyVillageGame } from './myvillage-game.js';
+import { quizConfig, questions } from './questions.js';
+
+class QuizGame {
+  constructor(root) {
+    this.root = root;
+    this.index = 0;
+    this.score = 0;
+    this.answered = false;
+
+    this.renderStart();
+
+    // Tell the MyVillage host the game is loaded and interactive.
+    MyVillageGame.ready();
+  }
+
+  renderStart() {
+    this.root.innerHTML = \`
+      <main class="screen">
+        <div class="card start-card">
+          <h1 class="title">\${quizConfig.title}</h1>
+          <p class="intro">\${quizConfig.intro}</p>
+          <button class="btn primary" id="start-btn">Start Quiz</button>
+        </div>
+      </main>
+    \`;
+    this.root.querySelector('#start-btn').addEventListener('click', () => this.begin());
+  }
+
+  begin() {
+    this.index = 0;
+    this.score = 0;
+    this.renderQuestion();
+  }
+
+  renderQuestion() {
+    if (this.index >= questions.length) {
+      this.renderResults();
+      return;
+    }
+
+    this.answered = false;
+    const q = questions[this.index];
+    const total = questions.length;
+    const progress = (this.index / total) * 100;
+
+    this.root.innerHTML = \`
+      <main class="screen">
+        <header class="quiz-header">
+          <div class="progress"><div class="progress-fill" style="width: \${progress}%"></div></div>
+          <div class="meta">
+            <span>Question \${this.index + 1} of \${total}</span>
+            <span>Score: \${this.score}</span>
+          </div>
+        </header>
+        <div class="card question-card">
+          <p class="question">\${q.question}</p>
+          <div class="choices">
+            \${q.choices.map((choice, i) => \`<button class="btn choice" data-index="\${i}">\${choice}</button>\`).join('')}
+          </div>
+        </div>
+      </main>
+    \`;
+
+    this.root.querySelectorAll('.choice').forEach((btn) => {
+      btn.addEventListener('click', () => this.answer(Number(btn.dataset.index)));
+    });
+  }
+
+  answer(choiceIndex) {
+    if (this.answered) return; // ignore extra taps while showing feedback
+    this.answered = true;
+
+    const q = questions[this.index];
+    if (choiceIndex === q.correct) this.score++;
+
+    // Reveal the right answer (and the wrong pick, if any).
+    const buttons = this.root.querySelectorAll('.choice');
+    buttons.forEach((btn, i) => {
+      btn.disabled = true;
+      if (quizConfig.showFeedback) {
+        if (i === q.correct) btn.classList.add('correct');
+        else if (i === choiceIndex) btn.classList.add('incorrect');
+      }
+    });
+
+    const delay = quizConfig.showFeedback ? 900 : 150;
+    window.setTimeout(() => {
+      this.index++;
+      this.renderQuestion();
+    }, delay);
+  }
+
+  renderResults() {
+    const total = questions.length;
+    const won = total > 0 && this.score / total >= quizConfig.passThreshold;
+    const pct = total > 0 ? Math.round((this.score / total) * 100) : 0;
+
+    this.root.innerHTML = \`
+      <main class="screen">
+        <div class="card results-card">
+          <h2 class="title">\${won ? 'Great job!' : 'Quiz complete'}</h2>
+          <p class="result-score">\${this.score} / \${total}</p>
+          <p class="result-pct">\${pct}% correct</p>
+          <button class="btn primary" id="again-btn">Play Again</button>
+        </div>
+      </main>
+    \`;
+    this.root.querySelector('#again-btn').addEventListener('click', () => this.begin());
+
+    // REQUIRED: tell the MyVillage host the game is finished. The host records
+    // the session, awards this game's MVT reward, and returns the player to the
+    // catalog. During \`npm run dev\` there's no host, so this just logs.
+    MyVillageGame.complete({ score: this.score, won, custom: { total } });
+  }
+}
+
+new QuizGame(document.getElementById('app'));
+`;
+}
+
+function generateQuizStyles() {
+  return `/* Quiz styling — tweak freely. Colors use the MyVillage palette. */
+
+:root {
+  --gold: #FFD700;
+  --primary: #B07C00;
+  --cream: #E4DCCB;
+  --dark: #302017;
+  --deep-green: #043922;
+  --green: #228B22;
+  --teal: #799C9F;
+  --correct: #2e9e4f;
+  --incorrect: #c0392b;
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+html, body {
+  height: 100%;
+  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+}
+
+body {
+  background: linear-gradient(160deg, var(--deep-green), var(--dark));
+  color: var(--cream);
+  display: flex;
+  -webkit-font-smoothing: antialiased;
+}
+
+#app { flex: 1; display: flex; }
+
+.screen {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 16px;
+  padding: 24px;
+  width: 100%;
+}
+
+.card {
+  width: 100%;
+  max-width: 480px;
+  background: rgba(48, 32, 23, 0.92);
+  border: 2px solid var(--primary);
+  border-radius: 20px;
+  padding: 28px 24px;
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.35);
+}
+
+.start-card, .results-card { text-align: center; }
+
+.title {
+  color: var(--gold);
+  font-size: 30px;
+  margin-bottom: 12px;
+}
+
+.intro {
+  font-size: 16px;
+  line-height: 1.5;
+  margin-bottom: 24px;
+  color: var(--cream);
+}
+
+/* Header: progress bar + meta row */
+.quiz-header { width: 100%; max-width: 480px; }
+
+.progress {
+  height: 8px;
+  background: rgba(255, 255, 255, 0.15);
+  border-radius: 99px;
+  overflow: hidden;
+  margin-bottom: 10px;
+}
+
+.progress-fill {
+  height: 100%;
+  background: var(--gold);
+  border-radius: 99px;
+  transition: width 0.3s ease;
+}
+
+.meta {
+  display: flex;
+  justify-content: space-between;
+  font-size: 14px;
+  color: var(--teal);
+  font-weight: 600;
+}
+
+.question {
+  font-size: 20px;
+  font-weight: 700;
+  color: var(--gold);
+  margin-bottom: 20px;
+  text-align: center;
+  line-height: 1.4;
+}
+
+.choices { display: flex; flex-direction: column; gap: 12px; }
+
+/* Buttons */
+.btn {
+  font-family: inherit;
+  font-size: 16px;
+  font-weight: 600;
+  border-radius: 12px;
+  border: none;
+  cursor: pointer;
+  min-height: 52px;
+  padding: 14px 18px;
+  transition: transform 0.05s ease, background 0.2s ease, border-color 0.2s ease;
+}
+
+.btn:active { transform: scale(0.98); }
+
+.btn.primary {
+  background: var(--primary);
+  color: #fff;
+  width: 100%;
+  font-size: 18px;
+}
+
+.btn.primary:hover { background: #c98f0a; }
+
+.choice {
+  background: var(--deep-green);
+  color: var(--cream);
+  border: 2px solid var(--green);
+  text-align: left;
+  width: 100%;
+}
+
+.choice:hover:not(:disabled) { border-color: var(--gold); }
+.choice:disabled { cursor: default; opacity: 0.95; }
+
+.choice.correct {
+  background: var(--correct);
+  border-color: var(--correct);
+  color: #fff;
+}
+
+.choice.incorrect {
+  background: var(--incorrect);
+  border-color: var(--incorrect);
+  color: #fff;
+}
+
+.result-score {
+  font-size: 48px;
+  font-weight: 800;
+  color: var(--gold);
+  margin: 12px 0 4px;
+}
+
+.result-pct {
+  font-size: 18px;
+  color: var(--teal);
+  margin-bottom: 24px;
+}
+`;
+}
+
+function generateQuizReadme(name, description, ageGroup) {
+  return `# ${name}
+
+${description}
+
+- **Game Type**: Quiz
+- **Target Age Group**: ${ageGroup}
+- **Built with**: MyVillageOS CLI
+
+A 2D quiz game — no 3D engine. Edit two files to make it yours:
+
+- **src/questions.js** — your questions, answers, and quiz settings (title, pass mark, feedback)
+- **src/styles.css** — colors, fonts, and layout
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run dev      # play it locally with live reload
+npm run build    # build for production (outputs to dist/)
+\`\`\`
+
+## Editing questions
+
+Open \`src/questions.js\`. Each question is an object with the prompt, the list of
+\`choices\`, and \`correct\` — the index of the right choice (0 = the first):
+
+\`\`\`js
+{
+  question: 'Which planet is closest to the Sun?',
+  choices: ['Venus', 'Mercury', 'Earth', 'Mars'],
+  correct: 1, // 'Mercury'
+}
+\`\`\`
+
+\`quizConfig\` at the top of the file controls the title, intro text, the pass
+threshold (fraction correct needed to "win"), and whether to flash right/wrong
+feedback after each answer.
+
+## The game contract
+
+When the quiz finishes it calls \`MyVillageGame.complete({ score, won })\`, so the
+MyVillage host records the session and awards the player this game's MVT reward.
+\`MyVillageGame.ready()\` is called on load. During \`npm run dev\` there's no host
+attached, so these just log to the console — that's expected.
+
+## Deploying
+
+Starter cover art ships in \`assets/\` — swap in your own thumbnail.png + banner.png, then:
+
+\`\`\`bash
+myvillage deploy
+\`\`\`
+
+## Learn More
+
+- [Vite Documentation](https://vitejs.dev/)
+- [MyVillageOS Developer Guide](https://portal.myvillageproject.ai)
+`;
+}
+
 // ── Unity Game Project ─────────────────────────────────────────────
 
 export async function createUnityGameProject(targetDir, options) {
@@ -180,6 +670,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 +949,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 +982,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 +1129,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 +1220,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 +1237,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 +1275,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 +1432,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 +1523,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 +1544,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 +1572,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 +1705,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 +2266,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() {