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.

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.ts
index 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.ts
index 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.ts
index 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 every
diff --git a/desktop/src/playableHost.ts b/desktop/src/playableHost.ts
index 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.ts
index 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 bundled
expect(html).toContain(`@uuid:${TEX}`); // asset keyed by ref
expect(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 name
expect(html).toContain('__GAME_SCENES__');
diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.ts
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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<vo
const 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<vo
module,
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.ts
index 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.ts
index 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==');
+ });
});