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(render): preserve sprites with incompatible WebGL S3TC dimensions
yhh29c139e6698b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e8194c5e5..a71e75665 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -31,6 +31,7 @@ published separately; it ships inside the editor.- **Imported material textures resolve correctly.** glTF material and texture import references stay consistent with the runtime asset loaders.- **Audio preview failures stay with their own clip.** A late failure cannot stop a replacement clip; synchronous playback failure clears preview state, and changing projects stops old browser previews.- **Waveforms preserve every audio channel.** Opposite-phase stereo and surround channels remain visible. Waveform fetches and scans are cancellable, decoding runs one file at a time without opening a live audio output device, and large scans yield background tasks so input can continue.+- **Compressed sprites keep their authored dimensions on WebGL.** S3TC mip chains that violate WebGL block alignment decode to RGBA before upload instead of registering an incomplete texture. Odd-sized images such as 70×70 sprites remain visible; valid compressed chains and small tail mips still use compression.## [0.77.0] - 2026-10-10diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.tsindex 82e5aabaa..a9e620e45 100644--- a/sdk/src/asset/compressed.ts+++ b/sdk/src/asset/compressed.ts@@ -248,6 +248,13 @@ function levelsOf(r: TranscodeResult | RgbaResult, opts?: CompressedUploadOptionreturn r.levels && r.levels.length > 0 ? r.levels : [base];}+/** S3TC requires each mip's dimensions, scaled to level zero, to align to+ * four texels. Small tail levels remain valid at their original mip index. */+function webglCompressedLevelsSupported(format: CompressedTextureFormat, levels: readonly TranscodedLevel[]): boolean {+ return format !== CompressedTextureFormat.S3TC_DXT5 || levels.every((level, index) =>+ (level.width * 2 ** index) % 4 === 0 && (level.height * 2 ** index) % 4 === 0);+}+/** Upload pre-transcoded compressed blocks via `gl.compressedTexImage2D`. */export function uploadCompressedTexture(gl: WebGL2RenderingContext, module: ESEngineModule,@@ -260,6 +267,9 @@ export function uploadCompressedTexture(// format is 4–8× smaller than the pool's RGBA8 estimate, and billing it at// the estimate would squat on most of the budget.const levels = levelsOf(t, opts);+ if (!webglCompressedLevelsSupported(fmt, levels)) {+ throw new Error('S3TC texture mip dimensions are not block aligned for WebGL');+ }const handle = handOverNewTexture(module, gl, (g) => {levels.forEach((l, i) => g.compressedTexImage2D(g.TEXTURE_2D, i, internalFormat, l.width, l.height, 0, l.data));applyParams(g, levels.length, false, opts);@@ -386,8 +396,11 @@ export async function loadCompressedTexture(const support = detectCompressedTextureSupport(gl);const target = chooseTargetFormat(support, opts?.srgb ?? false);const t = target !== null ? await transcoder.transcode(bytes, target) : null;- const decision = compressedUploadDecision(target, t !== null);- if (target !== null && t) {+ const aligned = target !== null && t !== null && webglCompressedLevelsSupported(target, levelsOf(t, opts));+ const decision: TextureUploadDecision = target !== null && t && !aligned+ ? { payload: 'ktx2', target, effective: 'rgba8', reason: 'not-block-aligned' }+ : compressedUploadDecision(target, t !== null);+ if (target !== null && t && aligned) {return { ...uploadCompressedTexture(gl, module, support, target, t, opts), decision };}const rgba = await transcoder.transcodeToRgba(bytes);diff --git a/sdk/tests/compressed-texture.test.ts b/sdk/tests/compressed-texture.test.tsindex 906d5fc6a..e1165ab60 100644--- a/sdk/tests/compressed-texture.test.ts+++ b/sdk/tests/compressed-texture.test.ts@@ -190,6 +190,34 @@ describe('loadCompressedTexture', () => {});describe('mip levels', () => {+ it('falls back for a 70px S3TC texture before registering an incomplete GPU image', async () => {+ const gl = makeGl({ s3tc: true });+ const transcoder = makeTranscoder({+ transcode: vi.fn(() => ({ width: 70, height: 70, data: new Uint8Array(5184) })),+ transcodeToRgba: vi.fn(() => ({ width: 70, height: 70, data: new Uint8Array(70 * 70 * 4) })),+ });+ const result = await loadCompressedTexture(gl as never, makeModule() as never, transcoder, KTX2_HEADER);+ expect(gl.compressedTexImage2D).not.toHaveBeenCalled();+ expect(gl.texImage2D).toHaveBeenCalledTimes(1);+ expect(result.decision).toEqual({payload:'ktx2',target:CompressedTextureFormat.S3TC_DXT5,effective:'rgba8',reason:'not-block-aligned'});+ expect(result.width).toBe(70);expect(result.height).toBe(70);+ });+ it('rejects an incompatible mip before allocating a GPU texture', () => {+ const gl = makeGl({s3tc:true});+ const t = {width:8,height:8,data:new Uint8Array(64),levels:[+ {width:8,height:8,data:new Uint8Array(64)}, {width:3,height:4,data:new Uint8Array(16)}]};+ expect(()=>uploadCompressedTexture(gl as never,makeModule() as never,detectCompressedTextureSupport(gl as never),CompressedTextureFormat.S3TC_DXT5,t)).toThrow(/block.aligned/i);+ expect(gl.createTexture).not.toHaveBeenCalled();+ });+ it('allows small tail levels and ignores excluded incompatible mips', () => {+ const gl = makeGl({s3tc:true}),module=makeModule(),support=detectCompressedTextureSupport(gl as never);+ const levels=[4,2,1].map(width=>({width,height:width,data:new Uint8Array(16)}));+ uploadCompressedTexture(gl as never,module as never,support,CompressedTextureFormat.S3TC_DXT5,{...levels[0],levels});+ expect(gl.compressedTexImage2D).toHaveBeenCalledTimes(3);+ uploadCompressedTexture(gl as never,module as never,support,CompressedTextureFormat.S3TC_DXT5,+ {...levels[0],levels:[levels[0],{width:3,height:3,data:new Uint8Array(16)}]},{mipmaps:false});+ expect(gl.compressedTexImage2D).toHaveBeenCalledTimes(4);+ });const minFilter = (gl: ReturnType<typeof makeGl>) =>gl.texParameteri.mock.calls.find((c) => c[1] === gl.TEXTURE_MIN_FILTER)?.[2];const maxLevel = (gl: ReturnType<typeof makeGl>) =>diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 8dd0ab3ea..d17f44716 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(render): preserve sprites with incompatible WebGL S3TC dimensions':+ { note: 'Compressed sprites keep their authored dimensions on WebGL.' },'fix(sdk): keep indexed access valid for strict consumers':{ internal: 'Preserves supported pool and cleanup behavior while satisfying strict compiler consumer type checks.' },'fix(sdk): resolve spawned entities before tracking scene ownership':