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(editor): Package dialog exposes texture compression + auto-atlas
yhhcf1ac3ec4729
diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.mdxindex 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 themanifest. 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 packsthem 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 countingdiff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdxindex 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 forWeb 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 settingsPer-target metadata lives in **Project Settings → Packaging** and is saved with thediff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/guides/wechat.mdxindex 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 movingon-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 isweight you don't ship.- **Test in WeChat DevTools**, not just the browser — the file system, storage, anddiff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdxindex 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.mdxindex 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.mdxindex 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`),让子包下载不卡过渡。