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): observe MRAID readiness and viewability
yhh45da9011de86
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 367ac8a7c..6ff508319 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,8 +22,12 @@ published separately; it ships inside the editor.### Fixed+- **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.+- **MRAID playables wait for ready and viewable hosts.** Unity, AppLovin and generic MRAID exports pause gameplay and audio until the host is ready and visible, stop when hidden, and release container callbacks on exit. Browser previews still run without an ad container.++- **Pointer carets keep supplementary characters intact.** Clicking single-line, multiline or password fields no longer places the caret between the UTF-16 halves of an emoji or another supplementary code point. DOM selection offsets remain UTF-16-based, and existing prefix measurement behavior is preserved.- **Native text-input notifications survive frame boundaries.** Update systems can read browser and native Change and Submit events after UI interaction clears the previous frame. Subscription callbacks remain synchronous, including focus changes made on Submit; their records reach frame consumers without replaying callbacks. Destroyed fields and disposed editors discard queued records.diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex cafa5a85e..7b6c08818 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -111,7 +111,7 @@ selected it is a no-op, so the same scene still runs in the editor and on the we| **Meta** (Facebook / Instagram) | 2MB for `index.html` | `FbPlayableAd.onCTAClick()` | Meta's 5MB figure is the total for a ZIP bundle; a single-file playable is capped by the `index.html` rule. Forbids any HTTP request. || **Google Ads** (App campaigns) | 5MB | `ExitApi.exit()` | Its exit API is a Google-hosted script, which the docs require as a literal `<script>` in `<head>` — the export writes it for you. Google uploads a **ZIP**, so compress the `index.html` before uploading. || **MRAID network** (generic) | 5MB | `mraid.open()` | For any MRAID host. `mraid` is injected by the webview, so nothing goes in `<head>`. |-| **Unity Ads** | 5MB | `mraid.open()` | Expects the playable to wait for MRAID's `viewableChange` before starting. |+| **Unity Ads** | 5MB | `mraid.open()` | The runtime waits for MRAID readiness and viewability, pauses on hidden ads, and removes host listeners on exit. || **AppLovin** | 5MB | `mraid.open()` | Requires every resource embedded — which a single-file playable already is. || **Mintegral** | 5MB | `window.install()` | Exports embedded `index.html` and matching `index.zip`. Waits for host start; game close pauses gameplay and audio. || **TikTok / overseas Pangle** | ZIP <5MB | `window.openAppStore()` | Includes root `config.json`, each network’s orientation field, and the mandatory official SDK before game scripts. Ads Manager preview acceptance remains required. |diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 3fd95c13a..ee783e64b 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -96,7 +96,7 @@ playableCta();| **Meta**(Facebook / Instagram) | `index.html` 2MB | `FbPlayableAd.onCTAClick()` | Meta 的 5MB 是 ZIP 包的总量;单文件试玩受 `index.html` 那条约束。禁止任何 HTTP 请求。 || **Google Ads**(应用广告系列) | 5MB | `ExitApi.exit()` | 它的退出接口是 Google 托管的脚本,官方要求以字面 `<script>` 写在 `<head>` 里——导出会帮你写好。Google 上传 **ZIP**,所以要先把 `index.html` 压缩。 || **MRAID 平台**(通用) | 5MB | `mraid.open()` | 适用于任何 MRAID 宿主。`mraid` 由宿主 webview 注入,`<head>` 无需任何内容。 |-| **Unity Ads** | 5MB | `mraid.open()` | 要求试玩包等到 MRAID 的 `viewableChange` 之后再开始。 |+| **Unity Ads** | 5MB | `mraid.open()` | 运行时自动等待 MRAID ready 和 viewable,隐藏时暂停游戏及音频,退出时释放宿主监听。 || **AppLovin** | 5MB | `mraid.open()` | 要求所有资源内嵌——单文件试玩本来就是。 || **Mintegral** | 5MB | `window.install()` | 导出资源内嵌的 `index.html` 和同名 `index.zip`。等待宿主开始,关闭时暂停游戏和音频。 || **TikTok / 海外 Pangle** | ZIP <5MB | `window.openAppStore()` | 根目录包含 `config.json`,方向字段按平台区分;游戏脚本前注入官方 SDK。仍需广告管理平台预览验收,国内穿山甲另行适配。 |diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.mdindex f34ce9617..679d60fb0 100644--- a/examples/playable-ad/README.md+++ b/examples/playable-ad/README.md@@ -29,3 +29,8 @@ domestic Pangle exports. Validate uploads in the appropriate Ads Manager previewSpecifications: [TikTok](https://ads.tiktok.com/resources/help/article/playable-ads?lang=en),[overseas Pangle](https://ads.tiktok.com/resources/help/article/how-to-create-tiktok-pangle-playable-ads).++The `mraid`, `unity`, and `applovin` profiles wait for host readiness and viewability.+A hidden ad pauses gameplay and audio; cleanup removes container listeners. Plain+browser preview remains active. Network upload and device acceptance remain separate+from a local mock-container check.diff --git a/examples/playable-ad/project.esproject b/examples/playable-ad/project.esprojectindex 39f6188f1..e7e44faf7 100644--- a/examples/playable-ad/project.esproject+++ b/examples/playable-ad/project.esproject@@ -40,6 +40,30 @@}},"platform": "playable"+ },+ "mraid": {+ "platform": "playable",+ "platforms": {+ "playable": {+ "network": "mraid"+ }+ }+ },+ "unity": {+ "platform": "playable",+ "platforms": {+ "playable": {+ "network": "unity"+ }+ }+ },+ "applovin": {+ "platform": "playable",+ "platforms": {+ "playable": {+ "network": "applovin"+ }+ }}}}diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.tsindex c6b88f5d4..3b02cb55c 100644--- a/pipeline/src/export/playableAdProfile.ts+++ b/pipeline/src/export/playableAdProfile.ts@@ -121,18 +121,29 @@ export const googlePlayableProfile: PlayableAdProfile = {};/**- * The MRAID networks. `mraid` is injected by the host webview, so nothing goes in- * `<head>` — and `mraid.open()` is what the spec requires for a click-through- * (an `<a href>` or `window.open` breaks click tracking, and some exchanges reject- * it outright).- *- * Note for the game: MRAID hosts expect the playable to wait for the- * `viewableChange` event before it starts, which is the game's call to make.- * @see https://mraid.io/+ * Host-injected MRAID handles store clicks and advert viewability.+ * The runtime waits for readiness and visibility before running gameplay.+ * @see https://docs.unity.com/en-us/grow/acquire/creatives/playable/specifications*/-const mraidBridge = (): string => 'window.__ESTELLA_PLAYABLE__={cta:function(){'- + 'if(typeof mraid!=="undefined"&&mraid.open)mraid.open();'- + '}};';+const mraidBridge = (): string => `(function(){+var host=window.mraid,listeners=[],active=!host,loaded=!host,subscribed=false;+function publish(value){active=value;listeners.slice().forEach(function(fn){try{fn(value);}catch(error){console.error("[playable] lifecycle listener failed",error);}});}+function viewable(value){publish(loaded&&!!value);}+function ready(){loaded=true;if(typeof host.removeEventListener==="function")host.removeEventListener("ready",ready);publish(typeof host.isViewable==="function"&&host.isViewable());}+function subscribe(){+if(!host||subscribed||typeof host.addEventListener!=="function")return;+subscribed=true;host.addEventListener("viewableChange",viewable);+if(typeof host.getState==="function"&&host.getState()==="loading")host.addEventListener("ready",ready);else ready();+}+function unsubscribe(){+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();},+onActive:function(fn){subscribe();listeners.push(fn);fn(active);return function(){listeners=listeners.filter(function(item){return item!==fn;});if(!listeners.length)unsubscribe();};}+};+})();`;export const mraidPlayableProfile: PlayableAdProfile = {id: 'mraid',diff --git a/pipeline/tests/playable-mraid.test.ts b/pipeline/tests/playable-mraid.test.tsnew file mode 100644index 000000000..5fcb7b6b7--- /dev/null+++ b/pipeline/tests/playable-mraid.test.ts@@ -0,0 +1,47 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect, vi } from 'vitest';+import { mraidPlayableProfile, unityPlayableProfile, applovinPlayableProfile } from '../src/export/playableAdProfile';++function container(profile = mraidPlayableProfile, state = 'loading', visible = false) {+ const events = new Map<string, Set<(...args: any[]) => void>>();+ const mraid = { getState: () => state, isViewable: () => visible, open: vi.fn(),+ addEventListener: (name: string, fn: (...args: any[]) => void) => { if (!events.has(name)) events.set(name, new Set()); events.get(name)!.add(fn); },+ removeEventListener: (name: string, fn: (...args: any[]) => void) => events.get(name)?.delete(fn) };+ const window: any = { mraid };+ new Function('window', profile.emitBridge!({ title: 'T', orientation: 'portrait' }))(window);+ return { bridge: window.__ESTELLA_PLAYABLE__, mraid, events,+ ready(value: boolean) { state = 'default'; visible = value; events.get('ready')?.forEach(fn => fn()); },+ viewable(value: boolean) { visible = value; events.get('viewableChange')?.forEach(fn => fn(value)); } };+}++describe('MRAID lifecycle', () => {+ it.each([mraidPlayableProfile, unityPlayableProfile, applovinPlayableProfile])('$id waits for readiness and viewability and detaches callbacks', profile => {+ const c = container(profile), active = vi.fn(), release = c.bridge.onActive(active);+ expect(active).toHaveBeenLastCalledWith(false);+ c.viewable(true); expect(active).toHaveBeenLastCalledWith(false);+ 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();+ 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);+ });++ it('starts an already-ready visible host and supports independent subscriptions', () => {+ const c = container(mraidPlayableProfile, 'default', true), a = vi.fn(), b = vi.fn();+ const first = c.bridge.onActive(a), second = c.bridge.onActive(b);+ expect(a).toHaveBeenLastCalledWith(true); expect(b).toHaveBeenLastCalledWith(true);+ first(); c.viewable(false); expect(a).toHaveBeenLastCalledWith(true); expect(b).toHaveBeenLastCalledWith(false);+ second(); expect(c.events.get('viewableChange')?.size).toBe(0);+ c.viewable(true); const again = vi.fn(), third = c.bridge.onActive(again);+ expect(again).toHaveBeenLastCalledWith(true); third();+ });++ 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();+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 29a82001a..77fccabce 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): observe MRAID readiness and viewability':+ { note: 'MRAID playables wait for ready and viewable hosts.' },'feat(playable): package TikTok and overseas Pangle creatives':{ note: 'TikTok and overseas Pangle package the same playable project.' },'perf(ui): reuse text geometry during inherited opacity fades':