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.

docs: ads and sharing get the guide that makes them exist

esengine146ac1740802
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index d40ef47f2..5e39f7095 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -132,6 +132,7 @@ export default defineConfig({
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
{ label: 'Saving & Loading', translations: { 'zh-CN': '存档与读档' }, slug: 'guides/save' },
{ label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },
+ { label: 'Ads & Sharing', translations: { 'zh-CN': '广告与分享' }, slug: 'guides/services' },
{ label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },
{ label: 'Android & iOS', translations: { 'zh-CN': 'Android 与 iOS' }, slug: 'guides/mobile' },
{ label: 'Hot Update', translations: { 'zh-CN': '热更新' }, slug: 'guides/hot-update' },
diff --git a/docs/astro/src/content/docs/guides/services.mdx b/docs/astro/src/content/docs/guides/services.mdx
new file mode 100644
index 000000000..d14df98d4
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/services.mdx
@@ -0,0 +1,97 @@
+---
+title: Ads & Sharing
+description: Rewarded and interstitial ads with the pause ceremony built in, and both of the host's share surfaces.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+On a mini-game host (WeChat, Douyin), monetization and sharing are platform
+calls every game wires up by hand — and the wiring is the part that goes wrong:
+the game keeps simulating under a rewarded video, audio keeps playing under the
+ad, an error path leaves the world paused forever. The `Ads` and `Share`
+services own that ceremony, and they exist on every platform, so gameplay code
+is written once and *asks* what this platform can do instead of branching on it.
+
+## Rewarded ads
+
+`Ads.showRewarded(adUnitId)` shows a rewarded video and resolves — after the ad
+closed and the game is running again — with whether the reward was earned:
+
+```typescript
+import { defineSystem, Res, GetWorld, Ads } from 'esengine';
+
+const reviveSystem = defineSystem([Res(Ads), GetWorld()], (ads, world) => {
+ if (!reviveClicked(world)) return;
+ ads.showRewarded('adunit-xxxx').then(({ completed }) => {
+ if (completed) revivePlayer(world); // watched to the end → grant the reward
+ else showToast(world, 'Watch the whole ad to revive');
+ }).catch(() => {
+ showToast(world, 'No ad available right now');
+ });
+}, { name: 'ReviveSystem' });
+```
+
+While the ad covers the screen, the service:
+
+- **pauses the game clock** — a revive must not cost the player their run;
+- **suspends the audio device** — without touching any volume the user set;
+- **restores both however the ad ends**, including every error path. A game you
+ paused yourself before the ad stays paused after it.
+
+The hosts' load/show dance (an ad with no fill must be loaded and retried once)
+is folded in, as is the runtime that grants a reward without reporting
+`isEnded` — an absent close record counts as completed, because that is what
+the host meant.
+
+`Ads.showInterstitial(adUnitId)` is the same contract minus the reward, and
+`Ads.preloadRewarded(adUnitId)` warms a unit so the show starts instantly.
+
+<Aside type="tip">
+The `adUnitId` comes from the host's ad console (WeChat: 流量主 → ad units in
+the MP dashboard). Ads only serve in a game that has monetization enabled
+there; the devtools simulator shows a test ad.
+</Aside>
+
+### Where ads exist
+
+`Ads.available` is `true` where SOME ad source exists — the platform's, or an
+installed provider. Use it to hide the "watch ad" button honestly:
+
+- **WeChat / Douyin builds** — the host's rewarded/interstitial ads, one family
+ implementation.
+- **The editor's Play mode** — a **mock provider** is installed automatically:
+ `showRewarded` "plays" for a moment and resolves `completed: true`, with the
+ real pause/audio ceremony running. Your revive flow rehearses at your desk.
+- **Web and native builds** — no ad system, `available` is `false`. A native
+ shell that integrates a mediation SDK installs it through the same door the
+ editor uses: `Ads.setProvider(...)`.
+
+## Sharing
+
+A mini-game host has **two** share surfaces, and a game should configure both:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, Share } from 'esengine';
+
+addStartupSystem(defineSystem([Res(Share)], (share) => {
+ // The DEFAULT card: what the host's own share menu (top-right on WeChat)
+ // shows, and what share() without arguments uses. A function is asked at
+ // share time, so the card can carry live state — a score, a room code.
+ share.setShareCard(() => ({
+ title: `I scored ${currentScore()} — beat me!`,
+ query: `room=${currentRoomCode()}`,
+ }));
+}, { name: 'SetupShare' }));
+
+// In the game's own share button handler (share is Res(Share) as above):
+share.share(); // the default card
+share.share({ title: 'Join my game' }); // or a one-off card
+```
+
+Whoever opens the shared card receives `query` in the host's launch options —
+that is how invite links and room codes travel.
+
+Sharing is fire-and-forget by design: since 2021 no mini-game host reports
+whether the player actually shared, so there is nothing to await. Off-platform
+(web, native, the editor) `Share.available` is `false` and `share()` returns
+`false` — hide the button rather than promise a sheet that cannot open.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/services.mdx b/docs/astro/src/content/docs/zh-cn/guides/services.mdx
new file mode 100644
index 000000000..574d8b4b6
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/services.mdx
@@ -0,0 +1,88 @@
+---
+title: 广告与分享
+description: 内置暂停仪式的激励视频/插屏广告,以及宿主的两个分享面。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+在小游戏宿主(微信、抖音)上,变现与分享是每个游戏都要手动接的平台调用——而接错的
+恰恰是接线本身:激励视频盖着屏幕时游戏还在跑、广告底下音频还在响、出错路径把世界
+永远留在暂停里。`Ads` 与 `Share` 服务把这套仪式收进引擎,并且在每个平台上都存在,
+所以玩法代码只写一份,用**询问**代替按平台分支。
+
+## 激励视频
+
+`Ads.showRewarded(adUnitId)` 展示一条激励视频,并在广告关闭、游戏恢复运行**之后**
+resolve,结果是奖励有没有赚到:
+
+```typescript
+import { defineSystem, Res, GetWorld, Ads } from 'esengine';
+
+const reviveSystem = defineSystem([Res(Ads), GetWorld()], (ads, world) => {
+ if (!reviveClicked(world)) return;
+ ads.showRewarded('adunit-xxxx').then(({ completed }) => {
+ if (completed) revivePlayer(world); // 看完了 → 发奖
+ else showToast(world, '看完整条视频才能复活');
+ }).catch(() => {
+ showToast(world, '暂时没有可用的广告');
+ });
+}, { name: 'ReviveSystem' });
+```
+
+广告覆盖屏幕期间,服务会:
+
+- **暂停游戏时钟**——复活广告不能反过来害玩家丢掉这条命;
+- **挂起音频设备**——不碰用户设置的任何音量;
+- **无论广告怎么结束都恢复以上两者**,包括所有出错路径。你自己在广告前暂停的游戏,
+ 广告后保持暂停。
+
+宿主文档里的 load/show 补救舞步(没有填充的广告要 load 一次再重试)已经折叠在内;
+老运行时"发了奖但不报 `isEnded`"的情况也是——关闭记录缺失按看完处理,因为宿主
+就是这个意思。
+
+`Ads.showInterstitial(adUnitId)` 是同一契约去掉奖励;`Ads.preloadRewarded(adUnitId)`
+预热一个广告位,让展示即点即出。
+
+<Aside type="tip">
+`adUnitId` 来自宿主的广告后台(微信:MP 后台的流量主 → 广告位)。只有开通了流量主
+的游戏才会出真广告;开发者工具的模拟器里出的是测试广告。
+</Aside>
+
+### 广告在哪些地方存在
+
+`Ads.available` 在**存在某个广告源**时为 true——平台自带的,或安装进来的 provider。
+用它诚实地隐藏"看广告"按钮:
+
+- **微信 / 抖音构建**——宿主的激励/插屏广告,同一份家族实现。
+- **编辑器 Play 模式**——自动安装 **mock provider**:`showRewarded`"播放"片刻后
+ resolve `completed: true`,真实的暂停/音频仪式照常运行。复活流程在工位上就能排练。
+- **Web 与原生构建**——没有广告系统,`available` 为 false。接入聚合 SDK 的原生壳
+ 走编辑器同一扇门:`Ads.setProvider(...)`。
+
+## 分享
+
+小游戏宿主有**两个**分享面,游戏两个都该配置:
+
+```typescript
+import { defineSystem, addStartupSystem, Res, Share } from 'esengine';
+
+addStartupSystem(defineSystem([Res(Share)], (share) => {
+ // 默认卡片:宿主自己的分享菜单(微信右上角)展示的内容,也是 share() 不带参数时
+ // 用的内容。传函数则在分享那一刻被询问,卡片可以携带实时状态——分数、房间号。
+ share.setShareCard(() => ({
+ title: `我拿了 ${currentScore()} 分,来超过我!`,
+ query: `room=${currentRoomCode()}`,
+ }));
+}, { name: 'SetupShare' }));
+
+// 在游戏自己的分享按钮回调里(share 同上,来自 Res(Share)):
+share.share(); // 默认卡片
+share.share({ title: '来加入我的游戏' }); // 或一次性卡片
+```
+
+打开被分享卡片的人会在宿主的启动参数里收到 `query`——邀请链接和房间号就是这样
+传递的。
+
+分享是有意的 fire-and-forget:2021 年起没有任何小游戏宿主报告玩家是否真的分享了,
+所以没有可等待的结果。平台之外(web、原生、编辑器)`Share.available` 为 false 且
+`share()` 返回 false——把按钮藏起来,而不是承诺一张打不开的分享面板。