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(assets): a texture's Compression is Auto, GPU compressed or Original image

esengined19ec375e183
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 299b746b8..030a62846 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Changed
+
+- **A texture's Compression is Auto, GPU compressed or Original image, and a build does what it says.** A build used to encode every texture with Compress on and then ship whichever file was smaller, overruling the row: ORCA Bistro's export shipped 321 of its textures as PNGs, 4.7 GiB decoded on a player's GPU. Every engine we looked at (Godot, Unity, Unreal, Cocos Creator) keeps the author's per-texture choice, and Godot's defaults are what Auto follows: a texture a mesh draws — directly, or through its material — is GPU compressed, where video memory is the cost; a sprite or UI image ships as its file, where a flat PNG is often a tenth of the KTX2. An explicit choice is kept whatever draws the texture. A `.meta` written before this keeps its meaning: its `true` was the default every fresh file got, so it reads as Auto, and `false` as Original image. Across the examples, the 2D ones ship the same bytes (tilemap-demo 6 KB more); a 3D one with a 1024 texture on a mesh ships it as a 1.3 MB KTX2 where the PNG was 14 KB. The Inspector says why a texture ships raw, and an export names the Original-image textures a mesh draws and what they cost decoded — a lightmap, kept exact by its bake, left out.
+
### Added
- **A directional light can be the environment's sun.** An HDRI with a sun in it lit a scene twice when the scene also had a sun — once in the environment's diffuse light, spread across the whole sky and into every shadow, and once from the light — and the two pointed wherever each was set. Importing a `.hdr` now finds its sun: the compact region around its brightest texel, when it carries a real share of the light. The `.esenv` keeps the full irradiance and adds the sun's direction, its strength and the sky's irradiance without it. A Directional light with **Follow Environment Sun** takes its direction and strength from that sun, turned with the environment and scaled by the ambient light as the panorama is; its own colour and intensity scale it on top. The environment then lights with the sky alone. The editor draws the light along the sun, and a light following an environment with no sun is left out of the frame with the reason in the Inspector. Bakes resolve it the same way. Under ORCA Bistro's HDRI the sunlit street's colour now matches the reference render, and its shadows are blue sky rather than warm sun. Reimport a `.hdr` to add its sun.
@@ -24,7 +28,9 @@ published separately; it ships inside the editor.
### Fixed
-- **A large project opens in minutes, not half an hour.** The editor uploaded every texture as decoded pixels. ORCA Bistro's 224 2K textures came to 4.7 GiB of video memory, past what an 8 GB card had free, so Windows paged them in and out while the GPU sat idle. One frame stalled for up to 25 minutes, and Chromium's GPU watchdog then restarted the GPU process and the whole load began again. The editor, and the play realm beside it, now draw textures GPU-compressed, as a build does: the same KTX2, from the same cook cache, so the editor pays nothing for art an export already compressed and an export after an editing session encodes nothing. A texture the cache does not hold yet is drawn from a preview no larger than 1024 while it compresses in the background, then reloaded, and the editor does not report idle until it is. Textures with Compress off stay as they are. The editor keeps the KTX2 even where a build ships the PNG because the file is smaller: in a viewport, video memory is the cost. Bistro now opens with a cold GPU cache in about two minutes, where it took 20 to 36.
+- **physics-3d's lightmap is read as the light it is.** Its `.meta` predated the bake owning an atlas's import settings, so it was sampled as sRGB and repeated at its edges. `bake-scene --check` now holds an atlas's import settings to the bake's too, which is how it was found.
+
+- **A large project opens in minutes, not half an hour.** The editor uploaded every texture as decoded pixels. ORCA Bistro's 224 2K textures came to 4.7 GiB of video memory, past what an 8 GB card had free, so Windows paged them in and out while the GPU sat idle. One frame stalled for up to 25 minutes, and Chromium's GPU watchdog then restarted the GPU process and the whole load began again. The editor, and the play realm beside it, now draw textures GPU-compressed, as a build does: the same KTX2, from the same cook cache, so the editor pays nothing for art an export already compressed and an export after an editing session encodes nothing. A texture the cache does not hold yet is drawn from a preview no larger than 1024 while it compresses in the background, then reloaded, and the editor does not report idle until it is. Textures with Compress off stay as they are. The editor draws each texture as the build ships it, by the same Compression rule. Bistro now opens with a cold GPU cache in about two minutes, where it took 20 to 36.
- **`bake-scene` refuses a scene made of prefab instances instead of crashing on it.** It cannot expand an instance, so it found nothing to bake and then threw on the instance entity; it now says to bake such a scene in the editor, as it already did for parented entities.
diff --git a/desktop b/desktop
index 50461b1d7..1c86428f2 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 50461b1d7d74ccad839cbfc0e00d7e7916280e61
+Subproject commit 1c86428f26676111e8a3f76dd57c8710543a4dc1
diff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdx
index 412e39028..8edc9bcfc 100644
--- a/docs/astro/src/content/docs/assets/overview.mdx
+++ b/docs/astro/src/content/docs/assets/overview.mdx
@@ -151,7 +151,8 @@ way it can:
- **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), mip chain included. Per-asset **Import Settings**
- decide this, with a tab per platform (below), so a texture can be compressed
+ decide this — **Auto** compresses what a mesh draws and ships sprites and UI as
+ their file — with a tab per platform (below), so a texture can be compressed
harder for a phone than for the web; the Package dialog's **Compression** switch
only chooses whether to honor those settings or skip them all.
- **Content-address** — name each shipped file by a hash of its bytes, so URLs
diff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdx
index b045ee367..28a053be4 100644
--- a/docs/astro/src/content/docs/assets/textures.mdx
+++ b/docs/astro/src/content/docs/assets/textures.mdx
@@ -118,8 +118,8 @@ Browser — every sprite that uses the texture inherits them.
| Setting | Default | What it does |
|---|---|---|
| **Max Size** | `2048` | Downscale cap applied at cook (a power of two). A source larger than this on its longest side is box-filtered down; a smaller source is untouched. |
-| **Compress** | `true` | GPU-compress to KTX2 (Basis Universal) at cook. It stays compressed in VRAM and transcodes per device. Turn **off** for crisp UI and smooth gradients. |
-| **Compress Format** | `uastc` | `uastc` — high quality, larger. `etc1s` — much smaller, lower quality (good for photographic art). Only used when Compress is on. |
+| **Compression** | `Auto` | **GPU compressed** ships a KTX2 (Basis Universal) that stays compressed in video memory — about a quarter of the decoded image — and transcodes per device. **Original image** ships the file as it is: exact, and for flat art far smaller to download, but decoded in full on the GPU. **Auto** is GPU compressed for a texture a mesh draws (directly or through its material) and the original image for sprites and UI. A build does what this row says; it never swaps one for the other because a file came out smaller. |
+| **Compress Format** | `uastc` | `uastc` — high quality, larger. `etc1s` — much smaller, lower quality (good for photographic art). Only used when the texture is GPU compressed. |
| **Filter** | `linear` | Sampling filter. `nearest` keeps pixel art crisp; `linear` smooths. |
| **Wrap** | `repeat` | How UVs outside `[0,1]` are addressed: `repeat`, `clamp`, `mirror`. |
| **Premultiply Alpha** | `false` | Multiply RGB by alpha at import. |
@@ -127,7 +127,8 @@ Browser — every sprite that uses the texture inherits them.
| **9-Slice Border** | `0,0,0,0` | Left/right/top/bottom border in **texture pixels**: where the image's corners end. Authored once here, inherited by every `UIVisual` set to Sliced. |
<Aside type="tip">
- **Pixel art**: set Filter to `nearest` and turn Compress **off**. Linear filtering
+ **Pixel art**: set Filter to `nearest` and Compression to **Original image** (Auto already
+ ships a sprite that way). Linear filtering
blurs the pixels you drew, and block compression puts artefacts exactly where hard
colour edges are.
</Aside>
@@ -147,7 +148,7 @@ is no honest picture of forty.
### Per-platform overrides
-Max Size, Compress and Compress Format can be overridden **per platform** — the tabs
+Max Size, Compression and Compress Format can be overridden **per platform** — the tabs
beside Default in Import Settings. This is the "encode once, transcode per GPU"
pipeline: ship the desktop build a 2048 UASTC texture and the WeChat build a 1024
ETC1S one from the same source file. See
diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
index 70d3aa5af..f58a77b14 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
@@ -132,7 +132,7 @@ const { failed } = await assets.preload(
- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8),连同 mip 链。这由逐资产的
- **导入设置**决定,每个平台一个页签(见下图),所以一张纹理可以为手机压得比网页端更狠;
+ **导入设置**决定——**Auto**(自动)压缩网格用到的贴图,精灵和 UI 按原文件发布——每个平台一个页签(见下图),所以一张纹理可以为手机压得比网页端更狠;
打包对话框的**资源压缩**开关只选择遵循还是全部跳过这些设置。
- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。
Web/桌面默认开启。
diff --git a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
index 9106d2382..25325b468 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
@@ -108,8 +108,8 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而
| 设置 | 默认 | 作用 |
|---|---|---|
| **Max Size** | `2048` | cook 时的降采样上限(2 的幂)。最长边超过它的源图会被 box 滤波缩下来;更小的源图原样保留。 |
-| **Compress** | `true` | cook 时压成 KTX2(Basis Universal)。它在显存里保持压缩、按设备转码。想要锐利 UI 和平滑渐变就**关掉**。 |
-| **Compress Format** | `uastc` | `uastc` —— 质量高、体积大。`etc1s` —— 小得多、质量低(适合照片类/低频美术)。仅在 Compress 开启时使用。 |
+| **Compression** | `Auto` | **GPU compressed**(GPU 压缩)发布 KTX2(Basis Universal),在显存里保持压缩——约为解码后的四分之一——并按设备转码。**Original image**(原图)按原文件发布:画质无损,平涂美术下载体积小得多,但在 GPU 上是完整解码的大小。**Auto**(自动)对网格用到的贴图(直接引用或经由材质)用 GPU 压缩,对精灵和 UI 用原图。构建严格按这一项执行,不会因为哪个文件更小就擅自替换。 |
+| **Compress Format** | `uastc` | `uastc` —— 质量高、体积大。`etc1s` —— 小得多、质量低(适合照片类/低频美术)。仅在贴图使用 GPU 压缩时生效。 |
| **Filter** | `linear` | 采样过滤。`nearest` 保持像素锐利;`linear` 平滑。 |
| **Wrap** | `repeat` | `[0,1]` 之外的 UV 如何寻址:`repeat`、`clamp`、`mirror`。 |
| **Premultiply Alpha** | `false` | 导入时把 RGB 乘上 alpha。 |
@@ -117,7 +117,7 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而
| **9-Slice Border** | `0,0,0,0` | 左/右/上/下边框,单位是**纹理像素**:图片的角在哪里结束。在这里授权一次,每个设成 Sliced 的 `UIVisual` 都继承。 |
<Aside type="tip">
- **像素画**:Filter 设 `nearest`,Compress **关掉**。线性过滤会把你画的像素糊掉,
+ **像素画**:Filter 设 `nearest`,Compression 设为 **Original image**(原图;自动模式下精灵本来就是原图)。线性过滤会把你画的像素糊掉,
而块压缩的瑕疵恰恰出现在硬色边上。
</Aside>
@@ -132,7 +132,7 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而
### 按平台覆盖
-Max Size、Compress、Compress Format 可以**按平台覆盖**——就是导入设置里 Default 旁边那排页签。
+Max Size、Compression、Compress Format 可以**按平台覆盖**——就是导入设置里 Default 旁边那排页签。
这就是「编码一次、按 GPU 转码」的管线:同一个源文件,桌面端发 2048 的 UASTC,微信发 1024 的
ETC1S。见[烘焙与压缩](/docs/zh-cn/assets/overview/#烘焙压缩与内容寻址)。
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index dd5de0712..87fa43a09 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -18,7 +18,7 @@
* This is the reachability + manifest + staging core they all build on.
*/
import { ENV_IMAGE_FIELDS } from './environmentFormat';
-import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { writeFile, mkdir, readFile, open } from 'node:fs/promises';
import { statSync } from 'node:fs';
import { isInsideRoot } from '../fs/pathSandbox';
import path from 'node:path';
@@ -32,7 +32,7 @@ import { readTextureCookSettings } from '../project/importSettings';
// The branch below IS this function — a cook that re-derived the choice would
// be a second answer to the question an inspector asks before a build runs.
import {
- decideTextureCook, cookIntentDefeated, explainTextureCook,
+ decideTextureCook, cookIntentDefeated, explainTextureCook, textureAsksCompression,
type TextureCookDecision,
} from './textureCookDecision';
// Single-source content hash (sdk/src/asset/contentHash.ts). Imported as source —
@@ -48,7 +48,8 @@ import {
readKtx2Layout, wantsMipChain, halveRgba, spliceMipChain,
} from './ktx2Mips';
import { cookCached } from './cookCache';
-import { cookTexture, loadTextureEncoder, COMPRESSED_TARGETS, type BasisEncoderModule } from './textureCook';
+import { cookTexture, loadTextureEncoder, pngDimensions, COMPRESSED_TARGETS, type BasisEncoderModule } from './textureCook';
+import { meshTextureRoles } from './textureUsage';
const MANIFEST = 'assets.manifest.json';
@@ -197,10 +198,24 @@ interface CookSink {
warnings: string[];
failed: string[];
defeatedByFormat: string[];
- grewUnderEncoding: Array<{ path: string; saved: number }>;
manifestEntries: CookManifestEntry[];
}
+/** A PNG's width and height from its IHDR, reading only the header; null for anything else. */
+async function pngHeaderSize(file: string): Promise<{ width: number; height: number } | null> {
+ let handle;
+ try {
+ handle = await open(file, 'r');
+ const header = new Uint8Array(24);
+ await handle.read(header, 0, 24, 0);
+ return header[1] === 0x50 && header[2] === 0x4e ? pngDimensions(header) : null;
+ } catch {
+ return null;
+ } finally {
+ await handle?.close();
+ }
+}
+
/** `fn` over `items` with at most `limit` running, results in the items' order. */
async function mapInOrder<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
const results = new Array<R>(items.length);
@@ -588,8 +603,11 @@ export async function cookAssets(
// one fact about the project's source art, and one line per JPEG would bury
// the per-asset findings that each need their own fix.
const defeatedByFormat: string[] = [];
- /** Encoded, measured, thrown away — summarized once rather than per texture. */
- const grewUnderEncoding: Array<{ path: string; saved: number }> = [];
+ // What Auto compression resolves by: whether a mesh anywhere in the project draws it.
+ const roles = await meshTextureRoles(root, shippable);
+ const drawnIn3D = new Set(roles.keys());
+ const pageCompressedBy = (frame: AssetEntry): boolean =>
+ textureAsksCompression(readTextureCookSettings(frame.importer, platform).compress, drawnIn3D.has(frame.uuid));
// ---- Auto-atlas (`<name>.atlas/` folder convention) -----------------------
// Pack the reachable PNGs of each atlas directory into pages BEFORE the
@@ -629,16 +647,13 @@ export async function cookAssets(
let pageBytes: Uint8Array = pagePng;
let pageExt = '.png';
let compressedFormats: string[] | undefined;
- if (encodePng) {
- // Same question the loose textures ask, and the same answer when the
- // page is flat art: a page nobody compresses also spares the package
- // the transcoder, which is the larger half of the bill.
- const encoded = await encodePng(pagePng);
- if (encoded.byteLength < pagePng.byteLength) {
- pageBytes = encoded;
- pageExt = '.ktx2';
- compressedFormats = COMPRESSED_TARGETS;
- } else grewUnderEncoding.push({ path: `${dir}.page${n}`, saved: encoded.byteLength - pagePng.byteLength });
+ // One payload for every frame on the page, so it is compressed when a
+ // frame on it asks to be; a page of sprites on Auto ships as a PNG.
+ const pageFrames = pages[n].placements.map((p) => byPath.get(p.key)).filter((e): e is AssetEntry => !!e);
+ if (encodePng && pageFrames.some((e) => pageCompressedBy(e))) {
+ pageBytes = await encodePng(pagePng);
+ pageExt = '.ktx2';
+ compressedFormats = COMPRESSED_TARGETS;
}
const pageHash = contentHashHex(pageBytes);
const { name: group, delivery } = resolveAssetGroup(`${dir}/`, groupsConfig);
@@ -668,7 +683,7 @@ export async function cookAssets(
// Each asset cooks on its own, and the encoder runs ENCODER_PARALLELISM images
// at once, so that many are kept in flight. What each reports is merged back in
// `reachable` order, which keeps the manifest and the warnings a serial cook's.
- const cookOne = async (uuid: string, { warnings, failed, defeatedByFormat, grewUnderEncoding,
+ const cookOne = async (uuid: string, { warnings, failed, defeatedByFormat,
manifestEntries }: CookSink): Promise<void> => {
const entry = byUuid.get(uuid);
if (!entry) return;
@@ -683,7 +698,8 @@ export async function cookAssets(
const frameTex = readTextureCookSettings(entry.importer, platform);
const frameCook = decideTextureCook({
compressTextures, atlasTextures, inAtlas: true, raster: true,
- compress: frameTex.compress, format: frameTex.format, size: null,
+ atlasPageCompressed: framePlan.compressedFormats !== undefined,
+ compress: frameTex.compress, drawnIn3D: drawnIn3D.has(entry.uuid), format: frameTex.format, size: null,
});
if (cookIntentDefeated(frameCook)) {
warnings.push(`${entry.path}: ${explainTextureCook(frameCook)}`);
@@ -750,12 +766,11 @@ export async function cookAssets(
const t = await cookTexture({
root, path: entry.path, data, ext, importer: entry.importer, platform,
encoder: textureEnc ? { module: textureEnc, id: encoderId } : null,
- compressTextures, atlasTextures,
+ compressTextures, atlasTextures, drawnIn3D: drawnIn3D.has(entry.uuid),
});
data = t.data; ext = t.ext; cook = t.cook; compressedFormats = t.compressedFormats;
warnings.push(...t.warnings);
if (t.defeatedByFormat) defeatedByFormat.push(entry.path);
- if (t.grew !== undefined) grewUnderEncoding.push({ path: entry.path, saved: t.grew });
}
// WAV sources re-encode to MP3 (universal decode); other audio formats are
// already compressed and pass through. Hash + name reflect the ENCODED bytes.
@@ -915,7 +930,7 @@ export async function cookAssets(
}
};
const sinks = await mapInOrder([...reachable], textureEnc?.ENCODER_PARALLELISM ?? 1, async (uuid) => {
- const sink: CookSink = { warnings: [], failed: [], defeatedByFormat: [], grewUnderEncoding: [], manifestEntries: [] };
+ const sink: CookSink = { warnings: [], failed: [], defeatedByFormat: [], manifestEntries: [] };
await cookOne(uuid, sink);
return sink;
});
@@ -923,7 +938,6 @@ export async function cookAssets(
warnings.push(...sink.warnings);
failed.push(...sink.failed);
defeatedByFormat.push(...sink.defeatedByFormat);
- grewUnderEncoding.push(...sink.grewUnderEncoding);
manifestEntries.push(...sink.manifestEntries);
}
manifestEntries.sort((a, b) => a.path.localeCompare(b.path));
@@ -952,11 +966,21 @@ export async function cookAssets(
const unused = index.entries.filter((e) => !reachable.has(e.uuid)).map((e) => e.uuid);
const includedPaths = [...reachable].map((uuid) => byUuid.get(uuid)?.path).filter((p): p is string => p !== undefined);
- if (grewUnderEncoding.length) {
- const bytes = grewUnderEncoding.reduce((n, g) => n + g.saved, 0);
- const kb = (n: number) => `${Math.round(n / 1024)}KB`;
- warnings.push(`${grewUnderEncoding.length} texture(s) ship raw because the KTX2 came out `
- + `larger — ${kb(bytes)} the package does not carry. Flat art compresses better as PNG.`);
+ // Said, not overridden: the author chose the file, and this is what it costs. A
+ // lightmap is left out — the bake keeps it exact on purpose.
+ const drawnRaw = compressTextures ? [...reachable].map((uuid) => byUuid.get(uuid)!)
+ .filter((e) => e.type === 'texture' && roles.get(e.uuid)?.has('surface') && !atlasPlan.has(e.path)
+ && readTextureCookSettings(e.importer, platform).compress === 'off') : [];
+ if (drawnRaw.length) {
+ let decoded = 0;
+ for (const e of drawnRaw) {
+ const size = await pngHeaderSize(path.join(root, e.path));
+ if (size) decoded += size.width * size.height * 4 * 4 / 3;
+ }
+ warnings.push(`${drawnRaw.length} texture(s) a mesh draws ship as their original image (Compression: `
+ + `Original image) — ${Math.round(decoded / 2 ** 20)} MiB of video memory decoded, where GPU `
+ + `compressed would take about a quarter of it: ${drawnRaw.slice(0, 5).map((e) => e.path).join(', ')}`
+ + `${drawnRaw.length > 5 ? ', …' : ''}`);
}
if (defeatedByFormat.length) {
const shown = defeatedByFormat.slice(0, 3).join(', ');
diff --git a/pipeline/src/assets/textureCook.ts b/pipeline/src/assets/textureCook.ts
index 9c396127a..344adc2ea 100644
--- a/pipeline/src/assets/textureCook.ts
+++ b/pipeline/src/assets/textureCook.ts
@@ -11,7 +11,7 @@
import { readTextureCookSettings } from '../project/importSettings';
import { decodePngImage, encodeRgbaPng, downscaleRgba } from './atlasPacker';
import {
- decideTextureCook, cookIntentDefeated, explainTextureCook, keepSmaller,
+ decideTextureCook, cookIntentDefeated, explainTextureCook,
type TextureCookDecision,
} from './textureCookDecision';
import { halveRgba, joinMipLevels, alphaCoverage, preserveAlphaCoverage } from './ktx2Mips';
@@ -107,14 +107,11 @@ export interface TextureCookInput {
encoder: TextureEncoder | null;
compressTextures: boolean;
atlasTextures: boolean;
+ /** A mesh draws this texture (texturesDrawnIn3D) — what Auto compression resolves by. */
+ drawnIn3D: boolean;
/** Answer only from the cook cache: an encode it would have to run is left
* undone, and the output says `pending` instead. */
cachedOnly?: boolean;
- /** Keep the KTX2 even where the source file is smaller. A package weighs its
- * download; a viewport holding a project's art weighs its video memory, where
- * a block-compressed texture is a quarter of the decoded one whatever the file
- * size. The encode, and the cache entry, are the same either way. */
- keepCompressed?: boolean;
}
export interface TextureCookOutput {
@@ -126,15 +123,13 @@ export interface TextureCookOutput {
warnings: string[];
/** Asked to compress, and its source format is one the encoder does not take. */
defeatedByFormat: boolean;
- /** Encoded and thrown away as larger than the source: by how many bytes. */
- grew?: number;
/** `cachedOnly`, and the encode this texture asks for has not been run. */
pending?: boolean;
}
/**
* One texture as a build ships it: capped at its `maxSize`, then compressed to
- * KTX2 where its settings and the build ask for it and the result is smaller.
+ * KTX2 where its Compression and the build ask for it.
* Encodes go through the cook cache under the source bytes, the settings that
* shape the output and the encoder's identity.
*/
@@ -156,16 +151,15 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
if (tex.maxSize < Math.max(dims.width, dims.height)) {
const scaled = downscaleRgba(decodePngImage(path, data), tex.maxSize);
rgba = scaled.rgba; tw = scaled.width; th = scaled.height;
- if (!tex.compress) data = encodeRgbaPng(tw, th, rgba); // ship the shrunk PNG
}
} catch (err) {
warnings.push(`${path}: texture resize skipped — ${err instanceof Error ? err.message : String(err)}`);
}
}
const size = raster ? (rgba ? { width: tw, height: th } : safePngDimensions(data)) : null;
- let cook = decideTextureCook({
+ const cook = decideTextureCook({
compressTextures: input.compressTextures, atlasTextures: input.atlasTextures, inAtlas: false, raster,
- compress: tex.compress, format: tex.format, size,
+ compress: tex.compress, drawnIn3D: input.drawnIn3D, format: tex.format, size,
});
let defeatedByFormat = false;
if (cookIntentDefeated(cook)) {
@@ -175,7 +169,8 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
else warnings.push(`${path}: ${explainTextureCook(cook, size)}`);
}
let compressedFormats: string[] | undefined;
- let grew: number | undefined;
+ // A texture that ships as an image ships the shrunk one.
+ if (cook.selected === 'raw' && rgba) data = encodeRgbaPng(tw, th, rgba);
if (cook.selected !== 'raw') {
// Only a build that encodes can select an encoding, and that is exactly
// when the encoder was loaded — an absent one here is a broken invariant
@@ -194,12 +189,9 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
: enc.encodeToKtx2({ type: enc.ImageType.PNG, data: source }, { mode, srgb: tex.srgb }));
const encoded = input.cachedOnly ? await cookCacheHit(root, key) : (await cookCached(root, key, produce)).bytes;
if (!encoded) return { data, ext, cook, warnings, defeatedByFormat, pending: true };
- if (!input.keepCompressed) cook = keepSmaller(cook, encoded.byteLength, data.byteLength, coverage > 0);
- if (cook.selected !== 'raw') {
- data = encoded;
- ext = '.ktx2';
- compressedFormats = COMPRESSED_TARGETS;
- } else grew = encoded.byteLength - data.byteLength;
+ data = encoded;
+ ext = '.ktx2';
+ compressedFormats = COMPRESSED_TARGETS;
}
- return { data, ext, cook, compressedFormats, warnings, defeatedByFormat, grew };
+ return { data, ext, cook, compressedFormats, warnings, defeatedByFormat };
}
diff --git a/pipeline/src/assets/textureCookDecision.ts b/pipeline/src/assets/textureCookDecision.ts
index 63f38bf9d..263bc76d8 100644
--- a/pipeline/src/assets/textureCookDecision.ts
+++ b/pipeline/src/assets/textureCookDecision.ts
@@ -15,6 +15,7 @@
* The cook calls this rather than re-deriving it, so what a build did and
* what an inspector predicts are one function with one branch order.
*/
+import type { TextureCompression } from '../project/importSettings';
/**
* What a source image becomes under the import's `maxSize` — the size every
@@ -52,14 +53,15 @@ export type TextureCookReason =
| 'compressed'
| 'build-skips-assets'
| 'asset-opt-out'
+ /** Compression is Auto and nothing draws the texture on a mesh: a sprite or UI
+ * image, which ships as its original file. */
+ | 'auto-2d'
| 'atlas-page'
| 'not-block-aligned'
- | 'not-raster'
- /** Encoded and thrown away: the KTX2 came out larger than the image. */
- | 'bigger-than-raw';
+ | 'not-raster';
export interface TextureCookDecision {
- /** The mode this asset asked for, or `none` when it opted out. */
+ /** The mode this asset asked for, or `none` when it did not ask to be compressed. */
readonly requested: TextureCookFormat | 'none';
readonly selected: CookedTexturePayload;
readonly reason: TextureCookReason;
@@ -72,10 +74,16 @@ export interface TextureCookInputs {
readonly atlasTextures: boolean;
/** This image is a frame of one of those atlases. */
readonly inAtlas: boolean;
+ /** For a frame: whether its page ships compressed — a page is compressed when a
+ * frame on it asks to be, since the page is the one payload they all share. */
+ readonly atlasPageCompressed?: boolean;
/** A source the KTX2 encoder takes — PNG. JPEG/WebP/SVG pass through as-is. */
readonly raster: boolean;
- /** The asset's own Compress row. */
- readonly compress: boolean;
+ /** The asset's own Compression row. */
+ readonly compress: TextureCompression;
+ /** A mesh draws this texture, directly or through its material — what Auto
+ * resolves by (textureUsage.ts). */
+ readonly drawnIn3D: boolean;
readonly format: TextureCookFormat;
/**
* The dimensions that would be ENCODED — after any Max Size downscale, not the
@@ -94,43 +102,41 @@ function wholeBlocks(size: TextureCookInputs['size']): boolean {
/** The payload a build ships for one texture, and the one reason it is that. */
export function decideTextureCook(input: TextureCookInputs): TextureCookDecision {
- const requested = input.compress ? input.format : 'none';
+ const requested = textureAsksCompression(input.compress, input.drawnIn3D) ? input.format : 'none';
// An atlas frame has no payload of its own: the PAGE ships, and a page
- // aggregates images whose settings disagree, so it is always UASTC. Recorded
- // rather than assumed — a frame that asked for ETC1S got the page's answer.
+ // aggregates images whose settings disagree, so it is always UASTC when it is
+ // encoded. Recorded rather than assumed — a frame got the page's answer.
if (input.atlasTextures && input.inAtlas) {
- return { requested, selected: input.compressTextures ? 'uastc' : 'raw', reason: 'atlas-page' };
+ const encoded = input.compressTextures && input.atlasPageCompressed === true;
+ return { requested, selected: encoded ? 'uastc' : 'raw', reason: 'atlas-page' };
}
if (!input.compressTextures) return { requested, selected: 'raw', reason: 'build-skips-assets' };
if (!input.raster) return { requested, selected: 'raw', reason: 'not-raster' };
- if (!input.compress) return { requested, selected: 'raw', reason: 'asset-opt-out' };
+ if (input.compress === 'off') return { requested, selected: 'raw', reason: 'asset-opt-out' };
+ if (requested === 'none') return { requested, selected: 'raw', reason: 'auto-2d' };
if (!wholeBlocks(input.size)) return { requested, selected: 'raw', reason: 'not-block-aligned' };
return { requested, selected: input.format, reason: 'compressed' };
}
/**
- * The payload once the encoder has answered: a KTX2 bigger than the image it
- * encoded is not a compression (a 512px sky came out 35x its PNG) — unless it
- * carries what the image cannot: a cutout's coverage-kept mips, which a chain
- * built on the device loses, so the leaves thin out with distance.
+ * Whether a texture's Compression asks for a KTX2: On does, Off does not, and Auto
+ * does for a texture a mesh draws — where video memory is the cost — and not for
+ * sprites and UI, where a flat PNG is often a tenth of the KTX2 to download.
*/
-export function keepSmaller(
- d: TextureCookDecision, encodedBytes: number, rawBytes: number, carriesMips = false,
-): TextureCookDecision {
- if (d.selected === 'raw' || carriesMips || encodedBytes < rawBytes) return d;
- return { ...d, selected: 'raw', reason: 'bigger-than-raw' };
+export function textureAsksCompression(compress: TextureCompression, drawnIn3D: boolean): boolean {
+ return compress === 'on' || (compress === 'auto' && drawnIn3D);
}
/**
* True when the asset asked for an encoding and the build did not give it.
*
- * Opting out, a build that skips assets, and an encoding that came out bigger
- * are all choices. This catches the silent kind: a request that survived every
- * dialog and lost to the image itself, or to the folder it was dropped in.
+ * Opting out and a build that skips assets are choices. This catches the silent
+ * kind: a request that survived every dialog and lost to the image itself, or to
+ * the folder it was dropped in.
*/
export function cookIntentDefeated(d: TextureCookDecision): boolean {
if (d.requested === 'none') return false;
- if (d.reason === 'build-skips-assets' || d.reason === 'bigger-than-raw') return false;
+ if (d.reason === 'build-skips-assets') return false;
return d.selected !== d.requested;
}
@@ -144,7 +150,9 @@ export function explainTextureCook(
case 'build-skips-assets':
return 'shipped raw — this build skips asset optimization';
case 'asset-opt-out':
- return 'shipped raw — Compress is off on this asset';
+ return 'shipped raw — Compression is set to Original image on this asset';
+ case 'auto-2d':
+ return 'shipped raw — Compression is Auto and no mesh draws this texture';
case 'atlas-page':
return d.selected === 'raw'
? 'packed into an atlas page, which this build ships raw'
@@ -154,7 +162,5 @@ export function explainTextureCook(
+ 'is not a multiple of 4, which a block-compressed texture must be';
case 'not-raster':
return 'shipped raw — only PNG sources are encoded';
- case 'bigger-than-raw':
- return 'shipped raw — the KTX2 came out larger than the image';
}
}
diff --git a/pipeline/src/assets/textureUsage.ts b/pipeline/src/assets/textureUsage.ts
new file mode 100644
index 000000000..54c7d399e
--- /dev/null
+++ b/pipeline/src/assets/textureUsage.ts
@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file textureUsage.ts
+ * @brief Which of a project's textures a mesh draws — what a texture's Auto
+ * compression resolves by.
+ *
+ * @details A texture on a mesh is sampled in full wherever the mesh is seen, and
+ * its decoded size is its cost in video memory; a sprite or UI image is
+ * usually flat art whose PNG is a fraction of a KTX2. So Auto compresses
+ * the first and ships the second as its file.
+ *
+ * The whole project is read, not what one build reaches: the editor and
+ * every build resolve Auto the same way, so what the editor shows is what
+ * ships whichever scenes a build starts from.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { AssetEntry } from './assetDb';
+import { isBuiltinAssetRef, resolveDocumentRef } from '../../../sdk/src/asset/documentRef';
+
+const UUID_PREFIX = '@uuid:';
+
+/** How a mesh draws a texture: on its surface, or as the baked light the surface reads. */
+export type MeshTextureRole = 'surface' | 'lightmap';
+
+/** Component fields whose texture a mesh draws, by the role it plays there. */
+const MESH_TEXTURE_FIELDS: Readonly<Record<string, Readonly<Record<string, MeshTextureRole>>>> = {
+ MeshRenderer: { texture: 'surface', normalMap: 'surface' },
+ MeshLightmap: { lightmap: 'lightmap' },
+};
+const MESH_MATERIAL_FIELDS: Readonly<Record<string, readonly string[]>> = {
+ MeshRenderer: ['material'],
+};
+
+interface Documented {
+ entities?: Array<{ components?: Array<{ type?: string; data?: Record<string, unknown> }> }>;
+}
+
+/** Every string anywhere under @p value. */
+function strings(value: unknown, into: string[]): void {
+ if (typeof value === 'string') into.push(value);
+ else if (Array.isArray(value)) for (const v of value) strings(v, into);
+ else if (value && typeof value === 'object') for (const v of Object.values(value)) strings(v, into);
+}
+
+/**
+ * The uuids of the textures a mesh in @p entries' scenes and prefabs draws, directly
+ * or through its material. @p read supplies a document's text (the project file
+ * by default).
+ */
+export async function texturesDrawnIn3D(
+ root: string,
+ entries: readonly AssetEntry[],
+ read?: (file: string) => Promise<string>,
+): Promise<Set<string>> {
+ return new Set((await meshTextureRoles(root, entries, read)).keys());
+}
+
+/** {@link texturesDrawnIn3D}, with the roles each texture plays: a material's are its surface. */
+export async function meshTextureRoles(
+ root: string,
+ entries: readonly AssetEntry[],
+ read: (file: string) => Promise<string> = (file) => readFile(path.join(root, file), 'utf8'),
+): Promise<Map<string, Set<MeshTextureRole>>> {
+ const byUuid = new Map(entries.map((e) => [e.uuid, e]));
+ const byPath = new Map(entries.map((e) => [e.path, e]));
+ const resolve = (ref: string, docPath: string): AssetEntry | undefined => {
+ if (ref.startsWith(UUID_PREFIX)) return byUuid.get(ref.slice(UUID_PREFIX.length));
+ if (ref === '' || isBuiltinAssetRef(ref) || ref.includes('://')) return undefined;
+ return byPath.get(resolveDocumentRef(docPath, ref).replace(/^\/+/, ''));
+ };
+
+ const drawn = new Map<string, Set<MeshTextureRole>>();
+ const draw = (uuid: string, role: MeshTextureRole): void => {
+ const roles = drawn.get(uuid) ?? new Set<MeshTextureRole>();
+ roles.add(role);
+ drawn.set(uuid, roles);
+ };
+ const materials = new Set<string>();
+ const docs = entries.filter((e) => e.type === 'scene' || e.type === 'prefab');
+ await Promise.all(docs.map(async (doc) => {
+ let parsed: Documented;
+ try {
+ parsed = JSON.parse(await read(doc.path)) as Documented;
+ } catch {
+ return;
+ }
+ for (const entity of parsed.entities ?? []) {
+ for (const component of entity.components ?? []) {
+ const type = component.type ?? '';
+ const data = component.data ?? {};
+ for (const [field, role] of Object.entries(MESH_TEXTURE_FIELDS[type] ?? {})) {
+ const ref = data[field];
+ const target = typeof ref === 'string' ? resolve(ref, doc.path) : undefined;
+ if (target?.type === 'texture') draw(target.uuid, role);
+ }
+ for (const field of MESH_MATERIAL_FIELDS[type] ?? []) {
+ const ref = data[field];
+ const target = typeof ref === 'string' ? resolve(ref, doc.path) : undefined;
+ if (target?.type === 'material') materials.add(target.uuid);
+ }
+ }
+ }
+ }));
+
+ await Promise.all([...materials].map(async (uuid) => {
+ const material = byUuid.get(uuid)!;
+ let refs: string[] = [];
+ try {
+ strings(JSON.parse(await read(material.path)), refs);
+ } catch {
+ refs = [];
+ }
+ for (const ref of refs) {
+ const target = resolve(ref, material.path);
+ if (target?.type === 'texture') draw(target.uuid, 'surface');
+ }
+ }));
+ return drawn;
+}
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index ad2b03156..439db26ca 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -44,6 +44,10 @@ export interface ImporterFieldSpec {
options?: ImporterEnumOption[];
/** For `type: 'select'`. */
selectOptions?: string[];
+ /** What a stored value means today, for a field whose vocabulary has changed —
+ * applied wherever the block is read, so a `.meta` written before the change
+ * shows, and cooks, as what it now stands for. */
+ read?: (stored: unknown) => ImporterValue;
}
const powerOfTwo = [256, 512, 1024, 2048, 4096, 8192];
@@ -56,10 +60,18 @@ const TEXTURE: ImporterFieldSpec[] = [
+ 'its longest side is box-filtered down; smaller sources are untouched.',
},
{
- key: 'compress', label: 'Compress', type: 'bool', default: true, category: 'Texture',
- tooltip: 'GPU-compress this texture to KTX2 (Basis Universal) at cook — it stays '
- + 'compressed in VRAM and transcodes per device. Turn OFF to ship the raw image '
- + '(crisp UI, smooth gradients). Only applies when the build compresses assets.',
+ key: 'compress', label: 'Compression', type: 'enum', default: 'auto', category: 'Texture',
+ options: [
+ { label: 'Auto (by use)', value: 'auto' },
+ { label: 'GPU compressed', value: 'on' },
+ { label: 'Original image', value: 'off' },
+ ],
+ read: textureCompression,
+ tooltip: 'GPU compressed ships a KTX2 that stays compressed in video memory — about a '
+ + 'quarter of the decoded image — and transcodes per device. Original image ships the '
+ + 'file as it is: exact, and for flat art far smaller to download, but decoded in full '
+ + 'on the GPU. Auto is GPU compressed for a texture a mesh draws and the original for '
+ + 'sprites and UI. Only applies when the build compresses assets.',
},
{
key: 'compressFormat', label: 'Compress Format', type: 'select', default: 'uastc',
@@ -272,7 +284,8 @@ export const sharesImporterSchema = (a: string, b: string): boolean =>
export interface TexturePlatformOverride {
enabled?: boolean;
maxSize?: number;
- compress?: boolean;
+ /** A TextureCompression, or the boolean an older `.meta` holds. */
+ compress?: TextureCompression | boolean;
compressFormat?: 'uastc' | 'etc1s';
}
@@ -280,8 +293,21 @@ export interface TexturePlatformOverride {
* texture decides its own KTX2 format, opt-out and size cap. An ENABLED
* `importer.overrides[platform]` wins per field; an unset field inherits the
* default. Defaults match a fresh `.meta`. */
+/** What a texture's Compression asks for. */
+export type TextureCompression = 'auto' | 'on' | 'off';
+
+/**
+ * A stored Compression value as it reads today. It was a boolean, written true
+ * into every fresh `.meta` whatever the texture was — so true means Auto, the
+ * default it was standing for, and false the Original image someone turned it to.
+ */
+export function textureCompression(stored: unknown): TextureCompression {
+ if (stored === 'on' || stored === 'off' || stored === 'auto') return stored;
+ return stored === false ? 'off' : 'auto';
+}
+
export function readTextureCookSettings(importer: Record<string, unknown> | undefined, platform?: string): {
- compress: boolean; format: 'uastc' | 'etc1s'; maxSize: number; srgb: boolean; mipCoverage: number;
+ compress: TextureCompression; format: 'uastc' | 'etc1s'; maxSize: number; srgb: boolean; mipCoverage: number;
} {
const compress = importer?.compress;
const mipCoverage = importer?.mipCoverage;
@@ -289,7 +315,7 @@ export function readTextureCookSettings(importer: Record<string, unknown> | unde
const maxSize = importer?.maxSize;
const srgb = importer?.sRGB;
const resolved = {
- compress: typeof compress === 'boolean' ? compress : true,
+ compress: textureCompression(compress),
format: (format === 'etc1s' ? 'etc1s' : 'uastc') as 'uastc' | 'etc1s',
maxSize: typeof maxSize === 'number' && maxSize > 0 ? maxSize : 2048,
srgb: typeof srgb === 'boolean' ? srgb : true,
@@ -298,7 +324,7 @@ export function readTextureCookSettings(importer: Record<string, unknown> | unde
const overrides = importer?.overrides as Record<string, TexturePlatformOverride> | undefined;
const ov = platform ? overrides?.[platform] : undefined;
if (ov?.enabled) {
- if (typeof ov.compress === 'boolean') resolved.compress = ov.compress;
+ if (ov.compress !== undefined) resolved.compress = textureCompression(ov.compress);
if (ov.compressFormat === 'etc1s' || ov.compressFormat === 'uastc') resolved.format = ov.compressFormat;
if (typeof ov.maxSize === 'number' && ov.maxSize > 0) resolved.maxSize = ov.maxSize;
}
diff --git a/pipeline/tests/cook-assets.test.ts b/pipeline/tests/cook-assets.test.ts
index 1283232c9..a3e8ca299 100644
--- a/pipeline/tests/cook-assets.test.ts
+++ b/pipeline/tests/cook-assets.test.ts
@@ -201,7 +201,7 @@ describe('cookAssets (A4)', () => {
}
});
- it('compresses raster textures to KTX2 (compressTextures) + records compressedFormats', async () => {
+ it('on Auto, compresses what a mesh draws to KTX2 + records compressedFormats, and ships a sprite\'s image', async () => {
const r = mkdtempSync(path.join(tmpdir(), 'estella-cook-ktx2-'));
try {
const TEX = '77777777-7777-4777-8777-777777777777';
@@ -216,10 +216,13 @@ describe('cookAssets (A4)', () => {
writeFileSync(abs, body);
writeFileSync(`${abs}.meta`, JSON.stringify({ uuid, version: '2.0', type, importer: {} }));
};
+ const SPRITE = '77777777-7777-4777-8777-777777777779';
wa('t/logo.png', 'texture', TEX, png);
+ wa('t/sprite.png', 'texture', SPRITE, png);
wa('s/main.esscene', 'scene', SC, JSON.stringify({
version: '1.0', name: 's', entities: [
- { id: 1, name: 'E', parent: null, children: [], components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] },
+ { id: 1, name: 'E', parent: null, children: [], components: [{ type: 'MeshRenderer', data: { mesh: 'builtin:cube', texture: `@uuid:${TEX}` } }] },
+ { id: 2, name: 'S', parent: null, children: [], components: [{ type: 'Sprite', data: { texture: `@uuid:${SPRITE}` } }] },
],
}));
const res = await cookAssets(r, { entryScenes: ['s/main.esscene'], outDir: 'out', compressTextures: true });
@@ -232,6 +235,11 @@ describe('cookAssets (A4)', () => {
const bytes = readFileSync(path.join(res.outDir, tex.path));
const magic = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
expect(magic.every((b, i) => bytes[i] === b)).toBe(true);
+
+ // The same image on a sprite, also on Auto: shipped as its file, and said why.
+ const sprite = m.entries.find((e) => e.uuid === SPRITE)!;
+ expect(sprite.path).toMatch(/\.png$/);
+ expect((sprite as { cook?: { reason?: string } }).cook?.reason).toBe('auto-2d');
} finally {
rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}
@@ -302,7 +310,7 @@ describe('cookAssets (A4)', () => {
const abs = path.join(r, 't/odd.png');
mkdirSync(path.dirname(abs), { recursive: true });
writeFileSync(abs, solidPng(70, 70, [10, 200, 40, 255]));
- writeFileSync(`${abs}.meta`, JSON.stringify({ uuid: TEX, version: '2.0', type: 'texture', importer: {} }));
+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid: TEX, version: '2.0', type: 'texture', importer: { compress: 'on' } }));
const sc = path.join(r, 's/main.esscene');
mkdirSync(path.dirname(sc), { recursive: true });
writeFileSync(sc, JSON.stringify({ version: '1.0', name: 's', entities: [{ id: 1, name: 'E', parent: null, children: [], components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] }] }));
@@ -337,7 +345,7 @@ describe('cookAssets (A4)', () => {
// Default: compress (KTX2). WeChat override: ship a small raw PNG instead.
writeFileSync(`${abs}.meta`, JSON.stringify({
uuid: TEX, version: '2.0', type: 'texture',
- importer: { compress: true, overrides: { wechat: { enabled: true, compress: false, maxSize: 64 } } },
+ importer: { compress: 'on', overrides: { wechat: { enabled: true, compress: 'off', maxSize: 64 } } },
}));
const sc = path.join(r, 's/main.esscene');
mkdirSync(path.dirname(sc), { recursive: true });
diff --git a/pipeline/tests/texture-cook-decision.test.ts b/pipeline/tests/texture-cook-decision.test.ts
index 0a837a49a..cf3494535 100644
--- a/pipeline/tests/texture-cook-decision.test.ts
+++ b/pipeline/tests/texture-cook-decision.test.ts
@@ -9,7 +9,7 @@
*/
import { describe, it, expect } from 'vitest';
import {
- decideTextureCook, cookIntentDefeated, explainTextureCook, keepSmaller,
+ decideTextureCook, cookIntentDefeated, explainTextureCook, textureAsksCompression,
type TextureCookInputs,
} from '../src/assets/textureCookDecision';
@@ -18,7 +18,8 @@ const base: TextureCookInputs = {
atlasTextures: true,
inAtlas: false,
raster: true,
- compress: true,
+ compress: 'on',
+ drawnIn3D: false,
format: 'uastc',
size: { width: 64, height: 64 },
};
@@ -46,7 +47,7 @@ describe('decideTextureCook', () => {
});
it('opting out is not a defeat: nothing was requested', () => {
- const d = decideTextureCook({ ...base, compress: false });
+ const d = decideTextureCook({ ...base, compress: 'off' });
expect(d).toEqual({ requested: 'none', selected: 'raw', reason: 'asset-opt-out' });
expect(cookIntentDefeated(d)).toBe(false);
});
@@ -63,25 +64,54 @@ describe('decideTextureCook', () => {
expect(cookIntentDefeated(d)).toBe(true);
});
+ describe('Compression: Auto', () => {
+ it('compresses what a mesh draws, where video memory is the cost', () => {
+ expect(decideTextureCook({ ...base, compress: 'auto', drawnIn3D: true })).toEqual({
+ requested: 'uastc', selected: 'uastc', reason: 'compressed',
+ });
+ });
+
+ it('ships a sprite or UI image as its file, and it is not a defeat — nothing asked', () => {
+ const d = decideTextureCook({ ...base, compress: 'auto', drawnIn3D: false });
+ expect(d).toEqual({ requested: 'none', selected: 'raw', reason: 'auto-2d' });
+ expect(cookIntentDefeated(d)).toBe(false);
+ expect(explainTextureCook(d)).toMatch(/Auto and no mesh draws/);
+ });
+
+ it('never overrules an explicit choice, whatever draws the texture', () => {
+ expect(decideTextureCook({ ...base, compress: 'on', drawnIn3D: false }).selected).toBe('uastc');
+ expect(decideTextureCook({ ...base, compress: 'off', drawnIn3D: true }).reason).toBe('asset-opt-out');
+ expect(textureAsksCompression('on', false)).toBe(true);
+ expect(textureAsksCompression('off', true)).toBe(false);
+ expect(textureAsksCompression('auto', true)).toBe(true);
+ expect(textureAsksCompression('auto', false)).toBe(false);
+ });
+ });
+
describe('atlas frames', () => {
it('take the page\'s encoding, not their own', () => {
- const d = decideTextureCook({ ...base, inAtlas: true, format: 'etc1s' });
+ const d = decideTextureCook({ ...base, inAtlas: true, atlasPageCompressed: true, format: 'etc1s' });
expect(d).toEqual({ requested: 'etc1s', selected: 'uastc', reason: 'atlas-page' });
// The row still reads ETC1S and never applied — the case this record exists for.
expect(cookIntentDefeated(d)).toBe(true);
});
it('agree with a frame that asked for what the page does anyway', () => {
- const d = decideTextureCook({ ...base, inAtlas: true });
+ const d = decideTextureCook({ ...base, inAtlas: true, atlasPageCompressed: true });
expect(d).toEqual({ requested: 'uastc', selected: 'uastc', reason: 'atlas-page' });
expect(cookIntentDefeated(d)).toBe(false);
});
it('ship raw when the build does not encode, and say the page is why', () => {
- const d = decideTextureCook({ ...base, inAtlas: true, compressTextures: false });
+ const d = decideTextureCook({ ...base, inAtlas: true, atlasPageCompressed: true, compressTextures: false });
expect(d).toEqual({ requested: 'uastc', selected: 'raw', reason: 'atlas-page' });
});
+ it('ship raw with a page no frame asked to compress', () => {
+ const d = decideTextureCook({ ...base, inAtlas: true, compress: 'auto', atlasPageCompressed: false });
+ expect(d).toEqual({ requested: 'none', selected: 'raw', reason: 'atlas-page' });
+ });
+
it('are only atlas frames when the build packs atlases', () => {
expect(decideTextureCook({ ...base, inAtlas: true, atlasTextures: false }).reason)
.toBe('compressed');
@@ -93,45 +123,12 @@ describe('decideTextureCook', () => {
for (const d of [
decideTextureCook(base),
decideTextureCook({ ...base, compressTextures: false, atlasTextures: false }),
- decideTextureCook({ ...base, compress: false }),
+ decideTextureCook({ ...base, compress: 'off' }),
decideTextureCook({ ...base, inAtlas: true }),
decideTextureCook({ ...base, size: { width: 70, height: 70 } }),
decideTextureCook({ ...base, raster: false }),
+ decideTextureCook({ ...base, compress: 'auto' }),
]) said.add(explainTextureCook(d));
- expect(said.size).toBe(6);
- });
-});
-
-/**
- * Flat art encodes LARGER: the space-shooter background was 2,515 bytes as a PNG
- * and 87,792 as UASTC, and the transcoder the package then has to carry is a
- * megabyte more. The audio path has always kept the smaller of the two.
- */
-describe('keepSmaller', () => {
- const compressed = decideTextureCook(base);
-
- it('keeps the encoding when it is smaller', () => {
- expect(keepSmaller(compressed, 1000, 4000)).toEqual(compressed);
- });
-
- it('throws the encoding away when it is not, and says so', () => {
- const d = keepSmaller(compressed, 87_792, 2_515);
- expect(d).toEqual({ requested: 'uastc', selected: 'raw', reason: 'bigger-than-raw' });
- // Not a defeat: the build chose this, the way it chooses for audio.
- expect(cookIntentDefeated(d)).toBe(false);
- expect(explainTextureCook(d)).toMatch(/larger than the image/);
- });
-
- it('is a no-op on a decision that was never going to encode', () => {
- const raw = decideTextureCook({ ...base, compress: false });
- expect(keepSmaller(raw, 1, 999_999)).toEqual(raw);
- });
-
- it('keeps a bigger encoding that carries a cutout\'s coverage-kept mips', () => {
- expect(keepSmaller(compressed, 87_792, 2_515, true)).toEqual(compressed);
- });
-
- it('keeps raw on a tie — equal bytes buy nothing and cost a transcoder', () => {
- expect(keepSmaller(compressed, 4000, 4000).selected).toBe('raw');
+ expect(said.size).toBe(7);
});
});
diff --git a/pipeline/tests/texture-cook.test.ts b/pipeline/tests/texture-cook.test.ts
index 1ceca8848..42a7ef4da 100644
--- a/pipeline/tests/texture-cook.test.ts
+++ b/pipeline/tests/texture-cook.test.ts
@@ -23,11 +23,11 @@ describe('a texture compressed for the editor', () => {
const abs = path.join(r, 't/noise.png');
mkdirSync(path.dirname(abs), { recursive: true });
writeFileSync(abs, png);
- writeFileSync(`${abs}.meta`, JSON.stringify({ uuid: TEX, version: '2.0', type: 'texture', importer: {} }));
+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid: TEX, version: '2.0', type: 'texture', importer: { compress: 'on' } }));
const encoder = await loadTextureEncoder();
const ask = (cachedOnly: boolean) => cookTexture({
- root: r, path: 't/noise.png', data: new Uint8Array(png), ext: '.png', importer: {},
- encoder, compressTextures: true, atlasTextures: false, cachedOnly,
+ root: r, path: 't/noise.png', data: new Uint8Array(png), ext: '.png', importer: { compress: 'on' },
+ encoder, compressTextures: true, atlasTextures: false, drawnIn3D: false, cachedOnly,
});
const cold = await ask(true);
@@ -59,22 +59,22 @@ describe('a texture compressed for the editor', () => {
}
}, 60_000);
- it('keeps the KTX2 for the editor where a build would ship the smaller PNG', async () => {
- const r = mkdtempSync(path.join(tmpdir(), 'estella-texcook-flat-'));
+ it('on Auto, ships flat art as its file and compresses what a mesh draws, whatever the bytes', async () => {
+ const r = mkdtempSync(path.join(tmpdir(), 'estella-texcook-auto-'));
try {
// A solid colour: PNG writes almost nothing, the KTX2 a byte a pixel.
const flat = new Uint8Array(solidPng(64, 64, [40, 90, 200, 255]));
const encoder = await loadTextureEncoder();
- const ask = (keepCompressed: boolean) => cookTexture({
+ const ask = (drawnIn3D: boolean) => cookTexture({
root: r, path: 'sky.png', data: flat, ext: '.png', importer: {},
- encoder, compressTextures: true, atlasTextures: false, keepCompressed,
+ encoder, compressTextures: true, atlasTextures: false, drawnIn3D,
});
- const build = await ask(false);
- expect(build.ext).toBe('.png');
- expect(build.cook.reason).toBe('bigger-than-raw');
- const editor = await ask(true);
- expect(editor.ext).toBe('.ktx2');
- expect(readdirSync(path.join(r, '.esengine/cache/cook')).length).toBe(1); // one encode for both
+ const sprite = await ask(false);
+ expect(sprite.ext).toBe('.png');
+ expect(sprite.cook.reason).toBe('auto-2d');
+ const onMesh = await ask(true);
+ expect(onMesh.ext).toBe('.ktx2');
+ expect(onMesh.data.byteLength).toBeGreaterThan(flat.byteLength); // bigger, and still what ships
} finally {
rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}
@@ -86,7 +86,7 @@ describe('a texture compressed for the editor', () => {
const out = await cookTexture({
root: r, path: 'lightmap.png', data: new Uint8Array(noisePng(64, 64)), ext: '.png',
importer: { compress: false }, encoder: await loadTextureEncoder(),
- compressTextures: true, atlasTextures: false, cachedOnly: true,
+ compressTextures: true, atlasTextures: false, drawnIn3D: true, cachedOnly: true,
});
expect(out.ext).toBe('.png');
expect(out.pending).toBeUndefined();
@@ -94,4 +94,32 @@ describe('a texture compressed for the editor', () => {
rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}
}, 60_000);
+
+ it('a build says what a mesh\'s Original-image texture costs, and leaves a lightmap out', async () => {
+ const r = mkdtempSync(path.join(tmpdir(), 'estella-texcook-hint-'));
+ try {
+ const ids = { wall: '71717171-7171-4717-8717-7171717171a1', light: '71717171-7171-4717-8717-7171717171a2',
+ scene: '81818181-8181-4818-8818-8181818181a1' };
+ const put = (rel: string, body: Buffer | string, meta: object) => {
+ const abs = path.join(r, rel);
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, body);
+ writeFileSync(`${abs}.meta`, JSON.stringify(meta));
+ };
+ put('t/wall.png', noisePng(64, 64), { uuid: ids.wall, version: '2.0', type: 'texture', importer: { compress: 'off' } });
+ put('t/light.png', noisePng(64, 64), { uuid: ids.light, version: '2.0', type: 'texture', importer: { compress: 'off', sRGB: false } });
+ put('s/main.esscene', JSON.stringify({ version: '1.0', name: 's', entities: [
+ { id: 1, name: 'W', parent: null, children: [], components: [
+ { type: 'MeshRenderer', data: { mesh: 'builtin:cube', texture: `@uuid:${ids.wall}` } },
+ { type: 'MeshLightmap', data: { lightmap: `@uuid:${ids.light}` } }] },
+ ] }), { uuid: ids.scene, version: '2.0', type: 'scene', importer: {} });
+ const res = await cookAssets(r, { entryScenes: ['s/main.esscene'], outDir: 'out', compressTextures: true });
+ const said = res.warnings.filter((w) => w.includes('ship as their original image'));
+ expect(said).toHaveLength(1);
+ expect(said[0]).toContain('t/wall.png');
+ expect(said[0]).not.toContain('t/light.png');
+ } finally {
+ rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+ }, 60_000);
});
diff --git a/pipeline/tests/texture-usage.test.ts b/pipeline/tests/texture-usage.test.ts
new file mode 100644
index 000000000..a6e272343
--- /dev/null
+++ b/pipeline/tests/texture-usage.test.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * What a texture's Auto compression resolves by: whether a mesh draws it, directly
+ * or through its material — and what an older `.meta` means by its boolean.
+ */
+import { describe, it, expect } from 'vitest';
+import { texturesDrawnIn3D, meshTextureRoles } from '../src/assets/textureUsage';
+import { readTextureCookSettings, textureCompression } from '../src/project/importSettings';
+import type { AssetEntry } from '../src/assets/assetDb';
+
+const entry = (uuid: string, path: string, type: string): AssetEntry => ({ uuid, path, type });
+
+describe('texturesDrawnIn3D', () => {
+ it('finds a mesh\'s own textures and its material\'s, and not a sprite\'s', async () => {
+ const entries = [
+ entry('scene', 'assets/scenes/main.esscene', 'scene'),
+ entry('prefab', 'assets/models/cafe/cafe.esprefab', 'prefab'),
+ entry('mat', 'assets/models/cafe/wood.esmaterial', 'material'),
+ entry('albedo', 'assets/models/cafe/wood_albedo.png', 'texture'),
+ entry('normal', 'assets/models/cafe/wood_normal.png', 'texture'),
+ entry('floor', 'assets/textures/floor.png', 'texture'),
+ entry('lightmap', 'assets/scenes/main_lightmap.png', 'texture'),
+ entry('hud', 'assets/ui/hud.png', 'texture'),
+ entry('both', 'assets/textures/crate.png', 'texture'),
+ ];
+ const files: Record<string, unknown> = {
+ 'assets/scenes/main.esscene': { entities: [
+ { components: [{ type: 'MeshRenderer', data: { texture: '@uuid:floor' } }, { type: 'MeshLightmap', data: { lightmap: 'assets/scenes/main_lightmap.png' } }] },
+ { components: [{ type: 'Sprite', data: { texture: '@uuid:hud' } }] },
+ { components: [{ type: 'Sprite', data: { texture: '@uuid:both' } }] },
+ { components: [{ type: 'MeshRenderer', data: { texture: 'assets/textures/crate.png' } }] },
+ ] },
+ // A prefab from an import names its material beside it, relative to itself.
+ 'assets/models/cafe/cafe.esprefab': { entities: [
+ { components: [{ type: 'MeshRenderer', data: { material: 'wood.esmaterial' } }] },
+ ] },
+ 'assets/models/cafe/wood.esmaterial': { shader: 'builtin:model', properties: {
+ u_albedoMap: 'wood_albedo.png', u_normalMap: '@uuid:normal', u_roughness: 0.5 } },
+ };
+ const drawn = await texturesDrawnIn3D('/p', entries, async (f) => JSON.stringify(files[f]));
+ expect([...drawn].sort()).toEqual(['albedo', 'both', 'floor', 'lightmap', 'normal']);
+ const roles = await meshTextureRoles('/p', entries, async (f) => JSON.stringify(files[f]));
+ expect([...roles.get('lightmap')!]).toEqual(['lightmap']);
+ expect([...roles.get('albedo')!]).toEqual(['surface']);
+ });
+});
+
+describe('a Compression value from an older .meta', () => {
+ it('reads true — the default every fresh .meta was given — as Auto, and false as the original image', () => {
+ expect(textureCompression(true)).toBe('auto');
+ expect(textureCompression(false)).toBe('off');
+ expect(textureCompression(undefined)).toBe('auto');
+ expect(textureCompression('on')).toBe('on');
+ expect(readTextureCookSettings({ compress: true }).compress).toBe('auto');
+ expect(readTextureCookSettings({ compress: 'on', overrides: { wechat: { enabled: true, compress: false } } }, 'wechat').compress).toBe('off');
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3c81fe803..84a3b32cc 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1310,6 +1310,12 @@ export const NOTED = {
{ note: 'A large project opens in minutes, not half an hour' },
'fix(gates): texture-format reads the cook where the texture decision now lives':
{ internal: 'a static gate reading moved source; nothing a creator runs changes' },
+ 'fix(bake): an atlas\'s import settings are the bake\'s, and --check holds them':
+ { note: 'physics-3d\'s lightmap is read as the light it is' },
+ 'feat(assets): a texture\'s Compression is Auto, GPU compressed or Original image':
+ { note: 'A texture\'s Compression is Auto, GPU compressed or Original image, and a build does what it says' },
+ 'feat(editor): a texture\'s Compression is Auto, GPU compressed or Original image':
+ { note: 'A texture\'s Compression is Auto, GPU compressed or Original image, and a build does what it says' },
'fix(bake): a coloured light bakes the colour it lights with':
{ note: 'A coloured light bakes the colour it lights with' },
'fix(bake): the collector reads the colour space from the engine host':