@myvillage/cli 2.6.1 → 2.7.0

package/package.json

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

package/src/utils/templates.js

@@ -235,7 +235,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 +435,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;
 }
 
@@ -851,10 +860,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;
 }
 
@@ -1085,11 +1103,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)`.'
     : '';
@@ -1125,7 +1143,7 @@ function generate3DGameAgents(name, type, orientation) {
     '## 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 +1152,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 +1863,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 +2082,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);
   }
@@ -2247,6 +2291,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 +2376,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 +2463,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 +2563,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 +2669,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 +2683,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 +2703,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 +2784,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 +2916,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 +2931,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 +2955,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 +2999,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) => {