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(audio): fades ride the frame loop, and a bus works without a mixer graph
esengine79e72bf5872c
diff --git a/desktop/src/i18n/messages/content.ts b/desktop/src/i18n/messages/content.tsindex a546cec23..c4d116740 100644--- a/desktop/src/i18n/messages/content.ts+++ b/desktop/src/i18n/messages/content.ts@@ -78,6 +78,7 @@ export const contentMessages = defineMessages({'cb.deliveryLocal': { en: 'Local (in package)', zh: '本地(打进包)' },'cb.deliverySubpackage': { en: 'Subpackage (on-demand)', zh: '分包(按需)' },'cb.deliveryRemote': { en: 'Remote (CDN / hot-update)', zh: '远端(CDN / 热更)' },+ 'cb.alwaysInclude': { en: 'Always include in builds', zh: '总是打进构建(即使无人引用)' },'cb.badgeSubpackage': { en: 'PKG', zh: '分包' },'cb.badgeRemote': { en: 'CDN', zh: 'CDN' },'cb.menuOpen': { en: 'Open', zh: '打开' },diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsxindex 60507dfde..e85ac072c 100644--- a/desktop/src/panels/ContentBrowser.tsx+++ b/desktop/src/panels/ContentBrowser.tsx@@ -1031,11 +1031,22 @@ export function ContentBrowser() {...(entry.isDir? [{label: t('cb.delivery'),- children: ASSET_GROUP_MODES.map((m) => ({- label: t(DELIVERY_MODE_META[m].labelKey),- checked: ProjectStore.folderDeliveryMode(path) === m,- onClick: () => void ProjectStore.setFolderDeliveryMode(path, m),- })),+ children: [+ ...ASSET_GROUP_MODES.map((m) => ({+ label: t(DELIVERY_MODE_META[m].labelKey),+ checked: ProjectStore.folderDeliveryMode(path) === m,+ onClick: () => void ProjectStore.setFolderDeliveryMode(path, m),+ })),+ { sep: true } as MenuItem,+ // A build cooks what it can REACH from the entry scenes; this is how+ // a folder says "ship me anyway" — for what only code names.+ {+ label: t('cb.alwaysInclude'),+ checked: ProjectStore.folderAlwaysInclude(path),+ onClick: () => void ProjectStore.setFolderAlwaysInclude(+ path, !ProjectStore.folderAlwaysInclude(path)),+ },+ ],}]: []),{ label: t('ui.rename'), onClick: () => startRename(path, !!ctx?.target?.inTree) },diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 08f23be4f..dd503bf1e 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { createStore } from 'zustand/vanilla';-import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, withActiveRemoteRoot } from 'esengine';+import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, folderAlwaysInclude, withFolderAlwaysInclude, withActiveRemoteRoot } from 'esengine';import { readTextureImportSettings } from './assetImporter';import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, StaleOverride, PrefabOverride, AddressableManifest, AssetGroupsConfig, AssetGroupMode } from 'esengine';import { EngineHost } from '@/engine/EngineHost';@@ -1742,6 +1742,12 @@ class ProjectStoreImpl {return folderGroupMode(this.assetGroupsConfig, folder);}+ /** Whether a folder is marked always-include (ships whether or not a scene+ * references it) — the Content Browser's menu check. */+ folderAlwaysInclude(folder: string): boolean {+ return folderAlwaysInclude(this.assetGroupsConfig, folder);+ }+/** The active build profile's CDN root ('' when unset) — the Build dialog field. */activeProfileRemoteRoot(): string {const cfg = this.assetGroupsConfig;@@ -1757,6 +1763,13 @@ class ProjectStoreImpl {await this.writeAssetGroups(withFolderGroup(this.assetGroupsConfig, folder, mode));}+ /** Mark a folder always-include, or clear it: a build cooks what it can reach+ * from the entry scenes, and this is how a project ships what only its CODE+ * names (a path built at run time, a texture in rich-text markup). */+ async setFolderAlwaysInclude(folder: string, on: boolean): Promise<void> {+ await this.writeAssetGroups(withFolderAlwaysInclude(this.assetGroupsConfig, folder, on));+ }+/** Set the active build profile's CDN root (empty → remote groups load same-origin). */async setActiveProfileRemoteRoot(remoteRoot: string): Promise<void> {await this.writeAssetGroups(withActiveRemoteRoot(this.assetGroupsConfig, remoteRoot));diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 8a3492d50..30e9f9e65 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1356 stable · 17 beta · 1 deprecated+Symbols: 1358 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -688,6 +688,7 @@ stopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => numberupdateDucking: () => void+updateFades: (dt: number) => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -8866,6 +8867,11 @@ EventBindingPluginFocusPlugin```+## folderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string): boolean+```+## folderGroupMode — function```(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode@@ -10411,6 +10417,11 @@ VideoPlugin(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig```+## withFolderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string, on: boolean): AssetGroupsConfig+```+## withFolderGroup — function```(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfigdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a8cd02212..024c04b6a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1375 stable · 22 beta · 1 deprecated+Symbols: 1377 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -688,6 +688,7 @@ stopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => numberupdateDucking: () => void+updateFades: (dt: number) => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -9069,6 +9070,11 @@ EventBindingPluginFocusPlugin```+## folderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string): boolean+```+## folderGroupMode — function```(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode@@ -10624,6 +10630,11 @@ VideoPlugin(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig```+## withFolderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string, on: boolean): AssetGroupsConfig+```+## withFolderGroup — function```(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfigdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 3cd714a95..19b5893a3 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1355 stable · 19 beta · 1 deprecated+Symbols: 1357 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -683,6 +683,7 @@ stopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => numberupdateDucking: () => void+updateFades: (dt: number) => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -8861,6 +8862,11 @@ EventBindingPluginFocusPlugin```+## folderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string): boolean+```+## folderGroupMode — function```(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode@@ -10416,6 +10422,11 @@ VideoPlugin(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig```+## withFolderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string, on: boolean): AssetGroupsConfig+```+## withFolderGroup — function```(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfigdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 8608f6a61..2ba0b2778 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1376 stable · 17 beta · 1 deprecated+Symbols: 1378 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -683,6 +683,7 @@ stopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => numberupdateDucking: () => void+updateFades: (dt: number) => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -9081,6 +9082,11 @@ EventBindingPluginFocusPlugin```+## folderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string): boolean+```+## folderGroupMode — function```(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode@@ -10636,6 +10642,11 @@ VideoPlugin(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig```+## withFolderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string, on: boolean): AssetGroupsConfig+```+## withFolderGroup — function```(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfigdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex dbe6b448d..945c52c4c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1366 stable · 17 beta · 1 deprecated+Symbols: 1368 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -683,6 +683,7 @@ stopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => numberupdateDucking: () => void+updateFades: (dt: number) => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -8885,6 +8886,11 @@ EventBindingPluginFocusPlugin```+## folderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string): boolean+```+## folderGroupMode — function```(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode@@ -10435,6 +10441,11 @@ VideoPlugin(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig```+## withFolderAlwaysInclude — function+```+(config: AssetGroupsConfig | null | undefined, folder: string, on: boolean): AssetGroupsConfig+```+## withFolderGroup — function```(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfigdiff --git a/sdk/src/asset/assetGroups.ts b/sdk/src/asset/assetGroups.tsindex 6814e70e6..b4434a89c 100644--- a/sdk/src/asset/assetGroups.ts+++ b/sdk/src/asset/assetGroups.ts@@ -144,32 +144,77 @@ export function folderGroupMode(config: AssetGroupsConfig | null | undefined, foreturn 'local';}-/**- * A copy of `config` with `folder` assigned delivery `mode` — the pure authoring- * mutation the editor writes to `.esengine/asset-groups.json`. `local` removes any- * group for the folder; otherwise the group name is the folder's last path segment- * (deduped against existing names).- */-export function withFolderGroup(+/** Whether `folder` has its own group marked {@link AssetGroupDef.alwaysInclude}+ * — the per-folder authoring state, for a menu check / badge. */+export function folderAlwaysInclude(config: AssetGroupsConfig | null | undefined,folder: string,- mode: AssetGroupMode,+): boolean {+ const norm = normFolder(folder);+ for (const def of Object.values(config?.groups ?? {})) {+ if (normFolder(def.folder) === norm) return def.alwaysInclude === true;+ }+ return false;+}++/** Write `folder`'s own group definition (or drop it when `def` is null), keeping+ * every other group. The name of a new group is the folder's last path segment,+ * deduped. Shared by the two authoring mutations below. */+function withFolderDef(+ config: AssetGroupsConfig | null | undefined,+ folder: string,+ def: AssetGroupDef | null,): AssetGroupsConfig {const norm = normFolder(folder);const groups: Record<string, AssetGroupDef> = { ...(config?.groups ?? {}) };- for (const [name, def] of Object.entries(groups)) {- if (normFolder(def.folder) === norm) delete groups[name];+ let existingName: string | null = null;+ for (const [name, g] of Object.entries(groups)) {+ if (normFolder(g.folder) === norm) { existingName = name; delete groups[name]; }}- if (norm !== '' && mode !== 'local') {- const base = norm.split('/').pop() || 'group';- let name = base;+ if (norm !== '' && def) {+ let name = existingName ?? (norm.split('/').pop() || 'group');let i = 2;- while (groups[name]) name = `${base}${i++}`;- groups[name] = { folder: norm, mode };+ while (groups[name]) name = `${norm.split('/').pop() || 'group'}${i++}`;+ groups[name] = def;}return { version: '1.0', ...config, groups };}+/**+ * A copy of `config` with `folder` assigned delivery `mode` — the pure authoring+ * mutation the editor writes to `.esengine/asset-groups.json`. `local` drops the+ * group, unless it is carrying an `alwaysInclude` that must outlive the mode+ * change (a folder can be ordinary local delivery AND always shipped).+ */+export function withFolderGroup(+ config: AssetGroupsConfig | null | undefined,+ folder: string,+ mode: AssetGroupMode,+): AssetGroupsConfig {+ const always = folderAlwaysInclude(config, folder);+ if (mode === 'local' && !always) return withFolderDef(config, folder, null);+ return withFolderDef(config, normFolder(folder), {+ folder: normFolder(folder), mode, ...(always ? { alwaysInclude: true } : {}),+ });+}++/**+ * A copy of `config` with `folder` marked (or unmarked) always-include: ship its+ * assets whether or not a scene references them. Clearing it on an otherwise+ * ordinary local folder drops the group entirely — a local group with nothing to+ * say is the same as no group.+ */+export function withFolderAlwaysInclude(+ config: AssetGroupsConfig | null | undefined,+ folder: string,+ on: boolean,+): AssetGroupsConfig {+ const norm = normFolder(folder);+ const mode = folderGroupMode(config, folder);+ if (!on && mode === 'local') return withFolderDef(config, norm, null);+ return withFolderDef(config, norm, { folder: norm, mode, ...(on ? { alwaysInclude: true } : {}) });+}+/** A copy of `config` with the active build profile's CDN root set (creating the* profile — default `dev` — and making it active). Pure. */export function withActiveRemoteRoot(diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.tsindex c44c6a6ee..b0f0c32bc 100644--- a/sdk/src/asset/index.ts+++ b/sdk/src/asset/index.ts@@ -18,6 +18,8 @@ export {modeToDelivery,folderGroupMode,withFolderGroup,+ folderAlwaysInclude,+ withFolderAlwaysInclude,withActiveRemoteRoot,ASSET_GROUP_MODES,type AssetGroupMode,diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex 0a44f9236..79d94880d 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -39,6 +39,26 @@ export interface AudioBufferStats {* Consumed as a resource: declare `Res(Audio)` as a system param or* grab it with `app.getResource(Audio)` outside ECS code.*/+/** A playing voice this API owns the volume of: base × bus gain × fade. */+interface SoftVoice {+ handle: AudioHandle;+ bus: string;+ base: number;+ fade: number;+}++/** One volume ramp in flight: a linear interpolation the frame loop advances. */+interface Fade {+ voice: SoftVoice;+ /** Fade FACTORS (0..1), multiplied onto the voice's base volume. */+ from: number;+ to: number;+ duration: number;+ elapsed: number;+ /** A fade-out stops its track when it reaches silence. */+ stopAtEnd: boolean;+}+export class AudioAPI {private readonly backend_: PlatformAudioBackend;private readonly mixer_: AudioMixer | null;@@ -50,7 +70,21 @@ export class AudioAPI {private bufferBudgetOverride_: number | null = null;private bgmHandle_: AudioHandle | null = null;private bgmVolume_ = 1.0;- private readonly fadeAnimIds_ = new Set<number>();+ /** Volume ramps in flight, advanced by {@link updateFades} from the frame+ * loop — NOT by requestAnimationFrame, which is a browser global a device+ * does not have (and which would keep ramping while the game is paused). */+ private readonly fades_: Fade[] = [];++ /**+ * Bus volume / mute for a backend with no mixer GRAPH (a device, WeChat):+ * the mixer's gain nodes are one way to apply a bus, not the meaning of one,+ * so where there are no nodes the gain is folded into each voice instead —+ * at play, and again on every voice already playing when a bus changes. The+ * mixer stays authoritative wherever it exists.+ */+ private readonly softBuses_ = new Map<string, { volume: number; muted: boolean }>();+ /** Voices whose volume this API computes: base × bus gain × fade. */+ private softVoices_: SoftVoice[] = [];// Handles mid fade-out. A cancelled fade RAF never reaches its handle.stop(),// so a rapid crossfade would orphan the outgoing track (playing forever) —// {@link cancelFades_} stops these when it tears the animations down.@@ -280,7 +314,7 @@ export class AudioAPI {const buffer = this.lookupBuffer_(url);if (!buffer) return null;if (config.bus) this.ensureBus(config.bus);- return this.backend_.play(buffer, config);+ return this.playVoice_(buffer, config);}playSFX(url: string, config?: {@@ -303,14 +337,14 @@ export class AudioAPI {if (this.disposed_) return;const buf = this.lookupBuffer_(url);if (buf) {- pending.resolve(this.backend_.play(buf, playConfig));+ pending.resolve(this.playVoice_(buf, playConfig));}}).catch(err => {log.warn('audio', `Failed to preload audio: ${url}`, err);});return pending;}- return this.backend_.play(buffer, playConfig);+ return this.playVoice_(buffer, playConfig);}playBGM(url: string, config?: {@@ -332,9 +366,9 @@ export class AudioAPI {}const fadeInDuration = config?.fadeIn ?? config?.crossFade;- this.bgmHandle_ = this.backend_.play(buffer, {+ this.bgmHandle_ = this.playVoice_(buffer, {bus: 'music',- volume: fadeInDuration ? 0 : targetVolume,+ volume: targetVolume,loop: true,});@@ -383,25 +417,33 @@ export class AudioAPI {setMasterVolume(volume: number): void {if (this.mixer_) {this.mixer_.master.volume = volume;+ return;}+ this.setSoftBus_('master', { volume });}setMusicVolume(volume: number): void {if (this.mixer_) {this.mixer_.music.volume = volume;+ return;}+ this.setSoftBus_('music', { volume });}setSFXVolume(volume: number): void {if (this.mixer_) {this.mixer_.sfx.volume = volume;+ return;}+ this.setSoftBus_('sfx', { volume });}setUIVolume(volume: number): void {if (this.mixer_) {this.mixer_.ui.volume = volume;+ return;}+ this.setSoftBus_('ui', { volume });}/** Mixerless backends (WeChat/Null) report unity volume and unmuted —@@ -422,17 +464,74 @@ export class AudioAPI {return this.mixer_?.ui.volume ?? 1;}- /** Unity (1) for an unknown bus or a mixerless backend. */+ /** Unity (1) for an unknown bus. */getBusVolume(busName: string): number {- return this.mixer_?.getBus(busName)?.volume ?? 1;+ if (this.mixer_) return this.mixer_.getBus(busName)?.volume ?? 1;+ return this.softBuses_.get(busName)?.volume ?? 1;}isBusMuted(busName: string): boolean {- return this.mixer_?.getBus(busName)?.muted ?? false;+ if (this.mixer_) return this.mixer_.getBus(busName)?.muted ?? false;+ return this.softBuses_.get(busName)?.muted ?? false;+ }++ /** Record a bus change for a mixerless backend and push it to live voices —+ * what a gain node would have done to the tracks already playing. */+ private setSoftBus_(busName: string, change: { volume?: number; muted?: boolean }): void {+ const bus = this.softBuses_.get(busName) ?? { volume: 1, muted: false };+ if (change.volume !== undefined) bus.volume = change.volume;+ if (change.muted !== undefined) bus.muted = change.muted;+ this.softBuses_.set(busName, bus);+ this.applyBus_(busName);+ }++ /** The gain a mixerless backend folds into a voice: its bus, times master. */+ private softGain_(busName: string): number {+ if (this.mixer_) return 1; // the graph already applies it+ const gainOf = (name: string): number => {+ const bus = this.softBuses_.get(name);+ if (!bus) return 1;+ return bus.muted ? 0 : bus.volume;+ };+ return busName === 'master' ? gainOf('master') : gainOf(busName) * gainOf('master');+ }++ /** Push a voice's computed volume to the backend. */+ private applyVoice_(voice: SoftVoice): void {+ voice.handle.setVolume(voice.base * this.softGain_(voice.bus) * voice.fade);+ }++ /** Re-apply after a bus (or master) changed, and forget voices that ended. */+ private applyBus_(busName: string): void {+ this.softVoices_ = this.softVoices_.filter((v) => v.handle.isPlaying || this.fadeOf_(v) !== null);+ for (const voice of this.softVoices_) {+ if (busName === 'master' || voice.bus === busName) this.applyVoice_(voice);+ }+ }++ private fadeOf_(voice: SoftVoice): Fade | null {+ return this.fades_.find((f) => f.voice === voice) ?? null;+ }++ /** Play through the backend as a tracked voice, so bus gain and fades have+ * one place to act — on every platform, mixer graph or not. */+ private playVoice_(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {+ const bus = config.bus ?? 'sfx';+ const base = config.volume ?? 1;+ const handle = this.backend_.play(buffer, { ...config, volume: base * this.softGain_(bus) });+ this.softVoices_.push({ handle, bus, base, fade: 1 });+ if (this.softVoices_.length > 64) {+ this.softVoices_ = this.softVoices_.filter((v) => v.handle.isPlaying);+ }+ return handle;}muteBus(busName: string, muted: boolean): void {- const bus = this.mixer_?.getBus(busName);+ if (!this.mixer_) {+ this.setSoftBus_(busName, { muted });+ return;+ }+ const bus = this.mixer_.getBus(busName);if (bus) {bus.muted = muted;}@@ -449,7 +548,11 @@ export class AudioAPI {}setBusVolume(busName: string, volume: number): void {- const bus = this.mixer_?.getBus(busName);+ if (!this.mixer_) {+ this.setSoftBus_(busName, { volume });+ return;+ }+ const bus = this.mixer_.getBus(busName);if (bus) {bus.volume = volume;}@@ -510,53 +613,60 @@ export class AudioAPI {this.backend_?.dispose();}- private fadeIn_(handle: AudioHandle, duration: number, targetVolume: number): void {- handle.setVolume(0);- const startTime = performance.now();- let animId = 0;- const tick = () => {- const elapsed = (performance.now() - startTime) / 1000;- const t = Math.min(elapsed / duration, 1);- handle.setVolume(t * targetVolume);- if (t < 1 && handle.isPlaying) {- animId = requestAnimationFrame(tick);- this.fadeAnimIds_.add(animId);- } else {- this.fadeAnimIds_.delete(animId);+ /**+ * Advance every fade by `dt` seconds — called once a frame by the audio+ * system, which is what makes a fade the game's clock rather than the+ * browser's: it pauses when the game does, and it exists on a device.+ */+ updateFades(dt: number): void {+ if (this.fades_.length === 0 || !(dt > 0)) return;+ for (let i = this.fades_.length - 1; i >= 0; i--) {+ const fade = this.fades_[i];+ fade.elapsed += dt;+ const t = fade.duration > 0 ? Math.min(fade.elapsed / fade.duration, 1) : 1;+ fade.voice.fade = fade.from + (fade.to - fade.from) * t;+ this.applyVoice_(fade.voice);+ // A track that ended (or was stopped) mid-ramp takes its fade with it.+ if (t >= 1 || !fade.voice.handle.isPlaying) {+ if (fade.stopAtEnd) {+ fade.voice.handle.stop();+ this.fadingOut_.delete(fade.voice.handle);+ }+ this.fades_.splice(i, 1);}- };- animId = requestAnimationFrame(tick);- this.fadeAnimIds_.add(animId);+ }+ }++ private fadeIn_(handle: AudioHandle, duration: number, targetVolume: number): void {+ const voice = this.voiceOf_(handle, targetVolume, 'music');+ voice.base = targetVolume;+ voice.fade = 0;+ this.applyVoice_(voice);+ this.fades_.push({ voice, from: 0, to: 1, duration, elapsed: 0, stopAtEnd: false });+ }++ /** The tracked voice for a handle, registering one if it came from outside+ * the play path (a deferred handle resolved later). */+ private voiceOf_(handle: AudioHandle, base: number, bus: string): SoftVoice {+ const found = this.softVoices_.find((v) => v.handle === handle);+ if (found) return found;+ const voice: SoftVoice = { handle, bus, base, fade: 1 };+ this.softVoices_.push(voice);+ return voice;}/** Cancel every in-flight fade AND stop the tracks that were fading out — a- * cancelled fade RAF would otherwise never reach their `stop()`. */+ * cancelled fade would otherwise never reach their `stop()`. */private cancelFades_(): void {- for (const id of this.fadeAnimIds_) cancelAnimationFrame(id);- this.fadeAnimIds_.clear();+ this.fades_.length = 0;for (const h of this.fadingOut_) h.stop();this.fadingOut_.clear();}private fadeOut_(handle: AudioHandle, duration: number, startVolume: number): void {this.fadingOut_.add(handle);- const startTime = performance.now();- let animId = 0;- const tick = () => {- const elapsed = (performance.now() - startTime) / 1000;- const t = Math.min(elapsed / duration, 1);- handle.setVolume(startVolume * (1 - t));- if (t < 1 && handle.isPlaying) {- animId = requestAnimationFrame(tick);- this.fadeAnimIds_.add(animId);- } else {- handle.stop();- this.fadeAnimIds_.delete(animId);- this.fadingOut_.delete(handle);- }- };- animId = requestAnimationFrame(tick);- this.fadeAnimIds_.add(animId);+ const voice = this.voiceOf_(handle, startVolume, 'music');+ this.fades_.push({ voice, from: voice.fade, to: 0, duration, elapsed: 0, stopAtEnd: true });}private createDeferredHandle_(): AudioHandle & { resolve(real: AudioHandle): void } {diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex 817900bdf..2210bd79a 100644--- a/sdk/src/audio/AudioPlugin.ts+++ b/sdk/src/audio/AudioPlugin.ts@@ -80,7 +80,7 @@ export class AudioPlugin implements Plugin {Schedule.PreUpdate,defineSystem([Res(Time), Res(Audio)],- (_time: TimeData, audioAPI: AudioAPI) => {+ (time: TimeData, audioAPI: AudioAPI) => {const playMode = !isEditor() || isPlayMode();if (!playMode) {@@ -92,6 +92,9 @@ export class AudioPlugin implements Plugin {}wasPlayMode = true;+ // Volume ramps ride the frame, not the browser's rAF: a device+ // has no such global, and a fade should pause with the game.+ audioAPI.updateFades(time.delta);audioAPI.updateDucking();const world = app.world;diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex ac0650c33..d0240b3d7 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -75,6 +75,8 @@ export {modeToDelivery,folderGroupMode,withFolderGroup,+ folderAlwaysInclude,+ withFolderAlwaysInclude,withActiveRemoteRoot,ASSET_GROUP_MODES,type AssetGroupMode,