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): honor authored texture and audio optimization

yhh68249c3be612
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e49188443..72dc1207e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Playable exports honor authored image and audio optimization.** Automatic asset optimization applies PNG Max Size (including playable overrides) without loading a GPU texture encoder, and converts eligible WAV clips to MP3 at their authored bitrate. Per-clip opt-outs and the build's Skip setting preserve originals; failed asset cooking prevents a successful export. Network budget driven quality selection remains pending.
+
- **Playable preview records identify the delivered archive.** Full export reports verify the adjacent ZIP hash before previewing, catching config changes even when HTML stays identical. Downloaded logs retain HTML/delivery hashes and explicitly disclose omitted events; HTML-only previews remain labeled accordingly.
diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index d8fdbb77f..0f950c6c3 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -85,6 +85,8 @@ Xcode, because only Apple can sign for a device.
## Playable ad networks
+With asset optimization set to **Auto**, playable exports honor PNG **Max Size**, including enabled `playable` import overrides, and compress eligible WAV clips to MP3 at the clip's authored bitrate. PNGs remain PNGs; no GPU texture decoder is added. A clip with compression disabled stays WAV, and **Skip** preserves source payloads. Sources and import settings are unchanged. These settings do not automatically reduce quality to meet a network budget; inspect the export's actual delivery size and check report.
+
Every network takes the same single HTML file but disagrees on three things: how big
it may be, what must sit in `<head>`, and which function sends the player to the
store. Pick the network in the **Package Project** dialog — it sits with the Playable
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
index aba9d326e..5960e37a3 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -73,6 +73,8 @@ import { Aside, Steps } from '@astrojs/starlight/components';
## 试玩广告平台
+资产优化为 **Auto** 时,试玩导出应用 PNG 的 **Max Size**,包括已启用的 `playable` 导入覆盖,并按音频资源设置的码率将可压缩 WAV 转为 MP3。PNG 仍为 PNG,不增加 GPU 纹理解码器;音频禁用压缩时保留 WAV,**Skip** 保留源文件载荷。源文件和导入设置不被修改。这些设置尚不会按网络预算自动降低质量,请查看实际交付文件大小及自检报告。
+
各家平台收的都是同一个单文件 HTML,但在三件事上不一致:体积上限、`<head>` 里必须放什么、
以及用哪个函数把玩家送去商店。在**打包项目**对话框里选平台(就在 Playable 目标自己的设置里),
导出会把这三件事都处理掉。同一个游戏投多家是常事,所以这是**每次打包时的选择**而不是项目属性;
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index f943f2b0d..63e8c007d 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -454,6 +454,8 @@ export async function cookAssets(
opts: {
entryScenes: string[]; outDir: string;
contentAddressed?: boolean; compressTextures?: boolean; atlasTextures?: boolean;
+ /** Honor PNG Max Size without enabling GPU compression or loading Basis. */
+ resizeTextures?: boolean;
compressAudio?: boolean; transcodeVideo?: boolean;
/** Target platform — selects each texture's per-platform Import Settings
* override (Default when absent). No effect on audio/video/atlas. */
@@ -767,6 +769,7 @@ export async function cookAssets(
root, path: entry.path, data, ext, importer: entry.importer, platform,
encoder: textureEnc ? { module: textureEnc, id: encoderId } : null,
compressTextures, atlasTextures, drawnIn3D: drawnIn3D.has(entry.uuid),
+ resizeTextures: opts.resizeTextures,
});
data = t.data; ext = t.ext; cook = t.cook; compressedFormats = t.compressedFormats;
warnings.push(...t.warnings);
diff --git a/pipeline/src/assets/textureCook.ts b/pipeline/src/assets/textureCook.ts
index 1df786611..116f59d73 100644
--- a/pipeline/src/assets/textureCook.ts
+++ b/pipeline/src/assets/textureCook.ts
@@ -106,6 +106,8 @@ export interface TextureCookInput {
/** Null when this cook compresses nothing — the decision is still taken. */
encoder: TextureEncoder | null;
compressTextures: boolean;
+ /** Apply authored Max Size while shipping raw PNGs, without a KTX2 encoder. */
+ resizeTextures?: boolean;
atlasTextures: boolean;
/** A mesh draws this texture (texturesDrawnIn3D) — what Auto compression resolves by. */
drawnIn3D: boolean;
@@ -146,7 +148,7 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
// compression (a huge UI sprite can ship as a smaller raw PNG), and the
// ENCODED size is what block alignment is judged on.
const sourceSize = raster ? safePngDimensions(data) : null;
- const scaled = !!(textureEnc && sourceSize && tex.maxSize > 0 &&
+ const scaled = !!((textureEnc || input.resizeTextures) && sourceSize && tex.maxSize > 0 &&
tex.maxSize < Math.max(sourceSize.width, sourceSize.height));
const size = scaled ? downscaledSize(sourceSize!.width, sourceSize!.height, tex.maxSize) : sourceSize;
const scaledImage = () => downscaleRgba(decodePngImage(path, data), tex.maxSize);
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 08ca9ad2b..39ed183f8 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -848,6 +848,8 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
title,
orientation,
minify: opts.minify,
+ resizeTextures: opts.compressTextures,
+ compressAudio: opts.compressAudio,
features: opts.features,
modulesByPlatform: opts.modulesByPlatform,
runtime,
diff --git a/pipeline/src/export/exportPlayable.ts b/pipeline/src/export/exportPlayable.ts
index 92957dd15..8a0ba6ac4 100644
--- a/pipeline/src/export/exportPlayable.ts
+++ b/pipeline/src/export/exportPlayable.ts
@@ -216,6 +216,10 @@ export async function exportPlayable(opts: {
* to the pixel). An explicit `false` is still honoured.
*/
minify?: boolean;
+ /** Honor authored PNG Max Size; playables still ship images rather than KTX2. */
+ resizeTextures?: boolean;
+ /** WAV to MP3 at the authored bitrate, honoring each clip's compression opt-out. */
+ compressAudio?: boolean;
/** What the project says about its engine modules; see ProjectFeatures.modules. */
features?: ProjectFeatures;
/** Per-target overrides laid over those. */
@@ -243,11 +247,14 @@ export async function exportPlayable(opts: {
// 1. Cook reachable assets to a temp dir (everything ends up inlined → removed after).
progress({ phase: 'Cooking assets' });
- // Playable inlines everything base64 (no KTX2 transcoder), so it doesn't set
- // compressTextures — the platform is threaded for when per-platform Import
- // Settings (e.g. a tighter Max Size for the ad-size cap) gain a raw-downscale path.
- const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: cookDir, platform: 'playable' });
+ // No KTX2 transcoder: PNGs honor Max Size through the raw-image path. Audio
+ // uses the same per-clip settings as other targets. Neither changes sources.
+ const cook = await cookAssets(opts.root, {
+ entryScenes: [opts.entryScene], outDir: cookDir, platform: 'playable',
+ resizeTextures: opts.resizeTextures, compressAudio: opts.compressAudio,
+ });
warnings.push(...cook.warnings);
+ errors.push(...cook.failed.map(failure => `assets: ${failure}`));
// 2. Assets → base64 data URLs, keyed by the scene's @uuid: refs; plus a
// compact logical-path → key map so PATH-style refs (a scene's material
diff --git a/pipeline/tests/export-playable.test.ts b/pipeline/tests/export-playable.test.ts
index 57cd6eb6b..e2e81b4f0 100644
--- a/pipeline/tests/export-playable.test.ts
+++ b/pipeline/tests/export-playable.test.ts
@@ -20,6 +20,8 @@ import { runtimeHostPrebuild } from '../src/bundle/runtimeHosts';
import { build } from 'esbuild';
import { inflateRaw } from '../src/runtime/inflate';
import { OFFICIAL_PACKAGES } from './officialPackagesDir';
+import { solidPng } from './fixtures/solidPng.mjs';
+import { decodePngImage } from '../src/assets/atlasPacker';
/**
* Read an inlined payload back out of the page, the way the host does.
@@ -91,6 +93,82 @@ export function glContextAttributes(){return {};}\n`);
afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
describe('exportGame (playable)', () => {
+ it('honors image platform overrides, audio settings and the build opt-out without changing sources', async () => {
+ const imageId = '11111111-1111-4111-8111-111111111111';
+ const audioId = '22222222-2222-4222-8222-222222222222';
+ const loopId = '33333333-3333-4333-8333-333333333333';
+ const png = solidPng(128, 64, [40, 90, 200, 128]);
+ const wav = Buffer.alloc(44 + 44100 * 2);
+ wav.write('RIFF'); wav.writeUInt32LE(wav.length - 8, 4); wav.write('WAVE', 8);
+ wav.write('fmt ', 12); wav.writeUInt32LE(16, 16);
+ wav.writeUInt16LE(1, 20); wav.writeUInt16LE(1, 22);
+ wav.writeUInt32LE(44100, 24); wav.writeUInt32LE(88200, 28);
+ wav.writeUInt16LE(2, 32); wav.writeUInt16LE(16, 34);
+ wav.write('data', 36); wav.writeUInt32LE(wav.length - 44, 40);
+ for (let f = 0; f < 44100; f++) wav.writeInt16LE(Math.round(Math.sin(f / 20) * 12000), 44 + f * 2);
+ const put = (file: string, bytes: Buffer, uuid: string, type: string, importer: object) => {
+ writeFileSync(path.join(root, file), bytes);
+ writeFileSync(path.join(root, `${file}.meta`), JSON.stringify({ uuid, version: '2.0', type, importer }));
+ };
+ put('assets/ad-image.png', png, imageId, 'texture', {
+ maxSize: 64, compress: 'off', overrides: { playable: { enabled: true, maxSize: 32 } },
+ });
+ put('assets/ad-sound.wav', wav, audioId, 'audio', { compress: true, bitrateKbps: 96 });
+ put('assets/ad-loop.wav', wav, loopId, 'audio', { compress: false });
+ const scene = 'scenes/optimized.esscene';
+ writeFileSync(path.join(root, scene), JSON.stringify({ version: '1.0', name: 'Optimized', entities: [
+ { id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${imageId}` } }] },
+ { id: 1, components: [{ type: 'AudioSource', data: { clip: `@uuid:${audioId}` } }] },
+ { id: 2, components: [{ type: 'AudioSource', data: { clip: `@uuid:${loopId}` } }] },
+ ] }));
+ writeFileSync(path.join(root, `${scene}.meta`), meta('44444444-4444-4444-8444-444444444444', 'scene'));
+ const optimized = await exportGame({
+ root, entryScene: scene, hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'optimized'), platform: 'playable', compressTextures: true, compressAudio: true,
+ });
+ const raw = await exportGame({
+ root, entryScene: scene, hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
+ sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'raw'), platform: 'playable', compressTextures: false, compressAudio: false,
+ });
+ const assetsIn = (dir: string): Record<string, string> => {
+ const html = readFileSync(path.join(dir, 'index.html'), 'utf8');
+ const json = html.split('window.__GAME_ASSETS__=')[1].split(';window.__GAME_PATHMAP__=')[0];
+ return JSON.parse(json);
+ };
+ expect(optimized.ok, optimized.errors.join('\n')).toBe(true);
+ expect(raw.ok, raw.errors.join('\n')).toBe(true);
+ const encoded = assetsIn(optimized.outDir), original = assetsIn(raw.outDir);
+ const resized = decodePngImage('ad-image', Buffer.from(encoded[`@uuid:${imageId}`].split(',')[1], 'base64'));
+ expect([resized.width, resized.height]).toEqual([32, 16]);
+ expect(Array.from(resized.rgba.slice(0, 4))).toEqual([40, 90, 200, 128]);
+ expect(encoded[`@uuid:${imageId}`]).toMatch(/^data:image\/png;/);
+ expect(encoded[`@uuid:${audioId}`]).toMatch(/^data:audio\/mpeg;/);
+ expect(encoded[`@uuid:${loopId}`]).toBe(`data:audio/wav;base64,${wav.toString('base64')}`);
+ expect(original[`@uuid:${imageId}`]).toBe(`data:image/png;base64,${png.toString('base64')}`);
+ expect(original[`@uuid:${audioId}`]).toBe(encoded[`@uuid:${loopId}`]);
+ expect(readFileSync(path.join(optimized.outDir, 'index.html')).byteLength)
+ .toBeLessThan(readFileSync(path.join(raw.outDir, 'index.html')).byteLength);
+ expect(readFileSync(path.join(root, 'assets/ad-image.png'))).toEqual(png);
+ expect(readFileSync(path.join(root, 'assets/ad-sound.wav'))).toEqual(wav);
+ }, 60_000);
+
+ it('fails when an authored image resize cannot produce a reached asset', async () => {
+ const id = '55555555-5555-4555-8555-555555555555';
+ writeFileSync(path.join(root, 'assets/broken.png'), solidPng(128, 64, [20, 30, 40, 255]).subarray(0, 33));
+ writeFileSync(path.join(root, 'assets/broken.png.meta'), JSON.stringify({ uuid: id, version: '2.0', type: 'texture', importer: { maxSize: 32 } }));
+ writeFileSync(path.join(root, 'scenes/broken.esscene'), JSON.stringify({ version: '1.0', name: 'Broken', entities: [
+ { id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${id}` } }] },
+ ] }));
+ writeFileSync(path.join(root, 'scenes/broken.esscene.meta'), meta('66666666-6666-4666-8666-666666666666', 'scene'));
+ const result = await exportGame({ root, entryScene: 'scenes/broken.esscene', hostsDir: HOSTS,
+ packagesDir: OFFICIAL_PACKAGES, sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
+ outDir: path.join(root, 'broken'), platform: 'playable', compressTextures: true });
+ expect(result.ok).toBe(false);
+ expect(result.errors.some(error => error.includes('assets/broken.png'))).toBe(true);
+ });
+
it('produces one self-contained index.html with everything inlined', async () => {
const res = await exportGame({
root,
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b7c603c7e..873c8962a 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(playable): honor authored texture and audio optimization':
+ { note: 'Playable exports honor authored image and audio optimization.' },
+
'fix(playable): bind preview records to delivery hashes':
{ note: 'Playable preview records identify the delivered archive.' },