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(render): preserve sprites with incompatible WebGL S3TC dimensions

yhh29c139e6698b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-10
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.ts
index 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?: CompressedUploadOption
return 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.ts
index 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.mjs
index 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':