@myvillage/cli 2.16.1 → 2.17.0

package/package.json

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

package/src/assets/game-toolkit/myvillage-game.js

@@ -1,4 +1,4 @@
-// MyVillage Game Bridge — the "mvgame" protocol (v2).
+// MyVillage Game Bridge — the "mvgame" protocol (v3).
 //
 // ONE contract for every MyVillage game, on every surface:
 //   - muni mobile app  (React Native WebView)
@@ -12,6 +12,13 @@
 // One the host ALWAYS provides, but you can trigger too:
 //   MyVillageGame.exit()                 // leave the game
 //
+// Play time is automatic. This file measures how long the player is actually
+// playing (screen visible, touched/clicked/pressed something recently) and
+// reports it to the host, which is how the platform tells a real play from
+// someone opening the game and closing it. Don't add timers or fake input for
+// it. Optionally, report the running score as the game goes:
+//   MyVillageGame.progress({ score })
+//
 // Real-time multiplayer (optional) — see "Multiplayer" below:
 //   const mp = await MyVillageGame.multiplayer({ arena, game: 'my-game' });
 //   await mp.quickMatch();              // or mp.host() / mp.join(code)
@@ -25,7 +32,7 @@
 
 const PROTOCOL = 'mvgame';
 const HOST_PROTOCOL = 'mvgame-host';
-const VERSION = 2;
+const VERSION = 3;
 
 const hasWindow = typeof window !== 'undefined';
 const inReactNative = hasWindow && !!window.ReactNativeWebView;
@@ -59,6 +66,73 @@ function post(message) {
   }
 }
 
+// ── Play time ───────────────────────────────────────────────────────────────
+// The platform counts a session as a play once the player has been actively
+// playing for a while (the threshold is the platform's, not ours). Only the game
+// page can tell a player who's playing from a game left open on a table, so the
+// measuring happens here: time counts while the page is visible and the player
+// has touched, clicked or pressed something in the last IDLE_AFTER_MS.
+//
+// The host forwards { type: 'progress', activeMs } to the platform. A message
+// with version >= 3 also tells the host this game measures its own time, so it
+// doesn't fall back to timing how long the game is on screen.
+
+const IDLE_AFTER_MS = 20000;
+const REPORT_EVERY_MS = 10000; // of active time
+const TICK_MS = 1000;
+
+let activeMs = 0;
+let lastInputAt = -Infinity;
+let lastTickAt = now();
+let reportedMs = -1;
+let lastReportAt = -Infinity;
+let pendingUpdate = null; // from progress(), sent with the next report
+let finished = false;
+
+function pageVisible() {
+  return typeof document === 'undefined' || document.visibilityState !== 'hidden';
+}
+
+function playTick() {
+  const t = now();
+  // A throttled background tab can skip ticks; never credit more than a tick or
+  // two for one interval.
+  const dt = Math.min(t - lastTickAt, TICK_MS * 2);
+  lastTickAt = t;
+  if (pageVisible() && t - lastInputAt < IDLE_AFTER_MS) activeMs += dt;
+  if (!finished && activeMs - reportedMs >= REPORT_EVERY_MS) reportProgress();
+}
+
+function reportProgress() {
+  if (finished) return;
+  reportedMs = activeMs;
+  lastReportAt = now();
+  const update = pendingUpdate;
+  pendingUpdate = null;
+  post({ type: 'progress', ...update, activeMs: Math.round(activeMs) });
+}
+
+if (hasWindow) {
+  const onInput = () => {
+    lastInputAt = now();
+  };
+  for (const type of ['pointerdown', 'pointermove', 'touchstart', 'touchmove', 'keydown', 'wheel']) {
+    window.addEventListener(type, onInput, { capture: true, passive: true });
+  }
+  setInterval(playTick, TICK_MS);
+  // Leaving (app backgrounded, tab hidden, page closing): report what we have.
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (!pageVisible() && activeMs > reportedMs) reportProgress();
+    });
+  }
+  window.addEventListener('pagehide', () => {
+    if (activeMs > reportedMs) reportProgress();
+  });
+  // Announce right away so the host knows this game reports its own play time.
+  setTimeout(() => reportProgress(), 0);
+}
+
 // ── Host context ────────────────────────────────────────────────────────────
 // Hosts that support multiplayer hand the game a context:
 //   { apiBase, game, playToken, platform, player: { displayName } }
@@ -451,7 +525,29 @@ export const MyVillageGame = {
    * `durationMs` is added automatically.
    */
   complete(result = {}) {
-    post({ type: 'complete', durationMs: Math.round(now() - startedAt), ...result });
+    if (finished) return;
+    playTick();
+    finished = true;
+    post({
+      type: 'complete',
+      durationMs: Math.round(now() - startedAt),
+      activeMs: Math.round(activeMs),
+      ...result,
+    });
+  },
+
+  /**
+   * Optional: report how the game is going, e.g. the running score. Play time is
+   * reported automatically — you never need to call this for a play to count.
+   *   { score?: number, custom?: object }
+   */
+  progress(update = {}) {
+    pendingUpdate = { ...pendingUpdate, ...update };
+    // Safe to call every frame: sent at most every couple of seconds.
+    if (now() - lastReportAt >= 2000) {
+      playTick();
+      reportProgress();
+    }
   },
 
   /** Request to leave the game. The host also always offers an Exit control. */

package/src/assets/templates/arena/AGENTS.md

@@ -67,6 +67,7 @@ A match starts by itself once `minPlayers` are connected. Until then players can
 - Keep `MyVillageGame.ready()` in `src/main.js`.
 - **Never send positions, hits or scores yourself.** Only `net.controls`. Anything else is ignored by the server, and it's the server's results that award MVT.
 - **Don't call `MyVillageGame.complete()` when a match ends.** The platform records multiplayer results from the match server. Hosts treat `complete()` as "close the game", which would stop players from playing again.
+- Plays count automatically: `src/myvillage-game.js` reports active play time to the host, and the platform counts a play after 30 seconds of it. Don't add anything for it.
 - Players are identified only by display name and an in-match id. Don't ask for, show or store anything more about them.
 - **Players only play with their own village.** The platform enforces it: codes only admit village-mates of the host, and quick match stays inside the player's villages. Don't build anything that suggests playing with strangers.
 - Don't add an Exit button; the host provides one (top-left). The in-game **Leave** button just returns to the lobby.

package/src/commands/deploy.js

@@ -9,6 +9,7 @@ import { villageSpinner, brand } from '../utils/brand.js';
 import { isAuthenticated } from '../utils/auth.js';
 import { deployGame, getGameUploadUrl, confirmGameUpload, submitGameForReview, getGameDetail, updateGameMetadata } from '../utils/api.js';
 import { preflightBundles } from '../utils/preflight.js';
+import { refreshGameToolkit, gameCallsComplete } from '../utils/game-toolkit.js';
 import { selectGameVillages } from '../utils/village-resolver.js';
 
 function readPackageJson(dir) {
@@ -269,6 +270,21 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
   const villageIds = await gatherVillages(pkg.myvillage.villages || [], options);
   if (villageIds === null) return; // could not resolve villages — abort
 
+  // Ship the current platform toolkit (play-time reporting, host protocol),
+  // whatever CLI version the game was created with.
+  const toolkitUpdated = refreshGameToolkit(projectDir);
+  if (toolkitUpdated.length && !json) {
+    console.log(brand.teal(`  Updated the MyVillage game toolkit (${toolkitUpdated.join(', ')})`));
+  }
+  // Multiplayer games never call complete() — the match server records results.
+  const warnings = [];
+  if (!multiplayer && !gameCallsComplete(projectDir)) {
+    warnings.push(
+      "This game never calls MyVillageGame.complete(). Plays still count, but finishing the game won't record a completion or pay the player's reward. Call it on every way the game can end (win, lose, game over).",
+    );
+  }
+  if (!json) for (const w of warnings) console.log(chalk.yellow(`  ⚠ ${w}`));
+
   const spinner = json ? null : villageSpinner('Building game...').start();
 
   const failOut = (msg) => {
@@ -360,6 +376,8 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
           status: finalStatus,
           title: metadata.title,
           villageIds,
+          toolkitUpdated,
+          warnings,
         }),
       );
       return;

package/src/utils/game-toolkit.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+
+// The platform files every JS game ships (see src/assets/game-toolkit). They're
+// copied into a game at scaffold time, so without a refresh a game keeps the
+// toolkit it was created with forever — and platform behaviour that lives in
+// the toolkit (like reporting play time) never reaches it. `deploy` refreshes
+// them, so every deploy from the CLI or MVP Studio ships the current toolkit.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOOLKIT_FILES = [
+  {
+    target: 'src/myvillage-game.js',
+    source: join(HERE, '..', 'assets', 'game-toolkit', 'myvillage-game.js'),
+    // Only replace a file that is still ours; a hand-rolled bridge is left alone.
+    isOurs: (text) => text.startsWith('// MyVillage Game Bridge'),
+  },
+  {
+    target: 'src/myvillage-realtime.js',
+    source: join(HERE, '..', '..', 'vendor', 'realtime', 'myvillage-realtime-client.js'),
+    isOurs: (text) => text.startsWith('// myvillage-realtime client'),
+    // The bridge imports it lazily, so it must exist next to the bridge for the
+    // build to resolve, even in games scaffolded before multiplayer existed.
+    createIfMissing: true,
+  },
+];
+
+/**
+ * Bring a game's platform files up to the toolkit bundled with this CLI.
+ * Returns the paths it changed. Does nothing for a game without our bridge.
+ */
+export function refreshGameToolkit(projectDir) {
+  const bridge = join(projectDir, 'src/myvillage-game.js');
+  if (!existsSync(bridge) || !TOOLKIT_FILES[0].isOurs(readFileSync(bridge, 'utf8'))) return [];
+
+  const changed = [];
+  for (const file of TOOLKIT_FILES) {
+    const target = join(projectDir, file.target);
+    const latest = readFileSync(file.source, 'utf8');
+    if (existsSync(target)) {
+      const current = readFileSync(target, 'utf8');
+      if (current === latest || !file.isOurs(current)) continue;
+    } else if (!file.createIfMissing) {
+      continue;
+    }
+    writeFileSync(target, latest);
+    changed.push(file.target);
+  }
+  return changed;
+}
+
+/**
+ * Whether the game's own code (not the toolkit) ever calls complete(). A game
+ * that never does can't record a finished game or pay its reward.
+ */
+export function gameCallsComplete(projectDir) {
+  const src = join(projectDir, 'src');
+  if (!existsSync(src)) return true; // not a toolkit game; nothing to judge
+  const toolkit = new Set(TOOLKIT_FILES.map((f) => join(projectDir, f.target)));
+  const stack = [src];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      if (statSync(path).isDirectory()) {
+        stack.push(path);
+      } else if (['.js', '.mjs', '.ts', '.jsx', '.tsx'].includes(extname(name)) && !toolkit.has(path)) {
+        if (/MyVillageGame\s*\.\s*complete\s*\(/.test(readFileSync(path, 'utf8'))) return true;
+      }
+    }
+  }
+  return false;
+}

package/src/utils/templates.js

@@ -1129,7 +1129,8 @@ function generate2DGameAgents(name, gameType, orientation) {
     'The game talks to its host through `src/myvillage-game.js`:',
     '',
     '- `MyVillageGame.ready()` — called on load. Leave it.',
-    '- `MyVillageGame.complete({ score, won })` — **required.** Called when the game ends (in `' + endFn + '`). It is how the host records the session and awards the player\'s reward. If you change the end flow, keep this call wired to the real end condition.',
+    '- `MyVillageGame.complete({ score, won })` — **required.** Called when the game ends (in `' + endFn + '`). It records a completion and awards the player\'s reward. If you change the end flow, keep it wired to **every** way the game can end (win, lose, out of time).',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
     '',
     'Do **not** add an Exit button — the host always provides its own.',
     '',
@@ -1224,7 +1225,8 @@ function generate3DGameAgents(name, type, orientation) {
     '## The MyVillage game contract — DO NOT BREAK',
     '',
     '- `MyVillageGame.ready()` — called after assets load in `src/main.js`. Leave it.',
-    '- `this.game.endGame({ won, score })` — call at your win/lose condition. It calls `MyVillageGame.complete(...)`, which is **required**: the host records the session and awards the player\'s reward.',
+    '- `this.game.endGame({ won, score })` — call at **every** win/lose condition. It calls `MyVillageGame.complete(...)`, which is **required**: it records a completion and awards the player\'s reward. An exploration game needs a real end (everything found, the exit reached) that calls it.',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
     '',
     'Do **not** add an Exit button — the host always provides its own. During `npm run dev` there is no host, so host calls just log to the console (expected).',
     '',
@@ -1290,6 +1292,7 @@ function generateUnityAgents(name, className, orientation) {
     '',
     '- The host drives your mission and runs `OnBegin()`. In the editor, `MockMissionHost` stands in and logs host calls to the Console.',
     '- **`CompleteMission(finalScore: n)`** — call when the player finishes. This is the native equivalent of the web games\' `MyVillageGame.complete()`; the host records the session and awards the player\'s reward. **Required to end the game properly.**',
+    '- Plays count automatically: the host times how long the mission is on screen and the platform counts a play after 30 seconds. Call `CompleteMission` on every way the mission can end so finished games are recorded too.',
     '- `FailMission(reason)` — the lose path. `Host.LogEvent("...")` — telemetry.',
     '- **Do not build an Exit button** — the host always shows its own and calls `OnEnd()` for cleanup when the player exits.',
     '',
@@ -1886,7 +1889,12 @@ consistent experience:
 - **Done / finished** — call \`MyVillageGame.complete({ score })\` when the game is
   over. The host records the session and awards the player this game's MVT reward
   (set by an admin when the game is published). The scaffold already calls this
-  from \`Game.endGame()\` in \`src/main.js\` — wire that to your real end condition.
+  from \`Game.endGame()\` in \`src/main.js\` — wire that to **every** way the game
+  can end (win, lose, out of time).
+- **Plays count automatically** — \`src/myvillage-game.js\` measures how long the
+  player is actively playing and the platform counts a play after 30 seconds of
+  it. You don't need to do anything for that. To pass along a running score, call
+  \`MyVillageGame.progress({ score })\` (optional; safe to call every frame).
 - **Exit any time** — the host (the muni mobile app or the web player) always
   shows an Exit control, so a player can leave at any moment. You don't build an
   exit button. You *may* trigger \`MyVillageGame.exit()\` yourself (e.g. a "Quit"