@mpgd/cli 0.20.0 → 0.20.1

package/dist/build-targets.d.ts

@@ -0,0 +1,4 @@
+export type ConfiguredBuildTargets = Readonly<Record<string, unknown>>;
+export declare const supportedBuildTargets: readonly ['browser', 'web', 'web-preview', 'microsoft-store', 'msstore', 'verse8', 'android', 'ios', 'ait', 'devvit', 'reddit'];
+export declare function normalizeBuildTarget(target: string, configuredTargets?: ConfiguredBuildTargets): string;
+export declare function normalizeConfiguredBuildTargets(configuredTargets: ConfiguredBuildTargets): readonly string[];

package/dist/build-targets.js

@@ -0,0 +1,80 @@
+import { assertDeploymentTargetName } from './target-name.js';
+export const supportedBuildTargets = [
+    'browser',
+    'web',
+    'web-preview',
+    'microsoft-store',
+    'msstore',
+    'verse8',
+    'android',
+    'ios',
+    'ait',
+    'devvit',
+    'reddit',
+];
+const canonicalBuildTargets = new Set([
+    'web-preview',
+    'microsoft-store',
+    'verse8',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+]);
+export function normalizeBuildTarget(target, configuredTargets = {}) {
+    const normalizedTarget = resolveBuildTarget(target, configuredTargets);
+    if (normalizedTarget !== undefined) {
+        return normalizedTarget;
+    }
+    throw new Error(`Unsupported target: ${target}`);
+}
+export function normalizeConfiguredBuildTargets(configuredTargets) {
+    const targets = new Set();
+    for (const target of Object.keys(configuredTargets)) {
+        const normalizedTarget = resolveBuildTarget(target, configuredTargets);
+        if (normalizedTarget !== undefined) {
+            targets.add(normalizedTarget);
+        }
+    }
+    return [...targets];
+}
+function resolveBuildTarget(target, configuredTargets) {
+    const configuredWebTarget = isConfiguredWebTarget(target, configuredTargets);
+    if (configuredWebTarget) {
+        assertDeploymentTargetName(target);
+    }
+    if (target === 'web' && configuredWebTarget) {
+        return target;
+    }
+    const builtInTarget = normalizeBuiltInBuildTarget(target);
+    if (builtInTarget !== undefined) {
+        return builtInTarget;
+    }
+    if (configuredWebTarget) {
+        return target;
+    }
+    return undefined;
+}
+function normalizeBuiltInBuildTarget(target) {
+    if (target === 'browser' || target === 'web') {
+        return 'web-preview';
+    }
+    if (target === 'msstore') {
+        return 'microsoft-store';
+    }
+    if (target === 'devvit') {
+        return 'reddit';
+    }
+    return canonicalBuildTargets.has(target) ? target : undefined;
+}
+function isConfiguredWebTarget(target, configuredTargets) {
+    if (!Object.prototype.hasOwnProperty.call(configuredTargets, target)) {
+        return false;
+    }
+    const configuredTarget = configuredTargets[target];
+    return typeof configuredTarget === 'object'
+        && configuredTarget !== null
+        && !Array.isArray(configuredTarget)
+        && 'kind' in configuredTarget
+        && configuredTarget.kind === 'web';
+}

package/dist/index.js

@@ -6,12 +6,14 @@ import completion from '@gunshi/plugin-completion';
 import i18n, { defineI18n } from '@gunshi/plugin-i18n';
 import resources from '@gunshi/resources';
 import { cli } from 'gunshi';
+import { normalizeConfiguredBuildTargets, normalizeBuildTarget as normalizeConfiguredTargetName, supportedBuildTargets, } from './build-targets.js';
 import { defaultGameAcceptanceCommandTimeoutMs, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, } from './game-acceptance.js';
 import { resolveGameplayE2EReportFile } from './gameplay-e2e.js';
 import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageAcceptance, } from './microsoft-store-package-acceptance.js';
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
 import { defaultMpgdKitPath, initializeMicrosoftStoreStarter, listMicrosoftStoreInitializerTemplateFiles, prepareBaseGameTemplateFile, } from './microsoft-store-starter.js';
 import { runMicrosoftStoreSubmissionPreflight } from './microsoft-store-submission.js';
+import { targetConfigExtensionsFileEnv } from './target-config-env.js';
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, } from './game-acceptance.js';
 export { createBrowserGameplayE2EDriver, } from './browser-gameplay-e2e.js';
 export { collectGameplayE2EPathEvidence, defaultGameplayE2EReportFile, maximumGameplayE2EStates, parseGameplayE2EPlan, readGameplayE2EPlan, renderGameplayE2EMarkdown, resolveGameplayE2EReportFile, runGameplayE2E, } from './gameplay-e2e.js';
@@ -67,19 +69,6 @@ const allMatrixTargetOrder = [
     'ait',
     'reddit',
 ];
-const supportedBuildTargets = [
-    'browser',
-    'web',
-    'web-preview',
-    'microsoft-store',
-    'msstore',
-    'verse8',
-    'android',
-    'ios',
-    'ait',
-    'devvit',
-    'reddit',
-];
 const supportedVariants = ['wrapper', 'sync', 'simulator', 'archive'];
 const acceptanceStepIds = {
     check: 'check',
@@ -1024,7 +1013,7 @@ const targetCommand = defineI18n({
             },
             run: async (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'generate-package']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Package generation is not available for target: ${target}`);
                 }
@@ -1102,7 +1091,7 @@ const targetCommand = defineI18n({
             },
             run: (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'preflight']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Submission preflight is not available for target: ${target}`);
                 }
@@ -1204,7 +1193,7 @@ const targetCommand = defineI18n({
             },
             run: (ctx) => {
                 const positionals = readLocalPositionals(ctx.positionals, ['target', 'accept-package']);
-                const target = normalizeBuildTarget(readRequiredPositional(positionals, 0, 'target'));
+                const target = normalizeConfiguredTargetName(readRequiredPositional(positionals, 0, 'target'));
                 if (target !== 'microsoft-store') {
                     throw new Error(`Package acceptance is not available for target: ${target}`);
                 }
@@ -1397,6 +1386,11 @@ function targetConfigArgs() {
             required: false,
             description: 'Output path for the resolved target config file.',
         },
+        'target-config-extensions-file': {
+            type: 'string',
+            required: false,
+            description: 'Optional game-owned target config extensions file.',
+        },
     };
 }
 function matrixArgResources() {
@@ -1836,6 +1830,7 @@ function createTargetCommandEnv(values) {
     const gameRoot = path.dirname(targetsFile);
     const kitPath = resolveKitPathForTarget(values);
     const resolvedTargetsFile = readOptionalString(values['resolved-targets-file']);
+    const targetConfigExtensionsFile = resolveTargetConfigExtensionsFile(gameRoot, readOptionalString(values['target-config-extensions-file']));
     const preparedTargetsFile = preparePlatformTargetsFile({
         targetsFile,
         kitPath,
@@ -1848,8 +1843,20 @@ function createTargetCommandEnv(values) {
         ...createGameOwnedReleaseEnv(gameRoot, process.env),
         MPGD_KIT_PATH: kitPath,
         MPGD_PLATFORM_TARGETS_FILE: preparedTargetsFile,
+        ...(targetConfigExtensionsFile === undefined
+            ? {}
+            : { [targetConfigExtensionsFileEnv]: targetConfigExtensionsFile }),
     };
 }
+function resolveTargetConfigExtensionsFile(gameRoot, configuredFile) {
+    const inheritedFile = readConfiguredPath(process.env[targetConfigExtensionsFileEnv]);
+    const candidate = configuredFile ?? inheritedFile;
+    if (candidate !== undefined) {
+        return path.resolve(gameRoot, candidate);
+    }
+    const gameOwnedFile = path.join(gameRoot, 'mpgd.target-config.json');
+    return existsSync(gameOwnedFile) ? gameOwnedFile : undefined;
+}
 function createGameOwnedReleaseEnv(gameRoot, baseEnv) {
     const monetizationFiles = resolveGameOwnedMonetizationFiles(gameRoot, baseEnv);
     const sourceGitSha = readOptionalString(baseEnv.MPGD_SOURCE_GIT_SHA)
@@ -1970,7 +1977,7 @@ function replaceTargetTokens(value, context) {
     return value;
 }
 function runTargetCommand(input) {
-    const target = normalizeBuildTarget(input.target);
+    const target = normalizeBuildTarget(input.target, input.env);
     const env = withTargetVariantEnv(target, input.variant, input.env);
     const profile = input.profile ?? 'production';
     const args = input.action === 'build'
@@ -1991,11 +1998,10 @@ function runTargetMatrix(input) {
     }
 }
 function variantForTarget(target, input) {
-    const normalized = normalizeBuildTarget(target);
-    if (normalized === 'ait') {
+    if (target === 'ait') {
         return input.aitVariant;
     }
-    if (normalized === 'ios') {
+    if (target === 'ios') {
         return input.iosVariant;
     }
     return undefined;
@@ -2033,7 +2039,7 @@ function parseTargetList(value, env) {
         .split(',')
         .map((target) => target.trim())
         .filter((target) => target.length > 0)
-        .map((target) => normalizeBuildTarget(target));
+        .map((target) => normalizeBuildTarget(target, env));
     if (targets.length === 0) {
         throw new Error('Target list cannot be empty.');
     }
@@ -2042,6 +2048,13 @@ function parseTargetList(value, env) {
 function configuredTargetsForOrder(env, order, label) {
     const configuredTargets = readConfiguredBuildTargets(env);
     const targets = order.filter((target) => configuredTargets.has(target));
+    if (label === 'all') {
+        for (const target of configuredTargets) {
+            if (!targets.includes(target)) {
+                targets.push(target);
+            }
+        }
+    }
     if (targets.length === 0) {
         throw new Error(`No ${label} targets are configured in ${readConfiguredTargetsFile(env)}.`);
     }
@@ -2052,14 +2065,7 @@ function readConfiguredBuildTargets(env) {
     const parsed = readJsonForCli(file);
     assertJsonObject(parsed, `targets file ${file}`);
     assertJsonObject(parsed.targets, `targets in ${file}`);
-    const targets = new Set();
-    for (const target of Object.keys(parsed.targets)) {
-        const normalized = normalizeConfiguredBuildTarget(target);
-        if (normalized !== undefined) {
-            targets.add(normalized);
-        }
-    }
-    return targets;
+    return new Set(normalizeConfiguredBuildTargets(parsed.targets));
 }
 function readConfiguredTargetsFile(env) {
     const file = env.MPGD_PLATFORM_TARGETS_FILE;
@@ -2111,26 +2117,24 @@ function resolvePotentiallyMissingPath(input) {
 }
 function normalizeConfiguredBuildTarget(target) {
     try {
-        return normalizeBuildTarget(target);
+        return normalizeConfiguredTargetName(target);
     }
     catch {
         return undefined;
     }
 }
-function normalizeBuildTarget(target) {
-    if (target === 'browser' || target === 'web') {
-        return 'web-preview';
-    }
-    if (target === 'msstore') {
-        return 'microsoft-store';
-    }
-    if (target === 'devvit') {
-        return 'reddit';
-    }
-    if (!supportedBuildTargets.includes(target)) {
-        throw new Error(`Unsupported target: ${target}`);
+function normalizeBuildTarget(target, env = process.env) {
+    return normalizeConfiguredTargetName(target, readConfiguredTargetMap(env));
+}
+function readConfiguredTargetMap(env) {
+    const file = env.MPGD_PLATFORM_TARGETS_FILE;
+    if (file === undefined || file.length === 0 || !existsSync(file)) {
+        return {};
     }
-    return target;
+    const parsed = readJsonForCli(file);
+    assertJsonObject(parsed, `targets file ${file}`);
+    assertJsonObject(parsed.targets, `targets in ${file}`);
+    return parsed.targets;
 }
 function assertJsonObject(input, label) {
     if (typeof input !== 'object' || input === null || Array.isArray(input)) {

package/dist/production-target-readiness.d.ts

@@ -4,5 +4,15 @@ export interface ProductionTargetReadinessInput {
   readonly targetsFile: string;
   readonly gameRoot: string;
   readonly gameServicesUrl?: string;
+  readonly targetPolicy?: ProductionTargetPolicy;
+}
+export interface ProductionTargetPolicy {
+  readonly runtime: string;
+  readonly features: {
+    readonly rewardedAds: boolean;
+  };
+  readonly monetization: {
+    readonly rewardedAds: boolean;
+  };
 }
 export declare function assertProductionTargetReadiness(input: ProductionTargetReadinessInput): void;

package/dist/production-target-readiness.js

@@ -16,13 +16,30 @@ export function assertProductionTargetReadiness(input) {
         return;
     }
     const ownerPathKey = ownerPathByTarget[input.target];
-    if (ownerPathKey === undefined) {
+    if (ownerPathKey === undefined && input.targetPolicy === undefined) {
+        throw new Error(`Production target ${input.target} requires a target policy.`);
+    }
+    const requiresVerse8RewardAuthority = input.targetPolicy?.runtime === 'verse8-web'
+        && (input.targetPolicy.features.rewardedAds
+            || input.targetPolicy.monetization.rewardedAds);
+    if (ownerPathKey === undefined && !requiresVerse8RewardAuthority) {
         return;
     }
     const targetConfig = readTargets(input.targetsFile)[input.target];
     if (!isRecord(targetConfig)) {
         throw new Error(`Missing target configuration for ${input.target}.`);
     }
+    if (ownerPathKey === undefined) {
+        if (requiresVerse8RewardAuthority
+            && targetConfig.authoritativeGameServices === false) {
+            throw new Error(`Production target ${input.target} cannot enable rewarded ads without `
+                + 'authoritative game services.');
+        }
+        if (requiresVerse8RewardAuthority || targetConfig.authoritativeGameServices !== false) {
+            assertAuthoritativeGameServicesUrl(input.gameServicesUrl, input.target);
+        }
+        return;
+    }
     const ownerPath = targetConfig[ownerPathKey];
     const webDir = targetConfig.webDir;
     if (typeof ownerPath !== 'string' || ownerPath.length === 0) {

package/dist/target-config-env.d.ts

@@ -0,0 +1,2 @@
+export declare const targetConfigExtensionsFileEnv = "MPGD_TARGET_CONFIG_EXTENSIONS_FILE";
+export declare const targetConfigMatrixFileEnv = "MPGD_TARGET_CONFIG_MATRIX_FILE";

package/dist/target-config-env.js

@@ -0,0 +1,2 @@
+export const targetConfigExtensionsFileEnv = 'MPGD_TARGET_CONFIG_EXTENSIONS_FILE';
+export const targetConfigMatrixFileEnv = 'MPGD_TARGET_CONFIG_MATRIX_FILE';

package/dist/target-name.d.ts

@@ -0,0 +1 @@
+export declare function assertDeploymentTargetName(target: string): void;

package/dist/target-name.js

@@ -0,0 +1,23 @@
+const deploymentTargetNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const reservedDeploymentTargetNames = new Set([
+    'aux',
+    'browser',
+    'con',
+    'devvit',
+    'index',
+    'msstore',
+    'nul',
+    'prn',
+    'constructor',
+    'prototype',
+    ...Array.from({ length: 9 }, (_, index) => `com${String(index + 1)}`),
+    ...Array.from({ length: 9 }, (_, index) => `lpt${String(index + 1)}`),
+]);
+const maximumDeploymentTargetNameLength = 64;
+export function assertDeploymentTargetName(target) {
+    if (!deploymentTargetNamePattern.test(target)
+        || target.length > maximumDeploymentTargetNameLength
+        || reservedDeploymentTargetNames.has(target)) {
+        throw new Error(`Invalid deployment target name: ${target}. Use lowercase kebab-case and avoid reserved names.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -51,18 +51,18 @@
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
     "@mpgd/adapter-ait": "0.8.0",
-    "@mpgd/adapter-browser": "0.5.1",
-    "@mpgd/adapter-devvit": "0.8.5",
-    "@mpgd/adapter-verse8": "0.2.2",
     "@mpgd/adapter-capacitor": "0.4.5",
+    "@mpgd/adapter-devvit": "0.8.6",
+    "@mpgd/adapter-verse8": "0.2.3",
+    "@mpgd/analytics": "0.3.8",
+    "@mpgd/adapter-browser": "0.5.1",
     "@mpgd/bridge": "0.7.0",
-    "@mpgd/game-services": "0.11.0",
+    "@mpgd/catalog": "0.5.2",
+    "@mpgd/game-services": "0.11.1",
     "@mpgd/i18n": "0.5.4",
-    "@mpgd/analytics": "0.3.8",
     "@mpgd/phaser-assets": "0.4.1",
     "@mpgd/platform": "0.8.0",
-    "@mpgd/catalog": "0.5.1",
-    "@mpgd/target-config": "0.10.0"
+    "@mpgd/target-config": "0.10.1"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/src/env.d.ts

@@ -5,6 +5,9 @@ declare const __MPGD_CONFIG_TARGET__: string;
 declare const __MPGD_PLATFORM_TARGET__:
   | import('@mpgd/target-config').EffectivePlatformTargetMetadata
   | undefined;
+declare const __MPGD_TARGET_CONFIG_MATRIX__:
+  | import('@mpgd/target-config').TargetConfigMatrix
+  | undefined;
 declare const __APP_VERSION__: string;
 declare const __BUILD_ID__: string;
 declare const __SOURCE_GIT_SHA__: string;

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

@@ -66,6 +66,7 @@ async function bootstrap(): Promise<void> {
     const gameServices = createStarterGameServices({
       gateway: platform,
       playerId: identitySession.playerId ?? player.playerId,
+      configTarget: runtime.configTarget,
       analytics: analyticsSink,
       analyticsSessionId,
     });

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

@@ -1,15 +1,21 @@
 import { createVerse8PlatformGateway } from '@mpgd/adapter-verse8';
-import type { AdPlacements } from '@mpgd/catalog';
+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> {
+export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
   const adPlacements = adPlacementsJson as AdPlacements;
   const placementIds = new Map(
     adPlacements.placements.flatMap((placement) => {
-      const platformPlacementId = placement.platformPlacementIds.verse8;
+      const platformPlacementId = resolveAdPlacementPlatformId(
+        placement,
+        runtime.configTarget,
+      );
 
       return platformPlacementId === undefined
         ? []

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

@@ -14,6 +14,7 @@ export type StarterGameServices = GameServicesRuntime;
 export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
+  readonly configTarget: string;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
@@ -26,6 +27,7 @@ export function createStarterGameServices(input: {
       : { analyticsSessionId: input.analyticsSessionId }),
     authorityMode: resolveGameServicesAuthorityMode(import.meta.env.MODE),
     target: import.meta.env.VITE_MPGD_GAME_SERVICES_TARGET ?? input.gateway.target,
+    deploymentTarget: input.configTarget,
     ...(import.meta.env.VITE_MPGD_GAME_SERVICES_URL === undefined
       ? {}
       : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),

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

@@ -15,7 +15,8 @@ import targetConfigMatrixJson from '@mpgd/target-config/targets.json';
 
 import type { RuntimeConfig } from './runtimeDetector';
 
-const targetConfigMatrix = targetConfigMatrixJson as TargetConfigMatrix;
+const targetConfigMatrix = __MPGD_TARGET_CONFIG_MATRIX__
+  ?? targetConfigMatrixJson as TargetConfigMatrix;
 const productCatalog = productCatalogJson as ProductCatalog;
 const adPlacements = adPlacementsJson as AdPlacements;
 const targetAdPlacements = adPlacements.placements.map((placement) => ({

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

@@ -0,0 +1,176 @@
+import type {
+  IntegrationAvailabilityState,
+  PresentationMode,
+  ReleaseProfile,
+  StorageSupport,
+  TargetConfig,
+  TargetConfigMatrix,
+  TargetIntegration,
+  TargetRuntimeKind,
+} from '@mpgd/target-config';
+
+export type { TargetConfigMatrix } from '@mpgd/target-config';
+
+const runtimeKinds = valueSet({
+  'web-preview': true,
+  'microsoft-store-pwa': true,
+  'capacitor-android': true,
+  'capacitor-ios': true,
+  'apps-in-toss': true,
+  'devvit-web': true,
+  'verse8-web': true,
+} satisfies Record<TargetRuntimeKind, true>);
+const releaseProfiles = valueSet({
+  'web-preview': true,
+  'microsoft-store': true,
+  'google-play': true,
+  'app-store': true,
+  'apps-in-toss': true,
+  'devvit': true,
+  'verse8': true,
+} satisfies Record<ReleaseProfile, true>);
+const storageSupportValues = valueSet({
+  local: true,
+  native: true,
+  none: true,
+} satisfies Record<StorageSupport, true>);
+const integrationAvailabilityValues = valueSet({
+  available: true,
+  disabled: true,
+  'approval-required': true,
+  'configuration-required': true,
+  unsupported: true,
+} satisfies Record<IntegrationAvailabilityState, true>);
+const presentationModeValues = valueSet({
+  fullscreen: true,
+  'inline-expanded': true,
+} satisfies Record<PresentationMode, true>);
+const targetIntegrations = Object.keys({
+  identityUpgrade: true,
+  presentation: true,
+  sharing: true,
+  inboundShare: true,
+  notifications: true,
+} satisfies Record<TargetIntegration, true>);
+
+export function assertRuntimeTargetConfigMatrix(input: unknown): TargetConfigMatrix {
+  assertRecord(input, 'target config matrix');
+  assertNonEmptyString(input.version, 'target config matrix.version');
+  assertRecord(input.targets, 'target config matrix.targets');
+
+  for (const [target, config] of Object.entries(input.targets)) {
+    assertNonEmptyString(target, 'target config matrix target name');
+    assertTargetConfig(config, `target config matrix.targets.${target}`);
+  }
+
+  return input as unknown as TargetConfigMatrix;
+}
+
+function assertTargetConfig(input: unknown, label: string): asserts input is TargetConfig {
+  assertRecord(input, label);
+  assertOneOf(input.runtime, runtimeKinds, `${label}.runtime`);
+
+  assertRecord(input.features, `${label}.features`);
+  assertBooleanFields(
+    input.features,
+    ['iap', 'rewardedAds', 'interstitialAds', 'leaderboard', 'localization'],
+    `${label}.features`,
+  );
+
+  assertRecord(input.capabilities, `${label}.capabilities`);
+  assertOneOf(input.capabilities.storage, storageSupportValues, `${label}.capabilities.storage`);
+  assertBoolean(input.capabilities.localization, `${label}.capabilities.localization`);
+
+  assertRecord(input.localization, `${label}.localization`);
+  assertNonEmptyString(input.localization.fallbackLocale, `${label}.localization.fallbackLocale`);
+
+  assertRecord(input.monetization, `${label}.monetization`);
+  assertBooleanFields(
+    input.monetization,
+    ['iap', 'rewardedAds', 'interstitialAds'],
+    `${label}.monetization`,
+  );
+
+  assertRecord(input.leaderboard, `${label}.leaderboard`);
+  assertBoolean(input.leaderboard.native, `${label}.leaderboard.native`);
+
+  assertRecord(input.release, `${label}.release`);
+  assertOneOf(input.release.profile, releaseProfiles, `${label}.release.profile`);
+
+  assertRecord(input.policy, `${label}.policy`);
+  assertBooleanFields(
+    input.policy,
+    [
+      'externalPaymentAllowed',
+      'remoteExecutableCodeAllowed',
+      'installOtherAppCTAAllowed',
+      'requiresStoreReview',
+      'requiresAitReview',
+    ],
+    `${label}.policy`,
+  );
+
+  if (input.integrations !== undefined) {
+    assertRecord(input.integrations, `${label}.integrations`);
+    for (const key of targetIntegrations) {
+      assertOneOf(
+        input.integrations[key],
+        integrationAvailabilityValues,
+        `${label}.integrations.${key}`,
+      );
+    }
+    assertOneOf(
+      input.integrations.presentationMode,
+      presentationModeValues,
+      `${label}.integrations.presentationMode`,
+    );
+  }
+}
+
+function assertBooleanFields(
+  input: Record<string, unknown>,
+  fields: readonly string[],
+  label: string,
+): void {
+  for (const field of fields) {
+    assertBoolean(input[field], `${label}.${field}`);
+  }
+}
+
+function assertBoolean(input: unknown, label: string): asserts input is boolean {
+  if (typeof input !== 'boolean') {
+    throw new Error(`${label} must be a boolean.`);
+  }
+}
+
+function assertNonEmptyString(input: unknown, label: string): asserts input is string {
+  if (typeof input !== 'string' || input.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function assertOneOf(input: unknown, values: ReadonlySet<string>, label: string): void {
+  if (typeof input !== 'string' || !values.has(input)) {
+    throw new Error(
+      `${label} has unsupported value ${formatValue(input)}; expected one of ${[...values].join(', ')}.`,
+    );
+  }
+}
+
+function formatValue(input: unknown): string {
+  try {
+    return JSON.stringify(input) ?? String(input);
+  } catch {
+    return String(input);
+  }
+}
+
+function valueSet<T extends string>(values: Record<T, true>): ReadonlySet<string> {
+  return new Set(Object.keys(values));
+}
+
+function assertRecord(input: unknown, label: string): asserts input is Record<string, unknown> {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}

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

@@ -4,6 +4,11 @@ import { resolve } from 'node:path';
 import ttsc from '@ttsc/unplugin/vite';
 import type { UserConfig } from 'vite';
 
+import {
+  assertRuntimeTargetConfigMatrix,
+  type TargetConfigMatrix,
+} from './vite.runtime-target-config';
+
 interface RuntimePlatformTargetMetadata {
   readonly kind: string;
   readonly adapter: string;
@@ -39,6 +44,9 @@ export function createGameViteSharedConfig(
     debug: !isProduction,
     buildId: process.env.BUILD_ID ?? 'local',
   });
+  const runtimeTargetConfigMatrix = readRuntimeTargetConfigMatrix(
+    process.env.MPGD_TARGET_CONFIG_MATRIX_FILE,
+  );
 
   return {
     base: './',
@@ -63,6 +71,10 @@ export function createGameViteSharedConfig(
       __MPGD_CONFIG_TARGET__: JSON.stringify(configTarget),
       __MPGD_PLATFORM_TARGET__:
         platformTarget === undefined ? 'undefined' : JSON.stringify(platformTarget),
+      __MPGD_TARGET_CONFIG_MATRIX__:
+        runtimeTargetConfigMatrix === undefined
+          ? 'undefined'
+          : JSON.stringify(runtimeTargetConfigMatrix),
       __APP_VERSION__: JSON.stringify(process.env.APP_VERSION ?? '0.0.0-dev'),
       __BUILD_ID__: JSON.stringify(process.env.BUILD_ID ?? 'local'),
       __SOURCE_GIT_SHA__: JSON.stringify(process.env.MPGD_SOURCE_GIT_SHA ?? 'uncommitted'),
@@ -71,6 +83,27 @@ export function createGameViteSharedConfig(
   };
 }
 
+function readRuntimeTargetConfigMatrix(
+  source: string | undefined,
+): TargetConfigMatrix | undefined {
+  const matrixFile = source?.trim();
+  if (matrixFile === undefined || matrixFile.length === 0) {
+    return undefined;
+  }
+
+  const resolvedMatrixFile = resolve(matrixFile);
+
+  try {
+    return assertRuntimeTargetConfigMatrix(
+      JSON.parse(readFileSync(resolvedMatrixFile, 'utf8')) as unknown,
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to read or validate MPGD_TARGET_CONFIG_MATRIX_FILE at ${resolvedMatrixFile}: ${formatError(error)}`,
+    );
+  }
+}
+
 export function resolveBuildGatewayModule(input: {
   readonly target: string;
   readonly debug: boolean;