@myvillage/cli 2.6.1 → 2.8.0

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);
@@ -235,7 +247,7 @@ function generate2DGameIndexHtml(name, orientation) {
 <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" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
   <!-- orientation: ${orientation} -->
   <title>${name}</title>
   <link rel="stylesheet" href="/src/styles.css" />
@@ -435,10 +447,19 @@ html, body {
   font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
 }
 
+/* The background runs edge to edge on a phone (behind the status bar and home
+   indicator); content stays inside the safe area. The extra top space keeps the
+   top-left corner clear for the host app's Exit button. The muni app injects
+   --mv-safe-* because Android web views don't report env() insets. */
 body {
+  --safe-top: max(env(safe-area-inset-top, 0px), var(--mv-safe-top, 0px));
+  --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--mv-safe-bottom, 0px));
+  --safe-left: max(env(safe-area-inset-left, 0px), var(--mv-safe-left, 0px));
+  --safe-right: max(env(safe-area-inset-right, 0px), var(--mv-safe-right, 0px));
   background: linear-gradient(160deg, var(--deep-green), var(--dark));
   color: var(--cream);
   display: flex;
+  padding: calc(var(--safe-top) + 44px) var(--safe-right) var(--safe-bottom) var(--safe-left);
   -webkit-font-smoothing: antialiased;
 }
 
@@ -664,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.
 //
@@ -851,10 +921,19 @@ html, body {
   font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
 }
 
+/* The background runs edge to edge on a phone (behind the status bar and home
+   indicator); content stays inside the safe area. The extra top space keeps the
+   top-left corner clear for the host app's Exit button. The muni app injects
+   --mv-safe-* because Android web views don't report env() insets. */
 body {
+  --safe-top: max(env(safe-area-inset-top, 0px), var(--mv-safe-top, 0px));
+  --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--mv-safe-bottom, 0px));
+  --safe-left: max(env(safe-area-inset-left, 0px), var(--mv-safe-left, 0px));
+  --safe-right: max(env(safe-area-inset-right, 0px), var(--mv-safe-right, 0px));
   background: linear-gradient(160deg, var(--deep-green), var(--dark));
   color: var(--cream);
   display: flex;
+  padding: calc(var(--safe-top) + 44px) var(--safe-right) var(--safe-bottom) var(--safe-left);
   -webkit-font-smoothing: antialiased;
 }
 
@@ -1041,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. |',
     '',
@@ -1085,11 +1165,11 @@ function generate3DGameAgents(name, type, orientation) {
     ? '9:16 (e.g. 1080x1920) for this portrait game'
     : '16:9 (e.g. 1920x1080) for this landscape game';
   const logicLine = isExploration
-    ? 'Holds the gameplay — player movement (via `input.getMovementVector()`), collectible spawning + collision, the follow-camera, score, and win condition. It calls `input.enableJoystick()` in `start()` so mobile gets on-screen movement.'
+    ? 'Holds the gameplay — player movement (via `input.getMovementVector()`), collectible spawning + collision, the drag-to-look follow camera, score, and win condition. It calls `input.enableJoystick()` and `input.enableLookControls()` in `start()` so phones get a move stick plus drag-to-look.'
     : 'A blank starter — `update(delta)` is empty with hints. Build your mechanics here; the 3D scene, input, audio, UI, and game loop are already wired.';
   const mobileLine = isExploration
-    ? 'This game already calls `this.game.input.enableJoystick()` in `GameLogic.start()`, so touch devices get an on-screen movement thumbstick (no-op on desktop). Read movement with `this.game.input.getMovementVector()`.'
-    : 'If your game uses movement, call `this.game.input.enableJoystick()` in `GameLogic.start()` to show an on-screen thumbstick on touch devices (no-op on desktop), then read it with `this.game.input.getMovementVector()`.';
+    ? 'This game already calls `this.game.input.enableJoystick()` and `this.game.input.enableLookControls()` in `GameLogic.start()`: left thumb moves (WASD on desktop), dragging anywhere else turns the camera (mouse drag on desktop). Movement is relative to where the camera faces. Keep both whenever a character moves through the 3D world.'
+    : 'If a character moves through the 3D world, give it BOTH controls in `GameLogic.start()`: `this.game.input.enableJoystick()` (on-screen move stick on touch devices, WASD on desktop; read with `getMovementVector()`) and `this.game.input.enableLookControls()` (drag to turn the camera; read with `getLookDelta()` each frame). Make movement relative to the camera\'s facing.';
   const uiExtra = isExploration
     ? ' This game also adds `showMinimap(pos, items)` and `showInventory(items)`.'
     : '';
@@ -1119,13 +1199,14 @@ 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. |',
     '',
     '## Engine API (reach it as `this.game` inside GameLogic)',
     '',
     '- `this.game.scene` — `.scene` (THREE.Scene), `.camera` (THREE.PerspectiveCamera), `.sampleObject`, `.update(delta)`.',
-    '- `this.game.input` — `getMovementVector()` (returns `{ x, z }` from WASD/arrows or the joystick), `isKeyDown(code)`, `isKeyJustPressed(code)`, `enableJoystick()`, `clearFrame()`, `mouse`, `touches`.',
+    '- `this.game.input` — `getMovementVector()` (returns `{ x, z }` from WASD/arrows or the joystick), `getLookDelta()` (drag since last frame, `{ x, y }` px), `isKeyDown(code)`, `isKeyJustPressed(code)`, `enableJoystick()`, `enableLookControls()`, `mouse`, `touches`. The loop calls `clearFrame()` for you.',
     '- `this.game.audio` — `playSFX(name)`, `playMusic(name)`, `stopMusic()`, `setMusicVolume(v)`, `setSFXVolume(v)`.',
     '- `this.game.ui` — `showMenu()`, `showHUD()`, `showPauseMenu()`, `showGameOver(result)`, `clearOverlay()`, `createElement(tag, styles)`.' + uiExtra,
     '- `this.game` — `startGame()`, `pauseGame()`, `resumeGame()`, `endGame(result)`, `state`.',
@@ -1134,6 +1215,12 @@ function generate3DGameAgents(name, type, orientation) {
     '',
     mobileLine,
     '',
+    '## Screen layout (phones)',
+    '',
+    '- The game fills the whole screen edge to edge, including behind the status bar and home indicator. Never letterbox it or add bars; on a wide desktop window `index.html` frames it automatically.',
+    '- Keep HUD inside the safe area with the CSS variables in `index.html`: top row at `var(--hud-top)`, and `var(--safe-bottom)` / `var(--safe-left)` / `var(--safe-right)` from the other edges.',
+    '- Leave the **top-left corner** (`var(--exit-clear)` wide, below `var(--safe-top)`) empty: the host app draws its Exit button there. Put Pause and other top buttons on the right.',
+    '',
     '## The MyVillage game contract — DO NOT BREAK',
     '',
     '- `MyVillageGame.ready()` — called after assets load in `src/main.js`. Leave it.',
@@ -1839,31 +1926,49 @@ cover art with the submission. An admin sets the game's MVT reward at review tim
 
 function generateIndexHtml(name, orientation = 'landscape') {
   const isPortrait = orientation === 'portrait';
-  // Portrait games are framed by a 9:16 stage so they look right both in the
-  // muni mobile shell (portrait WebView) and on the web. Landscape fills the
-  // viewport as before.
+  // Portrait games fill the whole phone screen edge to edge (behind the status
+  // bar and home indicator — the muni app draws a soft fade + Exit over the top
+  // corner). Only on a wide screen (desktop web) is the game framed in a 9:16
+  // stage so it doesn't stretch. Landscape always fills the viewport.
   const containerStyle = isPortrait
     ? `#game-container {
       position: relative;
-      width: min(100vw, calc(100vh * 9 / 16));
-      height: min(100vh, calc(100vw * 16 / 9));
-      margin: 0 auto;
+      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 { width: 100%; height: 100%; position: relative; overflow: hidden; }`;
   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" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
   <!-- orientation: ${orientation} -->
   <title>${name}</title>
   <style>
+    /* Screen-edge spacing. On a phone the game runs under the status bar and
+       home indicator; keep HUD inside these. The muni app also injects
+       --mv-safe-* (Android web views don't report env() insets).
+       --hud-top: first row of HUD buttons. The TOP-LEFT corner (--exit-clear
+       wide, below --safe-top) belongs to the app's Exit button — keep it empty. */
+    :root {
+      --safe-top: max(env(safe-area-inset-top, 0px), var(--mv-safe-top, 0px));
+      --safe-bottom: max(env(safe-area-inset-bottom, 0px), var(--mv-safe-bottom, 0px));
+      --safe-left: max(env(safe-area-inset-left, 0px), var(--mv-safe-left, 0px));
+      --safe-right: max(env(safe-area-inset-right, 0px), var(--mv-safe-right, 0px));
+      --hud-top: calc(var(--safe-top) + 12px);
+      --exit-clear: 64px;
+    }
     * { margin: 0; padding: 0; box-sizing: border-box; }
     html, body { width: 100%; height: 100%; overflow: hidden; }
     body { background: ${BRAND.darkBrown}; display: flex; align-items: center; justify-content: center; }
     ${containerStyle}
-    canvas { display: block; }
+    /* touch-action: none — drags on the game steer the camera, never scroll the page. */
+    canvas { display: block; touch-action: none; }
 
     /* Loading screen */
     #loading-screen {
@@ -2040,6 +2145,8 @@ class Game {
       this.gameLogic.update(delta);
       this.scene.update(delta);
     }
+    // One-shot input (just-pressed keys, look drag) lasts exactly one frame.
+    this.input.clearFrame();
 
     this.renderer.render(this.scene.scene, this.scene.camera);
   }
@@ -2056,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();
+  return readFileSync(join(ASSETS_DIR, 'game-toolkit', 'myvillage-game.js'), 'utf8');
 }
 
-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;
-}
-
-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) {
@@ -2247,6 +2283,11 @@ export class InputManager {
     // movement-based game calls enableJoystick(), and on desktop.
     this.joystick = null;
 
+    // Look-around drag, in pixels since the last frame. Stays inactive until a
+    // 3D game calls enableLookControls(); read it with getLookDelta().
+    this.lookEnabled = false;
+    this.lookDelta = { x: 0, y: 0 };
+
     this.setupEventListeners();
   }
 
@@ -2327,8 +2368,8 @@ export class InputManager {
     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))',
+      left: 'calc(24px + var(--safe-left, 0px))',
+      bottom: 'calc(24px + var(--safe-bottom, 0px))',
       width: '120px',
       height: '120px',
       borderRadius: '50%',
@@ -2414,6 +2455,66 @@ export class InputManager {
     window.addEventListener('resize', recenter);
   }
 
+  // Drag anywhere on the game (outside the joystick) to look around — one
+  // finger on a phone, or click-and-drag with a mouse. Pair it with
+  // enableJoystick() in any game where a character moves through a 3D world:
+  // left thumb moves, right thumb looks. Read the drag each frame with
+  // getLookDelta() and turn the camera with it. No-op if already enabled.
+  enableLookControls() {
+    if (this.lookEnabled) return;
+    this.lookEnabled = true;
+
+    let lookId = null;
+    let last = { x: 0, y: 0 };
+
+    this.canvas.addEventListener('pointerdown', (e) => {
+      if (lookId !== null) return;
+      if (e.pointerType === 'mouse' && e.button !== 0) return;
+      lookId = e.pointerId;
+      last = { x: e.clientX, y: e.clientY };
+      this.canvas.setPointerCapture(lookId);
+      hint.style.opacity = '0';
+    });
+
+    this.canvas.addEventListener('pointermove', (e) => {
+      if (e.pointerId !== lookId) return;
+      this.lookDelta.x += e.clientX - last.x;
+      this.lookDelta.y += e.clientY - last.y;
+      last = { x: e.clientX, y: e.clientY };
+    });
+
+    const release = (e) => {
+      if (e.pointerId === lookId) lookId = null;
+    };
+    this.canvas.addEventListener('pointerup', release);
+    this.canvas.addEventListener('pointercancel', release);
+
+    // A small hint on the right, gone after the first drag.
+    const hint = document.createElement('div');
+    hint.textContent = this.isTouchDevice ? 'Drag to look around' : 'Drag to look · WASD to move';
+    Object.assign(hint.style, {
+      position: 'absolute',
+      right: 'calc(20px + var(--safe-right, 0px))',
+      bottom: 'calc(64px + var(--safe-bottom, 0px))',
+      padding: '6px 12px',
+      borderRadius: '14px',
+      background: 'rgba(0, 0, 0, 0.35)',
+      color: 'rgba(255, 255, 255, 0.9)',
+      font: '13px system-ui, sans-serif',
+      pointerEvents: 'none',
+      transition: 'opacity 0.6s',
+      zIndex: '50',
+    });
+    (this.canvas.parentElement || document.body).appendChild(hint);
+    setTimeout(() => { hint.style.opacity = '0'; }, 6000);
+  }
+
+  // Look-around drag since the last frame, in pixels ({ x: right, y: down }).
+  // Multiply by a small sensitivity (e.g. 0.005 rad/px) to turn the camera.
+  getLookDelta() {
+    return { x: this.lookDelta.x, y: this.lookDelta.y };
+  }
+
   // Check if a key is currently held down
   isKeyDown(code) {
     return !!this.keys[code];
@@ -2454,6 +2555,8 @@ export class InputManager {
   // Call at the end of each frame to clear one-shot inputs
   clearFrame() {
     this.keysJustPressed = {};
+    this.lookDelta.x = 0;
+    this.lookDelta.y = 0;
   }
 }
 `;
@@ -2558,9 +2661,10 @@ function generateUI(type) {
     // Minimap rendering in top-right corner
     let minimap = this.overlay.querySelector('#minimap');
     if (!minimap) {
+      // Top-right, under the Pause button (the top-left corner is the app's Exit).
       minimap = this.createElement('canvas', {
-        position: 'absolute', top: '10px', right: '10px',
-        width: '150px', height: '150px',
+        position: 'absolute', top: 'calc(var(--hud-top) + 48px)', right: 'calc(12px + var(--safe-right))',
+        width: '120px', height: '120px',
         background: 'rgba(48,32,23,0.8)', borderRadius: '8px',
         border: '2px solid #B07C00',
       });
@@ -2571,7 +2675,7 @@ function generateUI(type) {
     }
 
     const ctx = minimap.getContext('2d');
-    ctx.clearRect(0, 0, 150, 150);
+    ctx.clearRect(0, 0, 150, 150); // drawing space stays 150; CSS scales it
 
     // Draw player
     ctx.fillStyle = '#FFD700';
@@ -2591,19 +2695,23 @@ function generateUI(type) {
   showInventory(items) {
     let inv = this.overlay.querySelector('#inventory');
     if (!inv) {
+      // Bottom-right, clear of the joystick (bottom-left) and the home indicator.
+      // pointerEvents none so drags over it still turn the camera.
       inv = this.createElement('div', {
-        position: 'absolute', bottom: '10px', left: '50%', transform: 'translateX(-50%)',
-        display: 'flex', gap: '8px', background: 'rgba(48,32,23,0.85)',
-        padding: '10px', borderRadius: '12px',
+        position: 'absolute', bottom: 'calc(12px + var(--safe-bottom))', right: 'calc(12px + var(--safe-right))',
+        maxWidth: '55%', display: 'flex', flexWrap: 'wrap', justifyContent: 'flex-end',
+        gap: '6px', background: 'rgba(48,32,23,0.85)',
+        padding: '8px', borderRadius: '12px', pointerEvents: 'none',
       });
       inv.id = 'inventory';
       this.overlay.appendChild(inv);
     }
     inv.innerHTML = '';
+    inv.style.display = items.length ? 'flex' : 'none';
 
     items.forEach((item) => {
       const slot = this.createElement('div', {
-        width: '48px', height: '48px', background: '#043922',
+        width: '40px', height: '40px', background: '#043922',
         borderRadius: '8px', border: '2px solid #228B22',
         display: 'flex', alignItems: 'center', justifyContent: 'center',
         color: '#FFD700', fontSize: '12px', textAlign: 'center',
@@ -2668,8 +2776,10 @@ export class UI {
   showHUD() {
     this.clearOverlay();
 
+    // Top-right, inside the safe area. Keep the top-left corner empty — the
+    // host app draws its Exit button there.
     const pauseBtn = this.createElement('button', {
-      position: 'absolute', top: '10px', right: '10px',
+      position: 'absolute', top: 'var(--hud-top)', right: 'calc(12px + var(--safe-right))',
       padding: '8px 16px', background: 'rgba(48,32,23,0.7)',
       color: '#E4DCCB', border: '1px solid #B07C00',
       borderRadius: '8px', cursor: 'pointer', fontSize: '14px',
@@ -2798,6 +2908,13 @@ export class GameLogic {
     this.player = null;
     this.collectibles = [];
     this.collectedItems = [];
+
+    // Follow camera: orbits the player. Drag to change yaw (turn) and pitch
+    // (tilt); movement is relative to where the camera faces.
+    this.cameraYaw = 0;
+    this.cameraPitch = 0.55; // radians above the horizon
+    this.cameraDistance = 12;
+    this.lookSensitivity = 0.005; // radians per dragged pixel
   }
 
   start() {
@@ -2806,8 +2923,10 @@ export class GameLogic {
     this.setupPlayer();
     this.spawnCollectibles();
 
-    // Show the on-screen movement joystick on touch devices (no-op on desktop).
+    // Phones: left thumb moves (joystick), drag anywhere else to look around.
+    // Desktop: WASD / arrows to move, mouse drag to look.
     this.game.input.enableJoystick();
+    this.game.input.enableLookControls();
   }
 
   reset() {
@@ -2828,8 +2947,19 @@ export class GameLogic {
     this.player.castShadow = true;
     this.game.scene.scene.add(this.player);
 
-    // Update camera to follow player
-    this.game.scene.camera.position.set(0, 8, 12);
+    this.updateCamera();
+  }
+
+  updateCamera() {
+    const cam = this.game.scene.camera;
+    const target = this.player.position;
+    const flat = Math.cos(this.cameraPitch) * this.cameraDistance;
+    cam.position.set(
+      target.x + Math.sin(this.cameraYaw) * flat,
+      target.y + Math.sin(this.cameraPitch) * this.cameraDistance,
+      target.z + Math.cos(this.cameraYaw) * flat
+    );
+    cam.lookAt(target);
   }
 
   spawnCollectibles() {
@@ -2861,19 +2991,26 @@ export class GameLogic {
   update(delta) {
     if (!this.player) return;
 
-    // WASD movement
+    // Look around: drag turns (x) and tilts (y) the camera.
+    const look = this.game.input.getLookDelta();
+    this.cameraYaw -= look.x * this.lookSensitivity;
+    this.cameraPitch = Math.max(0.15, Math.min(1.3, this.cameraPitch + look.y * this.lookSensitivity));
+
+    // Move relative to the camera: stick up / W walks away from the camera.
     const movement = this.game.input.getMovementVector();
-    this.player.position.x += movement.x * this.moveSpeed * delta;
-    this.player.position.z += movement.z * this.moveSpeed * delta;
+    const sin = Math.sin(this.cameraYaw);
+    const cos = Math.cos(this.cameraYaw);
+    const dx = movement.x * cos + movement.z * sin;
+    const dz = -movement.x * sin + movement.z * cos;
+    this.player.position.x += dx * this.moveSpeed * delta;
+    this.player.position.z += dz * this.moveSpeed * delta;
+    if (dx !== 0 || dz !== 0) this.player.rotation.y = Math.atan2(dx, dz);
 
     // Keep player within bounds
     this.player.position.x = Math.max(-24, Math.min(24, this.player.position.x));
     this.player.position.z = Math.max(-24, Math.min(24, this.player.position.z));
 
-    // Camera follows player
-    this.game.scene.camera.position.x = this.player.position.x;
-    this.game.scene.camera.position.z = this.player.position.z + 12;
-    this.game.scene.camera.lookAt(this.player.position);
+    this.updateCamera();
 
     // Check collisions with collectibles
     this.collectibles.forEach((item) => {