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
feat(assets): wechat + playable exports join the sourcePath resolution - three lines, one semantic
yhh9cc952dcb811
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.tsindex 336f80769..a51776db5 100644--- a/desktop/electron/exportGame.ts+++ b/desktop/electron/exportGame.ts@@ -244,6 +244,8 @@ export async function exportGame(opts: {appid: opts.wechatAppid,orientation: opts.wechatOrientation,minify: opts.minify,+ contentAddressed: opts.contentAddressed,+ compressTextures: opts.compressTextures,onProgress: opts.onProgress,});}diff --git a/desktop/electron/exportPlayable.ts b/desktop/electron/exportPlayable.tsindex 319d8110c..55ee4fb75 100644--- a/desktop/electron/exportPlayable.ts+++ b/desktop/electron/exportPlayable.ts@@ -38,7 +38,7 @@ export interface ExportPlayableResult {}interface CookManifest {- entries: { uuid: string; path: string; type: string }[];+ entries: { uuid: string; path: string; sourcePath?: string; type: string }[];}const MIME: Record<string, string> = {@@ -152,16 +152,23 @@ export async function exportPlayable(opts: {const cook = await cookAssets(opts.root, { entryScenes: [opts.entryScene], outDir: cookDir });warnings.push(...cook.warnings);- // 2. Assets → base64 data URLs, keyed by the scene's @uuid: refs.+ // 2. Assets → base64 data URLs, keyed by the scene's @uuid: refs; plus a+ // compact logical-path → key map so PATH-style refs (a scene's material+ // path, a material's rewritten logical refs) resolve to the same inlined+ // data — the runtime aliases them in memory, so the payload carries each+ // data URL exactly once.progress({ phase: 'Encoding assets' });const assets: Record<string, string> = {};+ const pathMap: Record<string, string> = {};let manifestEntries: CookManifest['entries'] = [];try {const manifest = JSON.parse(await readFile(path.join(cookDir, 'assets.manifest.json'), 'utf8')) as CookManifest;manifestEntries = manifest.entries;for (const e of manifest.entries) {const buf = await readFile(path.join(cookDir, e.path));- assets[`@uuid:${e.uuid}`] = `data:${mimeOf(e.path)};base64,${buf.toString('base64')}`;+ const key = `@uuid:${e.uuid}`;+ assets[key] = `data:${mimeOf(e.path)};base64,${buf.toString('base64')}`;+ pathMap[e.sourcePath ?? e.path] = key;}} catch (err) {errors.push(`assets: ${err instanceof Error ? err.message : String(err)}`);@@ -235,6 +242,7 @@ export async function exportPlayable(opts: {`window.__ENGINE_WASM__=${JSON.stringify(wasmB64)};` +`window.__SIDE_MODULES__=${JSON.stringify(sideModules)};` +`window.__GAME_ASSETS__=${JSON.stringify(assets)};` ++ `window.__GAME_PATHMAP__=${JSON.stringify(pathMap)};` +`window.__GAME_SCENES__=${JSON.stringify(scenes)};` +`window.__GAME_FIRST__=${JSON.stringify(sceneName)};`;const outFile = path.join(absOut, 'index.html');diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.tsindex 617b8964a..11b8845ca 100644--- a/desktop/electron/exportWeChat.ts+++ b/desktop/electron/exportWeChat.ts@@ -43,7 +43,7 @@ export interface ExportWeChatResult {}interface CookManifest {- entries: { uuid: string; path: string; type: string; contentHash?: string; size?: number; group?: string }[];+ entries: { uuid: string; path: string; sourcePath?: string; type: string; contentHash?: string; size?: number; group?: string }[];}// Editor asset type → AddressableAssetType (sdk/src/assetTypes.ts). The WeChat@@ -155,7 +155,7 @@ async function scanWeChatSideModules(* falls back to stat() for size only if a legacy cook omitted it. */async function buildAddressableManifest(absOut: string): Promise<string> {const cook = JSON.parse(await readFile(path.join(absOut, 'assets.manifest.json'), 'utf8')) as CookManifest;- type Entry = { path: string; type: string; size: number; labels: string[]; contentHash?: string };+ type Entry = { path: string; address?: string; type: string; size: number; labels: string[]; contentHash?: string };type Group = { bundleMode: string; labels: string[]; assets: Record<string, Entry> };// One group per cook group: 'main' is local (eager); every other is a lazy// subpackage. bundleMode here is the typed wire value the SDK's normalizeBundleMode@@ -170,6 +170,11 @@ async function buildAddressableManifest(absOut: string): Promise<string> {});const entry: Entry = { path: e.path, type: addrType(e.type), size, labels: [] };if (e.contentHash) entry.contentHash = e.contentHash;+ // The logical source path rides as the asset's address: path-style refs+ // resolve through it (ManifestModel indexes addresses; the runtime builds+ // its logical→staged catalog from them). Only meaningful when staging+ // renamed the file (content addressing / texture encoding).+ if (e.sourcePath && e.sourcePath !== e.path) entry.address = e.sourcePath;group.assets[e.uuid.toLowerCase()] = entry;}// Always emit a main group so the runtime's main package exists even if everydiff --git a/desktop/src/playableHost.ts b/desktop/src/playableHost.tsindex 24c05d89f..bb57e1eb2 100644--- a/desktop/src/playableHost.ts+++ b/desktop/src/playableHost.ts@@ -22,6 +22,7 @@ declare const __ENGINE_GLUE__: string;declare const __ENGINE_WASM__: string;declare const __SIDE_MODULES__: EmbeddedSideModuleRegistry;declare const __GAME_ASSETS__: Record<string, string>;+declare const __GAME_PATHMAP__: Record<string, string>;declare const __GAME_SCENES__: Array<{ name: string; data: SceneData }>;declare const __GAME_FIRST__: string;@@ -83,6 +84,8 @@ async function boot(): Promise<void> {module,canvas,assets: __GAME_ASSETS__,+ // Older exports predate the path map; the runtime treats it as optional.+ assetPathMap: typeof __GAME_PATHMAP__ !== 'undefined' ? __GAME_PATHMAP__ : undefined,scenes: __GAME_SCENES__,firstScene: __GAME_FIRST__,});diff --git a/desktop/tests/export-playable.test.ts b/desktop/tests/export-playable.test.tsindex 9b52f07c6..7eabb5f10 100644--- a/desktop/tests/export-playable.test.ts+++ b/desktop/tests/export-playable.test.ts@@ -84,6 +84,10 @@ describe('exportGame (playable)', () => {expect(html).toContain('SpawnMarker'); // project script bundledexpect(html).toContain(`@uuid:${TEX}`); // asset keyed by refexpect(html).toContain('data:image/png;base64,'); // asset inlined as data URL+ // Logical path → embedded key map (path refs alias in memory at runtime;+ // the data URL itself ships once, under the uuid key).+ expect(html).toContain('__GAME_PATHMAP__');+ expect(html).toMatch(new RegExp(`"assets/hero\\.png":"@uuid:${TEX}"`));expect(html).toContain('__GAME_FIRST__');expect(html).toContain('"main"'); // first scene nameexpect(html).toContain('__GAME_SCENES__');diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.tsindex 26783d717..c5be0dfe5 100644--- a/desktop/tests/export-wechat.test.ts+++ b/desktop/tests/export-wechat.test.ts@@ -108,4 +108,30 @@ describe('exportGame (wechat)', () => {expect(gjson.subPackages).toContainEqual({ name: 'level2', root: 'subpackages/level2' });expect(existsSync(path.join(out, 'subpackages', 'level2', 'extra.png'))).toBe(true);}, 60_000);++ it('content-addressed export carries the logical path as the asset address', async () => {+ const outCa = path.join(root, 'dist-wechat-ca');+ const res = await exportGame({+ root,+ entryScene: 'scenes/main.esscene',+ gameHostEntry: 'unused-for-wechat',+ scriptsEntry: 'src/main.ts',+ sdkDistDir: path.join(root, '_sdk'),+ wasmDir: path.join(root, '_wxwasm'),+ outDir: outCa,+ title: 'My Game',+ platform: 'wechat',+ contentAddressed: true,+ });+ expect(res.ok).toBe(true);++ const manifest = JSON.parse(readFileSync(path.join(outCa, 'asset-manifest.json'), 'utf8'));+ const tex = manifest.groups.main.assets[TEX];+ // Physical file renamed; the logical identity rides as the address —+ // the runtime's ManifestModel + catalog resolve path refs through it.+ expect(tex.path).toMatch(/^assets\/[0-9a-f]{16}\.png$/);+ expect(tex.address).toBe('assets/hero.png');+ // Scenes keep their logical path and carry no address.+ expect(manifest.groups.main.assets[SCN].address).toBeUndefined();+ }, 60_000);});diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.mdindex d07d01db4..80d7ecb6d 100644--- a/docs/REARCHITECTURE.md+++ b/docs/REARCHITECTURE.md@@ -196,7 +196,8 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:**音频并入单一解析通道(2026-07-08)**:Audio 的自有 fetch 曾绕过 resolveRef(`baseUrl` 前缀并行逻辑,CA 构建下 `playSFX('assets/…')` 404)——新增 `Audio.setRefResolver`,play realm 统一接 `resolvePlayAssetRef`(编辑器 realm 输出与旧 baseUrl 前缀逐字符一致零行为变化;cooked 构建命中 logical→staged 映射;uuid 音频引用顺带可用)。`baseUrl` 保留为未接线宿主的 legacy 前缀。**naga vendored(2026-07-08)**:SPIR-V→WGSL 侧零外部依赖——`tools/naga-spv2wgsl`(30 行 stdin→stdout WASI 封装 crate,Cargo.lock 钉版)编 wasm32-wasip1 产物入库 `build-tools/shader-twins/naga-spv2wgsl.wasm`(674KB,basis 先例同款 gitignore 白名单),`naga.mjs` 经 node:wasi 进程内运行;gen-shader-twins 改走 vendored 路径,**全部 fixture 重生成零 diff**(与 naga-cli 30 逐字节一致)。**glslang vendored(2026-07-08,用户批准 submodule)**:GLSL→SPIR-V 侧也零外部依赖——`third_party/glslang` submodule(钉 16.3.0)+ `tools/glslang-wasm/wrapper.cpp`(薄 C ABI,精确镜像 `glslangValidator -V --auto-map-locations`:Vulkan 1.0 语义、auto-map locations、无优化器)经 emscripten 构建入库 `build-tools/shader-twins/glslang-compile.{mjs,wasm}`(1.8MB)。**gen-shader-twins 自此零 PATH 依赖**(只需 build:web 产物);全 fixtures 经全 vendored 管线重生成**零 diff**(与本机 glslangValidator 16.0.0 + naga-cli 30 逐字节一致——跨 glslang 小版本仍稳定)。CI 新增两守卫(verify-render job):孪生覆盖检查(--check 全 fixtures)+ **管线冒烟**(剥孪生临时副本走完整 GLSL→SPIR-V→WGSL,每次 CI 真跑两个 wasm 转换器)。坑:工具改 `process.exitCode` 优雅退出——硬 process.exit 与存活的 emscripten 运行时在 Windows 上有拆除竞态(STATUS_STACK_BUFFER_OVERRUN)。-**剩余**:wechat/playable 导出线采用 CA 时复用 sourcePath 机制;CI 无 WebGPU 适配器(webgpu verify 仅本地)。+**wechat/playable 并入 sourcePath 解析(2026-07-08,三线归一收官)**:wechat——AddressableManifest 的 `address` 字段承载逻辑源路径(ManifestModel 索引 address 双拼写入 byKey → resolvePath 直接命中;initWeChatRuntime 从 address 构建 Catalog buildPath 喂 initRuntime,与 web 宿主同款双映射),exportWeChat 在 staging 改名时发射 address,exportGame 顺带补上 wechat 分支漏转发 contentAddressed/compressTextures 的穿线缺口。playable——导出器发射紧凑 `__GAME_PATHMAP__`(逻辑路径→`@uuid:` 键),运行时**内存内别名**到内嵌 assets 映射(别名共享 data-URL 字符串,载荷零重复;fetch/图像解码/音频三通道读同一张表)。三条导出线自此共用同一套"逻辑身份 → staged 物理"解析语义。+**剩余**:CI 无 WebGPU 适配器(webgpu verify 仅本地)。见 `REARCH_WGSL.md`(本地 gitignore,同 RC6/2D_PARITY 约定):着色器版图盘点(uniform 数据已全后端中立,剩程序文本)、岔路拍板(有限集人工孪生 / 图材质 AST 双发射 / 用户材质 cook 期转换——拒绝运行时翻译器的 MB 级体积代价)、四期计划(源语言接缝 → WebGPUDevice 原型 → 双语发射 → cook 期用户材质)。**Phase 0 已落地**:最后 3 个 GLSL ES 1.00 残留(SDK outline/drop-shadow/color-matrix 滤镜)重写为 fragment-only `.esshader` 反射路径——顺带修复其设计性破损(raw 形态无 `u_projection` 来源、无属性绑定、mat4 超 `setMaterialUniform` 的 vec4 上限**从未能传入**;色彩矩阵改为 4×vec4 行 + 偏移列,新增 `Filters.colorMatrixUniforms` 助手)。全仓每个程序自此都在现代缝上(300 es + UBO 反射)。**Phase 1(源语言接缝)已落地**:RHI 补上最后一块后端中立拼图——`createProgram` 收语言标签的 `GfxShaderSource`,新增 `supportsShaderLanguage` 能力查询(GL = 仅 GLSL ES 300;`Shader::compile` 在任何 GPU 调用前对不支持的语言快速失败);语言贯穿 Shader/ResourceManager(DrawParams 重写仅对 GLSL 生效);`ShaderParser::assembleStage` 获得 `ShaderTargetLanguage` 参数(WGSL 发射 = Phase 3)。MockGfxDevice 新增 `wgslSupported` 开关 + 语言门用例;行为零变化(8 harness + 场景抽样等价)。**Phase 2 切片 1(WebGPU 后端启动)已落地**:emdawnwebgpu 端口(Dawn)集成为测试目标独立依赖(主构建零影响);`renderer/webgpu/` 新增纯映射层(GfxEnums→WGPU 全翻译,blend/模板表镜像 GLDevice 语义,load-op 规则与 RenderPassDesc 契约一致)+ 空设备安全的 `WebGPUDevice` 骨架(缓冲/纹理/WGSL 模块真实现,布局/管线描述符保留待惰性构建,pass/draw 为切片 2 结构化桩);`test_webgpu_device` 用真 Dawn 头编译验证全部描述符拼写,入 CI。diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex e04902d82..27a483647 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -156,6 +156,15 @@ export class ManifestModel {// (a uuid/path appearing in two groups keeps its first entry).if (!byKey.has(key)) byKey.set(key, asset);if (!byPath.has(asset.path)) byPath.set(asset.path, asset);+ // The address (the asset's LOGICAL source path, kept when+ // content-addressed staging renames the physical file) is a+ // resolvable key too — path-style refs name it. Both the+ // bare and the "/"-rooted spellings the cook may emit.+ if (asset.address) {+ if (!byKey.has(asset.address)) byKey.set(asset.address, asset);+ const rooted = `/${asset.address}`;+ if (!byKey.has(rooted)) byKey.set(rooted, asset);+ }}}this.keyIndex_ = byKey;diff --git a/sdk/src/playableRuntime.ts b/sdk/src/playableRuntime.tsindex 899020158..5a0ab032c 100644--- a/sdk/src/playableRuntime.ts+++ b/sdk/src/playableRuntime.ts@@ -25,6 +25,14 @@ export interface PlayableRuntimeConfig {module: ESEngineModule;canvas: HTMLCanvasElement;assets: Record<string, string>;+ /**+ * Logical (source) path → embedded-asset key (`@uuid:<id>`), so path-style+ * refs (a scene's "assets/x.esmaterial", a material's rewritten logical+ * refs) resolve to the inlined data. Applied as in-memory ALIASES onto the+ * assets map — every channel (fetch, image decode, audio) reads that one+ * map, and aliases share the data-URL strings (no payload duplication).+ */+ assetPathMap?: Record<string, string>;scenes: Array<{ name: string; data: SceneData }>;firstScene: string;physicsConfig?: { gravity?: Vec2; fixedTimestep?: number; subStepCount?: number };@@ -58,7 +66,18 @@ function loadImagePixels(dataUrl: string): Promise<{ width: number; height: numb}export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promise<void> {- const { app, module, assets, scenes, firstScene } = config;+ const { app, module, scenes, firstScene } = config;++ // Alias logical paths onto the embedded map (both spellings the cook may+ // emit) — the aliases point at the SAME data-URL strings, so path refs cost+ // nothing and every consumer below resolves through one map.+ const assets = { ...config.assets };+ for (const [logical, key] of Object.entries(config.assetPathMap ?? {})) {+ const data = assets[key];+ if (!data) continue;+ assets[logical] ??= data;+ assets[`/${logical}`] ??= data;+ }// Canonical asset source: the shared EmbeddedBackend (data-URLs) + a DOM image// decode over the same data-URL. Refs are the map keys (resolveRef = identity).diff --git a/sdk/src/wechatRuntime.ts b/sdk/src/wechatRuntime.tsindex dc8dbbc37..cd5749efd 100644--- a/sdk/src/wechatRuntime.ts+++ b/sdk/src/wechatRuntime.ts@@ -16,6 +16,7 @@ import { applyBuildRuntimeConfig, type RuntimeBuildConfig } from './defaults';import { platformReadTextFile, platformInstantiateWasm, platformLoadImagePixels } from './platform';import { toBuildPath } from './assetTypes';import { ManifestModel, type AddressableManifest } from './asset/AddressableManifest';+import { Catalog, type CatalogEntry } from './asset/Catalog';import { createWeChatSideModuleHost, type WeChatSideModuleFactories } from './sideModules';import type { Vec2 } from './types';import type { SceneData } from './scene';@@ -80,6 +81,20 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<voconst manifestModel = ManifestModel.fromJson(manifest);const resolvePath = (ref: string): string => manifestModel.resolvePath(ref, toBuildPath);+ // Content-addressed packs: assets whose manifest entry carries an `address`+ // (the logical source path) get a catalog buildPath, so the loaders' inner+ // text refs (a material's shader) map logical → staged at their fetch+ // boundary — the same two-map contract the cooked web host wires.+ const catalogEntries: Record<string, CatalogEntry> = {};+ for (const asset of manifestModel.allAssets()) {+ if (!asset.address || asset.address === asset.path) continue;+ catalogEntries[asset.address] = { type: asset.type, buildPath: asset.path };+ catalogEntries[`/${asset.address}`] = { type: asset.type, buildPath: asset.path };+ }+ const catalog = Object.keys(catalogEntries).length > 0+ ? Catalog.fromJson({ version: 1, entries: catalogEntries })+ : undefined;+const canvas = wx.createCanvas();const info = wx.getSystemInfoSync();canvas.width = info.windowWidth * info.pixelRatio;@@ -140,6 +155,7 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<vomodule,source,manifest: manifestModel,+ catalog,scenes,firstScene: config.firstScene,physicsConfig: config.physicsConfig,diff --git a/sdk/tests/manifest-model.test.ts b/sdk/tests/manifest-model.test.tsindex 8e2cf446e..d0d452e22 100644--- a/sdk/tests/manifest-model.test.ts+++ b/sdk/tests/manifest-model.test.ts@@ -151,4 +151,26 @@ describe('ManifestModel resolution', () => {expect(model().resolvePath('nope', (s) => `${s}.x`)).toBe('nope.x');expect(model().resolvePath('nope')).toBe('nope');});++ // The address is the asset's LOGICAL source path, kept when content-addressed+ // staging renames the physical file — path-style refs resolve through it,+ // in both the bare and the "/"-rooted spellings the cook may emit.+ it('resolvePath: address hit (logical source path → staged path)', () => {+ const m = ManifestModel.fromJson({+ version: '2.0',+ groups: {+ main: {+ bundleMode: 'local', labels: [], assets: {+ 'uuid-9': {+ path: 'assets/1234abcd.ktx2', address: 'assets/hero.png',+ type: 'texture', size: 1, labels: [],+ },+ },+ },+ },+ });+ expect(m.resolvePath('assets/hero.png')).toBe('assets/1234abcd.ktx2');+ expect(m.resolvePath('/assets/hero.png')).toBe('assets/1234abcd.ktx2');+ expect(m.resolvePath('uuid-9')).toBe('assets/1234abcd.ktx2');+ });});diff --git a/sdk/tests/playableRuntime.test.ts b/sdk/tests/playableRuntime.test.tsindex 25da854da..1568438f7 100644--- a/sdk/tests/playableRuntime.test.ts+++ b/sdk/tests/playableRuntime.test.ts@@ -79,4 +79,23 @@ describe('initPlayableRuntime', () => {expect(config.app.run).toHaveBeenCalled();});++ // Path-style refs resolve via in-memory aliases onto the embedded map: the+ // alias keys share the data-URL strings (no duplication), and every channel+ // (fetch backend, image decode, audio) reads the same map.+ it('aliases assetPathMap logical paths onto the embedded assets', async () => {+ const config = createMockConfig({+ assets: { '@uuid:aaaa': 'data:text/plain;base64,QQ==' },+ assetPathMap: { 'assets/m.esmaterial': '@uuid:aaaa', 'assets/missing.png': '@uuid:zzzz' },+ });++ await initPlayableRuntime(config);++ const call = vi.mocked(initRuntime).mock.calls[0][0];+ const backend = call.source.backend as { resolveUrl(p: string): string };+ expect(backend.resolveUrl('assets/m.esmaterial')).toBe('data:text/plain;base64,QQ==');+ expect(backend.resolveUrl('/assets/m.esmaterial')).toBe('data:text/plain;base64,QQ==');+ // The original key still resolves; unknown targets alias nothing.+ expect(backend.resolveUrl('@uuid:aaaa')).toBe('data:text/plain;base64,QQ==');+ });});