@mpgd/cli 0.36.2 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.36.2",
+  "version": "0.38.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -54,8 +54,8 @@
     "typia": "13.0.2",
     "undici": "^7.29.1",
     "vite": "8.1.3",
-    "@mpgd/catalog": "0.7.6",
-    "@mpgd/target-config": "0.17.0",
+    "@mpgd/catalog": "0.7.8",
+    "@mpgd/target-config": "0.18.0",
     "@mpgd/phaser-assets": "0.7.0"
   },
   "devDependencies": {
@@ -63,16 +63,17 @@
     "@types/semver": "^7.8.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.12.7",
-    "@mpgd/adapter-browser": "0.7.8",
-    "@mpgd/adapter-capacitor": "0.6.2",
-    "@mpgd/adapter-devvit": "0.9.14",
-    "@mpgd/adapter-verse8": "0.3.12",
-    "@mpgd/bridge": "0.10.0",
-    "@mpgd/analytics": "0.4.0",
-    "@mpgd/game-services": "0.17.2",
-    "@mpgd/i18n": "0.6.5",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/adapter-ait": "0.13.1",
+    "@mpgd/adapter-browser": "0.8.0",
+    "@mpgd/adapter-capacitor": "0.7.1",
+    "@mpgd/adapter-devvit": "0.9.16",
+    "@mpgd/adapter-verse8": "0.4.1",
+    "@mpgd/analytics": "0.4.2",
+    "@mpgd/game-runtime": "0.4.0",
+    "@mpgd/bridge": "0.11.0",
+    "@mpgd/game-services": "0.18.1",
+    "@mpgd/i18n": "0.6.7",
+    "@mpgd/platform": "0.16.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/agent/acceptance.md

@@ -63,3 +63,16 @@ locked orientation modes as soft prompts instead of unsafe WebView hard locks.
 Verify safe-area geometry is reserved exactly once: CSS-padded containers must
 not also subtract `safeArea.contentBounds`, while full-bleed game surfaces use
 the snapshot bounds for persistent controls.
+
+## Shared native presentation
+
+- Purchase, rewarded, and interstitial requests use the same game-owned scope.
+- Native closure resumes gameplay while backend verification can remain pending.
+- Timeouts preserve unknown occupancy and late native/recovery observers.
+- Scene shutdown removes its action view and keyboard handler; it never unmutes
+  a live ad or updates a replacement scene from an old Promise.
+- Background and settings ownership remain after another native lease closes.
+- Rewarded v2 is unavailable until a durable encrypted journal is supplied via
+  bootstrap monetization ports. A test memory store is not durable recovery.
+- Use the real adapter's SDK-driven conformance tests and a game-owned platform
+  test environment; generic unit tests do not certify live ad delivery.

package/templates/phaser-game/agent/brief.md

@@ -39,3 +39,12 @@ the game-owned PWA before package generation, then run package acceptance on
 Windows before Partner Center submission. WACK remains an optional recommended
 evidence source, not a universal prerequisite.
 <!-- mpgd:microsoft-store:end -->
+
+## Game-owned execution and advertising
+
+Construct one `createGamePlatformRuntime` during bootstrap. Scenes bind gameplay
+execution with `audioOwner: 'game'`; the Phaser game's sound manager owns audio
+projection. Add SDKs only in target assembly or adapters. All rewarded views use
+the game-owned action coordinator and authoritative services, with an
+application-owned durable encrypted operation store. Keep recovery above scenes
+and reconcile existing operations on startup and resume without opening SDK UI.

package/templates/phaser-game/agent/game-manifest.json

@@ -5,8 +5,20 @@
     "title": "__GAME_TITLE__",
     "engine": "phaser-4"
   },
-  "targets": ["web-preview", "microsoft-store", "verse8", "android", "ios", "ait", "reddit"],
-  "futureTargets": ["telegram", "tauri"],
+  "targets": [
+    "web-preview",
+    "microsoft-store",
+    "verse8",
+    "crazygames",
+    "android",
+    "ios",
+    "ait",
+    "reddit"
+  ],
+  "futureTargets": [
+    "telegram",
+    "tauri"
+  ],
   "platformBoundary": "PlatformGateway",
   "agentWorkflow": {
     "guide": "docs/MPGD_KIT_WORKFLOWS.md",
@@ -67,6 +79,22 @@
     {
       "id": "telemetry.analytics.best-effort",
       "owner": "src/main.ts"
+    },
+    {
+      "id": "runtime.game.owned-presentation",
+      "owner": "src/main.ts",
+      "capabilities": [
+        "game-owned-execution",
+        "shared-full-screen-presentation",
+        "late-claim-recovery",
+        "game-owned-audio"
+      ],
+      "gotchas": [
+        "Create one game runtime above scene lifetimes; scene teardown must not release native presentation or global audio.",
+        "Rewarded v2 requires an application-owned durable encrypted operation journal; never substitute an in-memory map.",
+        "SDK earning and physical closure are separate from an authoritative backend ledger grant.",
+        "Recover existing claims on startup and resume without reopening SDK UI."
+      ]
     }
   ],
   "acceptance": [

package/templates/phaser-game/docs/MPGD_KIT_WORKFLOWS.md

@@ -104,6 +104,22 @@ state behind target services. Treat client commerce as pending; authoritative
 grants belong in a game-owned Agent8 server purchase event with consume-once
 catalog handling and verified completion logic for leaderboards.
 
+### CrazyGames
+
+Use the browser adapter's `/crazygames` entry point and the non-installable
+`crazygames` web target. `crazyGamesLaunch: "basic"` disables monetization;
+change it to `"full"` only after Full Launch approval. Configured midgame
+interstitials use the shared advertising presentation contract. SDK callbacks
+must never grant rewards or purchases: those capabilities remain disabled.
+
+Playable scenes own gameplay scopes through the game runtime. Keep loading,
+gameplay, and host `muteAudio` policy behind `PlatformGateway`; the host handles
+focus reporting. Build and smoke with `pnpm exec mpgd target build crazygames`
+and `pnpm exec mpgd target smoke crazygames`, providing `--kit-path` and the
+project's `--targets-file`. See the kit's
+[CrazyGames guide](https://github.com/imjlk/mpgd-kit/blob/main/docs/CRAZYGAMES.md)
+and [official SDK documentation](https://docs.crazygames.com/sdk/intro/).
+
 ### Apps in Toss
 
 Use official Apps in Toss documentation/MCP before SDK or review-flow changes.

package/templates/phaser-game/mpgd.targets.json

@@ -22,6 +22,17 @@
       "icon": { "profile": "web-preview" },
       "output": "artifacts/verse8"
     },
+    "crazygames": {
+      "kind": "web",
+      "gameApp": ".",
+      "adapter": "crazygames",
+      "icon": {
+        "profile": "web-preview"
+      },
+      "installable": false,
+      "crazyGamesLaunch": "basic",
+      "output": "artifacts/crazygames"
+    },
     "android": {
       "kind": "capacitor-android",
       "gameApp": ".",

package/templates/phaser-game/package.json

@@ -72,7 +72,8 @@
     "@mpgd/platform": "__MPGD_DEPENDENCY_VERSION_PLATFORM__",
     "@mpgd/phaser-assets": "__MPGD_DEPENDENCY_VERSION_PHASER_ASSETS__",
     "@mpgd/target-config": "__MPGD_DEPENDENCY_VERSION_TARGET_CONFIG__",
-    "phaser": "4.2.0"
+    "phaser": "4.2.0",
+    "@mpgd/game-runtime": "__MPGD_DEPENDENCY_VERSION_GAME_RUNTIME__"
   },
   "devDependencies": {
     "@ait-co/console-cli": "^0.1.49",

package/templates/phaser-game/src/main.ts

@@ -1,9 +1,11 @@
+import { createGamePlatformRuntime, type GamePlatformRuntime } from '@mpgd/game-runtime/game';
 import './styles.css';
 
 import { createAnalyticsReporter, createBufferedAnalyticsSink } from '@mpgd/analytics';
 import { resolveTargetMpgdLocale, type Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlatformGateway } from '@mpgd/platform';
 import {
+  getEffectiveAdPlacementConfig,
   measureTargetViewport,
   resolveTargetViewportSnapshot,
   waitForTargetViewportMeasurement,
@@ -15,14 +17,15 @@ import { t } from './i18n/messages';
 import { createClientId } from './runtime/id';
 import { createStarterGame } from './runtime/createGame';
 import { detectRuntime } from './platform/runtimeDetector';
-import { createStarterGameServices } from './platform/gameServices';
+import { createStarterGameServices, type StarterMonetizationPorts } from './platform/gameServices';
 import { installPlatform } from './platform/installPlatform';
 import { installMicrosoftStorePwa } from './platform/microsoftStorePwa';
 
 await bootstrap();
 
 /** Install target services, analytics, and viewport state before starting the game. */
-async function bootstrap(): Promise<void> {
+async function bootstrap(options: { readonly monetization?: StarterMonetizationPorts } = {}): Promise<void> {
+  let gameRuntime: GamePlatformRuntime | undefined;
   let locale: Locale = 'en';
   let disposeMicrosoftStorePwa: (() => void) | undefined;
 
@@ -71,13 +74,43 @@ async function bootstrap(): Promise<void> {
       sessionId: analyticsSessionId,
       sink: analyticsSink,
     });
-    const gameServices = createStarterGameServices({
+    const ownedRuntime = createGamePlatformRuntime({
       gateway: platform,
-      playerId: identitySession.playerId ?? player.playerId,
-      configTarget: runtime.configTarget,
-      analytics: analyticsSink,
-      analyticsSessionId,
+      initialLifecycleState: document.visibilityState === 'hidden' ? 'inactive' : 'active',
+      canShow: (placement) => {
+        const enabled = placement.format === 'rewarded'
+          ? runtime.config.features.rewardedAds
+          : runtime.config.features.interstitialAds;
+        const configured = runtime.effectiveConfig === undefined
+          ? undefined
+          : getEffectiveAdPlacementConfig(runtime.effectiveConfig, placement.placementId);
+        return enabled && (runtime.effectiveConfig === undefined || configured !== undefined && configured.reason !== 'target-disabled');
+      },
+      deadline: {
+        milliseconds: 30000,
+        schedule(callback, milliseconds) {
+          const timer = setTimeout(callback, milliseconds);
+          return () => clearTimeout(timer);
+        },
+      },
+      ...(options.monetization?.reconciliation === undefined ? {} : { reconciliation: options.monetization.reconciliation }),
+      ...(options.monetization?.purchasePresentation === undefined ? {} : { purchasePresentation: options.monetization.purchasePresentation }),
+      onObserverError: (error) => {
+        console.error('[game-runtime]', error);
+      },
+      createServices: (gateway) =>
+        createStarterGameServices({
+          gateway,
+          playerId: identitySession.playerId ?? player.playerId,
+          configTarget: runtime.configTarget,
+          ...(options.monetization === undefined ? {} : { operationStore: options.monetization.operationStore }),
+          analytics: analyticsSink,
+          analyticsSessionId,
+        }),
     });
+    gameRuntime = ownedRuntime;
+    const gameServices = ownedRuntime.services;
+    await ownedRuntime.reconcile();
 
     await analytics.track({
       name: 'game_started',
@@ -92,7 +125,8 @@ async function bootstrap(): Promise<void> {
       preserveBrowserTouchGestures:
         document.body.dataset.mpgdPreserveBrowserTouchGestures === 'true',
       context: {
-        platform,
+        platform: ownedRuntime.gateway,
+        gameRuntime: ownedRuntime,
         runtime,
         viewport,
         player,
@@ -105,6 +139,7 @@ async function bootstrap(): Promise<void> {
       },
     });
   } catch (error) {
+    gameRuntime?.dispose();
     disposeMicrosoftStorePwa?.();
     renderBootstrapError(error, locale);
     console.error('[bootstrap]', error);

package/templates/phaser-game/src/platform/buildGateways/crazygames.ts

@@ -0,0 +1,14 @@
+import { createCrazyGamesPlatformGateway } from '@mpgd/adapter-browser/crazygames';
+import { resolveAdPlacementPlatformId, type AdPlacements } from '@mpgd/catalog';
+import adPlacementsJson from '@mpgd/catalog/placements.json';
+import type { PlatformGateway } from '@mpgd/platform';
+import type { RuntimeConfig } from '../runtimeDetector';
+
+export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
+  const placements = (adPlacementsJson as AdPlacements).placements;
+  return createCrazyGamesPlatformGateway({
+    launch: __MPGD_PLATFORM_TARGET__?.crazyGamesLaunch ?? 'basic',
+    placementIds: placements.filter((placement) => placement.type === 'interstitial'
+      && resolveAdPlacementPlatformId(placement, runtime.configTarget) !== undefined).map((placement) => placement.id),
+  });
+}

package/templates/phaser-game/src/platform/gameServices.ts

@@ -5,8 +5,18 @@ import {
   resolveGameServicesTransport,
   type GameServicesRuntime,
   type GameServicesRuntimeMode,
+  type MonetizationOperationStore,
 } from '@mpgd/game-services';
 import type { PlatformGateway } from '@mpgd/platform';
+import type { GameActionReconciliationPort } from '@mpgd/game-runtime/actions';
+import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
+
+/** Supply a game-owned durable encrypted journal and trusted recovery/native facts. */
+export interface StarterMonetizationPorts {
+  readonly operationStore: MonetizationOperationStore;
+  readonly reconciliation?: GameActionReconciliationPort;
+  readonly purchasePresentation?: { subscribe(listener: (event: PurchasePresentationEvent) => void): () => void };
+}
 
 export type StarterBackendMode = GameServicesRuntimeMode;
 export type StarterGameServices = GameServicesRuntime;
@@ -15,12 +25,14 @@ export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
   readonly configTarget: string;
+  readonly operationStore?: MonetizationOperationStore;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
+    ...(input.operationStore === undefined ? {} : { operationStore: input.operationStore }),
     ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
     ...(input.analyticsSessionId === undefined
       ? {}

package/templates/phaser-game/src/platform/runtimeDetector.ts

@@ -7,6 +7,7 @@ const validTargets = new Set<string>([
   'microsoft-store',
   'reddit',
   'verse8',
+  'crazygames',
   'telegram',
   'tauri',
   'wechat',

package/templates/phaser-game/src/runtime/createGame.ts

@@ -1,3 +1,4 @@
+import { bindGameAudio } from '@mpgd/game-runtime/audio';
 import Phaser from 'phaser';
 
 import { BootScene } from '../scenes/BootScene';
@@ -26,9 +27,35 @@ export function createStarterGame(input: {
       autoCenter: Phaser.Scale.CENTER_BOTH,
     },
     scene: [BootScene, LobbyScene, PlayScene],
+    callbacks: {
+      postBoot(game: Phaser.Game) {
+        game.registry.set(starterContextKey, input.context);
+        ownGameAudio(game, input.context);
+      },
+    },
   });
 
   game.registry.set(starterContextKey, input.context);
 
   return game;
 }
+
+/** The sound manager and execution projection belong to the game, not a scene. */
+function ownGameAudio(game: Phaser.Game, context: StarterContext): void {
+  const audio = bindGameAudio({
+    execution: context.gameRuntime.execution,
+    sink: {
+      getMuted: () => game.sound.mute,
+      setMuted: (muted) => {
+        game.sound.mute = muted;
+      },
+    },
+    onError: (error) => {
+      console.error('[game-audio]', error);
+    },
+  });
+  game.events.once('destroy', () => {
+    context.gameRuntime.dispose();
+    audio.dispose();
+  });
+}

package/templates/phaser-game/src/runtime/gameContext.ts

@@ -1,4 +1,5 @@
 import type { AnalyticsReporter, BufferedAnalyticsSink } from '@mpgd/analytics';
+import type { GamePlatformRuntime } from '@mpgd/game-runtime/game';
 import type { Locale } from '@mpgd/i18n';
 import type { IdentitySession, LaunchIntent, PlayerIdentity } from '@mpgd/platform';
 import type {
@@ -12,6 +13,7 @@ import type { StarterGameServices } from '../platform/gameServices';
 export const starterContextKey = 'starterContext';
 
 export interface StarterContext {
+  readonly gameRuntime: GamePlatformRuntime<TargetConfiguredGateway, StarterGameServices>;
   readonly platform: TargetConfiguredGateway;
   readonly runtime: TargetRuntimeSnapshot;
   readonly viewport: TargetViewportSnapshot;

package/templates/phaser-game/src/scenes/BootScene.ts

@@ -2,6 +2,8 @@ import Phaser from 'phaser';
 
 import { loadPhaserAssets } from '@mpgd/phaser-assets';
 
+import { starterContextKey, type StarterContext } from '../runtime/gameContext';
+
 import { starterAssets } from '../assets/manifest';
 
 export class BootScene extends Phaser.Scene {
@@ -14,6 +16,7 @@ export class BootScene extends Phaser.Scene {
   }
 
   create(): void {
-    this.scene.start('LobbyScene');
+    const context = this.registry.get(starterContextKey) as StarterContext;
+    this.scene.start(context.launchIntent.entry === 'free-play' ? 'PlayScene' : 'LobbyScene');
   }
 }

package/templates/phaser-game/src/scenes/PlayScene.ts

@@ -1,3 +1,5 @@
+import type { GameActionController } from '@mpgd/game-runtime/actions';
+import { bindPhaserGameScene } from '@mpgd/game-runtime/phaser';
 import Phaser from 'phaser';
 
 import type { LogicalAdPlacementId } from '@mpgd/platform';
@@ -17,6 +19,7 @@ export class PlayScene extends Phaser.Scene {
   private rewardText!: Phaser.GameObjects.Text;
   private analyticsText!: Phaser.GameObjects.Text;
   private context!: StarterContext;
+  private rewardedAction: GameActionController<'rewarded-ad'> | undefined;
   private lastScore = -1;
   private lastAnalyticsCount = -1;
 
@@ -26,6 +29,19 @@ export class PlayScene extends Phaser.Scene {
 
   create(): void {
     this.context = this.registry.get(starterContextKey) as StarterContext;
+    bindPhaserGameScene({
+      controller: this.context.gameRuntime.execution,
+      gameplayScope: this.context.gameRuntime.createGameplayScope(),
+      scene: this,
+      renderingPolicy: 'visibility',
+      audioOwner: 'game',
+      resetInput: () => {
+        this.input.keyboard?.resetKeys();
+      },
+      onUnsupportedState: (_snapshot, reason) => {
+        console.error('[game-execution]', reason);
+      },
+    });
 
     this.marker = this.add.image(480, 250, starterAssetKeys.marker).setDisplaySize(72, 72);
     this.scoreText = this.add
@@ -50,8 +66,16 @@ export class PlayScene extends Phaser.Scene {
       })
       .setOrigin(0.5);
 
-    this.input.keyboard?.on('keydown-R', () => {
+    this.rewardedAction = this.context.gameRuntime.actions?.createRewardedAdController();
+    const action = this.rewardedAction;
+    const keyboard = this.input.keyboard;
+    const onReward = () => {
       void this.requestRewardedAd();
+    };
+    keyboard?.on('keydown-R', onReward);
+    this.events.once('shutdown', () => {
+      action?.dispose();
+      keyboard?.off('keydown-R', onReward);
     });
   }
 
@@ -77,7 +101,7 @@ export class PlayScene extends Phaser.Scene {
   private rewardHint(): string {
     const rewardedAds = this.context.runtime.features.rewardedAds;
 
-    if (!rewardedAds.enabled || this.context.gameServices.client === undefined) {
+    if (!rewardedAds.enabled || this.context.gameServices.client === undefined || this.context.gameServices.monetizationRecovery === undefined) {
       return t(this.context.locale, 'rewardUnavailable');
     }
 
@@ -86,19 +110,25 @@ export class PlayScene extends Phaser.Scene {
 
   private async requestRewardedAd(): Promise<void> {
     const rewardedAds = this.context.runtime.features.rewardedAds;
-    const gameServicesClient = this.context.gameServices.client;
+    const action = this.rewardedAction;
 
-    if (!rewardedAds.enabled || gameServicesClient === undefined) {
+    if (!rewardedAds.enabled || action === undefined || this.context.gameServices.monetizationRecovery === undefined) {
       this.rewardText.setText(t(this.context.locale, 'rewardUnavailable'));
       return;
     }
 
+    if (this.context.gameRuntime.actions?.getAvailability() !== 'ready') {
+      return;
+    }
     try {
-      const result = await gameServicesClient.claimRewardedAd({
+      const result = await action.execute({
         placementId: rewardedPlacementId,
         idempotencyKey: createClientId('starter-reward'),
       });
 
+      if (action.isDisposed() || this.rewardedAction !== action) {
+        return;
+      }
       this.rewardText.setText(
         result.claim?.granted === true
           ? t(this.context.locale, 'reward', { status: result.status })
@@ -112,7 +142,9 @@ export class PlayScene extends Phaser.Scene {
           granted: false,
         },
       });
-      this.rewardText.setText(t(this.context.locale, 'rewardError'));
+      if (!action.isDisposed() && this.rewardedAction === action) {
+        this.rewardText.setText(t(this.context.locale, 'rewardError'));
+      }
       console.error('[rewarded-ad]', error);
     }
   }

package/templates/phaser-game/vite.runtime-target-config.ts

@@ -20,6 +20,7 @@ const runtimeKinds = valueSet({
   'apps-in-toss': true,
   'devvit-web': true,
   'verse8-web': true,
+  'crazygames-web': true,
   'wechat-minigame': true,
   'tiktok-minigame': true,
 } satisfies Record<TargetRuntimeKind, true>);
@@ -32,6 +33,7 @@ const releaseProfiles = valueSet({
   'apps-in-toss': true,
   devvit: true,
   verse8: true,
+  crazygames: true,
   'wechat-minigame': true,
   'tiktok-minigame': true,
 } satisfies Record<ReleaseProfile, true>);

package/templates/phaser-game/vite.shared.ts

@@ -14,6 +14,7 @@ import { resolveTextSelectionMode } from './src/platform/textSelection';
 interface RuntimePlatformTargetMetadata {
   readonly kind: string;
   readonly adapter: string;
+  readonly crazyGamesLaunch?: 'basic' | 'full';
   readonly authoritativeGameServices?: boolean;
   readonly integrations?: Record<string, unknown>;
 }
@@ -151,6 +152,8 @@ export function resolveBuildGatewayModule(input: {
       return input.debug && input.buildId === devvitSandboxBuildId
         ? 'src/platform/buildGateways/redditSandbox.ts'
         : 'src/platform/buildGateways/reddit.ts';
+    case 'crazygames':
+      return 'src/platform/buildGateways/crazygames.ts';
     case 'verse8':
       return 'src/platform/buildGateways/verse8.ts';
     case 'microsoft-store':
@@ -245,6 +248,9 @@ function readRuntimePlatformTarget(
     throw new Error(`Platform target ${configTarget} must define kind and adapter.`);
   }
 
+  if (target.crazyGamesLaunch !== undefined && (target.adapter !== 'crazygames' || !['basic', 'full'].includes(target.crazyGamesLaunch as string))) {
+    throw new Error(`Invalid CrazyGames launch setting for ${configTarget}.`);
+  }
   if (target.integrations !== undefined && !isRecord(target.integrations)) {
     throw new Error(`Platform target ${configTarget} integrations must be an object.`);
   }
@@ -262,6 +268,7 @@ function readRuntimePlatformTarget(
     ...(target.authoritativeGameServices === undefined
       ? {}
       : { authoritativeGameServices: target.authoritativeGameServices }),
+    ...(target.crazyGamesLaunch === undefined ? {} : { crazyGamesLaunch: target.crazyGamesLaunch as 'basic' | 'full' }),
     ...(target.integrations === undefined ? {} : { integrations: target.integrations }),
   };
 }