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(textures): a transparent edge no longer shows a dark fringe

yhh3059969fd190
diff --git a/desktop b/desktop
index 1810b2429..1df21b57c 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1810b2429495075ef362039a72f0a1979e07686a
+Subproject commit 1df21b57c99957f2d584b5603998c87e9571be7f
diff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdx
index 0416c7d1e..e5451267b 100644
--- a/docs/astro/src/content/docs/assets/textures.mdx
+++ b/docs/astro/src/content/docs/assets/textures.mdx
@@ -124,6 +124,7 @@ Browser — every sprite that uses the texture inherits them.
| **Filter** | `linear` | Sampling filter. `nearest` keeps pixel art crisp; `linear` smooths. |
| **Wrap** | `repeat` | How UVs outside `[0,1]` are addressed: `repeat`, `clamp`, `mirror`. |
| **sRGB Color** | `true` | The image stores sRGB-encoded color (albedo, UI). Disable for authored-linear data — normal maps, masks. Only meaningful when the project renders in linear color. |
+| **Alpha Is Transparency** | `true` | When the texture is cooked (for a build and for the editor alike), fully clear texels take the colour of their solid neighbours, so filtering and mip maps at a transparent edge — a rounded panel's corner — no longer average in the black under alpha 0 as a dark fringe. Partly clear and solid texels keep their colour; premultiplied art is left alone. Turn off for an image whose RGB under alpha 0 a shader reads as data. |
| **Mip Coverage Cutoff** | `0` | For a cutout (leaves, grass, fences): the alpha cutoff its material tests. Each mip level keeps the share of texels above it that the full image has, so the cutout does not thin out with distance. `0` = off (0 to 1); applies to UASTC-compressed textures. |
| **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. |
| **Cell Width / Cell Height** | `0` | The size of one cell of a sprite sheet, in pixels. `0` means the image is not a sheet; setting it lets a `Sprite` pick a frame of the image instead of showing all of it. |
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 8421cec9e..e5e699235 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx
@@ -114,6 +114,7 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而
| **Filter** | `linear` | 采样过滤。`nearest` 保持像素锐利;`linear` 平滑。 |
| **Wrap** | `repeat` | `[0,1]` 之外的 UV 如何寻址:`repeat`、`clamp`、`mirror`。 |
| **sRGB Color** | `true` | 图片存的是 sRGB 编码的颜色(albedo、UI)。法线图、遮罩这类本来就是线性的数据要关掉。仅在项目按线性色渲染时有意义。 |
+| **Alpha Is Transparency** | `true` | 纹理烹饪时(构建和编辑器同样适用),完全透明的像素会取周围不透明像素的颜色,这样透明边缘(比如圆角面板的角)在过滤和 mip 时不会把 alpha 为 0 下的黑色混进来形成黑边。半透明和不透明像素保持原色;预乘内容不处理。如果某张图 alpha 为 0 处的 RGB 被 shader 当作数据读取,请关掉。 |
| **Mip Coverage Cutoff** | `0` | 用于镂空(树叶、草、栅栏):材质测试的 alpha 阈值。每一级 mip 都保留与完整图像相同比例的高于阈值的像素,镂空就不会随距离变稀。`0` = 关;对 UASTC 压缩贴图生效。 |
| **9-Slice Border** | `0,0,0,0` | 左/右/上/下边框,单位是**纹理像素**:图片的角在哪里结束。在这里授权一次,每个设成 Sliced 的 `UIVisual` 都继承。 |
| **Cell Width / Cell Height** | `0` | 精灵表里一个格子的大小,单位像素。`0` 表示这张图不是精灵表;设了之后,`Sprite` 可以选取图中的某一帧,而不是显示整张。 |
diff --git a/pipeline/src/assets/modelImages.ts b/pipeline/src/assets/modelImages.ts
index b4ef76aea..ced260c13 100644
--- a/pipeline/src/assets/modelImages.ts
+++ b/pipeline/src/assets/modelImages.ts
@@ -73,7 +73,11 @@ function constantColor(p: Pixels): number[] | null {
* a skin tone under eyelashes, white under a leaf; a mip averages it in with the strands, and seen from a distance the card drew a veil of
* that colour over what it covers (the render lab's probe eye came out pink). A texel that is solid keeps its colour exactly.
*/
-export function bleedCutoutColor(p: Pixels): Uint8Array {
+export function bleedCutoutColor(p: Pixels, options?: { clearOnly?: boolean }): Uint8Array {
+ // `clearOnly`: only texels with alpha 0 take the neighbourhood's colour. A
+ // straight-alpha sprite's partly clear texels (an anti-aliased edge) carry the
+ // colour that is SEEN, and pulling them toward a neighbour shifts the edge's hue.
+ const clearOnly = options?.clearOnly === true;
const levels: { w: number; h: number; c: Float32Array; a: Float32Array }[] = [];
let w = p.width, h = p.height;
let c = new Float32Array(w * h * 3), a = new Float32Array(w * h);
@@ -105,7 +109,7 @@ export function bleedCutoutColor(p: Pixels): Uint8Array {
for (let x = 0; x < p.width; x++) {
const i = y * p.width + x;
const alpha = p.rgba[i * 4 + 3]! / 255;
- if (alpha >= 1) continue;
+ if (alpha >= 1 || (clearOnly && alpha > 0)) continue;
// The colour of the nearest solid neighbourhood: the first level up whose cell holds any.
let fill: [number, number, number] | null = null;
for (let l = 1; l < levels.length; l++) {
diff --git a/pipeline/src/assets/textureCook.ts b/pipeline/src/assets/textureCook.ts
index 5c46b7d67..9131739bf 100644
--- a/pipeline/src/assets/textureCook.ts
+++ b/pipeline/src/assets/textureCook.ts
@@ -86,6 +86,47 @@ export function pngDimensions(png: Uint8Array): { width: number; height: number
return { width: dv.getUint32(16), height: dv.getUint32(20) };
}
+/**
+ * Whether a PNG can hold a transparent texel, from its header: grey+alpha or RGBA,
+ * or a palette with a tRNS chunk. Answered without decoding, so an opaque image
+ * costs nothing here.
+ */
+export function pngMayHaveAlpha(png: Uint8Array): boolean {
+ if (png.byteLength < 26) return false;
+ const colorType = png[25];
+ if (colorType === 4 || colorType === 6) return true;
+ if (colorType !== 3) return false;
+ // tRNS precedes IDAT; walk the chunks up to the first image data.
+ const dv = new DataView(png.buffer, png.byteOffset, png.byteLength);
+ for (let at = 8; at + 8 <= png.byteLength;) {
+ const len = dv.getUint32(at);
+ const type = String.fromCharCode(png[at + 4]!, png[at + 5]!, png[at + 6]!, png[at + 7]!);
+ if (type === 'tRNS') return true;
+ if (type === 'IDAT') return false;
+ at += 12 + len;
+ }
+ return false;
+}
+
+function hasClearTexel(rgba: Uint8Array): boolean {
+ for (let i = 3; i < rgba.length; i += 4) if (rgba[i] === 0) return true;
+ return false;
+}
+
+/**
+ * Whether the colour was multiplied by alpha already (a Spine PMA page): no channel
+ * above its texel's alpha anywhere. Such an image's RGB under alpha 0 is 0 BY
+ * DEFINITION, and premultiplied blending adds it — filling it in would light up
+ * every clear texel.
+ */
+function looksPremultiplied(rgba: Uint8Array): boolean {
+ for (let i = 0; i < rgba.length; i += 4) {
+ const a = rgba[i + 3]!;
+ if (rgba[i]! > a || rgba[i + 1]! > a || rgba[i + 2]! > a) return false;
+ }
+ return true;
+}
+
function safePngDimensions(png: Uint8Array): { width: number; height: number } | null {
try {
return pngDimensions(png);
@@ -167,12 +208,38 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
// A cutout (one that asks for its coverage kept) has the colour of its solid texels carried into its clear ones, as a model's cutouts do: what a
// painter leaves under alpha 0 is a mip's, and a filter's, to average in with the leaf, and the edge of every leaf shows it as a halo.
const cutout = raster && tex.mipmaps && tex.mipCoverage > 0;
+ // Any other colour image with clear texels gets the same treatment, held to
+ // those texels alone (Unity's "alpha is transparency"): the RGB an editor leaves
+ // under alpha 0 is usually black, and a bilinear sample or a mip at the edge of a
+ // rounded panel averages it in as a dark fringe. A partly clear texel keeps its
+ // colour — on a straight-alpha image it is the colour that is seen.
+ // The importer can say no (`alphaIsTransparency: false`): an image whose RGB under
+ // alpha 0 a shader reads as data.
+ const clearBleed = raster && !cutout && tex.srgb && input.importer?.alphaIsTransparency !== false && pngMayHaveAlpha(data);
const bled = (image: { rgba: Uint8Array; width: number; height: number }) =>
- cutout ? { ...image, rgba: bleedCutoutColor({ width: image.width, height: image.height, rgba: image.rgba }) } : image;
- // A texture that ships as an image ships the shrunk one.
- if (cook.selected === 'raw' && (scaled || cutout)) {
- const image = bled(scaled ? scaledImage() : decodePngImage(path, data));
- data = encodeRgbaPng(image.width, image.height, image.rgba);
+ cutout || (clearBleed && hasClearTexel(image.rgba) && !looksPremultiplied(image.rgba))
+ ? { ...image, rgba: bleedCutoutColor({ width: image.width, height: image.height, rgba: image.rgba }, { clearOnly: !cutout }) }
+ : image;
+ const bleedKey = cutout ? { bleed: 1 } : clearBleed ? { bleed: 'clear' } : {};
+ // A texture that ships as an image ships the shrunk one, and the bled one —
+ // through the cook cache, so the editor shows the same pixels a build ships.
+ if (cook.selected === 'raw' && (scaled || cutout || clearBleed)) {
+ const source = data;
+ const key = [source, JSON.stringify({ raw: 1, maxSize: tex.maxSize, scaled: scaled ? [size!.width, size!.height] : null, ...bleedKey })];
+ const file = cookCacheFile(root, key);
+ const produce = async (): Promise<Uint8Array> => {
+ const decoded = scaled ? scaledImage() : decodePngImage(path, source);
+ const image = bled(decoded);
+ // An image with nothing to change (an RGBA file that is opaque throughout)
+ // ships as it is, byte for byte.
+ if (!scaled && image === decoded) return source;
+ return encodeRgbaPng(image.width, image.height, image.rgba);
+ };
+ const shipped = input.cachedOnly ? await cookCacheHitAt(file) : (await cookCachedAt(file, produce)).bytes;
+ if (!shipped) return { data, ext, cook, warnings, defeatedByFormat, pending: true };
+ const unchanged = shipped.byteLength === source.byteLength && Buffer.from(shipped).equals(Buffer.from(source));
+ return unchanged ? { data: source, ext, cook, warnings, defeatedByFormat }
+ : { data: shipped, ext, cook, warnings, defeatedByFormat, cacheFile: file };
}
if (cook.selected !== 'raw') {
// Only a build that encodes can select an encoding, and that is exactly
@@ -189,9 +256,9 @@ export async function cookTexture(input: TextureCookInput): Promise<TextureCookO
const supercompress = mode === 'uastc';
const key = [source, JSON.stringify({ mode, srgb: tex.srgb, maxSize: tex.maxSize, scaled: scaled ? [size!.width, size!.height] : null,
// `chain: 3` marks the rescaled chain that replaced the share-of-coverage one (chain 2): an entry cooked before it is re-encoded.
- ...(coverage ? { mipCoverage: coverage, chain: 3 } : {}), ...(cutout ? { bleed: 1 } : {}), ...(supercompress ? { supercompress } : {}), ...mips }), input.encoder!.id];
+ ...(coverage ? { mipCoverage: coverage, chain: 3 } : {}), ...bleedKey, ...(supercompress ? { supercompress } : {}), ...mips }), input.encoder!.id];
const produce = (): Promise<Uint8Array> => {
- const image = scaled ? bled(scaledImage()) : cutout ? bled(decodePngImage(path, source)) : null;
+ const image = scaled ? bled(scaledImage()) : cutout || clearBleed ? bled(decodePngImage(path, source)) : null;
return coverage
? encodeCoverageChain(enc, image ?? decodePngImage(path, source), tex.srgb, coverage)
: image
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index 795279c07..9d60bc1e6 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -100,6 +100,14 @@ const TEXTURE: ImporterFieldSpec[] = [
tooltip: 'The image stores sRGB-encoded color (albedo/UI). Disable for authored-linear '
+ 'data like normal maps and masks — only meaningful when the project renders in linear color.',
},
+ {
+ key: 'alphaIsTransparency', label: 'Alpha Is Transparency', type: 'bool', default: true, category: 'Texture', advanced: true,
+ tooltip: 'Fill the colour of fully clear texels from their solid neighbours when the texture is '
+ + 'cooked, so filtering and mip maps at a transparent edge do not average in the black (or '
+ + 'whatever was painted) under alpha 0 as a dark fringe. Partly clear and solid texels keep '
+ + 'their colour, and premultiplied art is left as it is. Turn off for an image whose RGB under '
+ + 'alpha 0 a shader reads as data.',
+ },
{
key: 'mipCoverage', label: 'Mip Coverage Cutoff', type: 'number', default: 0, min: 0, max: 1, step: 0.01,
category: 'Texture', advanced: true,
diff --git a/pipeline/tests/texture-cook.test.ts b/pipeline/tests/texture-cook.test.ts
index 7d82538ea..dc910d3aa 100644
--- a/pipeline/tests/texture-cook.test.ts
+++ b/pipeline/tests/texture-cook.test.ts
@@ -82,14 +82,19 @@ describe('a texture compressed for the editor', () => {
}
}, 60_000);
- it('stays as it is where its settings keep it raw, and is never pending', async () => {
+ it('stays an image where its settings keep it raw, made at most once', async () => {
const r = mkdtempSync(path.join(tmpdir(), 'estella-texcook-raw-'));
try {
- const out = await cookTexture({
+ // An image with an alpha channel may need its clear texels filled: that is
+ // made once, in the background for the editor, and answered from the cache after.
+ const ask = (cachedOnly: boolean) => cookTexture({
root: r, path: 'lightmap.png', data: new Uint8Array(noisePng(64, 64)), ext: '.png',
- importer: { compress: false }, encoder: await loadTextureEncoder(),
- compressTextures: true, atlasTextures: false, drawnIn3D: true, cachedOnly: true,
+ importer: { compress: false }, encoder: null,
+ compressTextures: true, atlasTextures: false, drawnIn3D: true, cachedOnly,
});
+ const made = await ask(false);
+ expect(made.ext).toBe('.png');
+ const out = await ask(true);
expect(out.ext).toBe('.png');
expect(out.pending).toBeUndefined();
} finally {
@@ -142,8 +147,12 @@ describe('a cutout texture the cook ships', () => {
// A clear texel beside the leaf is green and still clear; a solid one is exactly as it was.
expect([...out.rgba.slice(5 * 4, 5 * 4 + 4)]).toEqual([20, 160, 30, 0]);
expect([...out.rgba.slice(0, 4)]).toEqual([20, 160, 30, 255]);
- const plain = await cook({ compress: false, mipmaps: true });
- expect(Buffer.from(plain.data).equals(Buffer.from(png))).toBe(true);
+ // No cutout, but a colour image: its clear texels are filled too, solid ones kept.
+ const plain = decodePngImage('leaf.png', (await cook({ compress: false, mipmaps: true })).data);
+ expect([...plain.rgba.slice(5 * 4, 5 * 4 + 4)]).toEqual([20, 160, 30, 0]);
+ // Unless the importer says its RGB under alpha is data.
+ const kept = await cook({ compress: false, mipmaps: true, alphaIsTransparency: false });
+ expect(Buffer.from(kept.data).equals(Buffer.from(png))).toBe(true);
});
});
@@ -170,3 +179,40 @@ describe('a UASTC texture the cook ships', () => {
}
});
});
+
+describe('a colour image with clear texels', () => {
+ it('ships with its clear texels filled from their neighbours, edges kept, opaque and data images untouched', async () => {
+ const r = mkdtempSync(path.join(tmpdir(), 'estella-bleed-'));
+ try {
+ // 4x1: white solid, white half-clear edge, then two clear texels whose RGB is black.
+ const rgba = new Uint8Array([255, 255, 255, 255, 255, 255, 255, 128, 0, 0, 0, 0, 0, 0, 0, 0]);
+ const png = encodeRgbaPng(4, 1, rgba);
+ const ask = (importer: Record<string, unknown>, data = png) => cookTexture({
+ root: r, path: 'ui/panel.png', data, ext: '.png', importer,
+ encoder: null, compressTextures: false, atlasTextures: false, drawnIn3D: false,
+ });
+ const out = await ask({});
+ expect(out.ext).toBe('.png');
+ expect(out.cacheFile).toBeDefined();
+ const px = decodePngImage('ui/panel.png', out.data).rgba;
+ expect(Array.from(px.subarray(0, 8))).toEqual([255, 255, 255, 255, 255, 255, 255, 128]); // solid and edge as painted
+ expect(Array.from(px.subarray(8, 11))).toEqual([255, 255, 255]); // clear: no longer black
+ expect(px[11]).toBe(0); // and still clear
+
+ const opaque = encodeRgbaPng(2, 1, new Uint8Array([10, 20, 30, 255, 40, 50, 60, 255]));
+ const same = await ask({}, opaque);
+ expect(Buffer.from(same.data).equals(Buffer.from(opaque))).toBe(true);
+ expect(same.cacheFile).toBeUndefined();
+
+ const data = await ask({ sRGB: false }); // a data texture: its RGB is not a colour
+ expect(Buffer.from(data.data).equals(Buffer.from(png))).toBe(true);
+
+ // Premultiplied art (no channel above alpha): its clear RGB must stay 0.
+ const pma = encodeRgbaPng(3, 1, new Uint8Array([200, 200, 200, 255, 100, 100, 100, 128, 0, 0, 0, 0]));
+ const kept = await ask({}, pma);
+ expect(Buffer.from(kept.data).equals(Buffer.from(pma))).toBe(true);
+ } finally {
+ rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+ });
+});
diff --git a/pipeline/tests/texture-supercompression.test.ts b/pipeline/tests/texture-supercompression.test.ts
index 88687f417..007bc3ba3 100644
--- a/pipeline/tests/texture-supercompression.test.ts
+++ b/pipeline/tests/texture-supercompression.test.ts
@@ -35,7 +35,7 @@ describe('Bistro texture crops, cooked as a build ships them', () => {
for (const f of files) {
const png = new Uint8Array(readFileSync(path.join(DIR, f)));
const cooked = await cookTexture({
- root, path: `t/${f}`, data: png, ext: '.png', importer: { compress: 'on' },
+ root, path: `t/${f}`, data: png, ext: '.png', importer: { compress: 'on', alphaIsTransparency: false },
encoder, compressTextures: true, atlasTextures: false, drawnIn3D: false,
});
expect(cooked.ext, f).toBe('.ktx2');
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index 849efda9d..ff27e7ea9 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -88,6 +88,8 @@ export function textureResidencyKey(path: string, flip: boolean): string {
return `${path}:${flip ? 'f' : 'n'}`;
}
+const isPng = (b: Uint8Array): boolean => b.byteLength > 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47;
+
export class TextureLoader implements AssetLoader<TextureResult> {
private readonly imageRevisions_ = new Map<string, number>();
@@ -308,6 +310,10 @@ export class TextureLoader implements AssetLoader<TextureResult> {
let preview = false;
if (!copy && this.compressedSource_) {
const compressed = await this.compressedSource_(path);
+ // The source may answer with the image a build ships rather than a KTX2 —
+ // a PNG resized or with its clear texels' colour filled in — and it is drawn
+ // the way any image is, so the editor shows the pixels the package holds.
+ if (compressed instanceof Uint8Array && isPng(compressed)) return this.uploadImageBytes_(compressed, flip, settings, maxEdge);
if (compressed instanceof Uint8Array) return this.uploadKtx2_(path, compressed, settings, maxEdge);
preview = compressed === 'pending';
}
@@ -333,6 +339,21 @@ export class TextureLoader implements AssetLoader<TextureResult> {
return full.width > made.width || full.height > made.height ? { ...made, fullWidth: full.width, fullHeight: full.height } : made;
}
+ /** An encoded image in memory, through the same image path a URL takes. */
+ private async uploadImageBytes_(
+ bytes: Uint8Array, flip: boolean, settings?: TextureImportSettings, maxEdge = 0,
+ ): Promise<TextureResult> {
+ const url = URL.createObjectURL(new Blob([bytes as Uint8Array<ArrayBuffer>], { type: 'image/png' }));
+ try {
+ const full = { width: 0, height: 0 };
+ const img = await this.loadImage(url, flip, maxEdge, undefined, full);
+ const made = this.createTextureFromImage(img, flip, settings);
+ return full.width > made.width || full.height > made.height ? { ...made, fullWidth: full.width, fullHeight: full.height } : made;
+ } finally {
+ URL.revokeObjectURL(url);
+ }
+ }
+
/**
* Upload a KTX2 (Basis) compressed texture: transcode to a device-supported GPU
* format (or RGBA8 fallback), and upload. KTX2 carries its own orientation, so
diff --git a/sdk/tests/texture-preview.test.ts b/sdk/tests/texture-preview.test.ts
index df539482b..953d86f16 100644
--- a/sdk/tests/texture-preview.test.ts
+++ b/sdk/tests/texture-preview.test.ts
@@ -44,4 +44,21 @@ describe('pending texture previews', () => {
expect((await loader.load('color.png', {} as LoadContext)).width).toBe(2048);
expect(decoder).toHaveBeenLastCalledWith('color.png', true, 0);
});
+
+ it('draws a PNG the compressed source answers with as an image, a KTX2 as a KTX2', async () => {
+ const loader = new TextureLoader(null);
+ const internals = loader as unknown as {
+ uploadImageBytes_: (...a: unknown[]) => Promise<unknown>; uploadKtx2_: (...a: unknown[]) => Promise<unknown>;
+ };
+ const image = vi.spyOn(internals, 'uploadImageBytes_').mockResolvedValue({ handle: 1, width: 4, height: 4 });
+ const ktx2 = vi.spyOn(internals, 'uploadKtx2_').mockResolvedValue({ handle: 2, width: 4, height: 4 });
+ const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0]);
+ loader.setCompressedSource(async () => png);
+ await loader.load('panel.png', {} as LoadContext);
+ expect(image).toHaveBeenCalledTimes(1);
+ expect(ktx2).not.toHaveBeenCalled();
+ loader.setCompressedSource(async () => new Uint8Array([0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0, 0]));
+ await loader.load('panel.png', {} as LoadContext);
+ expect(ktx2).toHaveBeenCalledTimes(1);
+ });
});