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(terrain): a splatmap's fourth layer no longer erases the other three

yhh1accbe4d7f22
diff --git a/sdk/src/asset/pngData.ts b/sdk/src/asset/pngData.ts
new file mode 100644
index 000000000..10b2a366e
--- /dev/null
+++ b/sdk/src/asset/pngData.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file pngData.ts
+ * @brief A PNG read as data: its bytes exactly as stored, for an image that is numbers (a heightmap, a splatmap).
+ *
+ * The image path decodes through a 2D canvas, which keeps colour premultiplied by alpha: a texel whose alpha is 0 comes back
+ * with red, green and blue at 0 too. For a picture that is right; for a splatmap whose alpha is the fourth layer's weight it
+ * erased the other three wherever that layer was absent. This inflates the stream itself (DecompressionStream) and undoes the
+ * row filters, so every channel is the byte the file holds.
+ */
+import type { DecodedPixels } from './imageDecode';
+
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+/** Whether `bytes` is a PNG this reader takes: 8 bits a channel, grey, grey+alpha, RGB or RGBA, not interlaced. */
+function header(bytes: Uint8Array): { width: number; height: number; channels: number } | null {
+ if (bytes.length < 33 || SIGNATURE.some((b, i) => bytes[i] !== b)) return null;
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ const width = view.getUint32(16), height = view.getUint32(20);
+ const depth = bytes[24], type = bytes[25], interlace = bytes[28];
+ const channels = ({ 0: 1, 2: 3, 4: 2, 6: 4 } as Record<number, number>)[type!];
+ if (depth !== 8 || !channels || interlace !== 0 || !width || !height) return null;
+ return { width, height, channels };
+}
+
+async function inflate(data: Uint8Array<ArrayBuffer>): Promise<Uint8Array> {
+ const stream = new Blob([data]).stream().pipeThrough(new DecompressionStream('deflate'));
+ return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+const paeth = (a: number, b: number, c: number): number => {
+ const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+ return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+};
+
+/**
+ * The RGBA bytes of a PNG, top row first, as stored; null when it is not a PNG this reads or the host has no
+ * DecompressionStream, and the caller decodes it as an image instead.
+ */
+export async function decodePngData(bytes: Uint8Array): Promise<DecodedPixels | null> {
+ const head = header(bytes);
+ if (!head || typeof DecompressionStream !== 'function') return null;
+ const { width, height, channels } = head;
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ const parts: Uint8Array[] = [];
+ for (let at = 8; at + 8 <= bytes.length;) {
+ const length = view.getUint32(at);
+ const type = String.fromCharCode(bytes[at + 4]!, bytes[at + 5]!, bytes[at + 6]!, bytes[at + 7]!);
+ if (type === 'IDAT') parts.push(bytes.subarray(at + 8, at + 8 + length));
+ if (type === 'IEND') break;
+ at += 12 + length;
+ }
+ const joined = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+ parts.reduce((at, p) => (joined.set(p, at), at + p.length), 0);
+ const raw = await inflate(joined);
+ const stride = width * channels;
+ if (raw.length < (stride + 1) * height) return null;
+ const rows = new Uint8Array(stride * height);
+ for (let y = 0; y < height; y++) {
+ const filter = raw[y * (stride + 1)]!;
+ const src = y * (stride + 1) + 1, dst = y * stride, up = dst - stride;
+ for (let x = 0; x < stride; x++) {
+ const a = x >= channels ? rows[dst + x - channels]! : 0;
+ const b = y > 0 ? rows[up + x]! : 0;
+ const c = x >= channels && y > 0 ? rows[up + x - channels]! : 0;
+ const v = raw[src + x]!;
+ rows[dst + x] = (filter === 1 ? v + a : filter === 2 ? v + b : filter === 3 ? v + ((a + b) >> 1)
+ : filter === 4 ? v + paeth(a, b, c) : v) & 255;
+ }
+ }
+ if (channels === 4) return { width, height, pixels: rows };
+ const pixels = new Uint8Array(width * height * 4);
+ for (let i = 0; i < width * height; i++) {
+ const s = i * channels, d = i * 4;
+ const grey = channels <= 2;
+ pixels[d] = rows[s]!;
+ pixels[d + 1] = grey ? rows[s]! : rows[s + 1]!;
+ pixels[d + 2] = grey ? rows[s]! : rows[s + 2]!;
+ pixels[d + 3] = channels === 2 ? rows[s + 1]! : channels === 4 ? rows[s + 3]! : 255;
+ }
+ return { width, height, pixels };
+}
diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.ts
index ee7816c38..9f7fcf567 100644
--- a/sdk/src/terrain/terrainPlugin.ts
+++ b/sdk/src/terrain/terrainPlugin.ts
@@ -23,6 +23,7 @@ import {
import { Assets } from '../asset/AssetPlugin';
import { platformLoadImagePixels } from '../platform/base';
import { decodeImagePixels } from '../asset/imageDecode';
+import { decodePngData } from '../asset/pngData';
import { log } from '../util/logger';
import type { Color, Entity } from '../types';
import {
@@ -270,8 +271,10 @@ export class TerrainPlugin implements Plugin {
if (!path) { log.warn('terrain', `no source image is known for texture ${handle}; the terrain falls back to its noise`); return null; }
try {
// The bytes the asset layer would load, decoded unmodified (no premultiply, no colour conversion): a height is data.
+ // A PNG is read as stored first: through a canvas, a splatmap's zero alpha erased the other three weights.
if (typeof createImageBitmap === 'function' && typeof Blob !== 'undefined') {
- return await decodeImagePixels(new Blob([await assets.fetchBinary(path)]));
+ const bytes = new Uint8Array(await assets.fetchBinary(path));
+ return await decodePngData(bytes) ?? await decodeImagePixels(new Blob([bytes]));
}
const image = await platformLoadImagePixels(assets.resolveLoadPath(path));
return { width: image.width, height: image.height, pixels: image.pixels };
diff --git a/sdk/tests/png-data.test.ts b/sdk/tests/png-data.test.ts
new file mode 100644
index 000000000..c974c5612
--- /dev/null
+++ b/sdk/tests/png-data.test.ts
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import { deflateSync } from 'node:zlib';
+import { decodePngData } from '../src/asset/pngData';
+
+/** A PNG of `rows` (bytes per row, unfiltered), each row written with `filter` applied, of colour `type` (0 grey, 2 RGB, 6 RGBA). */
+function png(width: number, height: number, type: number, rows: number[][], filter = 0): Uint8Array {
+ const channels = { 0: 1, 2: 3, 6: 4 }[type as 0 | 2 | 6];
+ const raw: number[] = [];
+ rows.forEach((row, y) => {
+ raw.push(filter);
+ row.forEach((v, x) => {
+ const a = x >= channels ? row[x - channels]! : 0;
+ const b = y > 0 ? rows[y - 1]![x]! : 0;
+ const c = x >= channels && y > 0 ? rows[y - 1]![x - channels]! : 0;
+ const p = a + b - c;
+ const pred = filter === 1 ? a : filter === 2 ? b : filter === 3 ? (a + b) >> 1
+ : filter === 4 ? (Math.abs(p - a) <= Math.abs(p - b) && Math.abs(p - a) <= Math.abs(p - c) ? a : Math.abs(p - b) <= Math.abs(p - c) ? b : c) : 0;
+ raw.push((v - pred) & 255);
+ });
+ });
+ const chunk = (name: string, data: Uint8Array): number[] => {
+ const len = [data.length >>> 24, (data.length >>> 16) & 255, (data.length >>> 8) & 255, data.length & 255];
+ return [...len, ...Array.from(name, (ch) => ch.charCodeAt(0)), ...data, 0, 0, 0, 0];
+ };
+ const ihdr = new Uint8Array(13);
+ new DataView(ihdr.buffer).setUint32(0, width);
+ new DataView(ihdr.buffer).setUint32(4, height);
+ ihdr[8] = 8; ihdr[9] = type;
+ return new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10, ...chunk('IHDR', ihdr), ...chunk('IDAT', deflateSync(Buffer.from(raw))), ...chunk('IEND', new Uint8Array())]);
+}
+
+describe('a PNG read as data', () => {
+ it('keeps red, green and blue where alpha is zero, which a canvas premultiplies away', async () => {
+ // A splatmap texel with no rock (alpha 0) and all grass: the grass weight must survive.
+ const out = await decodePngData(png(2, 1, 6, [[255, 0, 0, 0, 10, 200, 30, 0]]));
+ expect(Array.from(out!.pixels)).toEqual([255, 0, 0, 0, 10, 200, 30, 0]);
+ });
+
+ it('undoes every row filter', async () => {
+ const rows = [[10, 20, 30, 40, 50, 60, 70, 80], [90, 100, 110, 120, 130, 140, 150, 160], [5, 250, 7, 9, 200, 3, 128, 64]];
+ for (const filter of [0, 1, 2, 3, 4]) {
+ const out = await decodePngData(png(2, 3, 6, rows, filter));
+ expect(Array.from(out!.pixels), `filter ${filter}`).toEqual(rows.flat());
+ }
+ });
+
+ it('widens grey and RGB to RGBA with an opaque alpha', async () => {
+ expect(Array.from((await decodePngData(png(2, 1, 0, [[7, 200]])))!.pixels)).toEqual([7, 7, 7, 255, 200, 200, 200, 255]);
+ expect(Array.from((await decodePngData(png(1, 1, 2, [[1, 2, 3]])))!.pixels)).toEqual([1, 2, 3, 255]);
+ });
+
+ it('declines what it does not read, so the image path decodes it', async () => {
+ expect(await decodePngData(new Uint8Array([1, 2, 3]))).toBeNull();
+ });
+});