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(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.jsindex 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.jsindex 10a8316f6..db775be49 100644--- a/build-tools/cli.js+++ b/build-tools/cli.js@@ -26,7 +26,7 @@ programprogram.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.tsindex 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 thediff --git a/desktop/electron/sideModuleScan.ts b/desktop/electron/sideModuleScan.tsindex 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.tsindex 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.jsindex 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',