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.

fix(playable): drop the rotate-to-fit overlay, which could hide the game for good

esengine53b3b5a165cb
diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.ts
index 19dc546a5..99c7140e4 100644
--- a/desktop/electron/exportPlayable.ts
+++ b/desktop/electron/exportPlayable.ts
@@ -23,7 +23,7 @@ import path from 'node:path';
import { cookAssets } from './cookAssets';
import type { OnExportProgress } from './exportProgress';
import { esengineAlias } from './esengineResolve';
-import { orientationCss, orientationOverlayHtml, orientationLockScript, type ScreenOrientation } from './orientationHtml';
+import type { ScreenOrientation } from './orientationHtml';
import { genericPlayableProfile, playableAdInjection, type PlayableAdProfile } from './playableAdProfile';
import { makeZip } from './zipWriter';
import {
@@ -63,14 +63,27 @@ const mimeOf = (p: string): string => MIME[path.extname(p).slice(1).toLowerCase(
/** Escape `</script` so inlined content can't close the host <script> early. */
const inlineSafe = (s: string): string => s.replace(/<\/script/gi, '<\\/script');
-/** `network` is what the chosen ad-network profile contributes: markup for `<head>`
- * and the bridge script that gives `playableCta()` somewhere to go. The bridge runs
- * BEFORE the game bundle, so a CTA fired during boot still resolves. */
+/**
+ * The playable page. Deliberately WITHOUT the web export's rotate-to-fit overlay:
+ * inside an ad SDK the container's size is the SDK's business, so `@media
+ * (orientation:portrait)` reports the container's aspect and not the device's —
+ * turning the phone need not change it. An overlay keyed on that hides the canvas
+ * and never comes back, which is a playable that cannot be played. Every network
+ * asks for a responsive creative instead (Unity spells out both orientations), and
+ * the host already resizes the canvas to whatever container it is given.
+ *
+ * `orientation` therefore only reaches the network profile, which may still DECLARE
+ * it (Google wants an `ad.orientation` meta tag) — a declaration to the platform, not
+ * a demand on the player.
+ *
+ * `network` is what the chosen profile contributes: markup for `<head>` and the
+ * bridge that gives `playableCta()` somewhere to go. The bridge runs BEFORE the game
+ * bundle, so a CTA fired during boot still resolves.
+ */
function indexHtml(
title: string,
globals: string,
bundle: string,
- orientation: ScreenOrientation,
network: { head: string; bridge: string },
): string {
return `<!doctype html>
@@ -83,13 +96,10 @@ function indexHtml(
* { margin: 0; padding: 0; box-sizing: border-box; }
html, body { width: 100%; height: 100%; overflow: hidden; background: #0e121b; }
#canvas { display: block; width: 100%; height: 100%; touch-action: none; }
- ${orientationCss(orientation)}
</style>
</head>
<body>
- <canvas id="canvas"></canvas>
- ${orientationOverlayHtml(orientation)}
- ${orientationLockScript(orientation)}${network.bridge ? `\n <script>${inlineSafe(network.bridge)}</script>` : ''}
+ <canvas id="canvas"></canvas>${network.bridge ? `\n <script>${inlineSafe(network.bridge)}</script>` : ''}
<script>${inlineSafe(globals)}</script>
<script>${inlineSafe(bundle)}</script>
</body>
@@ -165,8 +175,9 @@ export async function exportPlayable(opts: {
wasmDir: string;
outDir: string;
title?: string;
- /** Screen orientation (format.ts resolveOrientation) → rotate-to-fit overlay +
- * best-effort lock in the single-file HTML. Default landscape. */
+ /** Project orientation (format.ts resolveOrientation). The page itself does NOT
+ * pin it — a playable must fit whatever container the SDK gives it — this only
+ * reaches the ad-network profile, which may declare it to the platform. */
orientation?: ScreenOrientation;
minify?: boolean;
/** Bitmask of render layers (0..31) that y-sort (Project Settings → Rendering). */
@@ -309,7 +320,7 @@ export async function exportPlayable(opts: {
const adProfile = opts.adProfile ?? genericPlayableProfile;
const network = playableAdInjection(adProfile, { title, orientation });
const outFile = path.join(absOut, 'index.html');
- await writeFile(outFile, indexHtml(title, globals, bundle, orientation, network));
+ await writeFile(outFile, indexHtml(title, globals, bundle, network));
await rm(cookDir, { recursive: true, force: true });
const htmlBytes = (await stat(outFile)).size;
diff --git a/desktop/electron/orientationHtml.ts b/desktop/electron/orientationHtml.ts
index f4d182f33..2d5972332 100644
--- a/desktop/electron/orientationHtml.ts
+++ b/desktop/electron/orientationHtml.ts
@@ -1,15 +1,18 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file orientationHtml.ts — the shared web/playable orientation pin. Both the web
- * export (exportGame) and the single-file playable export (exportPlayable)
- * ship the SAME rotate-to-fit behavior for the ONE project-wide orientation
- * (format.ts resolveOrientation): in the wrong device orientation the canvas
- * is hidden and a "rotate your device" overlay shows; screen.orientation.lock()
- * is attempted best-effort (it only takes in fullscreen / on some browsers, so
- * the CSS overlay is the universal fallback). WeChat handles orientation itself
- * via game.json deviceOrientation, and desktop sizes its window instead — this
- * is only the browser surfaces.
+ * @file orientationHtml.ts — the WEB export's orientation pin, for the ONE
+ * project-wide orientation (format.ts resolveOrientation): in the wrong device
+ * orientation the canvas is hidden and a "rotate your device" overlay shows;
+ * screen.orientation.lock() is attempted best-effort (it only takes in
+ * fullscreen / on some browsers, so the CSS overlay is the universal fallback).
+ *
+ * Web only, on purpose. A page a player opened in their own browser CAN be
+ * rotated, and there the media query reports the device. A playable lives in an
+ * SDK-sized container whose aspect the phone does not govern, so the same
+ * overlay would hide the game for good — it stays responsive instead
+ * (exportPlayable). WeChat pins orientation via game.json deviceOrientation,
+ * and desktop sizes its own window.
*/
import { createHash } from 'node:crypto';
diff --git a/desktop/tests/export-playable.test.ts b/desktop/tests/export-playable.test.ts
index 964950eab..4799a4956 100644
--- a/desktop/tests/export-playable.test.ts
+++ b/desktop/tests/export-playable.test.ts
@@ -93,11 +93,12 @@ describe('exportGame (playable)', () => {
expect(html).toContain('"main"'); // first scene name
expect(html).toContain('__GAME_SCENES__');
expect(html).toContain('<title>Playable Demo</title>');
- // Orientation pin: no explicit setting ⇒ landscape default (rotate-to-fit + lock).
- expect(html).toContain('id="rotate-hint"');
- expect(html).toContain('Rotate your device to landscape');
- expect(html).toContain('@media (orientation:portrait)'); // hide canvas when wrong way
- expect(html).toMatch(/screen\.orientation[\s\S]*lock\("landscape"\)/);
+ // NO rotate-to-fit overlay, unlike the web export. Inside an ad SDK the media
+ // query reports the CONTAINER's aspect, which turning the phone need not change,
+ // so an overlay keyed on it hid the canvas forever — a playable nobody could play.
+ expect(html).not.toContain('rotate-hint');
+ expect(html).not.toContain('@media (orientation');
+ expect(html).not.toContain('screen.orientation');
}, 60_000);
// The ad network is a PROFILE, not a branch: what it contributes is head markup, a
@@ -189,19 +190,27 @@ describe('exportGame (playable)', () => {
expect(html).toMatch(/"designWidth":750/);
}, 60_000);
- it('pins the single file to an explicit portrait orientation', async () => {
+ // A portrait project must ALSO stay playable in a landscape container: the page
+ // adapts rather than demanding a rotation the SDK may not honour. The orientation
+ // reaches the network profile, which is free to declare it to the platform.
+ it('does not pin the page even when the project is portrait', async () => {
const o = path.join(root, 'dist-playable-portrait');
const res = await exportGame({
root, entryScene: 'scenes/main.esscene', gameHostEntry: 'unused-for-playable',
playableHostEntry: PLAYABLE_HOST, scriptsEntry: 'src/main.ts',
sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
outDir: o, title: 'Playable Demo', platform: 'playable', orientation: 'portrait',
+ playableAdProfile: {
+ id: 'declares', label: 'Declares Orientation', maxBytes: 5 * 1024 * 1024,
+ limitNote: 'test', emitHead: (ctx) => `<meta name="ad.orientation" content="${ctx.orientation}">`,
+ },
});
expect(res.ok).toBe(true);
const html = readFileSync(path.join(o, 'index.html'), 'utf8');
- expect(html).toContain('Rotate your device to portrait');
- expect(html).toContain('@media (orientation:landscape)'); // hide canvas when wrong way
- expect(html).toMatch(/screen\.orientation[\s\S]*lock\("portrait"\)/);
+ expect(html).not.toContain('rotate-hint');
+ expect(html).not.toContain('@media (orientation');
+ // Declared to the platform, not enforced on the player.
+ expect(html).toContain('<meta name="ad.orientation" content="portrait">');
}, 60_000);
});
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index e06e3eb8a..32032aa0e 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -216,11 +216,19 @@ project:
Orientation is **one project-wide setting**, not per-target: **Project Settings →
Display → Orientation** (portrait or landscape), right beside the design resolution.
-Every target honors it — the WeChat `game.json` `deviceOrientation`, the web and
-playable builds' rotate-to-fit prompt (and a best-effort `screen.orientation.lock`),
-and the desktop window's aspect. Left unset, it's **derived from the design
-resolution's aspect** (wider-or-square ⇒ landscape, taller ⇒ portrait), so a
-landscape design ships landscape everywhere with zero configuration.
+Every target honors it — the WeChat `game.json` `deviceOrientation`, the web build's
+rotate-to-fit prompt (and a best-effort `screen.orientation.lock`), and the desktop
+window's aspect. Left unset, it's **derived from the design resolution's aspect**
+(wider-or-square ⇒ landscape, taller ⇒ portrait), so a landscape design ships
+landscape everywhere with zero configuration.
+
+A **playable is the exception, deliberately**: it never pins the page. Inside an ad
+SDK the container's size is the SDK's business, so a rotate-to-fit overlay can hide
+the game for good — the player turns the phone and nothing changes, because the media
+query was reading the container all along. Playables stay responsive (every network
+asks for that), and the orientation is only *declared* to the platform where one wants
+it, e.g. Google's `ad.orientation` meta tag. Design for both aspects, or letterbox
+with [a camera fit](#) so the framing survives either one.
See [The Editor](/docs/guides/editor/) for the settings UI.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
index 925d0e741..55d298a5c 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
@@ -183,7 +183,9 @@ node build-tools/cli.js build -t wechat
### 屏幕方向
-方向是**一个项目级设置**,而非逐平台:**项目设置 → 显示(Display) → 屏幕方向**(竖屏或横屏),就在设计分辨率旁边。所有目标都遵循它——微信 `game.json` 的 `deviceOrientation`、Web 与 Playable 构建的"请旋转设备"提示(以及尽力而为的 `screen.orientation.lock`)、桌面窗口的宽高比。留空则**从设计分辨率的宽高比推导**(更宽或方形 ⇒ 横屏,更高 ⇒ 竖屏),因此横屏设计零配置即在各处横屏发布。
+方向是**一个项目级设置**,而非逐平台:**项目设置 → 显示(Display) → 屏幕方向**(竖屏或横屏),就在设计分辨率旁边。所有目标都遵循它——微信 `game.json` 的 `deviceOrientation`、Web 构建的"请旋转设备"提示(以及尽力而为的 `screen.orientation.lock`)、桌面窗口的宽高比。留空则**从设计分辨率的宽高比推导**(更宽或方形 ⇒ 横屏,更高 ⇒ 竖屏),因此横屏设计零配置即在各处横屏发布。
+
+**试玩包是有意的例外**:它从不锁定页面方向。在广告 SDK 里,容器尺寸由 SDK 决定,因此"请旋转设备"这类遮罩可能把游戏永久挡住——玩家转了手机却毫无变化,因为那条 media query 一直在读容器而不是设备。试玩包保持自适应(各平台都要求如此),方向只在平台需要时**声明**出去,例如 Google 的 `ad.orientation` meta 标签。请为两种比例都设计,或用[相机适配](#)做 letterbox,让构图在任一比例下都成立。
设置界面见 [编辑器](/docs/zh-cn/guides/editor/)。