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(wechat): one SDK core per bundle (Res identity split-brain); KTX2 ships the Basis module

yhh7794549c92cf
diff --git a/build-tools/build.config.js b/build-tools/build.config.js
index 62e2c18fb..3aa2e2eb5 100644
--- a/build-tools/build.config.js
+++ b/build-tools/build.config.js
@@ -113,6 +113,15 @@ export default {
'sdk/physics.wasm': 'wasm/wechat/physics.wasm',
},
},
+ 'basis-wechat': {
+ buildDir: 'build-basis-wechat',
+ cmakeFlags: ['-DES_BUILD_WXGAME=ON', '-DES_BUILD_TESTS=OFF', '-DES_ENABLE_BASIS=ON'],
+ targets: ['basis_module'],
+ outputs: {
+ 'sdk/basis.js': 'wasm/wechat/basis.js',
+ 'sdk/basis.wasm': 'wasm/wechat/basis.wasm',
+ },
+ },
'spine-wechat': {
buildDir: 'build-spine-wechat',
cmakeFlags: ['-DES_BUILD_WXGAME=ON', '-DES_BUILD_TESTS=OFF'],
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 10a8316f6..db775be49 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -26,7 +26,7 @@ program
program
.command('build')
.description('Build ESEngine')
- .option('-t, --target <target>', 'Build target (web, wechat, playable, spine, spine38, spine41, physics, physics-wechat, spine-wechat, basis, sdk, all)', 'web')
+ .option('-t, --target <target>', 'Build target (web, wechat, playable, spine, spine38, spine41, physics, physics-wechat, spine-wechat, basis, basis-wechat, sdk, all)', 'web')
.option('-d, --debug', 'Debug build', false)
.option('-r, --release', 'Release build (default)', true)
.option('-c, --clean', 'Clean before build', false)
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index 3fb07285e..b0a6fcada 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -30,7 +30,7 @@ import type { OnExportProgress } from './exportProgress';
import { esengineAlias } from './esengineResolve';
import {
sceneUsesPhysics, detectSpineVersion, detectSpineVersionJson,
- spineModuleId, SIDE_MODULE_FILE,
+ spineModuleId, SIDE_MODULE_FILE, WECHAT_MODULE_BUILD_TARGET,
} from './sideModuleScan';
export interface ExportWeChatResult {
@@ -139,6 +139,9 @@ async function scanWeChatSideModules(
// meta type `spine`, so discriminate by extension — `.skel` is a binary
// skeleton, `.json` a JSON one; the `.atlas` sibling is not a skeleton.
for (const e of cookEntries) {
+ // Any staged KTX2 texture (compressTextures cook, or an authored .ktx2)
+ // needs the Basis transcoder at runtime.
+ if (e.path.toLowerCase().endsWith('.ktx2')) ids.add('basis');
if (e.type !== 'spine') continue;
const ext = path.extname(e.sourcePath ?? e.path).toLowerCase();
try {
@@ -155,7 +158,7 @@ async function scanWeChatSideModules(
for (const id of ids) {
const file = SIDE_MODULE_FILE[id];
if (file && existsSync(path.join(wasmDir, `${file}.js`))) present.push({ id, file });
- else errors.push(`scene needs "${id}" but ${file}.js is not in the wechat wasm dir — build it with \`node build-tools/cli.js build -t ${id === 'physics' ? 'physics-wechat' : 'spine-wechat'}\` and re-export.`);
+ else errors.push(`scene needs "${id}" but ${file}.js is not in the wechat wasm dir — build it with \`node build-tools/cli.js build -t ${WECHAT_MODULE_BUILD_TARGET[id] ?? id}\` and re-export.`);
}
return present;
}
@@ -258,18 +261,11 @@ export async function exportWeChat(opts: {
await mkdir(absOut, { recursive: true });
- // KTX2 decode needs the Basis transcoder side module, which has no WeChat
- // (WXWebAssembly) build yet — cooked .ktx2 textures could never load. Degrade
- // to uncompressed textures visibly instead of shipping an undecodable pack.
- let compressTextures = opts.compressTextures;
- if (compressTextures) {
- compressTextures = false;
- warnings.push('compressTextures: the Basis KTX2 transcoder has no WeChat build yet — textures export uncompressed.');
- }
-
- // 1. Cook reachable assets (paths preserved) + the flat manifest.
+ // 1. Cook reachable assets (paths preserved) + the flat manifest. KTX2
+ // textures are fine here: the scan below sees the staged .ktx2 files and
+ // ships the Basis transcoder side module with them.
progress({ phase: 'Cooking assets' });
- const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures, atlasTextures: opts.atlasTextures });
+ const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, atlasTextures: opts.atlasTextures });
warnings.push(...cook.warnings);
// 1b. Scan the scene for the optional modules it needs (physics/spine), so the
diff --git a/desktop/electron/sideModuleScan.ts b/desktop/electron/sideModuleScan.ts
index 0ae2f779b..957f85f9d 100644
--- a/desktop/electron/sideModuleScan.ts
+++ b/desktop/electron/sideModuleScan.ts
@@ -40,11 +40,21 @@ export type SpineVersion = '3.8' | '4.1' | '4.2';
/** id → artifact base name. Mirrors sdk/src/sideModules/registry.ts SIDE_MODULES. */
export const SIDE_MODULE_FILE: Record<string, string> = {
physics: 'physics',
+ basis: 'basis',
'spine:3.8': 'spine38',
'spine:4.1': 'spine41',
'spine:4.2': 'spine42',
};
+/** id → the `build-tools/cli.js build -t <target>` that produces its WeChat artifacts. */
+export const WECHAT_MODULE_BUILD_TARGET: Record<string, string> = {
+ physics: 'physics-wechat',
+ basis: 'basis-wechat',
+ 'spine:3.8': 'spine-wechat',
+ 'spine:4.1': 'spine-wechat',
+ 'spine:4.2': 'spine-wechat',
+};
+
export function spineModuleId(version: SpineVersion): string {
return `spine:${version}`;
}
diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.ts
index c6b8d116e..c42bf2ba5 100644
--- a/desktop/tests/export-wechat.test.ts
+++ b/desktop/tests/export-wechat.test.ts
@@ -210,23 +210,53 @@ describe('exportGame (wechat)', () => {
expect(res.errors.some((e) => e.includes('spine-wechat'))).toBe(true);
}, 60_000);
- it('degrades compressTextures to PNG with a warning (no WeChat Basis build)', async () => {
- const outCt = path.join(root, 'dist-wechat-ct');
+ it('a staged .ktx2 texture ships the Basis transcoder module', async () => {
+ const KTX = 'ffffffff-ffff-ffff-ffff-ffffffffffff';
+ const KTXSCN = 'abababab-abab-abab-abab-abababababab';
+ writeFileSync(path.join(root, 'assets', 'pre.ktx2'), 'KTX2BYTES');
+ writeFileSync(path.join(root, 'assets', 'pre.ktx2.meta'), meta(KTX, 'texture'));
+ writeFileSync(
+ path.join(root, 'scenes', 'ktx2.esscene'),
+ JSON.stringify({ version: '1.0', name: 'Ktx', entities: [{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${KTX}` } }] }] }),
+ );
+ writeFileSync(path.join(root, 'scenes', 'ktx2.esscene.meta'), meta(KTXSCN, 'scene'));
+ const wxDir = path.join(root, '_wxwasm-basis');
+ mkdirSync(wxDir, { recursive: true });
+ writeFileSync(path.join(wxDir, 'esengine.js'), 'module.exports = () => Promise.resolve({});');
+ writeFileSync(path.join(wxDir, 'esengine.wasm'), 'wasmbytes');
+ writeFileSync(path.join(wxDir, 'basis.js'), 'module.exports = () => {};');
+ writeFileSync(path.join(wxDir, 'basis.wasm'), 'wasmbytes');
+
+ const outKtx = path.join(root, 'dist-wechat-ktx2');
const res = await exportGame({
root,
- entryScene: 'scenes/main.esscene',
+ entryScene: 'scenes/ktx2.esscene',
gameHostEntry: 'unused-for-wechat',
scriptsEntry: 'src/main.ts',
sdkDistDir: path.join(root, '_sdk'),
- wasmDir: path.join(root, '_wxwasm'),
- outDir: outCt,
+ wasmDir: wxDir,
+ outDir: outKtx,
platform: 'wechat',
- compressTextures: true,
});
expect(res.ok).toBe(true);
- expect(res.warnings.some((w) => w.includes('Basis'))).toBe(true);
- const manifest = JSON.parse(readFileSync(path.join(outCt, 'asset-manifest.json'), 'utf8'));
- expect(manifest.groups.main.assets[TEX].path).toMatch(/\.png$/); // not .ktx2
+ expect(readFileSync(path.join(outKtx, 'game.js'), 'utf8')).toContain("\"basis\": asFactory(require('./wasm/basis.js'))");
+ expect(existsSync(path.join(outKtx, 'wasm', 'basis.wasm'))).toBe(true);
+ }, 60_000);
+
+ it('a .ktx2 texture without a wechat basis build fails the export', async () => {
+ const outNoBasis = path.join(root, 'dist-wechat-ktx2-missing');
+ const res = await exportGame({
+ root,
+ entryScene: 'scenes/ktx2.esscene',
+ gameHostEntry: 'unused-for-wechat',
+ scriptsEntry: 'src/main.ts',
+ sdkDistDir: path.join(root, '_sdk'),
+ wasmDir: path.join(root, '_wxwasm'), // engine only — no basis
+ outDir: outNoBasis,
+ platform: 'wechat',
+ });
+ expect(res.ok).toBe(false);
+ expect(res.errors.some((e) => e.includes('basis-wechat'))).toBe(true);
}, 60_000);
it('content-addressed export carries the logical path as the asset address', async () => {
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 2bf973fa0..7c1a9a189 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -11,8 +11,14 @@ const treeshake = {
const esmBuilds = [
{
+ // ONE code-split graph for every ESM entry a bundler can combine:
+ // `esengine` (web or wechat) and the `esengine/*` subpaths must resolve
+ // into the SAME shared chunks, or a game bundle that imports both gets
+ // two copies of the core — and identity-keyed resources (Res(Spine))
+ // split-brain: the runtime inserts into one copy, systems read the other.
input: {
'index': 'src/index.ts',
+ 'index.wechat': 'src/index.wechat.ts',
'physics/index': 'src/physics/index.ts',
'spine/index': 'src/spine/index.ts',
'wasm': 'src/wasm.ts',
@@ -35,12 +41,6 @@ const esmBuilds = [
plugins: [typescript({ tsconfig: './tsconfig.json', declaration: false }), terser({ format: { comments: (_, comment) => comment.value.includes('@vite-ignore') } })],
treeshake,
},
- {
- input: 'src/index.wechat.ts',
- output: { file: 'dist/index.wechat.js', format: 'esm', sourcemap: true },
- plugins: [typescript({ tsconfig: './tsconfig.json', declaration: false }), terser({ format: { comments: (_, comment) => comment.value.includes('@vite-ignore') } })],
- treeshake,
- },
{
input: 'src/index.wechat.ts',
output: { file: 'dist/index.wechat.cjs.js', format: 'cjs', sourcemap: true },
@@ -61,6 +61,7 @@ const dtsBuilds = [
input: {
'index': 'src/index.ts',
'index.node': 'src/index.node.ts',
+ 'index.wechat': 'src/index.wechat.ts',
'physics/index': 'src/physics/index.ts',
'spine/index': 'src/spine/index.ts',
'wasm': 'src/wasm.ts',