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(audio): audio joins the single asset-resolution channel

yhhd06febce5bb7
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index 9030b44a4..65fbe8a7b 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -193,7 +193,8 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:
**Phase 4 转换管线(2026-07-08)**:用户 `.esshader` 的 GLSL→WGSL 自动孪生落地——`tools/gen-shader-twins.mjs`:引擎 wasm 新绑定 `esshader_cookInfo`(web glue 可在纯 Node 加载)吐出与运行时逐字节一致的装配后 GLSL + 纹理单元反射(零漂移),经方言适配(310 es、precision 全 highp、显式引擎绑定注入、combined sampler 拆对、函数采样器参数/实参拆分、varying location 按名对齐)→ `glslangValidator -V` → `naga` → 自包含 `#pragma vertex|fragment wgsl full` 孪生段(ShaderParser 新语义:full 段跳过全部注入头)。9 个 fixture shader 批量生成后,mat-lit 系/mat-tex/mat-dissolve/mat-graph/mat-builtin-lit/mat-instance **在 WebGPU 全部从全黑转绿,lit 像素与 GL 逐点一致**(15 场景 battery)。带 `#pragma switch` 的 shader 跳过(排列需逐集合,手写孪生)。
**cook 集成第一层(2026-07-08)——资产依赖图现代化**:assetDb 依赖图从"仅 scene/prefab 的 @uuid:"扩展为**任意 JSON 资产 × 三种引用形态**——`@uuid:`、裸 uuid(anim 帧的 extractUuid 形态,仅命中索引才建边,防实体 id 误伤)、**路径引用**(项目路径 + 相对本文档目录,只有真实资产命中才建边零误报);扫描类型 scene/prefab/material/tileset/animclip/statemachine/behaviortree。真实项目(路径引用内容)的材质→shader→纹理链自此进入 cook 闭包(此前 deps 全空,整链被静默剔除)。cook manifest 新增 `sourcePath`(逻辑身份,内容寻址改名后路径引用的运行时映射依据);`.esshader` 无 WGSL 孪生 → cook 告警(生成是开发期步骤,保 cook 确定性 + 零转换器依赖)。
**cook 集成第二层(2026-07-08)——CA 构建运行时路径解析闭环**:三件套——① cook 期把材质的**相对引用重写为逻辑项目路径**(内容寻址摧毁了相对解析依赖的目录结构;非 assets/-根的逻辑路径写成 `/<logical>`,双拼写皆注册;@uuid:/URL/非资产字符串原样通过),顺带根治"@uuid: 引用的材质在 CA 构建下内部相对引用同样破损"的存量缺口——loader 零改动;② `resolvePlayAssetRef` 增 pathMap 参数(逻辑→staged,**先于扩展名嗅探**,.png→.ktx2 换名对 KTX2 检测可见,与 uuid 分支同契约);③ 生产首次喂 `Catalog` buildPath(`AssetsOptions.catalog` 一直存在但空转——loader 内部文本 fetch 如材质取 shader 走 `getBuildPath`),经 `RuntimeInitConfig.catalog`/`PlayRealmRuntimeConfig.catalogData` 管道在 per-App Assets 首次创建时注入,gameHost 从 manifest sourcePath 构建两张映射。验证:cooked e2e 升级为双象限——绿 KTX2 精灵(uuid 引用)+ **红材质精灵(全路径引用链:场景→材质项目路径→shader/纹理相对引用)**,发行运行时逐像素 PASS([0,181,0]/[255,0,0])。
-**剩余**:转换器 vendored wasm 交付(glslang wasm + naga wasm32-wasi,仿 build-tools/basis);音频路径引用在 CA 构建下仍走 assetBaseUrl 裸 fetch(Audio 有独立 loader,未过 resolveRef——已知缺口);wechat/playable 导出线采用 CA 时复用同一 sourcePath 机制;CI 无 WebGPU 适配器(webgpu verify 仅本地)。
+**音频并入单一解析通道(2026-07-08)**:Audio 的自有 fetch 曾绕过 resolveRef(`baseUrl` 前缀并行逻辑,CA 构建下 `playSFX('assets/…')` 404)——新增 `Audio.setRefResolver`,play realm 统一接 `resolvePlayAssetRef`(编辑器 realm 输出与旧 baseUrl 前缀逐字符一致零行为变化;cooked 构建命中 logical→staged 映射;uuid 音频引用顺带可用)。`baseUrl` 保留为未接线宿主的 legacy 前缀。
+**剩余**:转换器 vendored wasm 交付(glslang wasm + naga wasm32-wasi,仿 build-tools/basis);wechat/playable 导出线采用 CA 时复用同一 sourcePath 机制;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/audio/Audio.ts b/sdk/src/audio/Audio.ts
index 67f481b9b..a5ec109d9 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -51,6 +51,7 @@ export class AudioAPI {
private readonly fadeAnimIds_ = new Set<number>();
private disposed_ = false;
private assetResolver_: ((url: string) => ArrayBuffer | null) | null = null;
+ private refResolver_: ((ref: string) => string) | null = null;
baseUrl = '';
constructor(backend: PlatformAudioBackend, mixer: AudioMixer | null = null) {
@@ -196,7 +197,19 @@ export class AudioAPI {
this.assetResolver_ = resolver;
}
+ /**
+ * Route play refs through the realm's single asset resolver — the same
+ * channel every other asset type resolves through (uuid manifest, cooked
+ * logical→staged maps, project base). Takes precedence over the legacy
+ * `baseUrl` prefix, so `playSFX('assets/…')` works in cooked builds whose
+ * content-addressed staging renamed the physical files.
+ */
+ setRefResolver(resolver: ((ref: string) => string) | null): void {
+ this.refResolver_ = resolver;
+ }
+
private resolveUrl_(url: string): string {
+ if (this.refResolver_) return this.refResolver_(url);
if (!this.baseUrl || url.startsWith('/') || url.startsWith('http://') || url.startsWith('https://')) {
return url;
}
diff --git a/sdk/src/playRealmRuntime.ts b/sdk/src/playRealmRuntime.ts
index 8eb6aff65..dbb1b55ea 100644
--- a/sdk/src/playRealmRuntime.ts
+++ b/sdk/src/playRealmRuntime.ts
@@ -139,10 +139,14 @@ function createPlayRealmSource(
export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): Promise<void> {
const { app, module, canvas, sceneData, assetManifest, assetBaseUrl } = config;
const source = createPlayRealmSource(assetManifest, assetBaseUrl, config.assetPathMap);
- // Audio has its own loader (not the asset source), so point it at the project
- // root too: playSFX/playBGM take project-relative paths, not uuid refs.
- if (assetBaseUrl && app.hasResource(Audio)) {
- app.getResource(Audio).baseUrl = assetBaseUrl;
+ // Audio fetches its own buffers (playSFX/playBGM take plain paths, not uuid
+ // refs) — route them through the SAME resolver as every other asset: the
+ // editor realm prefixes the project root, cooked builds hit their
+ // logical→staged map. One resolution channel, no parallel baseUrl logic.
+ if (app.hasResource(Audio)) {
+ app.getResource(Audio).setRefResolver(
+ (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap),
+ );
}
await initRuntime({
app,
diff --git a/sdk/tests/audio-api.test.ts b/sdk/tests/audio-api.test.ts
index c0b59999b..99b39b957 100644
--- a/sdk/tests/audio-api.test.ts
+++ b/sdk/tests/audio-api.test.ts
@@ -91,6 +91,22 @@ describe('AudioAPI', () => {
await audio.preload('sfx.mp3');
expect(backend.loadBuffer).toHaveBeenCalledTimes(1);
});
+
+ it('prefixes relative urls with baseUrl (legacy prefix path)', async () => {
+ audio.baseUrl = 'estella://project';
+ await audio.preload('assets/sfx.mp3');
+ expect(backend.loadBuffer).toHaveBeenCalledWith('estella://project/assets/sfx.mp3');
+ });
+
+ // The realm's single asset resolver (uuid manifest / cooked
+ // logical→staged maps) takes precedence over the baseUrl prefix, so
+ // playSFX('assets/…') fetches the staged file in cooked builds.
+ it('routes refs through setRefResolver when wired (cooked builds)', async () => {
+ audio.baseUrl = 'estella://project';
+ audio.setRefResolver((ref) => `./assets/abcd1234.${ref.split('.').pop()}`);
+ await audio.preload('assets/sfx.mp3');
+ expect(backend.loadBuffer).toHaveBeenCalledWith('./assets/abcd1234.mp3');
+ });
});
describe('preloadAll', () => {