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): 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.md
index 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 | undefined
wasmBaseUrl: 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): boolean
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | undefined
wasmBaseUrl: 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): boolean
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | undefined
wasmBaseUrl: 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): boolean
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | undefined
wasmBaseUrl: 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): boolean
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | undefined
wasmBaseUrl: 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): boolean
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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();
+ });
+});