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
feat(playable): report export checks and pending acceptance
yhh7028e9e21b07
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 50791aead..db646ee35 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,10 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **Playable exports report static checks and pending acceptance.** Export results and the editor package dialog show actual HTML/delivery hashes, network size limits, literal resource references and orientation config checks. Mandatory network SDK scripts are allowed explicitly. CTA, lifecycle, dynamic requests and device/network acceptance remain pending runtime evidence, including when static checks pass.+## [0.81.0] - 2026-10-14### Addeddiff --git a/desktop b/desktopindex 3e056bfc4..9382c304c 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 3e056bfc416af2627fa35080049cb5d8856357aa+Subproject commit 9382c304cfa4b4bf8e82f63077fc7a8108b63934diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex b7d28259e..fc0282da6 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -124,6 +124,8 @@ For Mintegral, call `playableGameEnd()` on a win or loss and `playableRetry()` wMRAID store buttons must pass a destination with `playableCta(storeUrl)` or use a host-provided `window.clickTag`. HTTP(S), Android `market:` and iOS `itms-apps:` links are supported. Missing or invalid destinations produce a configuration warning without calling `mraid.open`. Other networks continue using their own store hooks.+Playable exports include `playableCheck` in their result; the package dialog displays it and the CLI can save it with `--json report.json`. Checks measure the actual delivered file, identify HTML/CSS resource references and validate required orientation config. Exact mandatory host SDK scripts are allowed by the selected profile. File hashes tie the findings to this export. CTA, host lifecycle, dynamic requests and device/network acceptance remain pending runtime verification. The report does not claim that a bridge declaration proves a successful store click.+### 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 7990531de..668ff468d 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -108,6 +108,8 @@ Mintegral 中,胜负结束时调用 `playableGameEnd()`,玩家重玩时调MRAID 安装按钮须通过 `playableCta(storeUrl)` 传入目标地址,或由宿主提供 `window.clickTag`。支持 HTTP(S)、Android `market:` 和 iOS `itms-apps:` 商店链接;地址缺失或无效时提示配置问题,不调用 `mraid.open`。其他网络继续使用自己的商店接口。+试玩导出结果包含 `playableCheck`,打包窗口可查看,命令行可通过 `--json report.json` 保存。报告测量实际交付文件,检查 HTML/CSS 资源引用及必需的方向配置;只按所选 profile 放行指定的宿主 SDK 脚本。文件哈希将检查结果对应到本次导出。CTA、宿主生命周期、动态请求和设备/平台验收保持待运行验证,不把接口声明算作商店跳转成功。+### 我们没内置的平台自己定义就行——内置的那几家写的就是这份契约,没有做不到的事。**打包项目 → 新建平台** 可以diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.mdindex 9c6a849db..044488751 100644--- a/examples/playable-ad/README.md+++ b/examples/playable-ad/README.md@@ -40,3 +40,9 @@ or let the ad host supply `window.clickTag`. HTTP(S), Android `market:` and iOS`itms-apps:` store links are supported. Without a valid destination the bridgereports the missing configuration and does not call `mraid.open`. The sampleproject has no published app destination; configure yours before network acceptance.++Exports return a `playableCheck` report. Save it with `--json report.json` on the CLI,+or inspect it in the editor’s package result. It records HTML/delivery hashes,+network budgets, literal resource references and required orientation config.+CTA, host lifecycle, dynamic requests and network/device acceptance remain marked+for runtime verification; a static pass does not imply ad approval.diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex 0625a7196..08ca9ad2b 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -54,6 +54,7 @@ const BUILTIN_MINIGAME_PROFILES: Readonly<Record<string, MiniGameExportProfile>>alipay: alipayExportProfile,huawei: huaweiExportProfile,};+import type { PlayableCheckReport } from './playableCheck';import { exportPlayable } from './exportPlayable';import { genericPlayableProfile, type PlayableAdProfile } from './playableAdProfile';import type { OnExportProgress } from './exportProgress';@@ -308,6 +309,7 @@ export interface ExportGameResult {packageFile?: string;/** Playable: what the single file is made of. See ExportPlayableResult. */inlineParts?: { path: string; bytes: number }[];+ playableCheck?: PlayableCheckReport;/** The start screen written into the host page, logo included. */splashBytes?: number;/** What the package weighs, and how it fared against the limits in force.diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.tsindex 46b51c2df..92957dd15 100644--- a/pipeline/src/export/exportPlayable.ts+++ b/pipeline/src/export/exportPlayable.ts@@ -34,6 +34,7 @@ import { officialPackagesPlugin } from '../bundle/officialPackages';import { explainBundleErrors, type BundleMessage } from '../bundle/bundleDiagnostics';import type { ScreenOrientation } from './orientationHtml';import { genericPlayableProfile, playableAdInjection, isPlayableZipFileName, type PlayableAdProfile } from './playableAdProfile';+import { checkPlayable, type PlayableCheckReport } from './playableCheck';import { makeZip } from '../../../build-tools/utils/zip.js';import { scanSideModuleIds, sideModuleFiles } from '../bundle/sideModuleScan';import { forcedSideModules, moduleChoices } from '../bundle/engineInstalls';@@ -59,6 +60,7 @@ export interface ExportPlayableResult {* n bytes — true, and useless on the one target where size is a hard cap.*/inlineParts: { path: string; bytes: number }[];+ playableCheck?: PlayableCheckReport;warnings: string[];errors: string[];}@@ -401,6 +403,7 @@ export async function exportPlayable(opts: {// stays beside it: it is what "Preview over http" serves, and what a developer opens// to look at the thing.let zipFile: string | undefined;+ let archiveFiles: { name: string; content: string }[] = [];let bytes = htmlBytes;if (adProfile.delivery === 'zip') {progress({ phase: 'Archiving' });@@ -420,6 +423,7 @@ export async function exportPlayable(opts: {names.add(name);files.push({ name: file.name, data: Buffer.from(file.content, 'utf8') });}+ archiveFiles = files.filter(file => file.name !== 'index.html').map(file => ({ name: file.name, content: file.data.toString('utf8') }));await writeFile(zipFile, makeZip(files));// The archive is the file being sent, so it is the one the limit applies to.bytes = (await stat(zipFile)).size;@@ -434,7 +438,9 @@ export async function exportPlayable(opts: {// the playable and the 4MB WeChat main package alike.if (adProfile.deliveryNote) warnings.push(adProfile.deliveryNote);+ const playableCheck = checkPlayable({ profile: adProfile, html: await readFile(outFile), delivery: await readFile(zipFile ?? outFile), archiveFiles });return {+ playableCheck,ok: errors.length === 0, platform: 'playable', outDir: absOut,included: cook.included.length, bytes, htmlBytes, zipFile, inlineParts: spans, warnings, errors,};diff --git a/pipeline/src/export/platformCatalog.ts b/pipeline/src/export/platformCatalog.tsindex f45c82044..369b0cd11 100644--- a/pipeline/src/export/platformCatalog.ts+++ b/pipeline/src/export/platformCatalog.ts@@ -512,6 +512,12 @@ async function importPlatformModule(if (candidate.zipFileName !== undefined && !isPlayableZipFileName(candidate.zipFileName)) {return { error: '`zipFileName` must be a portable alphanumeric/underscore ZIP filename' };}+ 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.configOrientationField !== undefined && (typeof candidate.configOrientationField !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate.configOrientationField))) {+ return { error: 'configOrientationField must name a JSON field' };+ }for (const hook of ['emitHead', 'emitBody', 'emitBridge', 'emitZipFiles'] as const) {if (candidate[hook] !== undefined && typeof candidate[hook] !== 'function') {return { error: `playable profile hook ${hook} must be a function` };@@ -637,6 +643,8 @@ export async function loadPlayableProfile(root: string | null, id: string | undemaxHtmlBytes: mod.maxHtmlBytes,delivery: mod.delivery,zipFileName: mod.zipFileName,+ allowedExternalScripts: mod.allowedExternalScripts,+ configOrientationField: mod.configOrientationField,deliveryNote: mod.deliveryNote,emitHead: mod.emitHead,emitBody: mod.emitBody,diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.tsindex fadfe37b1..65fba22dc 100644--- a/pipeline/src/export/playableAdProfile.ts+++ b/pipeline/src/export/playableAdProfile.ts@@ -52,6 +52,10 @@ export interface PlayableAdProfile {readonly delivery?: 'single-html' | 'zip';/** Portable archive filename; defaults to playable.zip. */readonly zipFileName?: string;+ /** Exact host SDK scripts allowed by this network’s published integration. */+ readonly allowedExternalScripts?: readonly string[];+ /** 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* warning, because an export that looks finished but isn't is worse. */readonly deliveryNote?: string;@@ -107,6 +111,7 @@ export const metaPlayableProfile: PlayableAdProfile = {* @see https://support.google.com/google-ads/answer/9981650*/export const googlePlayableProfile: PlayableAdProfile = {+ allowedExternalScripts: ['https://tpc.googlesyndication.com/pagead/gadgets/html5/api/exitapi.js'],id: 'google',label: 'Google Ads (App campaigns)',maxBytes: 5 * 1024 * 1024,@@ -206,6 +211,8 @@ 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'],+ configOrientationField: 'Playable_orientation',id: 'tiktok', label: 'TikTok', maxBytes: 5 * 1024 * 1024 - 1,limitNote: 'TikTok requires a ZIP less than 5MB (official September 2026 specification)',delivery: 'zip',@@ -224,6 +231,7 @@ export const tiktokPlayableProfile: PlayableAdProfile = {/** @see https://ads.tiktok.com/resources/help/article/how-to-create-tiktok-pangle-playable-ads */export const panglePlayableProfile: PlayableAdProfile = {...tiktokPlayableProfile,+ configOrientationField: 'playable_orientation',id: 'pangle', label: 'TikTok Ad Network (Pangle, overseas)',limitNote: 'TikTok Ad Network requires a ZIP less than 5MB (official September 2026 specification)',emitBody: () => '<script src="https://sf16-muse-va.ibytedtos.com/obj/union-fe-nc-i18n/playable/sdk/playable-sdk.js"></script>',diff --git a/pipeline/src/export/playableCheck.ts b/pipeline/src/export/playableCheck.tsnew file mode 100644index 000000000..994f4304c--- /dev/null+++ b/pipeline/src/export/playableCheck.ts@@ -0,0 +1,76 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+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 interface PlayableCheckItem {+ id: PlayableCheckId;+ status: 'pass' | 'fail' | 'needs-runtime';+ detail: string;+}++export interface PlayableCheckReport {+ version: 1;+ network: string;+ status: 'failed' | 'needs-runtime';+ htmlSha256: string;+ deliverySha256: string;+ checks: PlayableCheckItem[];+}++/** Checks literal HTML references; embedded scripts still need request tracing. */+function markupReferences(html: string): { tag: string; url: string }[] {+ const refs: { tag: string; url: string }[] = [];+ const css = (value: string) => {+ for (const match of value.matchAll(/url\(\s*['"]?([^'"\s)]+)['"]?\s*\)/gi)) refs.push({ tag: 'css', url: match[1] });+ for (const match of value.matchAll(/@import\s+['"]([^'"]+)['"]/gi)) refs.push({ tag: 'css', url: match[1] });+ };+ const markup = html.replace(/<!--[\s\S]*?-->/g, '').replace(/<(script|style)\b((?:"[^"]*"|'[^']*'|[^'">])*)>([\s\S]*?)<\/\1\s*>/gi,+ (_all, tag: string, attributes: string, body: string) => { if (tag.toLowerCase() === 'style') css(body); return `<${tag}${attributes}></${tag}>`; });+ for (const match of markup.matchAll(/<([a-z][\w:-]*)\b((?:"[^"]*"|'[^']*'|[^'">])*)>/gi)) {+ const tag = match[1].toLowerCase();+ for (const attr of match[2].matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g)) {+ const key = attr[1].toLowerCase(), value = attr[2] ?? attr[3] ?? attr[4];+ if (key === 'style') css(value);+ else if (key === 'src' || key === 'poster' || (key === 'data' && tag === 'object')+ || ((key === 'href' || key === 'xlink:href') && ['link', 'image', 'use'].includes(tag))) refs.push({ tag, url: value });+ else if (key === 'srcset') {+ for (const url of value.matchAll(/(?:https?:)?\/\/[^\s,]+/gi)) refs.push({ tag, url: url[0] });+ refs.push({ tag: 'srcset', url: value });+ }+ }+ }+ return refs.filter(ref => ref.tag === 'srcset' || !/^(data:|blob:|#)/i.test(ref.url));+}++export function checkPlayable(input: {+ profile: PlayableAdProfile;+ html: Buffer;+ delivery: Buffer;+ archiveFiles: { name: string; content: string }[];+}): PlayableCheckReport {+ const { profile, html, delivery, archiveFiles } = input;+ const checks: PlayableCheckItem[] = [];+ const check = (id: PlayableCheckId, valid: boolean, detail: string) => checks.push({ id, status: valid ? 'pass' : 'fail', detail });+ check('delivery-size', delivery.length <= profile.maxBytes, `${delivery.length} / ${profile.maxBytes} bytes; ${profile.limitNote}`);+ if (profile.maxHtmlBytes !== undefined) check('html-size', html.length <= profile.maxHtmlBytes, `${html.length} / ${profile.maxHtmlBytes} bytes`);+ const refs = markupReferences(html.toString('utf8'));+ 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.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. */ }+ check('orientation-config', valid, `config.json: ${profile.configOrientationField} must be 0, 1 or 2`);+ }+ checks.push(+ { id: 'cta-interaction', status: 'needs-runtime', detail: 'Verify the actual user gesture and destination in the network container; declaring a bridge does not prove a store click.' },+ { id: 'host-lifecycle', status: 'needs-runtime', detail: 'Verify readiness, start/viewability, close/background, audio and retry using the target host.' },+ { id: 'runtime-requests', status: 'needs-runtime', detail: 'Trace runtime requests, redirects and offline behavior; embedded JavaScript is not executed by this check.' },+ { id: 'network-acceptance', status: 'needs-runtime', detail: 'Complete the official network preview and physical device acceptance.' },+ );+ return { version: 1, network: profile.id, status: checks.some(item => item.status === 'fail') ? 'failed' : 'needs-runtime',+ htmlSha256: createHash('sha256').update(html).digest('hex'), deliverySha256: createHash('sha256').update(delivery).digest('hex'), checks };+}diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.tsindex ce5641af6..719095609 100644--- a/pipeline/tests/export-playable.test.ts+++ b/pipeline/tests/export-playable.test.ts@@ -109,6 +109,9 @@ describe('exportGame (playable)', () => {});expect(res.ok).toBe(true);+ expect(res.playableCheck?.status).toBe('needs-runtime');+ expect(res.playableCheck?.htmlSha256).toMatch(/^[a-f0-9]{64}$/);+ expect(res.playableCheck?.checks.find(check => check.id === 'cta-interaction')?.status).toBe('needs-runtime');expect(res.platform).toBe('playable');// Single file: only index.html, temp cook dir removed, no staged assets dir.diff --git a/pipeline/tests/playable-check.test.ts b/pipeline/tests/playable-check.test.tsnew file mode 100644index 000000000..dcebfd60e--- /dev/null+++ b/pipeline/tests/playable-check.test.ts@@ -0,0 +1,57 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { checkPlayable } from '../src/export/playableCheck';+import { genericPlayableProfile, tiktokPlayableProfile } from '../src/export/playableAdProfile';++const inspect = (html: string, profile = genericPlayableProfile, config?: string) => checkPlayable({+ profile, html: Buffer.from(html), delivery: Buffer.from(html),+ archiveFiles: config === undefined ? [] : [{ name: 'config.json', content: config }],+});++describe('playable export checks', () => {+ it('records bytes and file identity while keeping interactions unverified', () => {+ const report = inspect('<html><body><canvas></canvas></body></html>');+ expect(report.status).toBe('needs-runtime');+ expect(report.checks.find(item => item.id === 'delivery-size')?.status).toBe('pass');+ expect(report.checks.find(item => item.id === 'cta-interaction')?.status).toBe('needs-runtime');+ expect(report.checks.find(item => item.id === 'host-lifecycle')?.status).toBe('needs-runtime');+ expect(report.htmlSha256).toMatch(/^[a-f0-9]{64}$/);+ expect(inspect('<html>changed</html>').htmlSha256).not.toBe(report.htmlSha256);+ });++ it.each(['<img src="https://example.com/image.png">', '<script src="game.js"></script>',+ '<style>body{background:url(https://example.com/image.png)}</style>',+ '<style>@import "theme.css";</style>', '<svg><image href="https://example.com/image.png"/></svg>'])+ ('reports an unembedded resource: %s', html => {+ const report = inspect(html);+ expect(report.status).toBe('failed');+ expect(report.checks.find(item => item.id === 'markup-resources')?.status).toBe('fail');+ });++ it('ignores script text and comments as markup, and allows embedded resources', () => {+ const report = inspect('<script>const unused = "<img src=remote.png>";</script><!--<img src=remote.png>--><img src="data:image/png;base64,AAAA">');+ expect(report.checks.find(item => item.id === 'markup-resources')?.status).toBe('pass');+ });++ it('allows only the exact mandatory SDK script and verifies config field casing', () => {+ const script = tiktokPlayableProfile.emitBody!({ title: 'T', orientation: 'portrait' });+ const good = inspect(script, tiktokPlayableProfile, '{"Playable_orientation":0}');+ expect(good.checks.find(item => item.id === 'markup-resources')?.status).toBe('pass');+ expect(good.checks.find(item => item.id === 'orientation-config')?.status).toBe('pass');+ expect(inspect(script, tiktokPlayableProfile, '{"playable_orientation":0}').status).toBe('failed');+ expect(inspect(script.replace('<script src=', '<img src='), tiktokPlayableProfile, '{"Playable_orientation":0}').status).toBe('failed');+ });++ it('keeps ambiguous srcset parsing pending and rejects visible external candidates', () => {+ expect(inspect('<img srcset="data:image/png;base64,AAAA 1x">').checks.find(item => item.id === 'markup-resources')?.status).toBe('needs-runtime');+ expect(inspect('<img srcset="data:image/png;base64,AAAA 1x, https://example.com/img.png 2x">').status).toBe('failed');+ });++ it('reports an oversized deliverable without declaring runtime acceptance', () => {+ const report = inspect('<html></html>', { ...genericPlayableProfile, maxBytes: 1 });+ expect(report.status).toBe('failed');+ expect(report.checks.find(item => item.id === 'delivery-size')?.status).toBe('fail');+ expect(report.checks.find(item => item.id === 'network-acceptance')?.status).toBe('needs-runtime');+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d500abf8b..6b90860e0 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(playable): report export checks and pending acceptance':+ { note: 'Playable exports report static checks and pending acceptance.' },+ 'feat(editor): show playable export checks in package results':+ { note: 'Playable exports report static checks and pending acceptance.' },'fix(playable): pass store destinations through the CTA bridge':{ note: 'MRAID store clicks carry their destination.' },'fix(playable): observe MRAID readiness and viewability':