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(export): a texture a Terrain reads as its heightmap ships as the file it is, whatever its size cap - an 8-bit heightmap over Max Size was still shrunk

yhhb4eb48280f59
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index c8943678d..e33bca929 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -51,7 +51,7 @@ import {
} from './ktx2Mips';
import { cookCached } from './cookCache';
import { cookTexture, loadTextureEncoder, pngDimensions, fillClearTexels, fillsClearTexels, COMPRESSED_TARGETS, type BasisEncoderModule } from './textureCook';
-import { meshTextureRoles } from './textureUsage';
+import { meshTextureRoles, texturesReadAsNumbers } from './textureUsage';
import { makeStreamTail, type StreamTail } from './streamTail';
import { matchScriptAssetRefs, scanScriptAssetRefs } from './scriptAssetRefs';
import { readManifest } from '../project/readProject';
@@ -681,6 +681,7 @@ export async function cookAssets(
// 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 readAsNumbers = await texturesReadAsNumbers(root, shippable);
const pageCompressedBy = (frame: AssetEntry): boolean =>
textureAsksCompression(readTextureCookSettings(frame.importer, platform).compress, drawnIn3D.has(frame.uuid));
@@ -851,7 +852,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,
+ resizeTextures: opts.resizeTextures, readAsNumbers: readAsNumbers.has(entry.uuid),
});
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 df95a9b0c..6035984e3 100644
--- a/pipeline/src/assets/textureCook.ts
+++ b/pipeline/src/assets/textureCook.ts
@@ -179,6 +179,8 @@ export interface TextureCookInput {
atlasTextures: boolean;
/** A mesh draws this texture (texturesDrawnIn3D) — what Auto compression resolves by. */
drawnIn3D: boolean;
+ /** A component reads this texture as numbers (a Terrain's heightmap): it is neither resized nor encoded. */
+ readAsNumbers?: 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;
@@ -212,9 +214,9 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
const tex = readTextureCookSettings(input.importer, platform);
const raster = ext.toLowerCase() === '.png';
const textureEnc = input.encoder?.module ?? null;
- // A PNG of 16 bits a channel is numbers, not a picture: a heightmap, a field of measured values. Shrinking, filling and encoding all
- // decode to 8 bits first, so a build would ship 256 steps where the file holds 65536, a size smaller, and say nothing. It ships as it is.
- if (raster && pngBitDepth(data) === 16) {
+ // A texture a component reads as numbers (a heightmap), and any PNG of 16 bits a channel, is not a picture: the size cap would ship
+ // different ground, and shrinking, filling and encoding all decode to 8 bits first. It ships as the file it is.
+ if (input.readAsNumbers || (raster && pngBitDepth(data) === 16)) {
const cook = decideTextureCook({
compressTextures: input.compressTextures, atlasTextures: input.atlasTextures, inAtlas: false, raster,
compress: 'off', drawnIn3D: input.drawnIn3D, format: tex.format, size: safePngDimensions(data),
diff --git a/pipeline/src/assets/textureUsage.ts b/pipeline/src/assets/textureUsage.ts
index 54c7d399e..5b3c254c4 100644
--- a/pipeline/src/assets/textureUsage.ts
+++ b/pipeline/src/assets/textureUsage.ts
@@ -33,6 +33,14 @@ const MESH_MATERIAL_FIELDS: Readonly<Record<string, readonly string[]>> = {
MeshRenderer: ['material'],
};
+/**
+ * Component fields whose texture is read as numbers, a sample a texel, never drawn: a size cap or a codec is not a smaller
+ * picture there but different ground.
+ */
+const NUMBER_TEXTURE_FIELDS: Readonly<Record<string, readonly string[]>> = {
+ Terrain: ['heightmap'],
+};
+
interface Documented {
entities?: Array<{ components?: Array<{ type?: string; data?: Record<string, unknown> }> }>;
}
@@ -119,3 +127,37 @@ export async function meshTextureRoles(
}));
return drawn;
}
+
+/**
+ * The uuids of the textures a component in @p entries' scenes and prefabs reads as numbers (a Terrain's heightmap). A build ships
+ * these as the files they are.
+ */
+export async function texturesReadAsNumbers(
+ root: string,
+ entries: readonly AssetEntry[],
+ read: (file: string) => Promise<string> = (file) => readFile(path.join(root, file), 'utf8'),
+): Promise<Set<string>> {
+ const byUuid = new Map(entries.map((e) => [e.uuid, e]));
+ const byPath = new Map(entries.map((e) => [e.path, e]));
+ const found = new Set<string>();
+ await Promise.all(entries.filter((e) => e.type === 'scene' || e.type === 'prefab').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 ?? []) {
+ for (const field of NUMBER_TEXTURE_FIELDS[component.type ?? ''] ?? []) {
+ const ref = component.data?.[field];
+ if (typeof ref !== 'string' || ref === '' || isBuiltinAssetRef(ref) || ref.includes('://')) continue;
+ const target = ref.startsWith(UUID_PREFIX) ? byUuid.get(ref.slice(UUID_PREFIX.length))
+ : byPath.get(resolveDocumentRef(doc.path, ref).replace(/^\/+/, ''));
+ if (target?.type === 'texture') found.add(target.uuid);
+ }
+ }
+ }
+ }));
+ return found;
+}
diff --git a/pipeline/tests/texture-cook.test.ts b/pipeline/tests/texture-cook.test.ts
index a18c90f2c..f20eaf0a6 100644
--- a/pipeline/tests/texture-cook.test.ts
+++ b/pipeline/tests/texture-cook.test.ts
@@ -159,6 +159,36 @@ describe('a PNG of 16 bits a channel', () => {
});
});
+describe('a texture a component reads as numbers', () => {
+ it('is found from the Terrain that names it as its heightmap, by path or by uuid', async () => {
+ const { texturesReadAsNumbers } = await import('../src/assets/textureUsage');
+ const entries = [
+ { uuid: 'h1', path: 'assets/height.png', type: 'texture' }, { uuid: 'h2', path: 'assets/other.png', type: 'texture' },
+ { uuid: 'c1', path: 'assets/colour.png', type: 'texture' }, { uuid: 's1', path: 'assets/scenes/a.esscene', type: 'scene' },
+ ] as never[];
+ const scene = JSON.stringify({ entities: [
+ { components: [{ type: 'Terrain', data: { heightmap: 'assets/height.png', splatmap: 'assets/colour.png' } }] },
+ { components: [{ type: 'Terrain', data: { heightmap: '@uuid:h2' } }, { type: 'MeshRenderer', data: { texture: 'assets/colour.png' } }] },
+ ] });
+ expect([...await texturesReadAsNumbers('/', entries, async () => scene)].sort()).toEqual(['h1', 'h2']);
+ });
+
+ it('ships as the file it is though it is over its size cap', async () => {
+ const root = mkdtempSync(path.join(tmpdir(), 'estella-numbers-'));
+ try {
+ const png = noisePng(96, 96);
+ const input = { root, path: 'assets/height.png', data: png, ext: '.png', platform: 'web', importer: { maxSize: 32 },
+ compressTextures: false, atlasTextures: false, resizeTextures: true, drawnIn3D: false, encoder: null } as Parameters<typeof cookTexture>[0];
+ const capped = await cookTexture(input);
+ expect(decodePngImage('h', capped.data).width).toBe(32);
+ const kept = await cookTexture({ ...input, readAsNumbers: true });
+ expect(Buffer.from(kept.data).equals(Buffer.from(png))).toBe(true);
+ } finally {
+ rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+ });
+});
+
describe('a cutout texture the cook ships', () => {
it('has the colour of its solid texels carried into its clear ones, and a texture that is no cutout keeps what is under its alpha', async () => {
// Green on the left, and white under alpha 0 on the right: the white a mip would average in at the leaf's edge.