Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(export): a project can be packaged for Alipay

esengine9b4f4a37c3ef
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e3760117f..819cfc343 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A project can be packaged for Alipay (支付宝小游戏).** `game.json` turns on iOS high-performance mode — the only iOS mode with `MYWebAssembly`, which the runtime instantiates through with an absolute package path — and `project.config.json` turns off the review build's own transpile and minify, since the bundle is already down-levelled; the appid is passed to Alipay's tool (`minidev -a`), not packaged. The profile hands the family `my` in WeChat's words — a rewarded unit through `my.createRewardedAd`, sign-in through `my.getAuthCode`, share through the card `my.showSharePanel` reads off `my.onShareAppMessage`. It packages the engine build without SIMD, judged against 4 MB and 20 MB. Nothing has run on a device; purchase is not offered (Android and Harmony only, keyed by a `customId`), and Taobao — which only supports Cocos and Laya — is not a target.
- **A project can be packaged as a quick game — one signed `.rpk` for vivo, OPPO, Xiaomi and Honor (快游戏联盟).** Set the package name (it must end in `.minigame`) in Project Settings → Packaging → Quick game, and the export writes `manifest.json` (allianceVersion 1300), the project's icon (or Estella's mark), and `<package>.rpk` signed with your release key — or with Estella's public debug key, which a device debugger installs and a store refuses. It needs no vendor tool: the signing block is written here and matches the vendor CLI's byte for byte. The package runs on its own engine build (`build -t quickgame`) without wasm SIMD and BigInt i64, which the hosts' V8 8.3 refuses, and the runtime reads the hosts' window in physical pixels and turns WebAssembly on first. Verified end to end on vivo's engine in an Android emulator; OPPO grants WebGL2 only to a game that applied for it, and no device has run it yet.
- **A project can be packaged for Bilibili (B 站).** `game.json` carries the appid (Project Settings → Packaging → Bilibili) and the project's version, and turns on all four high-performance switches — Bilibili runs WebGL2 nowhere else, and the engine renders on nothing less. Scripts are lowered below async/await, which Bilibili asks a game to polyfill, and files are staged against Bilibili's own upload whitelist. The build is judged against 4 MB for the main package, 4 MB for each subpackage and 30 MB in all; a per-subpackage limit is new, and the size panel names the heaviest subpackage's files when it is over. Ads (rewarded only), share and sign-in are forwarded to `bl` and marked unverified; purchase is not offered. wasm on iOS is contradicted in Bilibili's own docs and needs a device.
- A mini-game host that asks to hear when the first screen has rendered is told, once, at the end of the first frame — Bilibili reviews a game by `bl.launchSuccess`.
diff --git a/desktop b/desktop
index 670b2b0c2..5b3e70dbd 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 670b2b0c2e85413fd75e0310340aaf2821433210
+Subproject commit 5b3e70dbda671dc2fbd74594ae8faf77efd76b73
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index b87cc04c4..4607612aa 100644
--- a/pipeline/src/bundle/engineSubpaths.ts
+++ b/pipeline/src/bundle/engineSubpaths.ts
@@ -23,6 +23,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
'esengine/kuaishou': 'kuaishou/index.js',
'esengine/bilibili': 'bilibili/index.js',
'esengine/quickgame': 'quickgame/index.js',
+ 'esengine/alipay': 'alipay/index.js',
'esengine/wasm': 'wasm.js',
};
@@ -31,7 +32,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
* loads, and a platform adapter an entry chooses rather than content asking for
* it. Named here so the pickable set is derived rather than written twice.
*/
-export const NOT_A_MODULE: ReadonlySet<string> = new Set(['esengine/wasm', 'esengine/douyin', 'esengine/kuaishou', 'esengine/bilibili', 'esengine/quickgame']);
+export const NOT_A_MODULE: ReadonlySet<string> = new Set(['esengine/wasm', 'esengine/douyin', 'esengine/kuaishou', 'esengine/bilibili', 'esengine/quickgame', 'esengine/alipay']);
/** The modules a project can force in or refuse, as `features.modules` keys it. */
export const ENGINE_MODULES: readonly string[] =
diff --git a/pipeline/src/bundle/runtimeHosts.ts b/pipeline/src/bundle/runtimeHosts.ts
index efbfa3d12..acfb674ff 100644
--- a/pipeline/src/bundle/runtimeHosts.ts
+++ b/pipeline/src/bundle/runtimeHosts.ts
@@ -17,7 +17,7 @@ import { ESENGINE_EXTERNAL } from './esengineResolve';
// editor has to ship it for the same reason it ships the hosts.
export const RUNTIME_HOSTS = [
'gameHost', 'playableHost', 'playableLoader', 'douyinPlatformProfile', 'kuaishouPlatformProfile',
- 'bilibiliPlatformProfile', 'quickgamePlatformProfile',
+ 'bilibiliPlatformProfile', 'quickgamePlatformProfile', 'alipayPlatformProfile',
] as const;
export type RuntimeHost = (typeof RUNTIME_HOSTS)[number];
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index b4b16cafd..3af49cf19 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -36,7 +36,7 @@ import {
import { engineImportMap, FULL_IMPORT_MAP, LEAN_ENTRY_FILE, FULL_ENTRY_FILE, type EngineImportMap } from '../bundle/importMap';
import { engineInstalls, forcedSideModules, moduleChoices, type EngineInstallPlan } from '../bundle/engineInstalls';
import { exportMiniGame } from './exportMiniGame';
-import { wechatExportProfile, douyinExportProfile, kuaishouExportProfile, bilibiliExportProfile, quickgameExportProfile } from './miniGameExportProfile';
+import { wechatExportProfile, douyinExportProfile, kuaishouExportProfile, bilibiliExportProfile, quickgameExportProfile, alipayExportProfile } from './miniGameExportProfile';
import type { MiniGameExportProfile } from './miniGameExportProfile';
/** The mini-game vendors the editor ships, by platform id. */
@@ -46,6 +46,7 @@ const BUILTIN_MINIGAME_PROFILES: Readonly<Record<string, MiniGameExportProfile>>
kuaishou: kuaishouExportProfile,
bilibili: bilibiliExportProfile,
quickgame: quickgameExportProfile,
+ alipay: alipayExportProfile,
};
import { exportPlayable } from './exportPlayable';
import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfile';
diff --git a/pipeline/src/export/miniGameExportProfile.ts b/pipeline/src/export/miniGameExportProfile.ts
index f57851119..db6b8f76c 100644
--- a/pipeline/src/export/miniGameExportProfile.ts
+++ b/pipeline/src/export/miniGameExportProfile.ts
@@ -27,7 +27,7 @@ import path from 'node:path';
* ship can still be exported by handing {@link exportMiniGame} a profile.
* Mirrors the SDK's `MiniGameVendor` (sdk/src/platform/minigame/api.ts).
*/
-export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | (string & {});
+export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | (string & {});
/** Vendor-neutral facts the pipeline computes, handed to the config emitter. */
export interface MiniGameConfigContext {
@@ -620,6 +620,59 @@ export const quickgameExportProfile: MiniGameExportProfile = {
},
};
+// =============================================================================
+// Alipay profile
+// =============================================================================
+
+/**
+ * Alipay (支付宝), from opendocs.alipay.com/mini-game: `subpackages` lower-case,
+ * the appid passed to the tools (`minidev -a`) rather than packaged, and the
+ * review build's own transpile and minify — on by default — turned off in
+ * `project.config.json`, since this bundle is already down-levelled.
+ */
+export const alipayExportProfile: MiniGameExportProfile = {
+ id: 'alipay',
+ sdkEntryFile: 'index.minigame.js',
+ runtimeInit: 'initMiniGameRuntime',
+ runtimeProfileHost: 'alipayPlatformProfile',
+ engineGlueCandidates: MINIGAME_ENGINE_GLUE,
+ // WeChat's floor, unconfirmed here: down-levelling costs nothing and a syntax
+ // error on a phone costs a release.
+ esTarget: 'es2017',
+ wasmBuildHint: 'quickgame',
+ hostGlobal: 'my',
+ sideModuleBuildTargets: {},
+ // Assumed to match the other vendors, not read from an Alipay doc; a wrong
+ // guess is a staged file the runtime cannot read.
+ nativeSuffixes: new Set(['.js', '.json']),
+ // No upload whitelist is published; nothing is restaged.
+ packerSuffixes: null,
+ // MYWebAssembly documents a `.wasm` path only.
+ wasmBrotli: false,
+ subpackageDir: 'subpackages',
+ // 「目录根目录下的 game.js 会作为入口文件」.
+ subpackageEntry: 'game.js',
+
+ emitConfigFiles(ctx) {
+ const gameCfg: Record<string, unknown> = {
+ deviceOrientation: ctx.orientation,
+ showStatusBar: false,
+ // MYWebAssembly runs on iOS only in high-performance mode; 10.8.6+ goes on
+ // to 高性能+ by default, and this keeps an older client off 普通模式.
+ iOSHighPerformance: true,
+ };
+ if (ctx.subPackages.length > 0) {
+ gameCfg.subpackages = ctx.subPackages.map((s) => ({ name: s.name, root: s.root }));
+ }
+ return [
+ { file: 'game.json', content: JSON.stringify(gameCfg, null, 2) + '\n' },
+ { file: 'project.config.json', content: JSON.stringify({ setting: { transpile: false, minify: false } }, null, 2) + '\n' },
+ ];
+ },
+
+ emitEntry: defaultMiniGameEntry,
+};
+
async function listFiles(root: string, prefix = ''): Promise<string[]> {
const out: string[] = [];
for (const e of await readdir(path.join(root, prefix), { withFileTypes: true })) {
diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.ts
index 5571450e4..e671548c3 100644
--- a/pipeline/src/export/platformCatalog.ts
+++ b/pipeline/src/export/platformCatalog.ts
@@ -132,6 +132,7 @@ function builtinReadiness(
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.minigame), looked: [...MINIGAME_ENGINE_GLUE], command: `node build-tools/cli.js build -t ${MINIGAME_ENGINE_BUILD}` } };
case 'quickgame':
+ case 'alipay':
return MINIGAME_ENGINE_GLUE.some((g) => has(dirs.quickgame, g))
? { ready: true }
: { ready: false, prereq: { kind: 'runtime-missing', dir: posix(dirs.quickgame), looked: [...MINIGAME_ENGINE_GLUE], command: 'node build-tools/cli.js build -t quickgame' } };
diff --git a/pipeline/src/project/platforms.ts b/pipeline/src/project/platforms.ts
index baf6ca221..148072e69 100644
--- a/pipeline/src/project/platforms.ts
+++ b/pipeline/src/project/platforms.ts
@@ -21,11 +21,11 @@
* Xcode), so a single row could not tell you what to run, whether this machine
* can run it, or where the package comes out.
*/
-export type BuiltinPlatform = 'web' | 'desktop' | 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'playable' | 'android' | 'ios';
+export type BuiltinPlatform = 'web' | 'desktop' | 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | 'playable' | 'android' | 'ios';
/** Built-ins, in the order they are offered. */
export const BUILTIN_PLATFORMS: readonly BuiltinPlatform[] = [
- 'web', 'desktop', 'wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'playable', 'android', 'ios',
+ 'web', 'desktop', 'wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'alipay', 'playable', 'android', 'ios',
];
/**
@@ -63,16 +63,17 @@ export function isNativePlatform(platform: ExportPlatform): platform is NativePl
* project's own vendor is one of these without appearing here, so that build
* lives in the family's export defaults rather than behind this list.
*/
-export const MINIGAME_PLATFORMS = ['wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame'] as const;
+export const MINIGAME_PLATFORMS = ['wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'alipay'] as const;
export type MiniGamePlatform = (typeof MINIGAME_PLATFORMS)[number];
/**
* Which engine build a web-runtime target packages: the browser one, the
- * CommonJS mini-game one, or that one again without wasm SIMD and BigInt i64 for
- * the quick-game hosts, whose V8 (8.3) refuses both.
+ * CommonJS mini-game one, or that one again without wasm SIMD and BigInt i64 —
+ * for the quick-game hosts, whose V8 (8.3) refuses both, and for Alipay, whose
+ * MYWebAssembly publishes no feature level to rely on.
*/
export function engineBuildFor(platform: ExportPlatform): 'web' | 'minigame' | 'quickgame' {
- if (platform === 'quickgame') return 'quickgame';
+ if (platform === 'quickgame' || platform === 'alipay') return 'quickgame';
return isMiniGamePlatform(platform) ? 'minigame' : 'web';
}
diff --git a/pipeline/src/project/serviceSupport.ts b/pipeline/src/project/serviceSupport.ts
index a7bb0816d..889fbe25b 100644
--- a/pipeline/src/project/serviceSupport.ts
+++ b/pipeline/src/project/serviceSupport.ts
@@ -232,6 +232,35 @@ const QUICKGAME_SERVICES: readonly ServiceStatus[] = [
{ service: 'achievements', support: 'no', note: ACHIEVEMENTS_LOCAL_ONLY },
];
+/** From opendocs.alipay.com/mini-game; nothing here has run on a device yet. */
+const ALIPAY_SERVICES: readonly ServiceStatus[] = [
+ {
+ service: 'ads',
+ support: 'unknown',
+ note: 'The engine forwards to my.createRewardedAd / my.createInterstitialAd (onClose carries isEnded);'
+ + ' unverified on a device.',
+ },
+ {
+ service: 'share',
+ support: 'unknown',
+ note: 'The engine sets the card on my.onShareAppMessage and opens my.showSharePanel, as Alipay documents;'
+ + ' unverified on a device.',
+ },
+ {
+ service: 'signIn',
+ support: 'unknown',
+ note: 'The engine forwards to my.getAuthCode (auth_base) and hands over its authCode for your server to'
+ + ' exchange; unverified on a device.',
+ },
+ {
+ service: 'purchase',
+ support: 'no',
+ note: 'my.requestGamePayment sells on Android and Harmony only (「需要对 ios 用户屏蔽内购功能」), keyed by a'
+ + ' customId the engine\'s purchase request does not carry — so the profile leaves the slot empty.',
+ },
+ { service: 'achievements', support: 'no', note: ACHIEVEMENTS_LOCAL_ONLY },
+];
+
const DESKTOP_SERVICES: readonly ServiceStatus[] = noHostServices().map((s) => (
s.service === 'achievements'
? {
@@ -256,6 +285,7 @@ export function builtinServiceSupport(platform: ExportPlatform): readonly Servic
if (platform === 'kuaishou') return KUAISHOU_SERVICES;
if (platform === 'bilibili') return BILIBILI_SERVICES;
if (platform === 'quickgame') return QUICKGAME_SERVICES;
+ if (platform === 'alipay') return ALIPAY_SERVICES;
if (platform === 'desktop') return DESKTOP_SERVICES;
if (platform === 'web' || platform === 'playable' || platform === 'android' || platform === 'ios') {
return noHostServices();
diff --git a/pipeline/src/project/sizeBudget.ts b/pipeline/src/project/sizeBudget.ts
index 43bad50ad..1cfcddec4 100644
--- a/pipeline/src/project/sizeBudget.ts
+++ b/pipeline/src/project/sizeBudget.ts
@@ -80,6 +80,7 @@ export function builtinSizeBudgets(platform: ExportPlatform): readonly SizeBudge
if (platform === 'kuaishou') return KUAISHOU_BUDGETS;
if (platform === 'bilibili') return BILIBILI_BUDGETS;
if (platform === 'quickgame') return QUICKGAME_BUDGETS;
+ if (platform === 'alipay') return ALIPAY_BUDGETS;
return NO_BUDGETS;
}
@@ -129,6 +130,15 @@ const QUICKGAME_BUDGETS: readonly SizeBudget[] = [
{ scope: 'total', maxBytes: 20 * MB, note: 'vivo caps a quick game at 20MB — a 4MB main package and 16MB of subpackages' },
];
+/**
+ * 「整个小游戏所有主包+分包大小不超过 20 M/主包不超过 4 M」
+ * https://opendocs.alipay.com/mini-game/08uo7z
+ */
+const ALIPAY_BUDGETS: readonly SizeBudget[] = [
+ { scope: 'initial', maxBytes: 4 * MB, note: "Alipay caps a mini-game's main package at 4MB (主包不超过 4 M)" },
+ { scope: 'total', maxBytes: 20 * MB, note: 'Alipay caps a mini-game at 20MB across the main package and all subpackages' },
+];
+
const NO_BUDGETS: readonly SizeBudget[] = [];
/**
diff --git a/pipeline/src/runtime/alipayPlatformProfile.ts b/pipeline/src/runtime/alipayPlatformProfile.ts
new file mode 100644
index 000000000..aa40b5915
--- /dev/null
+++ b/pipeline/src/runtime/alipayPlatformProfile.ts
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file alipayPlatformProfile.ts — the module an Alipay package installs its
+ * platform from, as the export profile's `runtimeProfileModule`.
+ */
+import { alipayProfile } from 'esengine/alipay';
+
+export default alipayProfile;
diff --git a/pipeline/tests/export-alipay.test.ts b/pipeline/tests/export-alipay.test.ts
new file mode 100644
index 000000000..bf162a1ea
--- /dev/null
+++ b/pipeline/tests/export-alipay.test.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Alipay MiniGame export. What is Alipay's own: `game.json` with iOS
+ * high-performance mode on (the only iOS mode with MYWebAssembly) and
+ * `subpackages` lower-case, a `project.config.json` that turns the review
+ * build's transpile and minify off, no appid in the package, and the
+ * engine build without SIMD.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { exportGame } from '../src/export/exportGame';
+import { alipayExportProfile } from '../src/export/miniGameExportProfile';
+import { builtinSizeBudgets } from '../src/project/sizeBudget';
+import { engineBuildFor } from '../src/project/platforms';
+import { runtimeConfigOf } from '../src/project/runtimeConfig';
+import { OFFICIAL_PACKAGES } from './officialPackagesDir';
+
+let root: string;
+let out: string;
+
+beforeAll(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-export-alipay-'));
+ mkdirSync(path.join(root, 'scenes'), { recursive: true });
+ writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({ version: '1.0', name: 'Main', entities: [] }));
+ writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'),
+ JSON.stringify({ uuid: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', version: '2.0', type: 'scene', importer: {} }));
+ mkdirSync(path.join(root, '_sdk', 'alipay'), { recursive: true });
+ writeFileSync(path.join(root, '_sdk', 'index.minigame.js'),
+ 'export function initMiniGameRuntime(){return Promise.resolve();}\nexport function installMiniGamePlatform(){}\n');
+ writeFileSync(path.join(root, '_sdk', 'alipay', 'index.js'), 'export const alipayProfile = { id: "alipay" };\n');
+ mkdirSync(path.join(root, '_wasm'), { recursive: true });
+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(root, '_wasm', 'esengine.wxgame.wasm'), 'wasm');
+ out = path.join(root, 'dist-alipay');
+}, 60_000);
+
+afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
+
+describe('exportGame (alipay)', () => {
+ it('writes the two configs Alipay reads, and no appid', async () => {
+ const res = await exportGame({
+ root, entryScene: 'scenes/main.esscene',
+ hostsDir: path.resolve(__dirname, '../src/runtime'), packagesDir: OFFICIAL_PACKAGES,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'), outDir: out,
+ title: 'My Game', platform: 'alipay', orientation: 'portrait',
+ runtime: runtimeConfigOf({ designResolution: { width: 720, height: 1280 } }),
+ miniGameAppid: 'should-not-appear',
+ });
+ expect(res.ok, res.errors.join('\n')).toBe(true);
+ expect(JSON.parse(readFileSync(path.join(out, 'game.json'), 'utf8')))
+ .toEqual({ deviceOrientation: 'portrait', showStatusBar: false, iOSHighPerformance: true });
+ expect(JSON.parse(readFileSync(path.join(out, 'project.config.json'), 'utf8')))
+ .toEqual({ setting: { transpile: false, minify: false } });
+ expect(readFileSync(path.join(out, 'game-bundle.js'), 'utf8')).toContain('alipay');
+ expect(readFileSync(path.join(out, 'game.js'), 'utf8')).not.toContain('should-not-appear');
+ }, 180_000);
+
+ it('declares subpackages under the key Alipay reads', () => {
+ const [cfg] = alipayExportProfile.emitConfigFiles({
+ title: 't', appid: '', version: '1.0.0', versionCode: 1, icon: null, orientation: 'landscape',
+ subPackages: [{ name: 'stage1', root: 'subpackages/stage1/' }],
+ includeSuffixes: [], hasOpenData: false, openDataRoot: 'open-data',
+ });
+ expect(JSON.parse(String(cfg.content)).subpackages).toEqual([{ name: 'stage1', root: 'subpackages/stage1/' }]);
+ });
+
+ it('runs on the engine build without SIMD, judged against 4MB and 20MB', () => {
+ expect(engineBuildFor('alipay')).toBe('quickgame');
+ expect(builtinSizeBudgets('alipay').map((b) => [b.scope, b.maxBytes / (1024 * 1024)]))
+ .toEqual([['initial', 4], ['total', 20]]);
+ });
+});
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 720168a3d..7aae352a1 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5232,7 +5232,7 @@ changedTouches: MiniGameTouch[]
## MiniGameVendor — type @experimental
```
-'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | (string & {})
+'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | (string & {})
```
## MissingAssetCallback — type @experimental
diff --git a/sdk/package.json b/sdk/package.json
index b66fa5b69..79e1a54a0 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -26,6 +26,7 @@
"./dist/kuaishou/index.js",
"./dist/bilibili/index.js",
"./dist/quickgame/index.js",
+ "./dist/alipay/index.js",
"./dist/index.wechat.cjs.js"
],
"main": "./dist/index.js",
@@ -105,6 +106,10 @@
"./quickgame": {
"import": "./dist/quickgame/index.js",
"types": "./dist/quickgame/index.d.ts"
+ },
+ "./alipay": {
+ "import": "./dist/alipay/index.js",
+ "types": "./dist/alipay/index.d.ts"
}
},
"files": [
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index e98b6c939..acc471bcd 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -105,6 +105,7 @@ export default defineConfig([
'kuaishou/index': 'src/platform/kuaishou/index.ts',
'bilibili/index': 'src/platform/bilibili/index.ts',
'quickgame/index': 'src/platform/quickgame/index.ts',
+ 'alipay/index': 'src/platform/alipay/index.ts',
'wasm': 'src/wasm.ts',
},
// Only the node entry reaches these; a browser entry that did would fail
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 433eeea80..0d67fee25 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -20,6 +20,7 @@ export default [
'kuaishou/index': 'src/platform/kuaishou/index.ts',
'bilibili/index': 'src/platform/bilibili/index.ts',
'quickgame/index': 'src/platform/quickgame/index.ts',
+ 'alipay/index': 'src/platform/alipay/index.ts',
'spine/index': 'src/spine/index.ts',
'tilemap/index': 'src/tilemap/index.ts',
'logic/index': 'src/logic/index.ts',
diff --git a/sdk/src/platform/alipay/index.ts b/sdk/src/platform/alipay/index.ts
new file mode 100644
index 000000000..5c51e1297
--- /dev/null
+++ b/sdk/src/platform/alipay/index.ts
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file index.ts
+ * @brief Alipay MiniGame platform (a profile of the mini-game family).
+ *
+ * Adapter, polyfills and install are the family's; Alipay adds only its profile, which is
+ * the point of the family existing.
+ */
+import { MiniGamePlatformAdapter, installMiniGamePlatform } from '../minigame';
+import { alipayProfile } from './profile';
+
+export const alipayAdapter = new MiniGamePlatformAdapter(alipayProfile);
+
+let initialized = false;
+
+/** Initialize the Alipay platform. */
+export function initAlipayPlatform(): void {
+ if (initialized) return;
+ initialized = true;
+ installMiniGamePlatform(alipayProfile, alipayAdapter);
+}
+
+export { alipayProfile };
diff --git a/sdk/src/platform/alipay/profile.ts b/sdk/src/platform/alipay/profile.ts
new file mode 100644
index 000000000..e1d049a35
--- /dev/null
+++ b/sdk/src/platform/alipay/profile.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file profile.ts
+ * @brief Alipay as a profile of the mini-game family.
+ *
+ * `my` has the family's shape under other names (opendocs.alipay.com/mini-game),
+ * so the profile hands the family a view of it in WeChat's words:
+ * `createRewardedAd` for a rewarded unit, `getAuthCode` for sign-in (its
+ * `authCode` is the one-time code), and share through a card the host reads off
+ * the `my.onShareAppMessage` PROPERTY when `my.showSharePanel()` opens.
+ * WebAssembly is `MYWebAssembly`, which takes an absolute package path.
+ *
+ * UNVERIFIED on a device: all of it. iOS runs MYWebAssembly only in
+ * high-performance mode (「暂不支持 iOS 普通模式」), which the export turns on.
+ *
+ * NOT CLAIMED: `pay` — `my.requestGamePayment` sells on Android and Harmony only,
+ * keyed by a `customId` the engine's request does not carry.
+ */
+import type { MiniGameGlobal, MiniGameProfile } from '../minigame';
+import type { MiniGameShareOptions } from '../minigame/api';
+import type { WasmInstantiateResult } from '../types';
+
+declare const my: Record<string, unknown>;
+declare const MYWebAssembly: { instantiate(path: string, imports: WebAssembly.Imports): Promise<WasmInstantiateResult> } | undefined;
+
+type Card = MiniGameShareOptions & { desc?: string };
+type Callbacks = { success?: (res: { code: string }) => void; fail?: (err: unknown) => void };
+
+/** Each renamed call and the host call it stands for. */
+const RENAMED_FROM = {
+ createRewardedVideoAd: 'createRewardedAd',
+ login: 'getAuthCode',
+ onShareAppMessage: 'showSharePanel',
+ shareAppMessage: 'showSharePanel',
+} as const;
+
+let passiveCard: (() => Card) | null = null;
+let activeCard: Card | null = null;
+
+function answerShare(): void {
+ my.onShareAppMessage = () => activeCard ?? passiveCard?.() ?? {};
+}
+
+/** `my` in the family's words; anything not renamed is `my`'s own, bound to it. */
+function view(): MiniGameGlobal {
+ const renamed: Record<string, unknown> = {
+ createRewardedVideoAd: (opts: { adUnitId: string }) => (my.createRewardedAd as (o: unknown) => unknown)(opts),
+ login: (opts: Callbacks) => (my.getAuthCode as (o: unknown) => void)({
+ scopes: ['auth_base'],
+ success: (res: { authCode?: string }) => opts.success?.({ code: res.authCode ?? '' }),
+ fail: opts.fail,
+ }),
+ onShareAppMessage: (provide: () => Card) => { passiveCard = provide; answerShare(); },
+ shareAppMessage: (card: Card) => {
+ activeCard = card;
+ answerShare();
+ (my.showSharePanel as (o: unknown) => void)({ complete: () => { activeCard = null; answerShare(); } });
+ },
+ };
+ return new Proxy(my, {
+ get(target, key) {
+ if (typeof key === 'string' && key in RENAMED_FROM) {
+ // Absent where the host lacks the call it stands for, as the family probes.
+ return typeof target[RENAMED_FROM[key as keyof typeof RENAMED_FROM]] === 'function' ? renamed[key] : undefined;
+ }
+ const v = target[key as string];
+ return typeof v === 'function' ? v.bind(target) : v;
+ },
+ }) as unknown as MiniGameGlobal;
+}
+
+let cached: MiniGameGlobal | null = null;
+
+export const alipayProfile: MiniGameProfile = {
+ id: 'alipay',
+ hostLabel: '支付宝',
+
+ get global(): MiniGameGlobal {
+ return (cached ??= view());
+ },
+
+ async instantiateWasm(pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports): Promise<WasmInstantiateResult> {
+ if (typeof pathOrBuffer !== 'string') throw new Error('MYWebAssembly takes a package path, not bytes');
+ if (typeof MYWebAssembly === 'undefined') {
+ throw new Error('MYWebAssembly is not available: it needs Alipay 10.7.6, and on iOS the high-performance mode');
+ }
+ const res = await MYWebAssembly.instantiate(pathOrBuffer.startsWith('/') ? pathOrBuffer : `/${pathOrBuffer}`, imports);
+ return { instance: res.instance, module: res.module };
+ },
+};
diff --git a/sdk/src/platform/minigame/api.ts b/sdk/src/platform/minigame/api.ts
index 226a9d031..5baf8b7ca 100644
--- a/sdk/src/platform/minigame/api.ts
+++ b/sdk/src/platform/minigame/api.ts
@@ -387,7 +387,7 @@ export interface MiniGameGlobal {
* never heard of and get the whole family for it. Nothing in the SDK branches on
* this value — it is identity (adapter name, diagnostics, logs), not behavior.
*/
-export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | (string & {});
+export type MiniGameVendor = 'wechat' | 'douyin' | 'kuaishou' | 'bilibili' | 'quickgame' | 'alipay' | (string & {});
/**
* A vendor described as DATA — three facts and, at most, one method.
diff --git a/sdk/tests/alipay-profile.test.ts b/sdk/tests/alipay-profile.test.ts
new file mode 100644
index 000000000..755304b84
--- /dev/null
+++ b/sdk/tests/alipay-profile.test.ts
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Alipay's `my`, as the family reads it. The profile renames rather than
+ * forks: each claim is that a family call reaches the Alipay call its docs
+ * name, with the argument shape that call takes, and is absent where the
+ * host lacks it — which is how the family decides a capability exists.
+ */
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { alipayProfile } from '../src/platform/alipay/profile';
+import { MiniGamePlatformAdapter } from '../src/platform/minigame/adapter';
+
+const host: Record<string, unknown> = {
+ createRewardedAd: vi.fn(() => ({ tag: 'rewarded' })),
+ getAuthCode: vi.fn((o: { scopes: string[]; success: (r: { authCode: string }) => void }) => o.success({ authCode: 'AUTH-123' })),
+ showSharePanel: vi.fn((o: { complete?: () => void }) => { host.panelSaw = (host.onShareAppMessage as () => unknown)(); o.complete?.(); }),
+ getSystemInfoSync: () => ({ platform: 'android' }),
+};
+
+beforeAll(() => { (globalThis as { my?: unknown }).my = host; });
+
+describe('Alipay, in the family\'s words', () => {
+ it('reaches a rewarded unit through createRewardedAd', () => {
+ const g = alipayProfile.global as unknown as { createRewardedVideoAd(o: unknown): unknown };
+ expect(g.createRewardedVideoAd({ adUnitId: 'unit' })).toEqual({ tag: 'rewarded' });
+ expect(host.createRewardedAd).toHaveBeenCalledWith({ adUnitId: 'unit' });
+ });
+
+ it('signs in through getAuthCode and hands over its authCode as the code', async () => {
+ const adapter = new MiniGamePlatformAdapter(alipayProfile);
+ expect(adapter.canSignIn()).toBe(true);
+ await expect(adapter.login()).resolves.toBe('AUTH-123');
+ expect(host.getAuthCode).toHaveBeenCalledWith(expect.objectContaining({ scopes: ['auth_base'] }));
+ });
+
+ it('shares by setting the card the host reads when its panel opens, and answers the passive menu', () => {
+ const adapter = new MiniGamePlatformAdapter(alipayProfile);
+ adapter.onShareRequest(() => ({ title: 'passive' }));
+ adapter.share({ title: 'my run', query: 'from=share' });
+ expect(host.panelSaw).toEqual({ title: 'my run', query: 'from=share' });
+ // Once the panel closes, the host's own menu shares the passive card again.
+ expect((host.onShareAppMessage as () => unknown)()).toEqual({ title: 'passive' });
+ });
+
+ it('offers nothing the host lacks, so the family reports it absent', () => {
+ const g = alipayProfile.global as unknown as Record<string, unknown>;
+ expect(g.createInterstitialAd).toBeUndefined();
+ expect(g.requestMidasPayment).toBeUndefined();
+ expect(new MiniGamePlatformAdapter(alipayProfile).canPay()).toBe(false);
+ });
+
+ it('instantiates through MYWebAssembly with an absolute package path, and says what is missing', async () => {
+ await expect(alipayProfile.instantiateWasm!('wasm/esengine.wxgame.wasm', {})).rejects.toThrow('MYWebAssembly is not available');
+ const instantiate = vi.fn(async () => ({ instance: { exports: {} }, module: {} }));
+ (globalThis as { MYWebAssembly?: unknown }).MYWebAssembly = { instantiate };
+ await alipayProfile.instantiateWasm!('wasm/esengine.wxgame.wasm', {});
+ expect(instantiate).toHaveBeenCalledWith('/wasm/esengine.wxgame.wasm', {});
+ delete (globalThis as { MYWebAssembly?: unknown }).MYWebAssembly;
+ });
+});
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index d1b0d7c58..9079917ca 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -26,7 +26,7 @@ const EXAMPLES = path.join(ROOT, 'examples');
export const TIERS = ['pr', 'nightly', 'release'];
/** Export targets a golden project can be asked to package + launch for. */
-export const TARGETS = ['web', 'playable', 'desktop', 'wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'android', 'ios'];
+export const TARGETS = ['web', 'playable', 'desktop', 'wechat', 'douyin', 'kuaishou', 'bilibili', 'quickgame', 'alipay', 'android', 'ios'];
/**
* How far a packaged frame may sit from the editor's frame of the same game.
diff --git a/tools/nativeScriptModules.js b/tools/nativeScriptModules.js
index 4d63110b6..07507aa9d 100644
--- a/tools/nativeScriptModules.js
+++ b/tools/nativeScriptModules.js
@@ -106,6 +106,10 @@ export const MODULES = {
disposition: 'forbidden-native-script',
why: "the quick-game platform profile — it names a host global (`qg`) that a native build does not have",
},
+ 'esengine/alipay': {
+ disposition: 'forbidden-native-script',
+ why: "Alipay's platform profile — it names a host global (`my`) that a native build does not have",
+ },
};
/** The `exports` subpath ("." / "./physics3d") a specifier corresponds to. */
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 489f298d5..1310ff9d5 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1002,6 +1002,10 @@ export const NOTED = {
{ note: 'A project can be packaged as a quick game' },
'fix(runtime): a WebGL2 context does not offer the WebGL1 extensions it made core':
{ note: 'A mini-game whose host\'s WebGL2 context also offers `OES_vertex_array_object` renders instead of hanging' },
+ 'feat(export): a project can be packaged for Alipay':
+ { note: 'A project can be packaged for Alipay (支付宝小游戏).' },
+ 'feat(editor): Alipay is a build target':
+ { note: 'A project can be packaged for Alipay (支付宝小游戏).' },
'fix(agent): the history toggle presses grey again, not the accent':
{ note: "The agent drawer's History button shows it is open with a grey press again, not the accent colour 0.71 gave it." },
};