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(asset): KTX2 refused on WeChat — WebGL2 check used a DOM global

yhh3f816a3cd8eb
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index 481d531ff..65b0a735d 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -241,15 +241,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {
}
private getWebGL2Context(): WebGL2RenderingContext | null {
- try {
- const glObj = this.module_.GL;
- if (glObj?.currentContext?.GLctx instanceof WebGL2RenderingContext) {
- return glObj.currentContext.GLctx;
- }
- } catch {
- // fallback
- }
- return null;
+ return findWebGL2Context(this.module_.GL);
}
private createTextureWebGL2(
@@ -346,3 +338,29 @@ function nextPowerOf2(n: number): number {
while (p < n) p *= 2;
return p;
}
+
+/**
+ * The engine's WebGL2 context, looked up through emscripten's GL bookkeeping.
+ * Duck-typed on `texStorage2D` (a WebGL2-only method): WeChat MiniGames have no
+ * `WebGL2RenderingContext` global — an `instanceof` check THREW there and read
+ * as "no context", refusing every KTX2 texture — and instanceof lies across
+ * realms anyway. Falls back to any registered context when none is current yet
+ * (a host registers the context before the renderer's first frame makes it
+ * current). Exported for tests.
+ */
+export function findWebGL2Context(glObj: ESEngineModule['GL'] | undefined): WebGL2RenderingContext | null {
+ try {
+ const current = glObj?.currentContext?.GLctx;
+ if (isWebGL2(current)) return current;
+ for (const rec of glObj?.contexts ?? []) {
+ if (rec && isWebGL2(rec.GLctx)) return rec.GLctx;
+ }
+ } catch {
+ // fall through — treated as "no WebGL2 context"
+ }
+ return null;
+}
+
+function isWebGL2(ctx: unknown): ctx is WebGL2RenderingContext {
+ return !!ctx && typeof (ctx as WebGL2RenderingContext).texStorage2D === 'function';
+}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index f8bbf6fa5..609f7ecc8 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -131,6 +131,8 @@ export interface ESEngineModule {
}): number;
/** Emscripten-internal: active GL context record (populated after registerContext). */
currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext };
+ /** Emscripten-internal: every registered context record, indexed by handle (holes possible). */
+ contexts?: ({ GLctx: WebGLRenderingContext | WebGL2RenderingContext } | null)[];
/** Emscripten-internal: allocate a new handle id into the given object pool. */
getNewId(pool: Record<number, unknown>): number;
/** Emscripten-internal: texture object pool keyed by handle id. */
diff --git a/sdk/tests/texture-webgl2-context.test.ts b/sdk/tests/texture-webgl2-context.test.ts
new file mode 100644
index 000000000..abdda097e
--- /dev/null
+++ b/sdk/tests/texture-webgl2-context.test.ts
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * findWebGL2Context — the KTX2 path's context lookup. WeChat MiniGames have no
+ * `WebGL2RenderingContext` global, so the old `instanceof` check threw (caught,
+ * read as "no context") and every KTX2 texture was refused on-device. The
+ * lookup is duck-typed on `texStorage2D` and falls back to a registered-but-
+ * not-yet-current context.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { findWebGL2Context } from '../src/asset/loaders/TextureLoader';
+import type { ESEngineModule } from '../src/wasm';
+
+type GLObj = ESEngineModule['GL'];
+
+const webgl2Like = (): WebGL2RenderingContext =>
+ ({ texStorage2D: () => { /* WebGL2-only surface */ } }) as unknown as WebGL2RenderingContext;
+const webgl1Like = (): WebGL2RenderingContext => ({}) as WebGL2RenderingContext;
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe('findWebGL2Context (WeChat: no WebGL2RenderingContext global)', () => {
+ it('finds the current context with the global ABSENT — the WeChat repro', () => {
+ vi.stubGlobal('WebGL2RenderingContext', undefined);
+ const ctx = webgl2Like();
+ const gl = { currentContext: { GLctx: ctx } } as unknown as GLObj;
+ expect(findWebGL2Context(gl)).toBe(ctx);
+ });
+
+ it('falls back to a registered context when none is current yet', () => {
+ const ctx = webgl2Like();
+ const gl = { contexts: [null, { GLctx: ctx }] } as unknown as GLObj;
+ expect(findWebGL2Context(gl)).toBe(ctx);
+ });
+
+ it('prefers the current context over other registered ones', () => {
+ const current = webgl2Like();
+ const other = webgl2Like();
+ const gl = {
+ currentContext: { GLctx: current },
+ contexts: [{ GLctx: other }],
+ } as unknown as GLObj;
+ expect(findWebGL2Context(gl)).toBe(current);
+ });
+
+ it('rejects a WebGL1 context and tolerates a missing GL object', () => {
+ const gl = { currentContext: { GLctx: webgl1Like() } } as unknown as GLObj;
+ expect(findWebGL2Context(gl)).toBeNull();
+ expect(findWebGL2Context(undefined)).toBeNull();
+ });
+});