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): a game asks for the CTA once, so the ad network stays out of its code
esengine48cacd88395a
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 30e9f9e65..9d0a5b5b7 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: 1358 stable · 17 beta · 1 deprecated+Symbols: 1361 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -4794,6 +4794,11 @@ uiThemeOverrides: ThemeOverrides | undefinedwasmBaseUrl: string | undefined```+## PlayableAdBridge — interface+```+cta: (() => void) | undefined+```+## PlayableRuntimeConfig — interface```app: App@@ -9087,6 +9092,11 @@ FsmPlugin(): Array<{ type: string; value: string; }>```+## hasPlayableCta — function+```+(): boolean+```+## headlessBasePlugins — const```() => Plugin[]@@ -9587,6 +9597,11 @@ PerceptionPlugin(): boolean```+## playableCta — function+```+(): void+```+## pointInHitArea — function```(px: number, py: number, area: HitAreaShape): booleandiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex bd6b98a58..52dfb7730 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: 1377 stable · 22 beta · 1 deprecated+Symbols: 1380 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -4948,6 +4948,11 @@ uiThemeOverrides: ThemeOverrides | undefinedwasmBaseUrl: string | undefined```+## PlayableAdBridge — interface+```+cta: (() => void) | undefined+```+## PlayableRuntimeConfig — interface```app: App@@ -9291,6 +9296,11 @@ FsmPlugin(): Array<{ type: string; value: string; }>```+## hasPlayableCta — function+```+(): boolean+```+## headlessBasePlugins — const```() => Plugin[]@@ -9801,6 +9811,11 @@ PerceptionPlugin(): boolean```+## playableCta — function+```+(): void+```+## pointInHitArea — function```(px: number, py: number, area: HitAreaShape): booleandiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 19b5893a3..77ca2f4c1 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: 1357 stable · 19 beta · 1 deprecated+Symbols: 1360 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -4789,6 +4789,11 @@ uiThemeOverrides: ThemeOverrides | undefinedwasmBaseUrl: string | undefined```+## PlayableAdBridge — interface+```+cta: (() => void) | undefined+```+## PlayableRuntimeConfig — interface```app: App@@ -9082,6 +9087,11 @@ FsmPlugin(): Array<{ type: string; value: string; }>```+## hasPlayableCta — function+```+(): boolean+```+## headlessBasePlugins — const```() => Plugin[]@@ -9592,6 +9602,11 @@ PerceptionPlugin(): boolean```+## playableCta — function+```+(): void+```+## pointInHitArea — function```(px: number, py: number, area: HitAreaShape): booleandiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 2ba0b2778..7839142f7 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: 1378 stable · 17 beta · 1 deprecated+Symbols: 1381 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -5004,6 +5004,11 @@ uiThemeOverrides: ThemeOverrides | undefinedwasmBaseUrl: string | undefined```+## PlayableAdBridge — interface+```+cta: (() => void) | undefined+```+## PlayableRuntimeConfig — interface```app: App@@ -9302,6 +9307,11 @@ FsmPlugin(): Array<{ type: string; value: string; }>```+## hasPlayableCta — function+```+(): boolean+```+## headlessBasePlugins — const```() => Plugin[]@@ -9812,6 +9822,11 @@ PerceptionPlugin(): boolean```+## playableCta — function+```+(): void+```+## pointInHitArea — function```(px: number, py: number, area: HitAreaShape): booleandiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 945c52c4c..085bbc0fe 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: 1368 stable · 17 beta · 1 deprecated+Symbols: 1371 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -4796,6 +4796,11 @@ uiThemeOverrides: ThemeOverrides | undefinedwasmBaseUrl: string | undefined```+## PlayableAdBridge — interface+```+cta: (() => void) | undefined+```+## PlayableRuntimeConfig — interface```app: App@@ -9106,6 +9111,11 @@ FsmPlugin(): Array<{ type: string; value: string; }>```+## hasPlayableCta — function+```+(): boolean+```+## headlessBasePlugins — const```() => Plugin[]@@ -9611,6 +9621,11 @@ PerceptionPlugin(): boolean```+## playableCta — function+```+(): void+```+## pointInHitArea — function```(px: number, py: number, area: HitAreaShape): booleandiff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex eac36e7ef..07ae2bf99 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -231,6 +231,12 @@ export {type PlayableRuntimeConfig,} from './playableRuntime';+export {+ playableCta,+ hasPlayableCta,+ type PlayableAdBridge,+} from './playableCta';+export {initPlayRealmRuntime,type PlayRealmRuntimeConfig,diff --git a/sdk/src/playableCta.ts b/sdk/src/playableCta.tsnew file mode 100644index 000000000..4f598937b--- /dev/null+++ b/sdk/src/playableCta.ts@@ -0,0 +1,58 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The one call a playable ad's game code makes when the player takes the+ * call to action, and the seam that keeps the ad network out of that code.+ *+ * Every network wants a different function for "the player clicked through"+ * — Meta wants `FbPlayableAd.onCTAClick()`, the mraid family wants+ * `mraid.open(url)`, and each new one wants its own. None of them can be+ * called directly from a game that also ships to the web, so the export+ * injects a bridge (see the desktop `PlayableAdProfile`) and this function+ * dispatches through it. A build with no network selected has no bridge and+ * this is a no-op — the game is playable, the click just goes nowhere.+ *+ * Deliberately its own module: importing a CTA call must not drag the whole+ * playable runtime into a web build.+ */++/** What the exported page installs on `globalThis` — one method per interaction. */+export interface PlayableAdBridge {+ /** Hand the player off to the store, the way THIS network spells it. */+ cta?(): void;+}++const GLOBAL_KEY = '__ESTELLA_PLAYABLE__';++let warned = false;++function bridge(): PlayableAdBridge | undefined {+ return (globalThis as Record<string, unknown>)[GLOBAL_KEY] as PlayableAdBridge | undefined;+}++/**+ * Send the player to the store. Call it from whatever the ad's call-to-action is+ * (an end-card button, a tap after the win) — once, from game code, with no+ * network in sight.+ *+ * Silently does nothing outside a playable build, so the same scene runs in the+ * editor and on the web.+ */+export function playableCta(): void {+ const cta = bridge()?.cta;+ if (cta) {+ cta();+ return;+ }+ if (!warned) {+ warned = true;+ console.warn('[playable] no ad-network bridge — the CTA went nowhere. '+ + 'Select an ad network in Project Settings → Packaging → Playable to install one.');+ }+}++/** 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';+}diff --git a/sdk/tests/playable-cta.test.ts b/sdk/tests/playable-cta.test.tsnew file mode 100644index 000000000..46dfa8419--- /dev/null+++ b/sdk/tests/playable-cta.test.ts@@ -0,0 +1,42 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The playable CTA seam: game code calls one function, the exported page+ * supplies the network's own API through the injected bridge. A build with+ * no bridge must stay playable rather than throw.+ */+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+import { playableCta, hasPlayableCta } from '../src/playableCta';++const KEY = '__ESTELLA_PLAYABLE__';+const g = globalThis as Record<string, unknown>;++describe('playableCta', () => {+ beforeEach(() => { delete g[KEY]; });+ afterEach(() => { delete g[KEY]; vi.restoreAllMocks(); });++ it('dispatches to the injected bridge', () => {+ const cta = vi.fn();+ g[KEY] = { cta };+ expect(hasPlayableCta()).toBe(true);+ playableCta();+ expect(cta).toHaveBeenCalledTimes(1);+ });++ it('is a no-op with no bridge, so the same scene runs on the web', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ expect(hasPlayableCta()).toBe(false);+ expect(() => playableCta()).not.toThrow();+ // Warned about, but only ever once — a CTA can sit on a per-frame handler.+ playableCta();+ playableCta();+ expect(warn.mock.calls.length).toBeLessThanOrEqual(1);+ });++ it('treats a bridge without a cta method as absent', () => {+ vi.spyOn(console, 'warn').mockImplementation(() => {});+ g[KEY] = {};+ expect(hasPlayableCta()).toBe(false);+ expect(() => playableCta()).not.toThrow();+ });+});