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): verify required SDK script presence and order
yhhe969e02fb6d9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c81ef3ae8..66dab1f89 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,8 +22,12 @@ published separately; it ships inside the editor.### Fixed+- **World transforms preserve mirrored axes.** Quaternion decomposition retains signed scale instead of converting reflected bases into invalid rotations. Planar transforms keep a Z rotation, including collapsed axes; mirrored UI pointer bounds and flat render bounds follow their displayed geometry.+- **Playable checks verify mandatory SDK scripts and placement.** The report detects missing Google/TikTok/Pangle scripts, incorrect head/body placement and delayed TikTok/Pangle loading before game code. Script text and JSON metadata do not count as SDK tags. The editor shows the SDK finding separately, while interaction and availability remain pending runtime evidence.++- **Nine-slice texture flips preserve asymmetric borders.** Flipped UV spans sample inside their original region and exchange opposing border widths, producing the complete mirrored texture. The shared geometry builder retains all cells for signed destination extents, including small boxes and rotated draws.- **Small nine-slice visuals keep borders inside their box.** Sprite and UI nine-slice geometry proportionally shrinks opposing borders when their total exceeds the destination size, retaining the texture's original border UVs. Zero-width or zero-height nine-slices emit no geometry; ordinary sizes retain their existing border widths.diff --git a/desktop b/desktopindex 9382c304c..7ca8ed152 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 9382c304cfa4b4bf8e82f63077fc7a8108b63934+Subproject commit 7ca8ed1524cb7b8621acfb5a0e338dbd51379995diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex 98efa5b64..77fbb8be2 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -128,6 +128,8 @@ Playable exports include `playableCheck` in their result; the package dialog disUse `pnpm preview:playable path/to/index.html --report export-result.json` from the engine repository for a local container mock. It prints a loopback URL and does not open a browser. Ready, Show and Hide simulate host callbacks; the viewport selector changes aspect ratio, and Save Log records store calls with the original HTML hash. MRAID can use `--store-url` for your destination. The served copy substitutes mandatory SDK scripts and blocks external requests; the delivered HTML stays unchanged. These mock records do not replace official SDK or device acceptance.+The required host SDK check verifies literal script tags and their placement. Google Exit API belongs in head; TikTok/Pangle must load before game scripts in body. Missing scripts, incorrect positions and delayed TikTok/Pangle SDK loading fail this static check. Actual SDK availability and CTA behavior remain runtime checks.+### A network we don't shipDefine it yourself — the built-in networks are written against this exact contract,diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 472df1b74..7139b12e3 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -112,6 +112,8 @@ MRAID 安装按钮须通过 `playableCta(storeUrl)` 传入目标地址,或由在引擎仓库执行 `pnpm preview:playable path/to/index.html --report export-result.json` 可启动本地容器模拟,只打印回环地址,不自动打开浏览器。Ready、Show、Hide 模拟宿主回调,可切换横竖屏;Save Log 保存商店调用及原 HTML 哈希。MRAID 可通过 `--store-url` 配置商店地址。预览副本替换必需 SDK 并阻止外部请求,原导出 HTML 不变;模拟记录不代替官方 SDK 或真机验收。+必需宿主 SDK 检查会核对真实的 script 标签及其位置:Google Exit API 位于 head,TikTok/Pangle 位于 body 且在游戏脚本之前。缺少脚本、位置错误或 TikTok/Pangle SDK 延迟加载都会使静态检查失败。真实 SDK 是否可用及 CTA 行为仍需运行验证。+### 我们没内置的平台自己定义就行——内置的那几家写的就是这份契约,没有做不到的事。**打包项目 → 新建平台** 可以diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.mdindex 9b61da7f3..faadbf5a3 100644--- a/examples/playable-ad/README.md+++ b/examples/playable-ad/README.md@@ -76,3 +76,8 @@ record marked `local-mock`, with the original HTML hash. External requests areblocked in this preview and recorded as violations, so this is a controlled mock,not proof of the original package's behavior in the real SDK. Official previewsand physical devices remain separate acceptance steps.++The `google` and `meta` named profiles export the same scene for the existing+networks. Mandatory SDK checks now verify both presence and placement: Google+Exit API in head, TikTok/Pangle before game scripts in body. SDK addresses merely+appearing in an allowlist or in JavaScript text do not satisfy this check.diff --git a/examples/playable-ad/project.esproject b/examples/playable-ad/project.esprojectindex e7e44faf7..1f76ebbfe 100644--- a/examples/playable-ad/project.esproject+++ b/examples/playable-ad/project.esproject@@ -64,6 +64,22 @@"network": "applovin"}}+ },+ "google": {+ "platform": "playable",+ "platforms": {+ "playable": {+ "network": "google"+ }+ }+ },+ "meta": {+ "platform": "playable",+ "platforms": {+ "playable": {+ "network": "meta"+ }+ }}}}diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.tsindex 369b0cd11..8f6301ae3 100644--- a/pipeline/src/export/platformCatalog.ts+++ b/pipeline/src/export/platformCatalog.ts@@ -515,6 +515,9 @@ async function importPlatformModule(if (candidate.allowedExternalScripts !== undefined && (!Array.isArray(candidate.allowedExternalScripts) || !candidate.allowedExternalScripts.every(url => typeof url === 'string' && /^https:\/\//.test(url)))) {return { error: 'allowedExternalScripts must list exact HTTPS host SDK URLs' };}+ if (candidate.requiredSdk !== undefined && (!candidate.requiredSdk || typeof candidate.requiredSdk.url !== 'string' || !/^https:\/\//.test(candidate.requiredSdk.url) || !['head', 'body-before-game'].includes(candidate.requiredSdk.placement))) {+ return { error: 'requiredSdk needs an HTTPS URL and head/body-before-game placement' };+ }if (candidate.configOrientationField !== undefined && (typeof candidate.configOrientationField !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate.configOrientationField))) {return { error: 'configOrientationField must name a JSON field' };}@@ -644,6 +647,7 @@ export async function loadPlayableProfile(root: string | null, id: string | undedelivery: mod.delivery,zipFileName: mod.zipFileName,allowedExternalScripts: mod.allowedExternalScripts,+ requiredSdk: mod.requiredSdk,configOrientationField: mod.configOrientationField,deliveryNote: mod.deliveryNote,emitHead: mod.emitHead,diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.tsindex 65fba22dc..bd336fe12 100644--- a/pipeline/src/export/playableAdProfile.ts+++ b/pipeline/src/export/playableAdProfile.ts@@ -54,6 +54,8 @@ export interface PlayableAdProfile {readonly zipFileName?: string;/** Exact host SDK scripts allowed by this network’s published integration. */readonly allowedExternalScripts?: readonly string[];+ /** Mandatory literal SDK script and its position in the delivered HTML. */+ readonly requiredSdk?: { url: string; placement: 'head' | 'body-before-game' };/** Required config.json orientation key; values are 0, 1 or 2. */readonly configOrientationField?: string;/** Anything else the developer must know before uploading. Reported as a@@ -112,6 +114,7 @@ export const metaPlayableProfile: PlayableAdProfile = {*/export const googlePlayableProfile: PlayableAdProfile = {allowedExternalScripts: ['https://tpc.googlesyndication.com/pagead/gadgets/html5/api/exitapi.js'],+ requiredSdk: { url: 'https://tpc.googlesyndication.com/pagead/gadgets/html5/api/exitapi.js', placement: 'head' },id: 'google',label: 'Google Ads (App campaigns)',maxBytes: 5 * 1024 * 1024,@@ -212,6 +215,7 @@ onActive:function(fn){listeners.push(fn);fn(active);return function(){listeners=/** @see https://ads.tiktok.com/resources/help/article/playable-ads?lang=en */export const tiktokPlayableProfile: PlayableAdProfile = {allowedExternalScripts: ['https://sf16-muse-va.ibytedtos.com/obj/union-fe-nc-i18n/playable/sdk/playable-sdk.js'],+ requiredSdk: { url: 'https://sf16-muse-va.ibytedtos.com/obj/union-fe-nc-i18n/playable/sdk/playable-sdk.js', placement: 'body-before-game' },configOrientationField: 'Playable_orientation',id: 'tiktok', label: 'TikTok', maxBytes: 5 * 1024 * 1024 - 1,limitNote: 'TikTok requires a ZIP less than 5MB (official September 2026 specification)',diff --git a/pipeline/src/export/playableCheck.ts b/pipeline/src/export/playableCheck.tsindex 994f4304c..7acd72dbe 100644--- a/pipeline/src/export/playableCheck.ts+++ b/pipeline/src/export/playableCheck.ts@@ -3,7 +3,7 @@import { createHash } from 'node:crypto';import type { PlayableAdProfile } from './playableAdProfile';-export type PlayableCheckId = 'delivery-size' | 'html-size' | 'markup-resources' | 'orientation-config' | 'cta-interaction' | 'host-lifecycle' | 'runtime-requests' | 'network-acceptance';+export type PlayableCheckId = 'delivery-size' | 'html-size' | 'markup-resources' | 'host-sdk' | 'orientation-config' | 'cta-interaction' | 'host-lifecycle' | 'runtime-requests' | 'network-acceptance';export interface PlayableCheckItem {id: PlayableCheckId;@@ -20,6 +20,29 @@ export interface PlayableCheckReport {checks: PlayableCheckItem[];}+/** Mask raw text while preserving positions so JS strings are not HTML tags. */+function sdkPlacement(html: string, rule: NonNullable<PlayableAdProfile['requiredSdk']>): boolean {+ const scripts: { index: number; src?: string; code: string; delayed: boolean; executable: boolean }[] = [];+ const markup = html.replace(/<!--[\s\S]*?-->/g, match => ' '.repeat(match.length))+ .replace(/<(script|style)\b((?:"[^"]*"|'[^']*'|[^'">])*)>([\s\S]*?)<\/\1\s*>/gi,+ (whole: string, tag: string, attributes: string, code: string, index: number) => {+ const attrs = [...attributes.matchAll(/([^\s=/'">]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)];+ const type = attrs.find(attr => attr[1].toLowerCase() === 'type')?.slice(2).find(value => value !== undefined)?.trim().toLowerCase() ?? '';+ if (tag.toLowerCase() === 'script') scripts.push({ index, code,+ src: attrs.find(attr => attr[1].toLowerCase() === 'src')?.slice(2).find(value => value !== undefined),+ executable: !type || type === 'module' || /^(text|application)\/(x-)?(java|ecma)script(1\.[0-9])?$/.test(type),+ delayed: type === 'module' || attrs.some(attr => ['async', 'defer'].includes(attr[1].toLowerCase())) });+ const prefix = 2 + tag.length + attributes.length;+ return whole.slice(0, prefix) + ' '.repeat(code.length) + whole.slice(prefix + code.length);+ });+ const section = rule.placement === 'head' ? /<head\b[^>]*>[\s\S]*?<\/head\s*>/i.exec(markup)+ : /<body\b[^>]*>[\s\S]*?<\/body\s*>/i.exec(markup);+ if (!section) return false;+ const sdk = scripts.find(script => script.src === rule.url);+ if (!sdk || !sdk.executable || (rule.placement === 'body-before-game' && sdk.delayed) || sdk.index < section.index || sdk.index >= section.index + section[0].length) return false;+ return rule.placement === 'head' || !scripts.some(script => script.index < sdk.index && script.executable && (script.src || script.code.trim()));+}+/** Checks literal HTML references; embedded scripts still need request tracing. */function markupReferences(html: string): { tag: string; url: string }[] {const refs: { tag: string; url: string }[] = [];@@ -60,6 +83,8 @@ export function checkPlayable(input: {const rejected = refs.filter(ref => ref.tag !== 'srcset' && (ref.tag !== 'script' || !profile.allowedExternalScripts?.includes(ref.url)));checks.push({ id: 'markup-resources', status: rejected.length ? 'fail' : refs.some(ref => ref.tag === 'srcset') ? 'needs-runtime' : 'pass',detail: rejected.length ? rejected.map(ref => `${ref.tag}: ${ref.url}`).join('\n') : 'No unapproved simple HTML/CSS references. Trace srcset, dynamic requests and generated markup at runtime.' });+ if (profile.requiredSdk) check('host-sdk', sdkPlacement(html.toString('utf8'), profile.requiredSdk),+ `Required script: ${profile.requiredSdk.url}; placement: ${profile.requiredSdk.placement}`);if (profile.configOrientationField) {let valid = false;try { const config = JSON.parse(archiveFiles.find(file => file.name === 'config.json')?.content ?? ''); valid = [0, 1, 2].includes(config?.[profile.configOrientationField]); } catch { /* Missing or malformed configuration is a failed check. */ }diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.tsindex 719095609..57cd6eb6b 100644--- a/pipeline/tests/export-playable.test.ts+++ b/pipeline/tests/export-playable.test.ts@@ -276,6 +276,7 @@ describe('exportGame (playable)', () => {});expect(res.ok).toBe(true);const html = readFileSync(path.join(o, 'index.html'), 'utf8');+ expect(res.playableCheck?.checks.find(check => check.id === 'host-sdk')?.status).toBe('pass');const sdk = profile.emitBody!({ title: 'T', orientation: 'portrait' });expect(html.indexOf(sdk)).toBeGreaterThan(html.indexOf('<body>'));expect(html.indexOf(sdk)).toBeLessThan(html.indexOf('window.__ESTELLA_PLAYABLE__'));diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.tsindex 139c3079d..353c1b28b 100644--- a/pipeline/tests/platform-catalog.test.ts+++ b/pipeline/tests/platform-catalog.test.ts@@ -438,6 +438,15 @@ describe('playable ad networks', () => {expect(row!.error).toMatch(/zipFileName/);});+ it('rejects an invalid mandatory SDK policy before exporting', async () => {+ writePlatform('bad-sdk-policy.mjs', `export default {+ id: 'bad-sdk-policy', kind: 'playable', label: 'Bad SDK policy', maxBytes: 100, limitNote: 'x',+ requiredSdk: { url: 'https://example.com/sdk.js', placement: 'anywhere' }+ };`);+ const row = (await listPlayableNetworks(root)).find(r => r.id === 'bad-sdk-policy');+ expect(row!.error).toMatch(/requiredSdk/);+ });+it('reports malformed host hooks before attempting export', async () => {writePlatform('bad-hook.mjs', `export default {id: 'bad-hook', kind: 'playable', label: 'Bad Hook', maxBytes: 100, limitNote: 'x', emitZipFiles: 'config.json'diff --git a/pipeline/tests/playable-check.test.ts b/pipeline/tests/playable-check.test.tsindex dcebfd60e..bb21f7495 100644--- a/pipeline/tests/playable-check.test.ts+++ b/pipeline/tests/playable-check.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, it, expect } from 'vitest';import { checkPlayable } from '../src/export/playableCheck';-import { genericPlayableProfile, tiktokPlayableProfile } from '../src/export/playableAdProfile';+import { genericPlayableProfile, tiktokPlayableProfile, googlePlayableProfile } from '../src/export/playableAdProfile';const inspect = (html: string, profile = genericPlayableProfile, config?: string) => checkPlayable({profile, html: Buffer.from(html), delivery: Buffer.from(html),@@ -48,6 +48,33 @@ describe('playable export checks', () => {expect(inspect('<img srcset="data:image/png;base64,AAAA 1x, https://example.com/img.png 2x">').status).toBe('failed');});+ it('rejects a missing SDK even when the allowlist permits its URL', () => {+ const report = inspect('<html><head></head><body></body></html>', tiktokPlayableProfile, '{"Playable_orientation":0}');+ expect(report.checks.find(item => item.id === 'markup-resources')?.status).toBe('pass');+ expect(report.checks.find(item => item.id === 'host-sdk')?.status).toBe('fail');+ });++ it('requires the Google exit script in head', () => {+ const script = googlePlayableProfile.emitHead!({ title: 'T', orientation: 'portrait' });+ expect(inspect(`<html><head>${script}</head><body></body></html>`, googlePlayableProfile).status).toBe('needs-runtime');+ expect(inspect(`<html><head></head><body>${script}</body></html>`, googlePlayableProfile).status).toBe('failed');+ });++ it.each(['head', 'late', 'async', 'defer', 'data'])('rejects incorrectly placed or nonexecuting TikTok SDK: %s', mode => {+ let script = tiktokPlayableProfile.emitBody!({ title: 'T', orientation: 'portrait' });+ if (['async', 'defer'].includes(mode)) script = script.replace('<script ', `<script ${mode} `);+ if (mode === 'data') script = script.replace('<script ', '<script type="application/json" ');+ const html = mode === 'head' ? `<head>${script}</head><body></body>`+ : `<head></head><body>${mode === 'late' ? '<script>startGame()</script>' : ''}${script}</body>`;+ expect(inspect(html, tiktokPlayableProfile, '{"Playable_orientation":0}').checks.find(item => item.id === 'host-sdk')?.status).toBe('fail');+ });++ it('ignores commented tags and JS strings, allowing JSON metadata before the SDK', () => {+ const script = tiktokPlayableProfile.emitBody!({ title: 'T', orientation: 'portrait' });+ const html = `<head><!-- <script src="ignored"></script> --><script type="application/json">{"x":"<body>"}</script></head><body>${script}<script>const text="<head>";</script></body>`;+ expect(inspect(html, tiktokPlayableProfile, '{"Playable_orientation":0}').checks.find(item => item.id === 'host-sdk')?.status).toBe('pass');+ });+it('reports an oversized deliverable without declaring runtime acceptance', () => {const report = inspect('<html></html>', { ...genericPlayableProfile, maxBytes: 1 });expect(report.status).toBe('failed');diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 116e166b6..ee53f77be 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,8 +28,15 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+'fix(transform): preserve reflected world transforms and UI bounds':{ note: 'World transforms preserve mirrored axes.' },++ 'fix(playable): verify required SDK script presence and order':+ { note: 'Playable checks verify mandatory SDK scripts and placement.' },+ 'feat(editor): label required host SDK export checks':+ { note: 'Playable checks verify mandatory SDK scripts and placement.' },+'fix(renderer): mirror nine-slice cells and texture borders':{ note: 'Nine-slice texture flips preserve asymmetric borders.' },'fix(renderer): fit nine-slice borders inside small boxes':