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(playable): add Mintegral container lifecycle

yhh17d657fb4c1f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 049f8d417..505940c1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **Playable exports handle Mintegral start, completion and retry.** The network profile embeds resources in `index.html` and emits `index.zip`; the runtime waits for host start, pauses gameplay and audio on close, and preserves game-owned pause state. `playableGameEnd()` and `playableRetry()` report gameplay outcomes separately from installation. A responsive CC0 space fleet example demonstrates the complete flow.
+
### Fixed
- **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.
diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index 76096db0e..f156ddbc5 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -113,11 +113,14 @@ selected it is a no-op, so the same scene still runs in the editor and on the we
| **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. |
| **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. |
Limits move, so each one is reported against the network it came from: an oversized
export names the cap it used and where that number is published, rather than a bare
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.
+
### A network we don't ship
Define 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.mdx
index 6c31b28f5..9dd9d1f58 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -98,10 +98,13 @@ playableCta();
| **MRAID 平台**(通用) | 5MB | `mraid.open()` | 适用于任何 MRAID 宿主。`mraid` 由宿主 webview 注入,`<head>` 无需任何内容。 |
| **Unity Ads** | 5MB | `mraid.open()` | 要求试玩包等到 MRAID 的 `viewableChange` 之后再开始。 |
| **AppLovin** | 5MB | `mraid.open()` | 要求所有资源内嵌——单文件试玩本来就是。 |
+| **Mintegral** | 5MB | `window.install()` | 导出资源内嵌的 `index.html` 和同名 `index.zip`。等待宿主开始,关闭时暂停游戏和音频。 |
上限会变,所以每条警告都指名它用的是哪一家的上限、以及这个数字出自哪里,而不是丢一个
让你盲信的数字。
+Mintegral 中,胜负结束时调用 `playableGameEnd()`,玩家重玩时调用 `playableRetry()`。运行时在启动完成后调用 `gameReady()`,并响应 `gameStart()` / `gameClose()`;安装按钮通过用户手势调用 `playableCta()`。参见 `playable-ad` 示例和[官方容器检测工具](https://www.playturbo.com/review)。检测通过仍需广告审核和真机验收。
+
### 我们没内置的平台
自己定义就行——内置的那几家写的就是这份契约,没有做不到的事。**打包项目 → 新建平台** 可以
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 91a638b18..d01b47adb 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 103,
- "experimental": 2194,
+ "experimental": 2196,
"deprecated": 3
},
- "total": 2412,
+ "total": 2414,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/examples/README.md b/examples/README.md
index 6d87f053b..7fd5571ca 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -17,6 +17,7 @@ for your own game.
| **event-system** | ECS | Decoupled gameplay with typed events — collect, score, react. |
| **scene-flow** | Basics | Runtime scene flow — menu → level 1 → level 2 through `SceneManager` fade transitions, over a persistent shell scene. |
| **save-load** | Basics | Versioned persistence — `SaveManager` save/load with a live v1→v2 migration, plus raw `Storage` preferences. |
+| **playable-ad** | Platform | A responsive CC0 space fleet game with Mintegral start/close, completion, retry and user-gesture install controls. |
| **record-share** | Platform | Record a run, mark highlights, share the clip with the mini-game recorder — the share button hides where the host cannot share. |
| **timers-demo** | Basics | `TimerManager` delays, intervals and handles — pause/resume/cancel/reset plus `timeScale`, replacing hand-rolled `time.delta` accumulators. |
| **sprite-rendering** | Rendering | Draw sprites with rotation, tint and flipping. A SortingGroup shows a subtree taking over its members' layers. |
diff --git a/examples/playable-ad/ASSET_LICENSES.md b/examples/playable-ad/ASSET_LICENSES.md
new file mode 100644
index 000000000..d17dc1c02
--- /dev/null
+++ b/examples/playable-ad/ASSET_LICENSES.md
@@ -0,0 +1,34 @@
+# Asset licenses
+
+`assets/textures/ship_K.png`, `star_tiny.png`, and `station_C.png` are unmodified default-resolution images from Kenney Simple Space 1.0.
+
+- Source: https://kenney.nl/assets/simple-space
+- License: https://creativecommons.org/publicdomain/zero/1.0/
+
+
+
+## Original license
+
+```text
+Simple Space
+
+ Created/distributed by Kenney (www.kenney.nl)
+ Creation date: 03-03-2021
+
+ ------------------------------
+
+ License: (Creative Commons Zero, CC0)
+ http://creativecommons.org/publicdomain/zero/1.0/
+
+ This content is free to use in personal, educational and commercial projects.
+
+ Support us by crediting Kenney or www.kenney.nl (this is not mandatory)
+
+ ------------------------------
+
+ Donate: http://support.kenney.nl
+ Patreon: http://patreon.com/kenney/
+
+ Follow on Twitter for updates:
+ http://twitter.com/KenneyNL
+```
diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.md
new file mode 100644
index 000000000..77a88b619
--- /dev/null
+++ b/examples/playable-ad/README.md
@@ -0,0 +1,19 @@
+# Playable Ad
+
+Tap the three ships to complete a fleet, use the persistent install button, and
+choose Try Again to restart. The CC0 space art and responsive Canvas support
+portrait and landscape ad containers.
+
+The default playable network is Mintegral. `playableGameEnd()` marks a win;
+`playableRetry()` reports an explicit restart; `playableCta()` uses the network's
+store hook. The runtime announces loaded resources and observes host start/close
+callbacks. Game and audio pauses preserve their own user-controlled state.
+
+Open the project normally for a local preview, or export the Playable target to
+produce `index.html` and the matching `index.zip` required by the official test
+tool. A plain Web preview has no store destination. Mintegral's
+official test container supplies its own install, ready, end and retry methods.
+An offline mock verifies wiring, not ad-network approval.
+
+See [asset licenses](ASSET_LICENSES.md) and the
+[official Mintegral test guide](https://www.playturbo.com/review/doc).
diff --git a/examples/playable-ad/assets/scenes/main.esscene b/examples/playable-ad/assets/scenes/main.esscene
new file mode 100644
index 000000000..1b2a33871
--- /dev/null
+++ b/examples/playable-ad/assets/scenes/main.esscene
@@ -0,0 +1,2004 @@
+{
+ "version": 4,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [
+ 2,
+ 3,
+ 4,
+ 5,
+ 6,
+ 7,
+ 8,
+ 9,
+ 10,
+ 11,
+ 12,
+ 13,
+ 14,
+ 15,
+ 16,
+ 17,
+ 18,
+ 19,
+ 20,
+ 21,
+ 22,
+ 23,
+ 24,
+ 25,
+ 26,
+ 27,
+ 28,
+ 29,
+ 30,
+ 31
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 600,
+ "y": 600
+ },
+ "scaleMode": 2
+ }
+ },
+ {
+ "type": "UINode",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Space backdrop",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 0
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 0
+ },
+ "width": {
+ "unit": 1,
+ "value": 100
+ },
+ "height": {
+ "unit": 1,
+ "value": 100
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": 0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": 0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0.045,
+ "g": 0.065,
+ "b": 0.11,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Star 00",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 5
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 5
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Star 01",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 42
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 28
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Star 02",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 79
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 51
+ },
+ "width": {
+ "unit": 0,
+ "value": 7
+ },
+ "height": {
+ "unit": 0,
+ "value": 7
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Star 03",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 26
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 74
+ },
+ "width": {
+ "unit": 0,
+ "value": 8
+ },
+ "height": {
+ "unit": 0,
+ "value": 8
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "Star 04",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 63
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 7
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "Star 05",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 10
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 30
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 9,
+ "name": "Star 06",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 47
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 53
+ },
+ "width": {
+ "unit": 0,
+ "value": 7
+ },
+ "height": {
+ "unit": 0,
+ "value": 7
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 10,
+ "name": "Star 07",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 84
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 76
+ },
+ "width": {
+ "unit": 0,
+ "value": 8
+ },
+ "height": {
+ "unit": 0,
+ "value": 8
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 11,
+ "name": "Star 08",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 31
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 9
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 12,
+ "name": "Star 09",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 68
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 32
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 13,
+ "name": "Star 10",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 15
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 55
+ },
+ "width": {
+ "unit": 0,
+ "value": 7
+ },
+ "height": {
+ "unit": 0,
+ "value": 7
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 14,
+ "name": "Star 11",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 52
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 78
+ },
+ "width": {
+ "unit": 0,
+ "value": 8
+ },
+ "height": {
+ "unit": 0,
+ "value": 8
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 15,
+ "name": "Star 12",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 89
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 11
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 16,
+ "name": "Star 13",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 36
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 34
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 17,
+ "name": "Star 14",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 73
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 57
+ },
+ "width": {
+ "unit": 0,
+ "value": 7
+ },
+ "height": {
+ "unit": 0,
+ "value": 7
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 18,
+ "name": "Star 15",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 20
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 80
+ },
+ "width": {
+ "unit": 0,
+ "value": 8
+ },
+ "height": {
+ "unit": 0,
+ "value": 8
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 19,
+ "name": "Star 16",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 57
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 13
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 20,
+ "name": "Star 17",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 94
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 36
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 21,
+ "name": "Star 18",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 41
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 59
+ },
+ "width": {
+ "unit": 0,
+ "value": 7
+ },
+ "height": {
+ "unit": 0,
+ "value": 7
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 22,
+ "name": "Star 19",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 78
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 82
+ },
+ "width": {
+ "unit": 0,
+ "value": 8
+ },
+ "height": {
+ "unit": 0,
+ "value": 8
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -4.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 23,
+ "name": "Star 20",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 25
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 15
+ },
+ "width": {
+ "unit": 0,
+ "value": 5
+ },
+ "height": {
+ "unit": 0,
+ "value": 5
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -2.5
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 24,
+ "name": "Star 21",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 62
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 38
+ },
+ "width": {
+ "unit": 0,
+ "value": 6
+ },
+ "height": {
+ "unit": 0,
+ "value": 6
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -3.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:037162af-6f6f-4aa8-998a-e8998df36333",
+ "color": {
+ "r": 0.55,
+ "g": 0.7,
+ "b": 0.9,
+ "a": 0.6
+ },
+ "uvOffset": {
+ "x": 0.375,
+ "y": 0.375
+ },
+ "uvScale": {
+ "x": 0.25,
+ "y": 0.25
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 25,
+ "name": "Title",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 50
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 14
+ },
+ "width": {
+ "unit": 0,
+ "value": 560
+ },
+ "height": {
+ "unit": 0,
+ "value": 60
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -280.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -30.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "BUILD YOUR SPACE FLEET",
+ "fontSize": 32,
+ "align": 1,
+ "verticalAlign": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 26,
+ "name": "Instructions",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 50
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 26
+ },
+ "width": {
+ "unit": 0,
+ "value": 560
+ },
+ "height": {
+ "unit": 0,
+ "value": 40
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -280.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -20.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "Tap all three ships to prepare your fleet.",
+ "fontSize": 24,
+ "align": 1,
+ "verticalAlign": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 27,
+ "name": "Ship 1",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 20
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 45
+ },
+ "width": {
+ "unit": 0,
+ "value": 120
+ },
+ "height": {
+ "unit": 0,
+ "value": 120
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -60.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -60.0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:b6845253-c02d-4181-87c9-553cdc015943",
+ "color": {
+ "r": 0.3,
+ "g": 0.85,
+ "b": 1,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 28,
+ "name": "Ship 2",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 50
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 45
+ },
+ "width": {
+ "unit": 0,
+ "value": 120
+ },
+ "height": {
+ "unit": 0,
+ "value": 120
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -60.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -60.0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:b6845253-c02d-4181-87c9-553cdc015943",
+ "color": {
+ "r": 0.8,
+ "g": 0.5,
+ "b": 1,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 29,
+ "name": "Ship 3",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 80
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 45
+ },
+ "width": {
+ "unit": 0,
+ "value": 120
+ },
+ "height": {
+ "unit": 0,
+ "value": 120
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -60.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -60.0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:b6845253-c02d-4181-87c9-553cdc015943",
+ "color": {
+ "r": 1,
+ "g": 0.7,
+ "b": 0.25,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "Interactable",
+ "data": {
+ "enabled": true,
+ "blockRaycast": true,
+ "raycastTarget": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 30,
+ "name": "Score",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 50
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 62
+ },
+ "width": {
+ "unit": 0,
+ "value": 560
+ },
+ "height": {
+ "unit": 0,
+ "value": 44
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -280.0
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -22.0
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "0 / 3 SHIPS READY",
+ "fontSize": 24,
+ "align": 1,
+ "verticalAlign": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 31,
+ "name": "Station",
+ "parent": 1,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "unit": 1,
+ "value": 50
+ },
+ "insetTop": {
+ "unit": 1,
+ "value": 69
+ },
+ "width": {
+ "unit": 0,
+ "value": 50
+ },
+ "height": {
+ "unit": 0,
+ "value": 50
+ },
+ "marginLeft": {
+ "unit": 0,
+ "value": -25
+ },
+ "marginTop": {
+ "unit": 0,
+ "value": -25
+ },
+ "pointerEvents": 1
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 2,
+ "texture": "@uuid:8b952ff9-dbbc-4aa0-8ce0-d4290801d633",
+ "color": {
+ "r": 0.6,
+ "g": 0.75,
+ "b": 1,
+ "a": 1
+ }
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/examples/playable-ad/assets/scenes/main.esscene.meta b/examples/playable-ad/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..84622559f
--- /dev/null
+++ b/examples/playable-ad/assets/scenes/main.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "eb2cb33e-2677-4097-a1cc-d6c58216c781",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/playable-ad/assets/textures/ship_K.png b/examples/playable-ad/assets/textures/ship_K.png
new file mode 100644
index 000000000..761a6cc4f
Binary files /dev/null and b/examples/playable-ad/assets/textures/ship_K.png differ
diff --git a/examples/playable-ad/assets/textures/ship_K.png.meta b/examples/playable-ad/assets/textures/ship_K.png.meta
new file mode 100644
index 000000000..bc38f1938
--- /dev/null
+++ b/examples/playable-ad/assets/textures/ship_K.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "b6845253-c02d-4181-87c9-553cdc015943",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/playable-ad/assets/textures/star_tiny.png b/examples/playable-ad/assets/textures/star_tiny.png
new file mode 100644
index 000000000..c0647535b
Binary files /dev/null and b/examples/playable-ad/assets/textures/star_tiny.png differ
diff --git a/examples/playable-ad/assets/textures/star_tiny.png.meta b/examples/playable-ad/assets/textures/star_tiny.png.meta
new file mode 100644
index 000000000..6b5f8e988
--- /dev/null
+++ b/examples/playable-ad/assets/textures/star_tiny.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "037162af-6f6f-4aa8-998a-e8998df36333",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/playable-ad/assets/textures/station_C.png b/examples/playable-ad/assets/textures/station_C.png
new file mode 100644
index 000000000..9c7b31ace
Binary files /dev/null and b/examples/playable-ad/assets/textures/station_C.png differ
diff --git a/examples/playable-ad/assets/textures/station_C.png.meta b/examples/playable-ad/assets/textures/station_C.png.meta
new file mode 100644
index 000000000..e87537432
--- /dev/null
+++ b/examples/playable-ad/assets/textures/station_C.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "8b952ff9-dbbc-4aa0-8ce0-d4290801d633",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/playable-ad/project.esproject b/examples/playable-ad/project.esproject
new file mode 100644
index 000000000..bc11af972
--- /dev/null
+++ b/examples/playable-ad/project.esproject
@@ -0,0 +1,20 @@
+{
+ "formatVersion": "1",
+ "name": "Playable Ad",
+ "description": "CC0 space fleet playable with persistent store CTA, completion and retry notifications.",
+ "tag": "Platform",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 600,
+ "height": 600
+ },
+ "spineVersion": "none",
+ "packaging": {
+ "platforms": {
+ "playable": {
+ "network": "mintegral"
+ }
+ }
+ }
+}
diff --git a/examples/playable-ad/src/main.ts b/examples/playable-ad/src/main.ts
new file mode 100644
index 000000000..6216c76dd
--- /dev/null
+++ b/examples/playable-ad/src/main.ts
@@ -0,0 +1,56 @@
+import {
+ addStartupSystem, addSystemToSchedule, defineSystem, Res, GetWorld, Schedule, Time,
+ UIEvents, UIEventType, UIVisual, Interactable, Text, Name, createButton, px, percent,
+ playableCta, hasPlayableCta, playableGameEnd, playableRetry, type Entity,
+} from 'esengine';
+
+let selected = new Set<Entity>();
+let cta: Entity | null = null;
+let completed = false;
+
+addStartupSystem(defineSystem([Res(UIEvents), GetWorld()], (events, world) => {
+ const canvas = world.findEntityByName('Canvas');
+ const score = world.findEntityByName('Score');
+ if (canvas === null || score === null) return;
+ const ships = ['Ship 1', 'Ship 2', 'Ship 3'].map(name => world.findEntityByName(name)).filter((entity): entity is Entity => entity !== null);
+ const colors = ships.map(entity => ({ ...world.get(entity, UIVisual).color }));
+ const caption = (content: string) => world.insert(score, Text, { ...world.get(score, Text), content });
+ for (const entity of ships) events.on(entity, UIEventType.Click, () => {
+ if (selected.has(entity)) return;
+ selected.add(entity);
+ world.insert(entity, Interactable, { ...world.get(entity, Interactable), enabled: false });
+ world.insert(entity, UIVisual, { ...world.get(entity, UIVisual), color: { ...world.get(entity, UIVisual).color, a: 0.3 } });
+ caption(`${selected.size} / 3 SHIPS READY`);
+ if (selected.size === ships.length) {
+ completed = true; caption('FLEET READY! START YOUR ADVENTURE'); playableGameEnd();
+ }
+ });
+ const install = createButton({ world, events, parent: canvas, userGesture: true,
+ node: { position: 1, insetLeft: percent(22), insetTop: percent(75), width: percent(56), height: px(84) },
+ text: { content: hasPlayableCta() ? 'INSTALL GAME' : 'AD PREVIEW', fontSize: 28, color: { r: 0.1, g: 0.075, b: 0.14, a: 1 } },
+ background: { color: { r: 1, g: 0.66, b: 0.23, a: 1 } },
+ states: { normal: { color: { r: 1, g: 0.66, b: 0.23, a: 1 } }, hover: { color: { r: 1, g: 0.79, b: 0.4, a: 1 } },
+ pressed: { color: { r: 0.84, g: 0.48, b: 0.15, a: 1 } } },
+ onClick: () => { if (hasPlayableCta()) playableCta(); else caption('Export a network playable to test install.'); },
+ });
+ cta = install.entity; world.insert(cta, Name, { value: 'Install' });
+ const retry = createButton({ world, events, parent: canvas, userGesture: true,
+ node: { position: 1, insetLeft: percent(33), insetBottom: px(12), width: percent(34), height: px(38) },
+ text: { content: 'TRY AGAIN', fontSize: 20 },
+ onClick: () => {
+ if (!completed) return;
+ playableRetry(); selected.clear(); completed = false; caption('0 / 3 SHIPS READY');
+ ships.forEach((entity, index) => {
+ world.insert(entity, Interactable, { ...world.get(entity, Interactable), enabled: true });
+ world.insert(entity, UIVisual, { ...world.get(entity, UIVisual), color: colors[index] });
+ });
+ },
+ });
+ world.insert(retry.entity, Name, { value: 'Retry' });
+}, { name: 'PlayableFleetSetup' }));
+
+addSystemToSchedule(Schedule.Update, defineSystem([Res(Time), GetWorld()], (time, world) => {
+ if (!completed || cta === null || !world.valid(cta)) return;
+ const pulse = 0.8 + Math.sin(time.elapsed * 5) * 0.2;
+ world.insert(cta, UIVisual, { ...world.get(cta, UIVisual), color: { r: 1, g: 0.62 + pulse * 0.16, b: 0.23, a: 1 } });
+}, { name: 'PlayableInstallPrompt' }));
diff --git a/examples/playable-ad/thumbnail.png b/examples/playable-ad/thumbnail.png
new file mode 100644
index 000000000..bf33b49be
Binary files /dev/null and b/examples/playable-ad/thumbnail.png differ
diff --git a/examples/playable-ad/thumbnail.png.meta b/examples/playable-ad/thumbnail.png.meta
new file mode 100644
index 000000000..aaa981b82
--- /dev/null
+++ b/examples/playable-ad/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "05fc9020-4f42-4ddb-864e-13c5560407d5",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/playable-ad/tsconfig.json b/examples/playable-ad/tsconfig.json
new file mode 100644
index 000000000..cc35d6c03
--- /dev/null
+++ b/examples/playable-ad/tsconfig.json
@@ -0,0 +1,37 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/spine": ["./.esengine/sdk/spine/index.d.ts"],
+ "esengine/tilemap": ["./.esengine/sdk/tilemap/index.d.ts"],
+ "esengine/logic": ["./.esengine/sdk/logic/index.d.ts"],
+ "esengine/debug-channel": ["./.esengine/sdk/debug-channel/index.d.ts"],
+ "esengine/ai": ["./.esengine/sdk/ai/index.d.ts"],
+ "esengine/replication": ["./.esengine/sdk/net/replication/index.d.ts"],
+ "esengine/gameplay": ["./.esengine/sdk/gameplay/index.d.ts"],
+ "esengine/dragonbones": ["./.esengine/sdk/dragonbones/index.d.ts"],
+ "esengine/physics": ["./.esengine/sdk/physics/index.d.ts"],
+ "esengine/physics3d": ["./.esengine/sdk/physics3d/index.d.ts"],
+ "esengine/douyin": ["./.esengine/sdk/douyin/index.d.ts"],
+ "esengine/kuaishou": ["./.esengine/sdk/kuaishou/index.d.ts"],
+ "esengine/bilibili": ["./.esengine/sdk/bilibili/index.d.ts"],
+ "esengine/quickgame": ["./.esengine/sdk/quickgame/index.d.ts"],
+ "esengine/alipay": ["./.esengine/sdk/alipay/index.d.ts"],
+ "esengine/huawei": ["./.esengine/sdk/huawei/index.d.ts"],
+ "estella-plugin-*": ["./.esengine/packages/*"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 46125b11b..d6cd0a469 100644
--- a/pipeline/src/export/exportPlayable.ts
+++ b/pipeline/src/export/exportPlayable.ts
@@ -33,7 +33,7 @@ import { esengineAlias } from '../bundle/esengineResolve';
import { officialPackagesPlugin } from '../bundle/officialPackages';
import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';
import type { ScreenOrientation } from './orientationHtml';
-import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';
+import { genericPlayableProfile, playableAdInjection, isPlayableZipFileName, type PlayableAdProfile } from './playableAdProfile';
import { makeZip } from '../../../build-tools/utils/zip.js';
import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';
import { forcedSideModules, moduleChoices } from '../bundle/engineInstalls';
@@ -389,6 +389,9 @@ export async function exportPlayable(opts: {
await rm(cookDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
const htmlBytes = (await stat(outFile)).size;
+ if (adProfile.maxHtmlBytes !== undefined && htmlBytes > adProfile.maxHtmlBytes) {
+ errors.push(`${adProfile.label}: index.html is ${htmlBytes} bytes, exceeding the uncompressed HTML limit of ${adProfile.maxHtmlBytes} bytes. ${adProfile.limitNote}`);
+ }
// The page, plus the JSON scaffolding around the spans. Derived rather than
// summed, so the parts add up to the file whatever the assembly gains later.
const inlined = spans.reduce((n, s) => n + s.bytes, 0);
@@ -401,10 +404,14 @@ export async function exportPlayable(opts: {
let bytes = htmlBytes;
if (adProfile.delivery === 'zip') {
progress({ phase: 'Archiving' });
- zipFile = path.join(absOut, 'playable.zip');
- await writeFile(zipFile, makeZip([{ name: 'index.html', data: await readFile(outFile) }]));
- // The archive is the file being sent, so it is the one the limit applies to.
- bytes = (await stat(zipFile)).size;
+ const zipName = adProfile.zipFileName ?? 'playable.zip';
+ if (!isPlayableZipFileName(zipName)) errors.push('Playable ZIP filename must be a portable name ending in .zip, without directories.');
+ else {
+ zipFile = path.join(absOut, zipName);
+ await writeFile(zipFile, makeZip([{ name: 'index.html', data: await readFile(outFile) }]));
+ // The archive is the file being sent, so it is the one the limit applies to.
+ bytes = (await stat(zipFile)).size;
+ }
}
// A full WASM engine + assets routinely exceeds what a network accepts, and this
diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.ts
index 80b2d7aec..f06205560 100644
--- a/pipeline/src/export/platformCatalog.ts
+++ b/pipeline/src/export/platformCatalog.ts
@@ -27,7 +27,7 @@ import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { defaultMiniGameEntry } from './miniGameExportProfile';
import {
- BUILTIN_PLAYABLE_PROFILES, builtinPlayableProfile, genericPlayableProfile,
+ BUILTIN_PLAYABLE_PROFILES, builtinPlayableProfile, genericPlayableProfile, isPlayableZipFileName,
type PlayableAdProfile,
} from './playableAdProfile';
import { BUILTIN_PLATFORMS, DESKTOP_OSES, compileTargetFor, desktopTemplateFor, type PlatformPrereq } from '../project/platforms';
@@ -500,12 +500,18 @@ async function importPlatformModule(
if (typeof candidate.maxBytes !== 'number' || !(candidate.maxBytes > 0)) {
return { error: 'playable profile needs a positive `maxBytes` (the size this network accepts)' };
}
+ if (candidate.maxHtmlBytes !== undefined && (!Number.isFinite(candidate.maxHtmlBytes) || candidate.maxHtmlBytes <= 0)) {
+ return { error: 'playable profile needs a positive finite `maxHtmlBytes`' };
+ }
if (typeof candidate.limitNote !== 'string' || !candidate.limitNote) {
return { error: 'playable profile needs a `limitNote` saying where `maxBytes` comes from' };
}
if (candidate.delivery !== undefined && candidate.delivery !== 'single-html' && candidate.delivery !== 'zip') {
return { error: `\`delivery\` must be 'single-html' or 'zip' (got ${JSON.stringify(candidate.delivery)})` };
}
+ if (candidate.zipFileName !== undefined && !isPlayableZipFileName(candidate.zipFileName)) {
+ return { error: '`zipFileName` must be a portable alphanumeric/underscore ZIP filename' };
+ }
return { mod: candidate };
}
if (typeof candidate.emitConfigFiles !== 'function') return { error: 'profile has no `emitConfigFiles(ctx)`' };
@@ -623,7 +629,9 @@ export async function loadPlayableProfile(root: string | null, id: string | unde
label: mod.label,
maxBytes: mod.maxBytes as number,
limitNote: mod.limitNote as string,
+ maxHtmlBytes: mod.maxHtmlBytes,
delivery: mod.delivery,
+ zipFileName: mod.zipFileName,
deliveryNote: mod.deliveryNote,
emitHead: mod.emitHead,
emitBridge: mod.emitBridge,
diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.ts
index 5ef4e66aa..377b55cc2 100644
--- a/pipeline/src/export/playableAdProfile.ts
+++ b/pipeline/src/export/playableAdProfile.ts
@@ -16,6 +16,11 @@
*/
import type { ScreenOrientation } from './orientationHtml';
+export function isPlayableZipFileName(value: unknown): value is string {
+ return typeof value === 'string' && /^[A-Za-z0-9_]+\.zip$/.test(value)
+ && !/^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])\.zip$/i.test(value);
+}
+
/** Neutral facts the pipeline computed, handed to a profile's emitters. */
export interface PlayableAdContext {
title: string;
@@ -33,6 +38,8 @@ export interface PlayableAdProfile {
* rather than a constant.
*/
readonly maxBytes: number;
+ /** Optional uncompressed HTML limit in addition to the uploaded archive limit. */
+ readonly maxHtmlBytes?: number;
/** Where {@link maxBytes} comes from, quoted in the warning so a developer can
* check it against the network's current docs rather than trusting us. */
readonly limitNote: string;
@@ -43,6 +50,8 @@ export interface PlayableAdProfile {
* Default `'single-html'`.
*/
readonly delivery?: 'single-html' | 'zip';
+ /** Portable archive filename; defaults to playable.zip. */
+ readonly zipFileName?: string;
/** Anything else the developer must know before uploading. Reported as a
* warning, because an export that looks finished but isn't is worse. */
readonly deliveryNote?: string;
@@ -149,6 +158,32 @@ export const applovinPlayableProfile: PlayableAdProfile = {
emitBridge: mraidBridge,
};
+/** @see https://www.playturbo.com/review/doc */
+export const mintegralPlayableProfile: PlayableAdProfile = {
+ id: 'mintegral',
+ label: 'Mintegral',
+ maxBytes: 5 * 1024 * 1024,
+ maxHtmlBytes: 5 * 1024 * 1024,
+ limitNote: 'Mintegral accepts an embedded HTML playable up to 5MB',
+ delivery: 'zip',
+ zipFileName: 'index.zip',
+ deliveryNote: 'Call playableGameEnd() on win or loss, and playableRetry() when restarting. Mintegral supplies the store, ready and lifecycle hooks.',
+ emitBridge: () => `(function(){
+var active=typeof window.gameReady!=="function",listeners=[],ready=false;
+var oldStart=window.gameStart,oldClose=window.gameClose;
+function visibility(value){active=value;listeners.slice().forEach(function(fn){try{fn(value);}catch(error){console.error("[playable] lifecycle listener failed",error);}});}
+window.gameStart=function(){visibility(true);if(typeof oldStart==="function")oldStart.apply(this,arguments);};
+window.gameClose=function(){visibility(false);if(typeof oldClose==="function")oldClose.apply(this,arguments);};
+window.__ESTELLA_PLAYABLE__={
+cta:function(){if(typeof window.install==="function")window.install();},
+ready:function(){if(ready)return;ready=true;if(typeof window.gameReady==="function")window.gameReady();else visibility(true);},
+gameEnd:function(){if(typeof window.gameEnd==="function")window.gameEnd();},
+retry:function(){if(typeof window.gameRetry==="function")window.gameRetry();},
+onActive:function(fn){listeners.push(fn);fn(active);return function(){listeners=listeners.filter(function(item){return item!==fn;});};}
+};
+})();`,
+};
+
/** The networks the editor ships, by id. A network absent here is not unsupported:
* a project defines its own with the same contract (`kind: 'playable'`). */
export const BUILTIN_PLAYABLE_PROFILES: readonly PlayableAdProfile[] = [
@@ -158,6 +193,7 @@ export const BUILTIN_PLAYABLE_PROFILES: readonly PlayableAdProfile[] = [
mraidPlayableProfile,
unityPlayableProfile,
applovinPlayableProfile,
+ mintegralPlayableProfile,
];
export function builtinPlayableProfile(id: string | undefined): PlayableAdProfile | null {
diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.ts
index 54efccb15..80f1cd892 100644
--- a/pipeline/tests/export-playable.test.ts
+++ b/pipeline/tests/export-playable.test.ts
@@ -232,7 +232,7 @@ describe('exportGame (playable)', () => {
// A zip-delivery network gets an archive with index.html at the root, and the cap
// then applies to the ARCHIVE — the file actually being uploaded.
- it('writes playable.zip for a zip-delivery network and measures that', async () => {
+ it.each([undefined, 'index.zip'])('writes the selected ZIP filename (%s) and measures that', async (zipFileName) => {
const o = path.join(root, 'dist-playable-zip');
const res = await exportGame({
root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES, scriptsEntry: 'src/main.ts',
@@ -240,12 +240,12 @@ describe('exportGame (playable)', () => {
outDir: o, platform: 'playable',
playableAdProfile: {
id: 'zipnet', label: 'Zip Net', maxBytes: 5 * 1024 * 1024,
- limitNote: 'Zip Net docs', delivery: 'zip',
+ limitNote: 'Zip Net docs', delivery: 'zip', zipFileName,
},
});
expect(res.ok).toBe(true);
- const zip = path.join(o, 'playable.zip');
+ const zip = path.join(o, zipFileName ?? 'playable.zip');
expect(existsSync(zip)).toBe(true);
// The HTML stays: it is what "Preview over http" serves.
expect(existsSync(path.join(o, 'index.html'))).toBe(true);
@@ -260,10 +260,22 @@ describe('exportGame (playable)', () => {
expect(sized.bytes).toBeLessThan(sized.htmlBytes);
// The archive is what the limit is measured against, and it is NOT counted a
// second time as a file sitting in the output dir.
- expect(res.size?.deliverableName).toBe('playable.zip');
+ expect(res.size?.deliverableName).toBe(zipFileName ?? 'playable.zip');
expect(res.size?.deliverableBytes).toBe(sized.bytes);
}, 60_000);
+ it('rejects an oversized HTML even when a ZIP is the uploaded file', async () => {
+ const res = await exportGame({
+ root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
+ scriptsEntry: 'src/main.ts', sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'html-cap'), platform: 'playable',
+ playableAdProfile: { id: 'htmlcap', label: 'HTML cap', maxBytes: 5 * 1024 * 1024,
+ maxHtmlBytes: 1, limitNote: 'HTML cap docs', delivery: 'zip' },
+ });
+ expect(res.ok).toBe(false);
+ expect(res.errors.join('\n')).toMatch(/uncompressed HTML limit/);
+ }, 60_000);
+
it('injects nothing and keeps the default cap with no network selected', async () => {
const o = path.join(root, 'dist-playable-generic');
const res = await exportGame({
diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.ts
index aa1bfc6e6..6c1163e01 100644
--- a/pipeline/tests/platform-catalog.test.ts
+++ b/pipeline/tests/platform-catalog.test.ts
@@ -363,7 +363,7 @@ describe('playable ad networks', () => {
};`);
const rows = await listPlayableNetworks(root);
expect(rows.filter((r) => r.source === 'builtin').map((r) => r.id))
- .toEqual(['generic', 'meta', 'google', 'mraid', 'unity', 'applovin']);
+ .toEqual(['generic', 'meta', 'google', 'mraid', 'unity', 'applovin', 'mintegral']);
// A project network names the file that defines it, so the dialog can point at it
// (and at the error, when one fails to load). Built-ins have no file.
expect(rows.find((r) => r.id === 'acme-ads')).toMatchObject({
@@ -429,6 +429,15 @@ describe('playable ad networks', () => {
expect(row!.error).toMatch(/delivery/);
});
+ it('rejects ZIP filenames that escape the export directory', async () => {
+ writePlatform('unsafe-zip.mjs', `export default {
+ id: 'unsafe-zip', kind: 'playable', label: 'Unsafe ZIP', maxBytes: 100, limitNote: 'x',
+ delivery: 'zip', zipFileName: '../escape.zip',
+ };`);
+ const row = (await listPlayableNetworks(root)).find((r) => r.id === 'unsafe-zip');
+ expect(row!.error).toMatch(/zipFileName/);
+ });
+
it('rejects a playable profile missing the facts the warning needs', async () => {
writePlatform('bad.mjs', "export default { id: 'bad', kind: 'playable', label: 'Bad' };");
const row = (await listPlayableNetworks(root)).find((r) => r.id === 'bad');
diff --git a/pipeline/tests/playable-mintegral.test.ts b/pipeline/tests/playable-mintegral.test.ts
new file mode 100644
index 000000000..23131b409
--- /dev/null
+++ b/pipeline/tests/playable-mintegral.test.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect, vi } from 'vitest';
+import { mintegralPlayableProfile, isPlayableZipFileName } from '../src/export/playableAdProfile';
+
+function host(withContainer = true) {
+ const window = {
+ install: withContainer ? vi.fn() : undefined,
+ gameReady: withContainer ? vi.fn() : undefined,
+ gameEnd: withContainer ? vi.fn() : undefined,
+ gameRetry: withContainer ? vi.fn() : undefined,
+ gameStart: undefined as (() => void) | undefined,
+ gameClose: undefined as (() => void) | undefined,
+ __ESTELLA_PLAYABLE__: undefined as {
+ cta(): void; ready(): void; gameEnd(): void; retry(): void;
+ onActive(listener: (active: boolean) => void): () => void;
+ } | undefined,
+ };
+ new Function('window', mintegralPlayableProfile.emitBridge!({ title: 'Demo', orientation: 'portrait' }))(window);
+ return window;
+}
+
+describe('Mintegral profile', () => {
+ it('uses a same-basename ZIP and rejects unsafe archive paths', () => {
+ expect(mintegralPlayableProfile.zipFileName).toBe('index.zip');
+ expect(isPlayableZipFileName('custom_1.zip')).toBe(true);
+ for (const name of ['../escape.zip', 'C:\\escape.zip', '/escape.zip', 'CON.zip', 'LPT1.zip', 'archive.html', '', null]) {
+ expect(isPlayableZipFileName(name)).toBe(false);
+ }
+ });
+
+ it('waits for host start, announces loaded resources once, and releases listeners', () => {
+ const window = host(), active = vi.fn(), bridge = window.__ESTELLA_PLAYABLE__!;
+ const release = bridge.onActive(active);
+ expect(active).toHaveBeenLastCalledWith(false);
+ bridge.ready(); bridge.ready(); expect(window.gameReady).toHaveBeenCalledTimes(1);
+ window.gameStart!(); expect(active).toHaveBeenLastCalledWith(true);
+ window.gameClose!(); expect(active).toHaveBeenLastCalledWith(false);
+ release(); const calls = active.mock.calls.length;
+ window.gameStart!(); expect(active).toHaveBeenCalledTimes(calls);
+ });
+
+ it('uses the host install/end/retry APIs without synthesizing a win on CTA', () => {
+ const window = host(), bridge = window.__ESTELLA_PLAYABLE__!;
+ bridge.cta(); expect(window.install).toHaveBeenCalledTimes(1);
+ expect(window.gameEnd).not.toHaveBeenCalled();
+ bridge.gameEnd(); bridge.retry();
+ expect(window.gameEnd).toHaveBeenCalledTimes(1); expect(window.gameRetry).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps a local preview active when no ad container exists', () => {
+ const bridge = host(false).__ESTELLA_PLAYABLE__!, active = vi.fn();
+ bridge.onActive(active); expect(active).toHaveBeenLastCalledWith(true);
+ expect(() => { bridge.ready(); bridge.cta(); bridge.gameEnd(); bridge.retry(); }).not.toThrow();
+ });
+});
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index df51120eb..d3bda2e21 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1578 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1580 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6212,6 +6212,10 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
cta: (() => void) | undefined
+gameEnd: (() => void) | undefined
+onActive: ((listener: (active: boolean) => void) => () => void) | undefined
+ready: (() => void) | undefined
+retry: (() => void) | undefined
```
## PlayableRuntimeConfig — interface @experimental
@@ -12283,6 +12287,16 @@ ParticlePlugin
(): void
```
+## playableGameEnd — function @experimental
+```
+(): void
+```
+
+## playableRetry — function @experimental
+```
+(): void
+```
+
## playheadRuns — function @experimental
```
(from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean): PlayheadRun[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 5155945af..d59f3b72f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 96 beta · 1597 experimental · 3 deprecated
+Symbols: 115 public · 96 beta · 1599 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6415,6 +6415,10 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
cta: (() => void) | undefined
+gameEnd: (() => void) | undefined
+onActive: ((listener: (active: boolean) => void) => () => void) | undefined
+ready: (() => void) | undefined
+retry: (() => void) | undefined
```
## PlayableRuntimeConfig — interface @experimental
@@ -12546,6 +12550,16 @@ ParticlePlugin
(): void
```
+## playableGameEnd — function @experimental
+```
+(): void
+```
+
+## playableRetry — function @experimental
+```
+(): void
+```
+
## playheadRuns — function @experimental
```
(from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean): PlayheadRun[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index c199e3f59..3030b6a04 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 93 beta · 1577 experimental · 3 deprecated
+Symbols: 115 public · 93 beta · 1579 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6207,6 +6207,10 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
cta: (() => void) | undefined
+gameEnd: (() => void) | undefined
+onActive: ((listener: (active: boolean) => void) => () => void) | undefined
+ready: (() => void) | undefined
+retry: (() => void) | undefined
```
## PlayableRuntimeConfig — interface @experimental
@@ -12288,6 +12292,16 @@ ParticlePlugin
(): void
```
+## playableGameEnd — function @experimental
+```
+(): void
+```
+
+## playableRetry — function @experimental
+```
+(): void
+```
+
## playheadRuns — function @experimental
```
(from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean): PlayheadRun[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 49b449185..ce33f6bdb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1599 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1601 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6500,6 +6500,10 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
cta: (() => void) | undefined
+gameEnd: (() => void) | undefined
+onActive: ((listener: (active: boolean) => void) => () => void) | undefined
+ready: (() => void) | undefined
+retry: (() => void) | undefined
```
## PlayableRuntimeConfig — interface @experimental
@@ -12592,6 +12596,16 @@ ParticlePlugin
(): void
```
+## playableGameEnd — function @experimental
+```
+(): void
+```
+
+## playableRetry — function @experimental
+```
+(): void
+```
+
## playheadRuns — function @experimental
```
(from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean): PlayheadRun[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index efaf38d51..94b32edc3 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1590 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1592 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6214,6 +6214,10 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
cta: (() => void) | undefined
+gameEnd: (() => void) | undefined
+onActive: ((listener: (active: boolean) => void) => () => void) | undefined
+ready: (() => void) | undefined
+retry: (() => void) | undefined
```
## PlayableRuntimeConfig — interface @experimental
@@ -12319,6 +12323,16 @@ ParticlePlugin
(): void
```
+## playableGameEnd — function @experimental
+```
+(): void
+```
+
+## playableRetry — function @experimental
+```
+(): void
+```
+
## playheadRuns — function @experimental
```
(from: number, to: number, duration: number, mode: WrapMode, inclusiveStart: boolean): PlayheadRun[]
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index a7fc211b4..76a0969fc 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -6,6 +6,7 @@
*/
import { World } from '../ecs/world';
+
import { installQuality } from '../render/qualityRuntime';
import type { QualityConfig } from '../render/quality';
import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';
@@ -55,6 +56,21 @@ import type { SideModuleHost } from '../sideModules/host';
import { watchWebGPUDeviceLoss } from '../render/renderer';
import { log } from '../util/logger';
+const hostPauseOwners = new WeakMap<App, Set<object>>();
+
+/** Internal host pause ownership, independent of the game's setPaused intent. */
+export function setAppHostPaused(app: App, owner: object, paused: boolean): void {
+ if (paused) {
+ let owners = hostPauseOwners.get(app);
+ if (!owners) hostPauseOwners.set(app, owners = new Set());
+ owners.add(owner);
+ } else {
+ const owners = hostPauseOwners.get(app);
+ owners?.delete(owner);
+ if (!owners?.size) hostPauseOwners.delete(app);
+ }
+}
+
// =============================================================================
// Plugin Interface
// =============================================================================
@@ -847,7 +863,7 @@ export class App {
}
isPaused(): boolean {
- return this.user_paused_;
+ return this.user_paused_ || !!hostPauseOwners.get(this)?.size;
}
stepFrame(): void {
@@ -1182,7 +1198,7 @@ export class App {
try {
await this.frameInFlight_;
this.user_paused_ = false;
- for (let i = 0; i < frames; i++) await this.tick(dt);
+ for (let i = 0; i < frames; i++) { this.step_pending_ = true; await this.tick(dt); }
} finally {
this.user_paused_ = wasPaused;
if (wasRunning && version === this.loopVersion_) {
@@ -1398,7 +1414,7 @@ export class App {
this.world_.resetQueryPool();
this.frame_paused_ = false;
- if (this.user_paused_ && !this.step_pending_) {
+ if (this.isPaused() && !this.step_pending_) {
await this.runSchedule(Schedule.Last);
} else {
await this.runSchedule(Schedule.First);
@@ -1773,7 +1789,7 @@ export class App {
const time = this.resources_.get(Time);
const scale = time.scale >= 0 ? time.scale : 0;
time.unscaledDelta = delta;
- time.delta = delta * scale;
+ time.delta = hostPauseOwners.get(this)?.size && !this.step_pending_ ? 0 : delta * scale;
time.elapsed += time.delta;
time.frameCount++;
time.fixedDelta = this.fixedTimestep_;
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index 34e329077..4c0f6de35 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -7,6 +7,16 @@ import { defineResource } from '../ecs/resource';
import { RuntimeConfig } from '../defaults';
import { log } from '../util/logger';
+const hostSuspensions = new WeakMap<AudioAPI, { owners: Set<object>; sync(): void }>();
+
+/** Internal host suspension, preserving explicit Audio.suspend/resume intent. */
+export function setAudioHostSuspended(audio: AudioAPI, owner: object, suspended: boolean): void {
+ const state = hostSuspensions.get(audio);
+ if (!state) return;
+ if (suspended) state.owners.add(owner); else state.owners.delete(owner);
+ state.sync();
+}
+
/**
* One decoded buffer's residency record. Mirrors the texture pool's
* three-state lifecycle: held (refCount > 0, pinned by Assets) →
@@ -125,6 +135,7 @@ export class AudioAPI {
private readonly fadingOut_ = new Set<AudioHandle>();
private disposed_ = false;
private suspended_ = false;
+ private deviceSuspended_ = false;
private assetResolver_: ((url: string) => ArrayBuffer | null) | null = null;
private refResolver_: ((ref: string) => string) | null = null;
baseUrl = '';
@@ -132,6 +143,7 @@ export class AudioAPI {
constructor(backend: PlatformAudioBackend, mixer: AudioMixer | null = null) {
this.backend_ = backend;
this.mixer_ = mixer;
+ hostSuspensions.set(this, { owners: new Set(), sync: () => this.syncHostSuspension_() });
}
/** What this platform's backend needs in order to play a clip — asked by the
@@ -475,12 +487,22 @@ export class AudioAPI {
suspend(): void {
this.backend_.suspend();
this.suspended_ = true;
+ this.deviceSuspended_ = true;
}
/** Resume the audio device after {@link suspend}. */
resume(): void {
- this.backend_.resume();
this.suspended_ = false;
+ if (!hostSuspensions.get(this)?.owners.size) {
+ this.backend_.resume(); this.deviceSuspended_ = false;
+ }
+ }
+
+ private syncHostSuspension_(): void {
+ const suspended = this.suspended_ || !!hostSuspensions.get(this)?.owners.size;
+ if (this.disposed_ || suspended === this.deviceSuspended_) return;
+ this.deviceSuspended_ = suspended;
+ if (suspended) this.backend_.suspend(); else this.backend_.resume();
}
setMasterVolume(volume: number): void {
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 64ffb28f2..a3177e441 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -339,6 +339,8 @@ export {
export {
playableCta,
hasPlayableCta,
+ playableGameEnd,
+ playableRetry,
type PlayableAdBridge,
} from './runtime/playableCta';
diff --git a/sdk/src/runtime/playableCta.ts b/sdk/src/runtime/playableCta.ts
index 4f598937b..09c2adeac 100644
--- a/sdk/src/runtime/playableCta.ts
+++ b/sdk/src/runtime/playableCta.ts
@@ -20,13 +20,17 @@
export interface PlayableAdBridge {
/** Hand the player off to the store, the way THIS network spells it. */
cta?(): void;
+ ready?(): void;
+ gameEnd?(): void;
+ retry?(): void;
+ onActive?(listener: (active: boolean) => void): () => void;
}
const GLOBAL_KEY = '__ESTELLA_PLAYABLE__';
let warned = false;
-function bridge(): PlayableAdBridge | undefined {
+export function playableAdBridge(): PlayableAdBridge | undefined {
return (globalThis as Record<string, unknown>)[GLOBAL_KEY] as PlayableAdBridge | undefined;
}
@@ -39,7 +43,7 @@ function bridge(): PlayableAdBridge | undefined {
* editor and on the web.
*/
export function playableCta(): void {
- const cta = bridge()?.cta;
+ const cta = playableAdBridge()?.cta;
if (cta) {
cta();
return;
@@ -54,5 +58,11 @@ export function playableCta(): void {
/** Whether an ad-network bridge is installed — for a game that wants to hide its
* store button when there is nowhere to send the player. */
export function hasPlayableCta(): boolean {
- return typeof bridge()?.cta === 'function';
+ return typeof playableAdBridge()?.cta === 'function';
}
+
+/** Notify the ad container when the game reaches a win or loss. */
+export function playableGameEnd(): void { playableAdBridge()?.gameEnd?.(); }
+
+/** Notify the ad container when the player explicitly restarts the game. */
+export function playableRetry(): void { playableAdBridge()?.retry?.(); }
diff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.ts
index ed16adf81..dad5a5415 100644
--- a/sdk/src/runtime/playableRuntime.ts
+++ b/sdk/src/runtime/playableRuntime.ts
@@ -11,6 +11,7 @@
* entry only owns the embedded asset source + the runtime boot.
*/
import type { App } from '../app/app';
+import { setAppHostPaused } from '../app/app';
import type { ESEngineModule } from '../wasm';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import { initRuntime } from './runtimeLoader';
@@ -20,7 +21,9 @@ import { EmbeddedBackend } from '../asset/Backend';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
-import { Audio } from '../audio/Audio';
+import { Audio, setAudioHostSuspended } from '../audio/Audio';
+import { Input, inputEventCallbacks } from '../input/input';
+import { playableAdBridge } from './playableCta';
import { VideoPlayer } from '../video/VideoAPI';
export interface PlayableRuntimeConfig {
@@ -160,5 +163,26 @@ export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promis
aspectRatio: config.canvas.width / config.canvas.height,
});
- app.run();
+ const bridge = playableAdBridge();
+ if (bridge?.onActive) {
+ const owner = {};
+ let release: (() => void) | undefined;
+ app.addPlugin({
+ name: 'playable-network-lifecycle',
+ build() {
+ release = bridge.onActive!(active => {
+ setAppHostPaused(app, owner, !active);
+ if (app.hasResource(Input)) inputEventCallbacks(app.getResource(Input)).onInputCancel?.();
+ if (app.hasResource(Audio)) setAudioHostSuspended(app.getResource(Audio), owner, !active);
+ });
+ },
+ cleanup() {
+ release?.();
+ setAppHostPaused(app, owner, false);
+ if (app.hasResource(Audio)) setAudioHostSuspended(app.getResource(Audio), owner, false);
+ },
+ });
+ }
+ await app.run();
+ bridge?.ready?.();
}
diff --git a/sdk/tests/playable-cta.test.ts b/sdk/tests/playable-cta.test.ts
index fa81be17b..9393792bc 100644
--- a/sdk/tests/playable-cta.test.ts
+++ b/sdk/tests/playable-cta.test.ts
@@ -6,7 +6,7 @@
* no bridge must stay playable rather than throw.
*/
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { playableCta, hasPlayableCta } from '../src/runtime/playableCta';
+import { playableCta, hasPlayableCta, playableGameEnd, playableRetry } from '../src/runtime/playableCta';
const KEY = '__ESTELLA_PLAYABLE__';
const g = globalThis as Record<string, unknown>;
@@ -39,4 +39,14 @@ describe('playableCta', () => {
expect(hasPlayableCta()).toBe(false);
expect(() => playableCta()).not.toThrow();
});
+
+ it('notifies completion and retry separately from store clicks', () => {
+ const gameEnd = vi.fn(), retry = vi.fn(), cta = vi.fn();
+ g[KEY] = { gameEnd, retry, cta };
+ playableGameEnd(); playableRetry();
+ expect(gameEnd).toHaveBeenCalledTimes(1); expect(retry).toHaveBeenCalledTimes(1);
+ expect(cta).not.toHaveBeenCalled();
+ delete g[KEY];
+ expect(() => { playableGameEnd(); playableRetry(); }).not.toThrow();
+ });
});
diff --git a/sdk/tests/playable-host-pause.test.ts b/sdk/tests/playable-host-pause.test.ts
new file mode 100644
index 000000000..5e578a481
--- /dev/null
+++ b/sdk/tests/playable-host-pause.test.ts
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect, vi } from 'vitest';
+import { App, setAppHostPaused } from '../src/app/app';
+import { Schedule, defineSystem } from '../src/ecs/system';
+import { Time } from '../src/ecs/resource';
+import { AudioAPI, setAudioHostSuspended } from '../src/audio/Audio';
+import type { PlatformAudioBackend } from '../src/audio/PlatformAudioBackend';
+
+describe('playable host pause ownership', () => {
+ it('freezes simulation time and preserves user pause across independent hosts', async () => {
+ const app = App.new();
+ let updates = 0;
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { updates++; }));
+ await app.tick(0.1);
+ const before = updates, elapsed = app.getResource(Time).elapsed;
+ const first = {}, second = {};
+ setAppHostPaused(app, first, true); setAppHostPaused(app, second, true);
+ app.setPaused(false);
+ await app.tick(0.3);
+ expect(updates).toBe(before);
+ expect(app.getResource(Time).elapsed).toBe(elapsed);
+ expect(app.getResource(Time).unscaledDelta).toBe(0.3);
+ setAppHostPaused(app, first, false);
+ expect(app.isPaused()).toBe(true);
+ app.setPaused(true); setAppHostPaused(app, second, false);
+ expect(app.isPaused()).toBe(true);
+ app.setPaused(false); await app.tick(0.1);
+ expect(updates).toBeGreaterThan(before);
+ app.quit();
+ });
+
+ it('allows an explicit debug step without releasing the host pause', async () => {
+ const app = App.new(); let updates = 0;
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { updates++; }));
+ const owner = {}; setAppHostPaused(app, owner, true);
+ await app.stepFrames(2);
+ expect(updates).toBe(2); expect(app.isPaused()).toBe(true);
+ setAppHostPaused(app, owner, false); app.quit();
+ });
+
+ it('does not resume manually suspended audio or bypass another host', () => {
+ const backend = { delivery: 'bytes', suspend: vi.fn(), resume: vi.fn(), dispose: vi.fn() } as unknown as PlatformAudioBackend;
+ const audio = new AudioAPI(backend); const first = {}, second = {};
+ setAudioHostSuspended(audio, first, true); setAudioHostSuspended(audio, second, true);
+ expect(backend.suspend).toHaveBeenCalledTimes(1);
+ audio.resume(); expect(backend.resume).not.toHaveBeenCalled();
+ setAudioHostSuspended(audio, first, false); expect(backend.resume).not.toHaveBeenCalled();
+ audio.suspend(); setAudioHostSuspended(audio, second, false);
+ expect(backend.resume).not.toHaveBeenCalled();
+ audio.resume(); expect(backend.resume).toHaveBeenCalledTimes(1);
+ audio.dispose(); setAudioHostSuspended(audio, first, true);
+ expect(backend.suspend).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/sdk/tests/playableRuntime.test.ts b/sdk/tests/playableRuntime.test.ts
index 58330344e..c1024fbbe 100644
--- a/sdk/tests/playableRuntime.test.ts
+++ b/sdk/tests/playableRuntime.test.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
vi.mock('../src/runtime/runtimeLoader', () => ({
initRuntime: vi.fn().mockResolvedValue(undefined),
@@ -14,6 +14,9 @@ import { initPlayableRuntime } from '../src/runtime/playableRuntime';
import type { PlayableRuntimeConfig } from '../src/runtime/playableRuntime';
import { initRuntime } from '../src/runtime/runtimeLoader';
import { Assets } from '../src/asset/AssetPlugin';
+import { App } from '../src/app/app';
+import { Input, InputState } from '../src/input/input';
+import type { PlayableAdBridge } from '../src/runtime/playableCta';
function createMockConfig(overrides?: Partial<PlayableRuntimeConfig>): PlayableRuntimeConfig {
const canvas = { width: 320, height: 480 } as HTMLCanvasElement;
@@ -44,6 +47,32 @@ function createMockConfig(overrides?: Partial<PlayableRuntimeConfig>): PlayableR
describe('initPlayableRuntime', () => {
beforeEach(() => {
vi.clearAllMocks();
+ delete (globalThis as Record<string, unknown>).__ESTELLA_PLAYABLE__;
+ });
+ afterEach(() => { delete (globalThis as Record<string, unknown>).__ESTELLA_PLAYABLE__; vi.restoreAllMocks(); });
+
+ it('announces ready after resources load and preserves game pause through host visibility', async () => {
+ const app = App.new(), state = new InputState(), order: string[] = [];
+ app.insertResource(Input, state); state.keysDown.add('KeyD');
+ state.setVirtualSource({}, 'move', 1, 0); state.setVirtual('manual', 1);
+ let active!: (value: boolean) => void;
+ const release = vi.fn();
+ const bridge: PlayableAdBridge = {
+ ready: () => { order.push('ready'); },
+ onActive: listener => { active = listener; listener(false); return release; },
+ };
+ (globalThis as Record<string, unknown>).__ESTELLA_PLAYABLE__ = bridge;
+ vi.mocked(initRuntime).mockImplementationOnce(async () => { order.push('loaded'); });
+ vi.spyOn(app, 'run').mockImplementation(async () => { order.push('run'); });
+ await initPlayableRuntime(createMockConfig({ app }));
+ expect(order).toEqual(['loaded', 'run', 'ready']);
+ expect(app.isPaused()).toBe(true); expect(state.keysDown.size).toBe(0);
+ expect(state.getVirtual('move').x).toBe(0); expect(state.getVirtual('manual').x).toBe(1);
+ app.setPaused(true); active(true); expect(app.isPaused()).toBe(true);
+ app.setPaused(false); active(false); expect(app.isPaused()).toBe(true);
+ state.keysDown.add('Space'); active(true); expect(app.isPaused()).toBe(false);
+ expect(state.keysDown.size).toBe(0);
+ app.quit(); expect(release).toHaveBeenCalledTimes(1);
});
it('passes scenes array and firstScene to initRuntime', async () => {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index eb058da01..1bf31381b 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -44,6 +44,8 @@ export const NOTED = {
{ note: 'Hidden text and skeletal batches skip vertex conversion.' },
'perf(renderer): cull bulk draws before staging geometry':
{ note: 'Camera-excluded bulk draws skip transient geometry.' },
+ 'feat(playable): add Mintegral container lifecycle':
+ { note: 'Playable exports handle Mintegral start, completion and retry.' },
'perf(renderer): reject full texture runs before copying indices':
{ note: 'Full texture batches avoid unused index copies.' },
'fix(examples): distinguish motion requests from sensor samples':