@mpgd/cli 0.52.0 → 0.54.0

package/templates/notifications-overlay/phaser/src/scenes/NotificationSettingsScene.ts

@@ -0,0 +1,301 @@
+import Phaser from 'phaser';
+
+import {
+  starterNotificationLabelsFor,
+  type StarterNotificationLabels,
+  type StarterNotificationSettings,
+  type StarterNotificationSettingsView,
+} from '../platform/notificationSettings';
+import {
+  createStarterNotificationSettingsModel,
+  subscribeStarterNotificationOpens,
+} from '../platform/notifications';
+import { starterContextKey, type StarterContext } from '../runtime/gameContext';
+
+export const notificationSettingsSceneKey = 'NotificationSettingsScene';
+
+const textStyle = { color: '#d6dee8', fontFamily: 'Arial, sans-serif', fontSize: '18px' } as const;
+const buttonStyle = { ...textStyle, color: '#5eead4' } as const;
+/** List rows and the outcome strip share this column (x=60..900) on the 960x540 game. */
+const listTextWidth = 840;
+/** Below the title. The outcome strip grows downward from here. */
+const outcomeTop = 68;
+/** The list ends above the Back button. */
+const listBottom = 480;
+const minListTop = 110;
+
+/**
+ * Routes notification opens: one whose route is the settings screen (the
+ * advertising opt-out action, a consent notice) shows the screen, after boot
+ * when the open started the game. Route your other topics' opens in `other`
+ * (see `subscribeStarterNotificationOpens`): this is the first subscriber,
+ * the one that receives a cold-start open. An open during play leaves the
+ * run; the play scene saves its checkpoint when it shuts down.
+ */
+export function routeNotificationSettingsOpens(game: Phaser.Game, context: StarterContext): void {
+  const activeKeys = (): string[] => game.scene.getScenes(true).map((scene) => scene.scene.key);
+  const show = (): void => {
+    for (const key of activeKeys()) {
+      if (key !== notificationSettingsSceneKey) {
+        game.scene.stop(key);
+      }
+    }
+    game.scene.start(notificationSettingsSceneKey);
+  };
+  let waiting = false;
+  const afterBoot = (): void => {
+    const active = activeKeys();
+    if (active.length === 0 || active.includes('BootScene')) {
+      return;
+    }
+    game.events.off('poststep', afterBoot);
+    waiting = false;
+    show();
+  };
+  const unsubscribe = subscribeStarterNotificationOpens(context.platform, {
+    settings: () => {
+      const active = activeKeys();
+      if (active.length > 0 && !active.includes('BootScene')) {
+        show();
+      } else if (!waiting) {
+        // Booting: show the screen once the first scene after boot runs.
+        waiting = true;
+        game.events.on('poststep', afterBoot);
+      }
+    },
+  });
+  game.events.once('destroy', () => {
+    unsubscribe();
+    game.events.off('poststep', afterBoot);
+  });
+}
+
+/**
+ * The game-rendered notification settings: the OS or host permission,
+ * reminder topics, and the advertising consent the Korean rules require
+ * before any advertising push (`notificationSettings.ts` holds the
+ * logic). Night consent covers advertising that arrives between 21:00 and
+ * 08:00 KST. Every change is a tap; no switch starts on. The list has a camera
+ * of its own, which clips it under WebGL and Canvas alike and keeps hidden
+ * rows from taking taps; it scrolls by dragging.
+ */
+export class NotificationSettingsScene extends Phaser.Scene {
+  private settings!: StarterNotificationSettings;
+  private labels!: StarterNotificationLabels;
+  private content!: Phaser.GameObjects.Container;
+  private listCamera!: Phaser.Cameras.Scene2D.Camera;
+  /** The last tap's outcome, in a strip that does not scroll. */
+  private outcome!: Phaser.GameObjects.Text;
+  private busy = false;
+  /** Each visit's token: a pending action from an earlier visit changes nothing. */
+  private visit = 0;
+
+  constructor() {
+    super(notificationSettingsSceneKey);
+  }
+
+  create(): void {
+    const rawContext = this.registry.get(starterContextKey);
+    if (rawContext === undefined || rawContext === null) {
+      throw new Error('Starter context is missing from Phaser registry.');
+    }
+    const context = rawContext as StarterContext;
+    this.visit += 1;
+    this.busy = false;
+    this.labels = starterNotificationLabelsFor(context.locale);
+    this.settings = createStarterNotificationSettingsModel(context.platform, {
+      locale: context.locale,
+    });
+    const title = this.add
+      .text(480, 40, this.labels.title, { ...textStyle, color: '#ffffff', fontSize: '30px' })
+      .setOrigin(0.5);
+    const back = this.button(480, 510, this.labels.back, () => {
+      this.scene.start('LobbyScene');
+    }).setOrigin(0.5);
+    this.outcome = this.add
+      .text(480, outcomeTop, '', {
+        ...textStyle,
+        align: 'center',
+        color: '#f59e0b',
+        fontSize: '16px',
+        wordWrap: { width: listTextWidth },
+      })
+      .setOrigin(0.5, 0);
+    this.content = this.add.container(0, 0);
+    this.listCamera = this.cameras.add(0, minListTop, 960, listBottom - minListTop);
+    this.placeListBelowOutcome();
+    this.listCamera.ignore([title, back, this.outcome]);
+    this.cameras.main.ignore(this.content);
+    this.enableScroll();
+    const visit = this.visit;
+    void this.apply(visit, () => this.settings.load());
+  }
+
+  private enableScroll(): void {
+    let lastY: number | undefined;
+    this.input.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
+      lastY = pointer.y;
+    });
+    this.input.on('pointerup', () => {
+      lastY = undefined;
+    });
+    this.input.on('pointermove', (pointer: Phaser.Input.Pointer) => {
+      if (lastY === undefined || !pointer.isDown) {
+        return;
+      }
+      this.scrollTo(this.listCamera.scrollY - (pointer.y - lastY));
+      lastY = pointer.y;
+    });
+  }
+
+  private placeListBelowOutcome(): void {
+    const top = Math.max(minListTop, Math.ceil(this.outcome.y + this.outcome.height) + 8);
+    this.listCamera.setPosition(0, top);
+    this.listCamera.setSize(960, Math.max(0, listBottom - top));
+  }
+
+  private scrollTo(scrollY: number): void {
+    const height = this.content.getBounds().height;
+    this.listCamera.scrollY = Phaser.Math.Clamp(scrollY, 0, Math.max(0, height - this.listCamera.height));
+  }
+
+  private async apply(visit: number, action: () => Promise<StarterNotificationSettingsView>): Promise<void> {
+    if (this.busy) {
+      return;
+    }
+    this.busy = true;
+    try {
+      const view = await action();
+      if (visit !== this.visit || !this.sys.isActive()) {
+        return;
+      }
+      this.render(view);
+      if (view.notices.length > 0) {
+        // Recorded in the background: taps need not wait for it.
+        void this.settings.recordNoticesShown();
+      }
+    } catch (error) {
+      // The model reports its own failures as messages; anything else is logged.
+      console.error('[notifications] settings screen failed.', error);
+    } finally {
+      if (visit === this.visit) {
+        this.busy = false;
+      }
+    }
+  }
+
+  private render(view: StarterNotificationSettingsView): void {
+    const text = this.labels;
+    this.content.removeAll(true);
+    const visit = this.visit;
+    let y = 0;
+    const line = (value: string, style: Phaser.Types.GameObjects.Text.TextStyle = textStyle) => {
+      const object = this.add.text(60, y, value, { ...style, wordWrap: { width: listTextWidth } });
+      this.content.add(object);
+      y += object.height + 10;
+    };
+    const action = (value: string, run: () => Promise<StarterNotificationSettingsView>) => {
+      const object = this.button(60, y, `[ ${value} ]`, () => {
+        void this.apply(visit, run);
+      });
+      this.content.add(object);
+      y += object.height + 8;
+    };
+
+    // The outcome of the last tap stays in view above the list, wherever it is scrolled.
+    this.outcome.setText(view.message ?? '');
+    this.placeListBelowOutcome();
+    if (!view.available) {
+      if (view.message === undefined) {
+        line(text.unavailable);
+      }
+      this.scrollTo(0);
+      return;
+    }
+    if (!view.permission.perTopic) {
+      line(view.permission.state === 'granted' ? text.permissionOn : text.permissionOff);
+      if (view.permission.canRequest) {
+        // Explain before the one-shot OS prompt; the prompt runs only from the tap below.
+        line(text.explanation, { ...textStyle, fontSize: '15px' });
+        action(text.turnOn, () => this.settings.turnOn());
+      }
+      if (view.permission.canLogin) {
+        action(text.logIn, () => this.settings.logIn());
+      }
+      if (view.permission.canOpenSettings) {
+        action(text.openSettings, () => this.settings.openSettings());
+      }
+      if (view.permission.canRevoke) {
+        action(text.turnOff, () => this.settings.turnOff());
+      }
+    }
+    if (!view.recording && (view.reminders.length > 0 || view.advertising !== undefined)) {
+      // No switch without the player's records: it could not show or change the truth.
+      line(view.choices === 'unreadable' ? text.choicesUnreadable : text.notConnected, {
+        ...textStyle,
+        fontSize: '15px',
+      });
+    } else if (view.reminders.length > 0) {
+      line(text.reminders, { ...textStyle, color: '#ffffff' });
+      for (const reminder of view.reminders) {
+        action(`${reminder.label}: ${reminder.enabled ? text.on : text.off}`, () =>
+          this.settings.setReminder(reminder.topic, !reminder.enabled),
+        );
+      }
+    }
+    if (view.agreements.length > 0) {
+      // Per-topic hosts (Apps in Toss): service messages the player agrees to
+      // one by one; the host's settings withdraw them.
+      line(text.agreements, { ...textStyle, color: '#ffffff' });
+      for (const agreement of view.agreements) {
+        const state = agreement.state === 'granted' ? text.on : text.off;
+        if (agreement.canRequest) {
+          action(`${agreement.label}: ${state} - ${text.agree}`, () =>
+            this.settings.agree(agreement.topic),
+          );
+        } else {
+          line(`${agreement.label}: ${state}`);
+        }
+      }
+    }
+    if (view.recording && view.advertising !== undefined) {
+      const { granted, night, nightSelectable } = view.advertising;
+      action(`${text.advertising}: ${granted ? text.on : text.off}`, () =>
+        this.settings.setAdvertising({ advertising: !granted }),
+      );
+      line(text.advertisingHelp, { ...textStyle, fontSize: '15px' });
+      if (nightSelectable) {
+        action(`${text.night}: ${night ? text.on : text.off}`, () =>
+          this.settings.setAdvertising({ night: !night }),
+        );
+      } else {
+        // Night consent adds to advertising consent: not selectable without it.
+        line(`${text.night}: ${text.off}\n${text.nightNeedsAdvertising}`, {
+          ...textStyle,
+          color: '#7b8794',
+        });
+      }
+    }
+    if (view.notices.length > 0) {
+      line(text.notices, { ...textStyle, color: '#ffffff' });
+      for (const notice of view.notices) {
+        line(`${notice.title}\n${notice.body}`, { ...textStyle, fontSize: '15px' });
+      }
+    }
+    // Keep the scroll position across a re-render, within the new height.
+    this.scrollTo(this.listCamera.scrollY);
+  }
+
+  private button(x: number, y: number, value: string, onTap: () => void): Phaser.GameObjects.Text {
+    return this.add
+      .text(x, y, value, buttonStyle)
+      .setPadding(0, 8, 24, 8)
+      .setInteractive({ useHandCursor: true })
+      // A drag that scrolls the list and ends on a button is not a tap.
+      .on('pointerup', (pointer: Phaser.Input.Pointer) => {
+        if (pointer.getDistance() < 12) {
+          onTap();
+        }
+      });
+  }
+}

package/templates/phaser-game/apps/target-ait/src/main.ts

@@ -12,6 +12,7 @@ installAitHostBridge({
   adGroupIds: runtimeConfig.adGroupIds,
   adPlacementTypes: runtimeConfig.adPlacementTypes,
   ...iapBridgeOptions(),
+  ...notificationBridgeOptions(),
   ...identityBridgeOptions(),
 });
 
@@ -38,6 +39,20 @@ function iapBridgeOptions(): Pick<
   return runtimeConfig.iapProducts.length === 0 ? {} : { iapProducts: runtimeConfig.iapProducts };
 }
 
+/**
+ * Notifications v2 topics come from the notification topic catalog's
+ * `targets.ait` mappings at build time. Without one the host bridge offers no
+ * notifications event channel, so the game exposes no `notificationsV2`; with
+ * them the bridge asks for each topic's agreement through
+ * `Notification.requestAgreement` and routes notification landings. Agreements
+ * are recorded by the game backend, never trusted from the wrapper.
+ */
+function notificationBridgeOptions(): Pick<InstallAitHostBridgeOptions, 'notificationTopics'> {
+  return Object.keys(runtimeConfig.notificationTopics).length === 0
+    ? {}
+    : { notificationTopics: runtimeConfig.notificationTopics };
+}
+
 function identityBridgeOptions(): Pick<InstallAitHostBridgeOptions, 'dependencies'> {
   return import.meta.env.VITE_MPGD_AIT_MOCK_IDENTITY === '1'
     ? {

package/templates/phaser-game/apps/target-ait/src/runtime-config.types.ts

@@ -8,6 +8,11 @@ declare module 'virtual:mpgd-ait-runtime-config' {
     >>;
     /** Catalog products sold on Apps in Toss (`platformProductIds.ait`), read at build time. */
     readonly iapProducts: readonly import('@mpgd/adapter-ait').AitIapProductConfig[];
+    /** Notifications v2 topics mapped for Apps in Toss (`targets.ait`), read at build time. */
+    readonly notificationTopics: Readonly<Record<
+      string,
+      import('@mpgd/adapter-ait/notification-config').AitNotificationTopicMapping
+    >>;
   }>;
 
   export default runtimeConfig;

package/templates/phaser-game/apps/target-ait/vite.config.ts

@@ -1,14 +1,33 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import type { AitIapProductConfig } from '@mpgd/adapter-ait';
 import { extractAitAdBridgeConfig, type AitAdBridgeConfig } from '@mpgd/adapter-ait/ad-config';
 import { extractAitIapProductConfig } from '@mpgd/adapter-ait/iap-config';
+import {
+  readAitNotificationTopicsFile,
+  type AitNotificationTopicMapping,
+} from '@mpgd/adapter-ait/notification-config';
 import ttsc from '@ttsc/unplugin/vite';
 import { defineConfig, type Plugin } from 'vite';
 
 const aitAppName = process.env.MPGD_AIT_APP_NAME?.trim() || '__GAME_NAME__';
 const aitAdConfig = readAitAdConfig(process.env.MPGD_AD_PLACEMENTS_FILE);
 const aitIapProducts = readAitIapProducts(process.env.MPGD_PRODUCT_CATALOG_FILE);
+// Notifications v2 topics come from the notification topic catalog
+// (`targets.ait`), so the wrapper and the backend share one source:
+// MPGD_NOTIFICATION_TOPICS_FILE (a relative path names a file of the game),
+// else notifications/topics.json when it exists. Without a catalog, or with
+// no topic mapped for Apps in Toss, the host bridge exposes no notifications.
+const aitNotificationTopics = readAitNotificationTopicsFile(
+  {
+    configured: process.env.MPGD_NOTIFICATION_TOPICS_FILE,
+    rootDir: fileURLToPath(new URL('../..', import.meta.url)),
+    defaultFile: 'notifications/topics.json',
+  },
+  { existsSync, readFileSync, resolve },
+);
 
 export default defineConfig(({ command, isPreview }) => {
   const enableLocalAitMock = command === 'serve'
@@ -33,6 +52,7 @@ export default defineConfig(({ command, isPreview }) => {
         adGroupIds: aitAdConfig.adGroupIds,
         adPlacementTypes: aitAdConfig.adPlacementTypes,
         iapProducts: aitIapProducts,
+        notificationTopics: aitNotificationTopics,
       }),
       ...(command === 'build'
         ? [ttsc({ project: 'tsconfig.json', plugins: false })]
@@ -51,6 +71,7 @@ function createAitRuntimeConfigPlugin(input: Readonly<{
   readonly adGroupIds: Readonly<Record<string, string>>;
   readonly adPlacementTypes: AitAdBridgeConfig['adPlacementTypes'];
   readonly iapProducts: readonly AitIapProductConfig[];
+  readonly notificationTopics: Readonly<Record<string, AitNotificationTopicMapping>>;
 }>): Plugin {
   const publicId = 'virtual:mpgd-ait-runtime-config';
   const resolvedId = `\0${publicId}`;

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

@@ -165,3 +165,17 @@ game-owned production credentials, deployment, signing, or store evidence.
 Use `@mpgd/adapter-browser/oneplay` through `PlatformGateway`. Build and smoke the `oneplay` target with the configured kit path. The adapter initializes the H5 SDK before gameplay; `completeLoading()` awaits host acknowledgement. Exit checkpoints must be synchronous through `storage.saveSync`. Use game-owned issued placement IDs and server verification before enabling ads or purchases. Check final HTTPS hosting headers for both ONE store domain families. See the [ONE play guide](https://github.com/imjlk/mpgd-kit/blob/main/docs/ONEPLAY.md) and [official SDK guide](https://onestore-dev.gitbook.io/dev/tools/web-sdk).
 
 Wire `rewardRequests` and `commerceServer` in `src/platform/buildGateways/oneplay.ts`. Server-only `@mpgd/game-services/oneplay-reward`, `oneplay-purchase-client`, `oneplay-purchase` and `oneplay-pns` provide signed SSV, authenticated checkout intents, API V7 verification, post-ledger consume/acknowledge and signed notification recovery. The game owns durable stores, routes, an encrypted client journal and atomic cancellation fencing. A completed PNS requires completed finalization. Missing ports keep capabilities unavailable; subscriptions are unsupported. See `commerce.checkout.verified-intent` in the game manifest and the ONE play acceptance notes before enabling policies.
+
+## ONEplay official SDK skill
+
+From this game's repository root, install or explicitly refresh the official instructions:
+
+```sh
+npx skills add ONE-store/onestore_web_sdk_skills --agent codex --yes
+```
+
+Review the resulting `.agents/skills/onestore-web-sdk` and `skills-lock.json` diff before committing.
+Use the skill's doctor and pre-release checklist alongside Kit's `docs/ONEPLAY.md`.
+Keep SDK imports in composition, game-services credentials on the server, and rewards behind
+purchase verification / signed SSV. The official standalone HTML template is reference material,
+not a replacement for the generated gateway. Do not refresh skills inside production builds.

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

@@ -15,6 +15,7 @@ import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
 import { resolveStarterCommerceProducts } from './commerceProducts';
 import { createStorageMonetizationOperationStore } from './monetizationJournal';
+import { resolveStarterServerSession } from './serverSession';
 
 const productCatalog = productCatalogJson as ProductCatalog;
 
@@ -47,6 +48,7 @@ export function createStarterGameServices(input: {
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
+  const session = resolveStarterServerSession({ once: true });
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
@@ -64,5 +66,6 @@ export function createStarterGameServices(input: {
       ? {}
       : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),
     transport: resolveGameServicesTransport(import.meta.env.VITE_MPGD_GAME_SERVICES_TRANSPORT),
+    ...(session === undefined ? {} : { getHeaders: () => session.getHeaders() }),
   });
 }

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

@@ -0,0 +1,66 @@
+import type { GameServicesHeaderResolver } from '@mpgd/game-services';
+
+/**
+ * The game's server-backed session: who is signed in to the game backend,
+ * and the `Authorization` header for that session. The starter has none, so
+ * `resolveStarterServerSession` returns `undefined`. Set yours with
+ * `setStarterServerSession`, over your own session holder and identity
+ * service. The commerce client then sends its header. In a game created with
+ * `--providers notifications`, the notifications runtime uses the same
+ * session and header for the game-services Worker's notification routes.
+ *
+ * `sessionId` must be the stable session-family id: the `sessionId` your
+ * identity service answers to the Worker's `authenticateNotificationSession`
+ * for this session's header, the same across token refreshes. Do not pass a
+ * per-token or rotating id: a `GuestSessionCoordinator` view's `sessionId`
+ * may rotate on refresh, so it is not that id.
+ */
+export interface StarterServerSession {
+  /**
+   * The signed-in player and session, or `undefined` while signed out.
+   * `sessionId` is the stable session-family id (see above).
+   */
+  current(): { readonly playerId: string; readonly sessionId: string } | undefined;
+  /** Calls `listener` when a session becomes current (sign-in, restore, account switch); returns the unsubscribe. */
+  onAuthenticated(
+    listener: (session: { readonly playerId: string; readonly sessionId: string }) => void,
+  ): () => void;
+  /** The current session's request headers, such as `{ authorization: 'Bearer …' }`. */
+  readonly getHeaders: GameServicesHeaderResolver;
+}
+
+let serverSession: StarterServerSession | undefined;
+/** Whether the commerce client read the session already: it reads it once. */
+let readOnce = false;
+
+/**
+ * The game's server-backed session; `undefined` until the game sets one with
+ * `setStarterServerSession`. `once` marks a reader that keeps what it reads
+ * (the commerce client), so a later change warns.
+ */
+export function resolveStarterServerSession(
+  options: { readonly once?: boolean } = {},
+): StarterServerSession | undefined {
+  if (options.once === true) {
+    readOnce = true;
+  }
+  return serverSession;
+}
+
+/**
+ * Sets the game's server-backed session. Call it at the top of `main.ts`,
+ * before `bootstrap()`: `createStarterGameServices` reads it once, and the
+ * notification settings and opens read it until a backend exists. Its
+ * `current()` may answer `undefined` until the player signs in. A session
+ * set after the commerce client was created does not reach that client,
+ * which this warns about.
+ */
+export function setStarterServerSession(session: StarterServerSession | undefined): void {
+  if (readOnce && session !== undefined && session !== serverSession) {
+    console.warn(
+      '[game-services] setStarterServerSession ran after the commerce client was created; '
+        + "it does not send this session's header. Call it before bootstrap().",
+    );
+  }
+  serverSession = session;
+}