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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(playable): pass store destinations through the CTA bridge
yhh0948e006dadc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6ff508319..61bf87bcd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,8 @@ published separately; it ships inside the editor.### Fixed+- **MRAID store clicks carry their destination.** `playableCta(url)` forwards an explicit store link, with host-provided `clickTag` as the MRAID fallback. Missing and malformed destinations no longer call `mraid.open` with no URL. HTTP(S), Android market and iOS App Store schemes are supported; other networks retain their host-selected store destinations.+- **UI text fades reuse cached geometry.** Inherited opacity changes update vertex alpha without repeating glyph lookup, layout or index generation. Bitmap and SDF text retain their original fill, rich-text, shadow and outline alpha, restoring it without cumulative fading; authored color and layout changes still rebuild the cache.diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex 7b6c08818..b7d28259e 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -122,6 +122,8 @@ number to trust.For Mintegral, call `playableGameEnd()` on a win or loss and `playableRetry()` when the player restarts. The runtime calls `gameReady()` after startup finishes and responds to `gameStart()` / `gameClose()`. Keep installation tied to a user gesture through `playableCta()`. See the `playable-ad` example and [official container checker](https://www.playturbo.com/review). Passing that checker does not replace campaign approval or device acceptance.+MRAID store buttons must pass a destination with `playableCta(storeUrl)` or use a host-provided `window.clickTag`. HTTP(S), Android `market:` and iOS `itms-apps:` links are supported. Missing or invalid destinations produce a configuration warning without calling `mraid.open`. Other networks continue using their own store hooks.+### A network we don't shipDefine it yourself — the built-in networks are written against this exact contract,diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex ee783e64b..7990531de 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -106,6 +106,8 @@ playableCta();Mintegral 中,胜负结束时调用 `playableGameEnd()`,玩家重玩时调用 `playableRetry()`。运行时在启动完成后调用 `gameReady()`,并响应 `gameStart()` / `gameClose()`;安装按钮通过用户手势调用 `playableCta()`。参见 `playable-ad` 示例和[官方容器检测工具](https://www.playturbo.com/review)。检测通过仍需广告审核和真机验收。+MRAID 安装按钮须通过 `playableCta(storeUrl)` 传入目标地址,或由宿主提供 `window.clickTag`。支持 HTTP(S)、Android `market:` 和 iOS `itms-apps:` 商店链接;地址缺失或无效时提示配置问题,不调用 `mraid.open`。其他网络继续使用自己的商店接口。+### 我们没内置的平台自己定义就行——内置的那几家写的就是这份契约,没有做不到的事。**打包项目 → 新建平台** 可以diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.mdindex 679d60fb0..9c6a849db 100644--- a/examples/playable-ad/README.md+++ b/examples/playable-ad/README.md@@ -34,3 +34,9 @@ The `mraid`, `unity`, and `applovin` profiles wait for host readiness and viewabA hidden ad pauses gameplay and audio; cleanup removes container listeners. Plainbrowser preview remains active. Network upload and device acceptance remain separatefrom a local mock-container check.++For MRAID store buttons, pass your app’s destination to `playableCta(storeUrl)`+or let the ad host supply `window.clickTag`. HTTP(S), Android `market:` and iOS+`itms-apps:` store links are supported. Without a valid destination the bridge+reports the missing configuration and does not call `mraid.open`. The sample+project has no published app destination; configure yours before network acceptance.diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.tsindex 3b02cb55c..fadfe37b1 100644--- a/pipeline/src/export/playableAdProfile.ts+++ b/pipeline/src/export/playableAdProfile.ts@@ -140,7 +140,12 @@ if(!subscribed)return;subscribed=false;if(typeof host.removeEventListener==="function"){host.removeEventListener("ready",ready);host.removeEventListener("viewableChange",viewable);}}window.__ESTELLA_PLAYABLE__={-cta:function(){if(window.mraid&&typeof window.mraid.open==="function")window.mraid.open();},+cta:function(url){+var target=url===undefined?window.clickTag:url,valid=false;+try{var parsed=new URL(target);valid=typeof target==="string"&&!/\\s/.test(target)&&["http:","https:","market:","itms-apps:"].indexOf(parsed.protocol)>=0&&!!parsed.hostname;}catch(error){}+if(!valid){console.warn("[playable] MRAID CTA needs a store URL passed to playableCta(url) or supplied as clickTag.");return;}+if(window.mraid&&typeof window.mraid.open==="function")window.mraid.open(target);+},onActive:function(fn){subscribe();listeners.push(fn);fn(active);return function(){listeners=listeners.filter(function(item){return item!==fn;});if(!listeners.length)unsubscribe();};}};})();`;diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.tsindex 211d86db2..139c3079d 100644--- a/pipeline/tests/platform-catalog.test.ts+++ b/pipeline/tests/platform-catalog.test.ts@@ -401,7 +401,7 @@ describe('playable ad networks', () => {// the host webview injects mraid itself.for (const id of ['mraid', 'unity', 'applovin']) {const p = (await loadPlayableProfile(root, id))!;- expect(p.emitBridge!({ title: 'T', orientation: 'landscape' })).toContain('mraid.open()');+ expect(p.emitBridge!({ title: 'T', orientation: 'landscape' })).toContain('mraid.open(');expect(p.emitHead).toBeUndefined();}// No selection ⇒ generic, so a project that never chose still exports.diff --git a/pipeline/tests/playable-mraid.test.ts b/pipeline/tests/playable-mraid.test.tsindex 5fcb7b6b7..caad3bd9f 100644--- a/pipeline/tests/playable-mraid.test.ts+++ b/pipeline/tests/playable-mraid.test.ts@@ -23,7 +23,7 @@ describe('MRAID lifecycle', () => {c.ready(false); expect(active).toHaveBeenLastCalledWith(false);c.viewable(true); expect(active).toHaveBeenLastCalledWith(true);c.viewable(false); expect(active).toHaveBeenLastCalledWith(false);- c.bridge.cta(); expect(c.mraid.open).toHaveBeenCalledOnce();+ c.bridge.cta('https://example.com/store'); expect(c.mraid.open).toHaveBeenCalledWith('https://example.com/store');release(); expect(c.events.get('ready')?.size).toBe(0); expect(c.events.get('viewableChange')?.size).toBe(0);const previous = active.mock.calls.length; c.viewable(true); expect(active).toHaveBeenCalledTimes(previous);});@@ -38,10 +38,24 @@ describe('MRAID lifecycle', () => {expect(again).toHaveBeenLastCalledWith(true); third();});+ it('uses a host clickTag and refuses missing or unsafe destinations', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const window: any = { clickTag: 'https://example.com/store', mraid: { open: vi.fn() } };+ new Function('window', mraidPlayableProfile.emitBridge!({ title: 'T', orientation: 'portrait' }))(window);+ window.__ESTELLA_PLAYABLE__.cta(); expect(window.mraid.open).toHaveBeenCalledWith(window.clickTag);+ window.mraid.open.mockClear(); delete window.clickTag;+ for (const url of [undefined, '', 'javascript:alert(1)', 'https://example.com/with space', 'https://']) window.__ESTELLA_PLAYABLE__.cta(url);+ expect(window.mraid.open).not.toHaveBeenCalled();+ for (const url of ['market://details?id=com.example.game', 'itms-apps://itunes.apple.com/app/id123']) {+ window.__ESTELLA_PLAYABLE__.cta(url); expect(window.mraid.open).toHaveBeenLastCalledWith(url);+ }+ warn.mockRestore();+ });+it('keeps a standalone browser preview active with no MRAID container', () => {const window: any = {};new Function('window', mraidPlayableProfile.emitBridge!({ title: 'T', orientation: 'portrait' }))(window);const active = vi.fn(); window.__ESTELLA_PLAYABLE__.onActive(active);- expect(active).toHaveBeenCalledWith(true); expect(() => window.__ESTELLA_PLAYABLE__.cta()).not.toThrow();+ expect(active).toHaveBeenCalledWith(true); expect(() => window.__ESTELLA_PLAYABLE__.cta('https://example.com/store')).not.toThrow();});});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex d3bda2e21..6ab09968d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6211,7 +6211,7 @@ wasmBaseUrl: string | undefined## PlayableAdBridge — interface @experimental```-cta: (() => void) | undefined+cta: ((url?: string) => void) | undefinedgameEnd: (() => void) | undefinedonActive: ((listener: (active: boolean) => void) => () => void) | undefinedready: (() => void) | undefined@@ -12284,7 +12284,7 @@ ParticlePlugin## playableCta — function @experimental```-(): void+(url?: string): void```## playableGameEnd — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex d59f3b72f..b78d6933b 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6414,7 +6414,7 @@ wasmBaseUrl: string | undefined## PlayableAdBridge — interface @experimental```-cta: (() => void) | undefined+cta: ((url?: string) => void) | undefinedgameEnd: (() => void) | undefinedonActive: ((listener: (active: boolean) => void) => () => void) | undefinedready: (() => void) | undefined@@ -12547,7 +12547,7 @@ ParticlePlugin## playableCta — function @experimental```-(): void+(url?: string): void```## playableGameEnd — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 3030b6a04..0115504b6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6206,7 +6206,7 @@ wasmBaseUrl: string | undefined## PlayableAdBridge — interface @experimental```-cta: (() => void) | undefined+cta: ((url?: string) => void) | undefinedgameEnd: (() => void) | undefinedonActive: ((listener: (active: boolean) => void) => () => void) | undefinedready: (() => void) | undefined@@ -12289,7 +12289,7 @@ ParticlePlugin## playableCta — function @experimental```-(): void+(url?: string): void```## playableGameEnd — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ce33f6bdb..1f39a1a89 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6499,7 +6499,7 @@ wasmBaseUrl: string | undefined## PlayableAdBridge — interface @experimental```-cta: (() => void) | undefined+cta: ((url?: string) => void) | undefinedgameEnd: (() => void) | undefinedonActive: ((listener: (active: boolean) => void) => () => void) | undefinedready: (() => void) | undefined@@ -12593,7 +12593,7 @@ ParticlePlugin## playableCta — function @experimental```-(): void+(url?: string): void```## playableGameEnd — function @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 94b32edc3..417538571 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6213,7 +6213,7 @@ wasmBaseUrl: string | undefined## PlayableAdBridge — interface @experimental```-cta: (() => void) | undefined+cta: ((url?: string) => void) | undefinedgameEnd: (() => void) | undefinedonActive: ((listener: (active: boolean) => void) => () => void) | undefinedready: (() => void) | undefined@@ -12320,7 +12320,7 @@ ParticlePlugin## playableCta — function @experimental```-(): void+(url?: string): void```## playableGameEnd — function @experimentaldiff --git a/sdk/src/runtime/playableCta.ts b/sdk/src/runtime/playableCta.tsindex 09c2adeac..04de93c4a 100644--- a/sdk/src/runtime/playableCta.ts+++ b/sdk/src/runtime/playableCta.ts@@ -19,7 +19,7 @@/** What the exported page installs on `globalThis` — one method per interaction. */export interface PlayableAdBridge {/** Hand the player off to the store, the way THIS network spells it. */- cta?(): void;+ cta?(url?: string): void;ready?(): void;gameEnd?(): void;retry?(): void;@@ -35,17 +35,14 @@ export function playableAdBridge(): PlayableAdBridge | undefined {}/**- * Send the player to the store. Call it from whatever the ad's call-to-action is- * (an end-card button, a tap after the win) — once, from game code, with no- * network in sight.- *- * Silently does nothing outside a playable build, so the same scene runs in the- * editor and on the web.+ * Dispatch a user-gesture store click through the selected network.+ * MRAID accepts an explicit store URL; other hosts select their own destination.+ * Without a bridge, the scene remains playable and reports missing configuration.*/-export function playableCta(): void {+export function playableCta(url?: string): void {const cta = playableAdBridge()?.cta;if (cta) {- cta();+ cta(url);return;}if (!warned) {diff --git a/sdk/tests/playable-cta.test.ts b/sdk/tests/playable-cta.test.tsindex 9393792bc..c66f05f22 100644--- a/sdk/tests/playable-cta.test.ts+++ b/sdk/tests/playable-cta.test.ts@@ -23,6 +23,12 @@ describe('playableCta', () => {expect(cta).toHaveBeenCalledTimes(1);});+ it('forwards an explicit store URL to the network bridge', () => {+ const cta = vi.fn(); g[KEY] = { cta };+ playableCta('https://example.com/store');+ expect(cta).toHaveBeenCalledWith('https://example.com/store');+ });+it('is a no-op with no bridge, so the same scene runs on the web', () => {const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});expect(hasPlayableCta()).toBe(false);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 77fccabce..9577ca76c 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(playable): pass store destinations through the CTA bridge':+ { note: 'MRAID store clicks carry their destination.' },'fix(playable): observe MRAID readiness and viewability':{ note: 'MRAID playables wait for ready and viewable hosts.' },'feat(playable): package TikTok and overseas Pangle creatives':