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.

feat(editor): Package dialog exposes texture compression + auto-atlas

yhhcf1ac3ec4729
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 69c0f6106..df2212c4f 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -524,7 +524,7 @@ ipcMain.handle('project:cookAssets', async (_e, outDir?: string) => {
// Export a runnable web build (play == ship): cook + game host + wasm + index.html.
ipcMain.handle(
'project:exportGame',
- async (e, opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable' }) => {
+ async (e, opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable'; compressTextures?: boolean; atlasTextures?: boolean }) => {
const root = requireRoot();
const manifest = await readManifest(root);
const entryScene = manifest.defaultScene;
@@ -557,6 +557,8 @@ ipcMain.handle(
wechatOrientation: plat?.wechat?.orientation,
minify: opts?.minify,
sourcemap: opts?.sourcemap,
+ compressTextures: opts?.compressTextures,
+ atlasTextures: opts?.atlasTextures,
onProgress: (p) => e.sender.send('project:exportProgress', p),
});
},
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 4dc523fdb..a0a650084 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -87,7 +87,7 @@ const api = {
/** Cook reachable assets for shipping → staged files + runtime manifest in `outDir`. */
cookAssets: (outDir?: string): Promise<CookResult> => ipcRenderer.invoke('project:cookAssets', outDir),
/** Export a runnable web build (play==ship) → self-contained `outDir` (default dist-game/). */
- exportGame: (opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable' }): Promise<ExportGameResult> =>
+ exportGame: (opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable'; compressTextures?: boolean; atlasTextures?: boolean }): Promise<ExportGameResult> =>
ipcRenderer.invoke('project:exportGame', opts),
/** Subscribe to export build-log phases while a package runs. Returns unsubscribe. */
onExportProgress: (cb: (p: { phase: string; detail?: string }) => void): (() => void) => {
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index e61f7a071..5746da4de 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -91,6 +91,8 @@ export function BuildDialog() {
const [outDir, setOutDir] = useState(saved.outDir?.[initialPlatform] ?? initialDef.defaultOut);
const [openFolder, setOpenFolder] = useState(saved.openFolder ?? true);
const [sourceMaps, setSourceMaps] = useState(saved.sourceMaps ?? false);
+ const [compressTextures, setCompressTextures] = useState(saved.compressTextures ?? false);
+ const [atlasTextures, setAtlasTextures] = useState(saved.atlasTextures ?? false);
const [phase, setPhase] = useState<Phase>('idle');
const [result, setResult] = useState<Result | null>(null);
const [log, setLog] = useState<string[]>([]);
@@ -117,7 +119,7 @@ export function BuildDialog() {
setResult(null);
setLog([]);
// Persist the chosen settings to project.esproject (restored next time).
- void ProjectStore.setPackaging({ platform, config, sourceMaps, openFolder, outDir: { [platform]: outDir } });
+ void ProjectStore.setPackaging({ platform, config, sourceMaps, openFolder, compressTextures, atlasTextures, outDir: { [platform]: outDir } });
// Live build log (UE-style): each export phase streams over IPC.
const unsub = window.estella.project?.onExportProgress?.((p) =>
setLog((l) => [...l, p.detail ? `${p.phase} — ${p.detail}` : p.phase]),
@@ -128,6 +130,8 @@ export function BuildDialog() {
outDir,
minify: config === 'shipping',
sourcemap: def.sourceMaps && sourceMaps,
+ compressTextures,
+ atlasTextures,
})) as Result | null;
if (!res) {
setResult({ ok: false, outDir, included: 0, warnings: [], errors: ['no project open'] });
@@ -229,6 +233,14 @@ export function BuildDialog() {
Include source maps
</label>
)}
+ <label className="build__opt">
+ <input type="checkbox" checked={compressTextures} onChange={(e) => setCompressTextures(e.target.checked)} />
+ Compress textures (PNG → KTX2)
+ </label>
+ <label className="build__opt">
+ <input type="checkbox" checked={atlasTextures} onChange={(e) => setAtlasTextures(e.target.checked)} />
+ Pack .atlas folders into atlases
+ </label>
{def.prereq && (
<div className="build__prereq">
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 2cda9a6bf..71a45c808 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1091,7 +1091,7 @@ class ProjectStoreImpl {
* (default `dist-game/`). Returns the bridge result so the Build dialog can
* render status/log; null if no project is open.
*/
- async exportGame(opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable' }) {
+ async exportGame(opts?: { outDir?: string; minify?: boolean; sourcemap?: boolean; platform?: 'web' | 'desktop' | 'wechat' | 'playable'; compressTextures?: boolean; atlasTextures?: boolean }) {
if (!this.state) return null;
return window.estella.project.exportGame(opts);
}
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 99615e746..2ca583561 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -103,6 +103,10 @@ export interface ProjectPackaging {
config?: 'development' | 'shipping';
sourceMaps?: boolean;
openFolder?: boolean;
+ /** Cook PNGs to GPU-ready KTX2 (Basis Universal). */
+ compressTextures?: boolean;
+ /** Pack `<name>.atlas/` folders into atlas pages at cook time. */
+ atlasTextures?: boolean;
/** Per-platform output-dir overrides (else the per-platform default). */
outDir?: Partial<Record<'web' | 'desktop' | 'wechat' | 'playable', string>>;
/** Per-platform packaging config (appid, app id, orientation, …). */
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index f60f58ca7..8ba62a842 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -115,14 +115,16 @@ At build time the **cook** walks the dependency graph from your entry scene(s),
**culls anything unreachable**, stages the reachable files, and writes the
manifest. Along the way it can:
-- **Compress textures** — PNGs are encoded to GPU-ready **KTX2** (Basis
- Universal), which the runtime transcodes to the best format the device supports
- (ASTC → ETC2 → S3TC, falling back to RGBA8).
+- **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal),
+ which the runtime transcodes to the best format the device supports (ASTC → ETC2
+ → S3TC, falling back to RGBA8). Toggle **Compress textures** in the Package dialog.
- **Content-address** — name each shipped file by a hash of its bytes, so URLs
- are immutable and identical files dedupe to a single copy.
+ are immutable and identical files dedupe to a single copy. On by default for
+ Web/Desktop.
- **Auto-atlas** — put loose PNGs in a `<name>.atlas/` folder and the cook packs
them into atlas pages (with the frame UVs written into the manifest), so many
- small sprites ship as one texture and batch in one draw call. Opt-in per export.
+ small sprites ship as one texture and batch in one draw call. Toggle **Pack .atlas
+ folders** in the Package dialog.
## Lifetime & reference counting
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdx
index 205615579..75aafa8c1 100644
--- a/docs/astro/src/content/docs/guides/build-export.mdx
+++ b/docs/astro/src/content/docs/guides/build-export.mdx
@@ -59,6 +59,19 @@ The Package Project dialog reminds you when a target's runtime is missing.
- **Source maps** map the running bundle back to your TypeScript. They're available for
Web and Desktop; leave them off for a release build.
+## Asset cook options
+
+The Package dialog also drives what the **cook** does to your assets:
+
+- **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal), which
+ the runtime transcodes to the best format each device supports (ASTC → ETC2 → S3TC,
+ falling back to RGBA8). Smaller downloads and less VRAM; leave off to ship raw PNGs.
+- **Pack `.atlas` folders** — pack the loose PNGs in each `<name>.atlas/` folder into
+ atlas pages at cook time, so many small sprites ship as one texture and batch in one
+ draw call.
+- **Content addressing** is on by default for Web/Desktop (each file named by a hash of
+ its bytes — immutable URLs, automatic dedupe).
+
## Packaging settings
Per-target metadata lives in **Project Settings → Packaging** and is saved with the
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdx
index 2a2f38335..7df1c6211 100644
--- a/docs/astro/src/content/docs/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/guides/wechat.mdx
@@ -63,8 +63,8 @@ levels download on demand rather than bloating the initial package:
- **Stay under the main-package limit** (WeChat caps the initial package) by moving
on-demand content into `subpackages/<name>/` — see [Assets](/docs/guides/assets/).
-- **Compress textures** (PNG→KTX2 at cook time) to shrink the package and speed
- first load.
+- **Compress textures** — enable **Compress textures** in the Package dialog to cook
+ PNGs to KTX2, shrinking the package and speeding first load.
- **Build only the side modules you use** — each unused `*-wechat` module you skip is
weight you don't ship.
- **Test in WeChat DevTools**, not just the browser — the file system, storage, and
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
index 3bd842670..23f2245ae 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -103,11 +103,13 @@ const { failed } = await assets.preload(
构建时,**烘焙**从入口场景出发遍历依赖图,**剔除一切触达不到的资源**,暂存可达文件,
并写出清单。过程中它还能:
-- **压缩纹理** —— PNG 被编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
- 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。
+- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
+ 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。在打包对话框勾选**压缩纹理**。
- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。
+ Web/桌面默认开启。
- **自动图集** —— 把零散的 PNG 放进 `<name>.atlas/` 文件夹,烘焙时会把它们打包成图集页
- (帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。按导出可选开启。
+ (帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。在打包对话框勾选
+ **打包 .atlas 文件夹**。
## 生命周期与引用计数
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 e1d5616c5..400ff765e 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
@@ -53,6 +53,17 @@ node build-tools/cli.js build -t playable
- **Shipping** —— 为体积和速度压缩。这是你发布用的。
- **source map** 把运行的 bundle 映射回你的 TypeScript。Web 和桌面可用;发布构建请关掉。
+## 资产烘焙选项
+
+打包对话框还控制**烘焙**如何处理你的资产:
+
+- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
+ 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。下载更小、显存更省;关掉则
+ 发布原始 PNG。
+- **打包 `.atlas` 文件夹** —— 烘焙时把每个 `<name>.atlas/` 文件夹里零散的 PNG 打包成图集页,
+ 于是许多小精灵作为一张纹理发布、在一次绘制里合批。
+- **内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。
+
## 打包设置
每个目标的元数据在 **项目设置 → 打包(Packaging)** 里,并随项目保存:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
index 60657f37e..f0c046ca9 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
@@ -59,7 +59,7 @@ node build-tools/cli.js build -t physics-wechat
- **保持在主包限制以内**(微信对初始包有上限):把按需内容移到 `subpackages/<name>/`——见
[资源](/docs/zh-cn/guides/assets/)。
-- **压缩纹理**(cook 时 PNG→KTX2)以缩小包体、加快首屏加载。
+- **压缩纹理** —— 在打包对话框勾选**压缩纹理**,把 PNG 烘焙为 KTX2,缩小包体、加快首屏加载。
- **只构建你用到的侧模块**——每跳过一个未用的 `*-wechat` 模块就是少发的体积。
- **在微信开发者工具里测试**,而不只是浏览器——文件系统、存储与套接字后端都与 Web 不同。
- **在游玩中预加载下一关的分组**(`loadGroup`),让子包下载不卡过渡。