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.

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.ts
index 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.tsx
index 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.ts
index 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 Team
import { 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.md
index 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: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
updateDucking: () => void
+updateFades: (dt: number) => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -8866,6 +8867,11 @@ EventBindingPlugin
FocusPlugin
```
+## 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): AssetGroupsConfig
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
updateDucking: () => void
+updateFades: (dt: number) => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -9069,6 +9070,11 @@ EventBindingPlugin
FocusPlugin
```
+## 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): AssetGroupsConfig
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
updateDucking: () => void
+updateFades: (dt: number) => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -8861,6 +8862,11 @@ EventBindingPlugin
FocusPlugin
```
+## 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): AssetGroupsConfig
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
updateDucking: () => void
+updateFades: (dt: number) => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -9081,6 +9082,11 @@ EventBindingPlugin
FocusPlugin
```
+## 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): AssetGroupsConfig
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
updateDucking: () => void
+updateFades: (dt: number) => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -8885,6 +8886,11 @@ EventBindingPlugin
FocusPlugin
```
+## 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): AssetGroupsConfig
diff --git a/sdk/src/asset/assetGroups.ts b/sdk/src/asset/assetGroups.ts
index 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, fo
return '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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,