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
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.tsindex 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.tsindex 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.tsindex 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 nameexpect(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.mdxindex 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.mdxindex 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/)。