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
feat(playable): add Mintegral container lifecycle
yhh17d657fb4c1f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdxindex 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 oversizedexport names the cap it used and where that number is published, rather than a barenumber 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 shipDefine it yourself — the built-in networks are written against this exact contract,diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 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.jsonindex 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.esscenenew file mode 100644index 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.metanew file mode 100644index 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.pngnew file mode 100644index 000000000..761a6cc4fBinary files /dev/null and b/examples/playable-ad/assets/textures/ship_K.png differdiff --git a/examples/playable-ad/assets/textures/ship_K.png.meta b/examples/playable-ad/assets/textures/ship_K.png.metanew file mode 100644index 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.pngnew file mode 100644index 000000000..c0647535bBinary files /dev/null and b/examples/playable-ad/assets/textures/star_tiny.png differdiff --git a/examples/playable-ad/assets/textures/star_tiny.png.meta b/examples/playable-ad/assets/textures/star_tiny.png.metanew file mode 100644index 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.pngnew file mode 100644index 000000000..9c7b31aceBinary files /dev/null and b/examples/playable-ad/assets/textures/station_C.png differdiff --git a/examples/playable-ad/assets/textures/station_C.png.meta b/examples/playable-ad/assets/textures/station_C.png.metanew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.pngnew file mode 100644index 000000000..bf33b49beBinary files /dev/null and b/examples/playable-ad/thumbnail.png differdiff --git a/examples/playable-ad/thumbnail.png.meta b/examples/playable-ad/thumbnail.png.metanew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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 thisdiff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.tsindex 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 | undelabel: 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): PromisaspectRatio: 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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>): PlayableRdescribe('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.mjsindex 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':