A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(textures): a transparent edge no longer shows a dark fringe
yhh3059969fd190
diff --git a/desktop b/desktopindex 1810b2429..1df21b57c 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 1810b2429495075ef362039a72f0a1979e07686a+Subproject commit 1df21b57c99957f2d584b5603998c87e9571be7fdiff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdxindex 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.mdxindex 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.tsindex 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.tsindex 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: numberreturn { 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<TextureCookOconst 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): imagediff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.tsindex 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.tsindex 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.tsindex 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.tsindex 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, sodiff --git a/sdk/tests/texture-preview.test.ts b/sdk/tests/texture-preview.test.tsindex 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);+ });});