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(audio): add deterministic sound event definitions
yhhf1ceef07657f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 90b05aaef..43f571785 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,10 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **Sound event definitions share deterministic selection.** Beta `.esaudioevent` assets validate weighted clip slots, sequential and no-repeat selection, volume/rate ranges and event playback settings. The shared selector uses independent seeded streams for clip and parameter choices, combines duplicate audio identities, and reports empty or disabled pools. Definitions load through Assets without decoding every candidate; export dependency scanning retains all candidates and UUID references survive file moves. This provides the resource and selection layer for RM-066; automatic event playback limits, dedicated authoring, component and visual-script integration remain in progress.+### Fixed- **Mixer bus edits retain the project's voice budget.** Adding, changing or removing a bus preserves the other audio settings, including an explicit unlimited voice count, instead of silently restoring the runtime default limit.diff --git a/desktop b/desktopindex 0bc3c2275..29e0b24c5 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 0bc3c22757062e4a4aae4b88dc25bf11a88135cb+Subproject commit 29e0b24c5d851f4a50af8afa88d0c35a5a7370c0diff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxindex d6a56a9da..d8eec1a42 100644--- a/docs/astro/src/content/docs/assets/audio.mdx+++ b/docs/astro/src/content/docs/assets/audio.mdx@@ -45,6 +45,46 @@ const play = defineSystem([Res(Audio)], (audio) => {current track, optionally cross-fading. Both auto-preload an uncached clip and playit once ready.+## Sound event definitions (beta)++A `.esaudioevent` is a versioned JSON asset containing `clips` with audio references+and relative `weight` values. Load it with `assets.load<SoundEventAsset>('sound-event', ref)`;+the loader validates the document without decoding every candidate. Candidate UUID+references participate in export dependencies, including slots whose weight is zero.++```typescript+import { parseSoundEvent, SoundEventSelector } from 'esengine';++const event = parseSoundEvent({+ version: 1,+ mode: 'no-repeat',+ clips: [{ clip: 'assets/step-a.wav', weight: 1 }, { clip: 'assets/step-b.wav', weight: 3 }],+ volume: [0.8, 1],+ playbackRate: [0.9, 1.1],+});+const selector = new SoundEventSelector(event, 42);+const result = selector.next();+if (result.selection) {+ const { clip, volume, playbackRate } = result.selection;+ audio.playSFX(clip, { volume, pitch: playbackRate });+}+```++`random` uses relative weights; `sequence` cycles enabled slots in authored order;+`no-repeat` excludes the previous audio identity when another positive-weight clip+exists. Duplicate identities combine weights in random modes and report their first+slot. Zero-weight slots are disabled in every mode. An empty or entirely disabled+pool returns `empty` or `zero-weight` without a selection; one enabled clip may repeat.++The seed controls clip and parameter choices independently of the playback backend.+Changing parameter ranges preserves clip order. Playback rate changes pitch **and+duration**. It does not preserve duration while shifting pitch.++The selector only chooses clips and parameters. The document also stores bus,+priority, spatial attenuation, `maxInstances` and cooldown settings; the caller+must apply these while controlling playback. Event-level playback management,+the dedicated editor, and component/visual-script integration remain in RM-066.+## `Audio` API reference| Method | Description |diff --git a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdxindex 0924780c9..fa38a74c2 100644--- a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx@@ -40,6 +40,40 @@ const play = defineSystem([Res(Audio)], (audio) => {`playSFX` 触发一次性播放并返回一个句柄;`playBGM` 循环并替换当前曲目,可选交叉淡入。两者都会自动预加载未缓存的片段并在就绪后播放。+## 音效事件定义(beta)++`.esaudioevent` 是带有 `version: 1` 的 JSON 资源,`clips` 保存音频引用和相对 `weight`。+使用 `assets.load<SoundEventAsset>('sound-event', ref)` 加载并校验定义,不会解码所有候选声音。+候选的 UUID 引用会进入导出依赖,权重为零的槽位也保留依赖。++```typescript+import { parseSoundEvent, SoundEventSelector } from 'esengine';++const event = parseSoundEvent({+ version: 1,+ mode: 'no-repeat',+ clips: [{ clip: 'assets/step-a.wav', weight: 1 }, { clip: 'assets/step-b.wav', weight: 3 }],+ volume: [0.8, 1],+ playbackRate: [0.9, 1.1],+});+const selector = new SoundEventSelector(event, 42);+const result = selector.next();+if (result.selection) {+ const { clip, volume, playbackRate } = result.selection;+ audio.playSFX(clip, { volume, pitch: playbackRate });+}+```++`random` 按权重选择,`sequence` 按作者排列的顺序循环启用槽位,`no-repeat` 在存在其他正权重声音时排除上次的音频标识。+随机模式会合并相同音频标识的权重并返回其首个槽位。所有模式均跳过零权重槽位;空池和全零权重池分别返回+`empty`、`zero-weight` 原因。只有一个启用声音时允许重复。++固定种子可重现片段及参数选择,不承诺后端采样同步;修改参数范围不会改变片段顺序。+播放速率同时影响音高和时长,不是保时长变调。++选择器只负责选择片段和参数。定义也保存总线、优先级、空间衰减、事件并发上限和冷却设置,调用者负责在播放时应用。+事件级播放管理、专用制作界面、组件和可视化脚本接入仍在 RM-066 中继续实施。+## `Audio` API 参考| 方法 | 说明 |diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex ef8d54604..9f777d2ab 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 115,- "beta": 103,+ "beta": 110,"experimental": 2203,"deprecated": 3},- "total": 2421,+ "total": 2428,"subsystems": [{"id": "mobile-controls",@@ -2501,6 +2501,78 @@"minigame"]},+ {+ "name": "SoundEventAsset",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SoundEventClip",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SoundEventMode",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SoundEventSelection",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SoundEventSelectionResult",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SoundEventSelector",+ "kind": "class",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "SpawnOverride","kind": "type",@@ -2950,6 +3022,18 @@"minigame"]},+ {+ "name": "parseSoundEvent",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "presentedCameraView","kind": "const",diff --git a/pipeline/tests/sound-event-deps.test.ts b/pipeline/tests/sound-event-deps.test.tsnew file mode 100644index 000000000..2b921d08e--- /dev/null+++ b/pipeline/tests/sound-event-deps.test.ts@@ -0,0 +1,34 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, expect, it } from 'vitest';+import { mkdtempSync, writeFileSync, renameSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { scanAssetDatabase } from '../src/assets/assetDb';++const roots: string[] = [];+afterEach(() => {+ for (const root of roots.splice(0)) {+ if (path.dirname(path.resolve(root)) !== path.resolve(tmpdir())) throw new Error('Unexpected fixture root');+ rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+});++it('keeps every event candidate as a dependency, including disabled slots and moved UUID references', async () => {+ const root = mkdtempSync(path.join(tmpdir(), 'estella-sound-event-')); roots.push(root);+ const clips = ['11111111-1111-4111-8111-111111111111', '22222222-2222-4222-8222-222222222222'];+ const event = '33333333-3333-4333-8333-333333333333';+ for (let i = 0; i < clips.length; ++i) {+ writeFileSync(path.join(root, `${i}.wav`), 'audio fixture');+ writeFileSync(path.join(root, `${i}.wav.meta`), JSON.stringify({ uuid: clips[i], version: '2.0', type: 'audio', importer: {} }));+ }+ writeFileSync(path.join(root, 'steps.esaudioevent'), JSON.stringify({ version: 1, clips: clips.map((uuid, i) => ({ clip: `@uuid:${uuid}`, weight: i })) }));+ writeFileSync(path.join(root, 'steps.esaudioevent.meta'), JSON.stringify({ uuid: event, version: '2.0', type: 'json', importer: {} }));+ const first = await scanAssetDatabase(root, { write: false });+ expect(first.index.deps[event]).toEqual(clips);+ renameSync(path.join(root, '0.wav'), path.join(root, 'renamed.wav'));+ renameSync(path.join(root, '0.wav.meta'), path.join(root, 'renamed.wav.meta'));+ const second = await scanAssetDatabase(root, { write: false });+ expect(second.index.deps[event]).toEqual(clips);+ expect(second.index.entries.find(entry => entry.uuid === clips[0])?.path).toBe('renamed.wav');+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex eaaae4751..48b9118ee 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: 115 public · 91 beta · 1581 experimental · 3 deprecated+Symbols: 115 public · 98 beta · 1581 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -8018,6 +8018,52 @@ layer: numberorder: number```+## SoundEventAsset — interface @beta+```+bus: string+clips: SoundEventClip[]+cooldown: number+maxInstances: number+mode: SoundEventMode+playbackRate: [number, number]+priority: number+spatial: SpatialAudioConfig | undefined+version: 1+volume: [number, number]+```++## SoundEventClip — interface @beta+```+clip: string+weight: number+```++## SoundEventMode — type @beta+```+'random' | 'no-repeat' | 'sequence'+```++## SoundEventSelection — interface @beta+```+clip: string+playbackRate: number+slot: number+volume: number+```++## SoundEventSelectionResult — type @beta+```+{ selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' }+```++## SoundEventSelector — class @beta+```+next: () => SoundEventSelectionResult+static new (asset: SoundEventAsset, seed?: number): SoundEventSelector+static prototype: SoundEventSelector+```+## SourceDelta — interface @experimental```added: readonly AddedEntity[]@@ -12191,6 +12237,11 @@ MeshRendererPlugin(input: string): RichTextRun[]```+## parseSoundEvent — function @beta+```+(value: unknown): SoundEventAsset+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 3242b0b4f..c6c60f167 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: 115 public · 96 beta · 1600 experimental · 3 deprecated+Symbols: 115 public · 103 beta · 1600 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -8231,6 +8231,52 @@ layer: numberorder: number```+## SoundEventAsset — interface @beta+```+bus: string+clips: SoundEventClip[]+cooldown: number+maxInstances: number+mode: SoundEventMode+playbackRate: [number, number]+priority: number+spatial: SpatialAudioConfig | undefined+version: 1+volume: [number, number]+```++## SoundEventClip — interface @beta+```+clip: string+weight: number+```++## SoundEventMode — type @beta+```+'random' | 'no-repeat' | 'sequence'+```++## SoundEventSelection — interface @beta+```+clip: string+playbackRate: number+slot: number+volume: number+```++## SoundEventSelectionResult — type @beta+```+{ selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' }+```++## SoundEventSelector — class @beta+```+next: () => SoundEventSelectionResult+static new (asset: SoundEventAsset, seed?: number): SoundEventSelector+static prototype: SoundEventSelector+```+## SourceDelta — interface @experimental```added: readonly AddedEntity[]@@ -12454,6 +12500,11 @@ MeshRendererPlugin(input: string): RichTextRun[]```+## parseSoundEvent — function @beta+```+(value: unknown): SoundEventAsset+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex cc0652cdb..6eae56df9 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: 115 public · 93 beta · 1580 experimental · 3 deprecated+Symbols: 115 public · 100 beta · 1580 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8013,6 +8013,52 @@ layer: numberorder: number```+## SoundEventAsset — interface @beta+```+bus: string+clips: SoundEventClip[]+cooldown: number+maxInstances: number+mode: SoundEventMode+playbackRate: [number, number]+priority: number+spatial: SpatialAudioConfig | undefined+version: 1+volume: [number, number]+```++## SoundEventClip — interface @beta+```+clip: string+weight: number+```++## SoundEventMode — type @beta+```+'random' | 'no-repeat' | 'sequence'+```++## SoundEventSelection — interface @beta+```+clip: string+playbackRate: number+slot: number+volume: number+```++## SoundEventSelectionResult — type @beta+```+{ selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' }+```++## SoundEventSelector — class @beta+```+next: () => SoundEventSelectionResult+static new (asset: SoundEventAsset, seed?: number): SoundEventSelector+static prototype: SoundEventSelector+```+## SourceDelta — interface @experimental```added: readonly AddedEntity[]@@ -12196,6 +12242,11 @@ NodePlatformAdapter(input: string): RichTextRun[]```+## parseSoundEvent — function @beta+```+(value: unknown): SoundEventAsset+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex c757ce83f..ed80ab140 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: 115 public · 91 beta · 1602 experimental · 3 deprecated+Symbols: 115 public · 98 beta · 1602 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8306,6 +8306,52 @@ layer: numberorder: number```+## SoundEventAsset — interface @beta+```+bus: string+clips: SoundEventClip[]+cooldown: number+maxInstances: number+mode: SoundEventMode+playbackRate: [number, number]+priority: number+spatial: SpatialAudioConfig | undefined+version: 1+volume: [number, number]+```++## SoundEventClip — interface @beta+```+clip: string+weight: number+```++## SoundEventMode — type @beta+```+'random' | 'no-repeat' | 'sequence'+```++## SoundEventSelection — interface @beta+```+clip: string+playbackRate: number+slot: number+volume: number+```++## SoundEventSelectionResult — type @beta+```+{ selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' }+```++## SoundEventSelector — class @beta+```+next: () => SoundEventSelectionResult+static new (asset: SoundEventAsset, seed?: number): SoundEventSelector+static prototype: SoundEventSelector+```+## SourceDelta — interface @experimental```added: readonly AddedEntity[]@@ -12500,6 +12546,11 @@ MeshRendererPlugin(input: string): RichTextRun[]```+## parseSoundEvent — function @beta+```+(value: unknown): SoundEventAsset+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 579c21544..d2090df1e 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: 115 public · 91 beta · 1593 experimental · 3 deprecated+Symbols: 115 public · 98 beta · 1593 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8020,6 +8020,52 @@ layer: numberorder: number```+## SoundEventAsset — interface @beta+```+bus: string+clips: SoundEventClip[]+cooldown: number+maxInstances: number+mode: SoundEventMode+playbackRate: [number, number]+priority: number+spatial: SpatialAudioConfig | undefined+version: 1+volume: [number, number]+```++## SoundEventClip — interface @beta+```+clip: string+weight: number+```++## SoundEventMode — type @beta+```+'random' | 'no-repeat' | 'sequence'+```++## SoundEventSelection — interface @beta+```+clip: string+playbackRate: number+slot: number+volume: number+```++## SoundEventSelectionResult — type @beta+```+{ selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' }+```++## SoundEventSelector — class @beta+```+next: () => SoundEventSelectionResult+static new (asset: SoundEventAsset, seed?: number): SoundEventSelector+static prototype: SoundEventSelector+```+## SourceDelta — interface @experimental```added: readonly AddedEntity[]@@ -12227,6 +12273,11 @@ MeshRendererPlugin(input: string): RichTextRun[]```+## parseSoundEvent — function @beta+```+(value: unknown): SoundEventAsset+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 26320bdb8..75d9e20f2 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -51,6 +51,7 @@ import { preparePrefabFromSource, type PreparedPrefab } from '../prefab/preparedimport type { PrefabOverride } from '../prefab';import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';import { JsonAssetLoader } from './loaders/JsonAssetLoader';+import { SoundEventAssetLoader } from './loaders/SoundEventAssetLoader';import { getComponentDefaults } from '../ecs/component';import { getComponentAssetFieldDescriptors } from '../scene/scene';import { discoverSceneAssets } from './discoverAssets';@@ -2606,6 +2607,7 @@ export class Assets {this.register(new AvatarAssetLoader());this.register(new LocaleAssetLoader());this.register(new JsonAssetLoader());+ this.register(new SoundEventAssetLoader());// …and whatever an optional subsystem brought with it. A loader names// its subsystem's parser, so one the core constructs is one every// package carries.diff --git a/sdk/src/asset/loaders/SoundEventAssetLoader.ts b/sdk/src/asset/loaders/SoundEventAssetLoader.tsnew file mode 100644index 000000000..f9d16da6d--- /dev/null+++ b/sdk/src/asset/loaders/SoundEventAssetLoader.ts@@ -0,0 +1,23 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import type { AssetLoader, LoadContext } from '../AssetLoader';+import { parseSoundEvent, type SoundEventAsset } from '../../audio/SoundEvent';++/** Loads a validated event definition without decoding every candidate sound. */+export class SoundEventAssetLoader implements AssetLoader<SoundEventAsset> {+ readonly type = 'sound-event';+ readonly extensions = ['.esaudioevent'];++ async load(path: string, ctx: LoadContext): Promise<SoundEventAsset> {+ const text = await ctx.loadText(ctx.catalog.getBuildPath(path));+ try {+ return parseSoundEvent(JSON.parse(text));+ } catch (error) {+ throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);+ }+ }++ unload(): void {+ // Definitions hold no audio buffers; voices own their decoded clip leases.+ }+}diff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.tsindex e7f7da40b..b528920d9 100644--- a/sdk/src/assetTypes.ts+++ b/sdk/src/assetTypes.ts@@ -77,6 +77,7 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [// @uuid (transitive dep).{ extensions: ['estileset'], contentType: 'json', editorType: 'tileset', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },{ extensions: ['estimeline'], contentType: 'json', editorType: 'timeline', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },+ { extensions: ['esaudioevent'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },// Locale string table (LocaleAssetLoader → Localization.addCatalog) — one locale per file.{ extensions: ['eslocale'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },// State machine (registerFsm / FsmAssetLoader) — data-driven FSM definition.diff --git a/sdk/src/audio/SoundEvent.ts b/sdk/src/audio/SoundEvent.tsnew file mode 100644index 000000000..2541f8327--- /dev/null+++ b/sdk/src/audio/SoundEvent.ts@@ -0,0 +1,185 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { extractUuid } from '../asset/AssetRegistry';+import { AttenuationModel, type SpatialAudioConfig } from './SpatialAudio';++/** Clip selection policy. Zero-weight slots are disabled in every mode. @beta */+export type SoundEventMode = 'random' | 'no-repeat' | 'sequence';+/** An authored audio reference and its relative weight. @beta */+export interface SoundEventClip { clip: string; weight: number }+/** Versioned `.esaudioevent` document shared by authoring and playback. @beta */+export interface SoundEventAsset {+ version: 1;+ clips: SoundEventClip[];+ mode: SoundEventMode;+ volume: [number, number];+ /** Playback rate changes both pitch and duration; this is not time stretching. */+ playbackRate: [number, number];+ bus: string;+ priority: number;+ /** 0 means unlimited. Pending loads and paused voices still own a slot. */+ maxInstances: number;+ /** Seconds on the consumer's simulation clock. */+ cooldown: number;+ spatial?: SpatialAudioConfig;+}++function object(value: unknown, path: string): Record<string, unknown> {+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path}: expected an object`);+ return value as Record<string, unknown>;+}++function number(value: unknown, path: string, minimum: number, fallback?: number): number {+ if (value === undefined && fallback !== undefined) return fallback;+ if (typeof value !== 'number' || !Number.isFinite(value) || value < minimum) {+ throw new Error(`${path}: expected a finite number >= ${minimum}`);+ }+ return value;+}++function range(value: unknown, path: string, positive: boolean): [number, number] {+ if (value === undefined) return [1, 1];+ if (!Array.isArray(value) || value.length !== 2) throw new Error(`${path}: expected [min, max]`);+ const min = number(value[0], `${path}[0]`, 0), max = number(value[1], `${path}[1]`, min);+ if (positive && min <= 0) throw new Error(`${path}: playback rate must be positive`);+ return [min, max];+}++/** Validates the authored document with slot-specific errors; never drops a broken clip. @beta */+export function parseSoundEvent(value: unknown): SoundEventAsset {+ const raw = object(value, 'soundEvent');+ if (raw.version !== 1) throw new Error('soundEvent.version: expected 1');+ if (!Array.isArray(raw.clips)) throw new Error('soundEvent.clips: expected an array');+ const clips = raw.clips.map((value, i) => {+ const path = `soundEvent.clips[${i}]`, slot = object(value, path);+ if (typeof slot.clip !== 'string' || !slot.clip.trim()) throw new Error(`${path}.clip: expected an audio reference`);+ return { clip: slot.clip, weight: number(slot.weight, `${path}.weight`, 0, 1) };+ });+ const mode = raw.mode ?? 'no-repeat';+ if (mode !== 'random' && mode !== 'no-repeat' && mode !== 'sequence') throw new Error('soundEvent.mode: unknown selection mode');+ const bus = raw.bus ?? 'sfx';+ if (typeof bus !== 'string' || !bus.trim()) throw new Error('soundEvent.bus: expected a bus name');+ const maxInstances = number(raw.maxInstances, 'soundEvent.maxInstances', 0, 0);+ if (!Number.isSafeInteger(maxInstances)) throw new Error('soundEvent.maxInstances: expected a safe integer');+ const asset: SoundEventAsset = {+ version: 1, clips, mode, bus, maxInstances,+ volume: range(raw.volume, 'soundEvent.volume', false),+ playbackRate: range(raw.playbackRate, 'soundEvent.playbackRate', true),+ priority: number(raw.priority, 'soundEvent.priority', -Number.MAX_VALUE, 0),+ cooldown: number(raw.cooldown, 'soundEvent.cooldown', 0, 0),+ };+ if (raw.spatial !== undefined) {+ const spatial = object(raw.spatial, 'soundEvent.spatial');+ const model = spatial.model;+ if (model !== AttenuationModel.Linear && model !== AttenuationModel.Inverse && model !== AttenuationModel.Exponential) {+ throw new Error('soundEvent.spatial.model: unknown attenuation model');+ }+ const refDistance = number(spatial.refDistance, 'soundEvent.spatial.refDistance', Number.MIN_VALUE);+ asset.spatial = {+ model, refDistance,+ maxDistance: number(spatial.maxDistance, 'soundEvent.spatial.maxDistance', refDistance),+ rolloff: number(spatial.rolloff, 'soundEvent.spatial.rolloff', 0),+ };+ }+ return asset;+}++/** Selected authored slot and sampled playback parameters. @beta */+export interface SoundEventSelection { clip: string; slot: number; volume: number; playbackRate: number }+/** A selection or the reason no candidate can sound. @beta */+export type SoundEventSelectionResult = { selection: SoundEventSelection; reason?: never }+ | { selection: null; reason: 'empty' | 'zero-weight' };++interface Group { slot: number; weight: number; end: number; scale: number; sum: number }++/** Immutable compiled choices; selecting allocates no candidate lists or retained history.+ * Selection and parameter random streams are independent so range edits preserve clip order.+ * Duplicate clip identities combine weights in random modes; their first slot is reported.+ * The seed is reduced to 32 bits; only selection and sampled parameters are reproducible.+ * @beta */+export class SoundEventSelector {+ private readonly asset: SoundEventAsset;+ private readonly groups: Group[] = [];+ private readonly sequence: number[] = [];+ private total = 0;+ private cursor = 0;+ private last = -1;+ private choiceState: number;+ private parameterState: number;++ constructor(asset: SoundEventAsset, seed = 0) {+ this.asset = parseSoundEvent(asset);+ if (!Number.isSafeInteger(seed)) throw new Error('soundEvent.seed: expected a safe integer');+ this.choiceState = seed >>> 0; this.parameterState = (seed ^ 0x9e3779b9) >>> 0;+ let maximum = 0;+ for (const slot of this.asset.clips) maximum = Math.max(maximum, slot.weight);+ const byClip = new Map<string, Group>();+ for (let i = 0; i < this.asset.clips.length; ++i) {+ const slot = this.asset.clips[i];+ if (!slot.weight) continue;+ this.sequence.push(i);+ const key = extractUuid(slot.clip) ?? slot.clip;+ let group = byClip.get(key);+ if (!group) { group = { slot: i, weight: 0, end: 0, scale: 0, sum: 0 }; byClip.set(key, group); this.groups.push(group); }+ if (slot.weight > group.scale) {+ group.sum = group.sum * (group.scale / slot.weight) + 1; group.scale = slot.weight;+ } else group.sum += slot.weight / group.scale;+ }+ for (const group of this.groups) {+ group.weight = (group.scale / maximum) * group.sum;+ this.total += group.weight; group.end = this.total;+ }+ }++ next(): SoundEventSelectionResult {+ if (!this.sequence.length) return { selection: null, reason: this.asset.clips.length ? 'zero-weight' : 'empty' };+ let slot: number;+ if (this.asset.mode === 'sequence') {+ slot = this.sequence[this.cursor]; this.cursor = (this.cursor + 1) % this.sequence.length;+ } else {+ const excluded = this.asset.mode === 'no-repeat' && this.groups.length > 1 && this.last >= 0+ ? this.groups[this.last] : null;+ const unit = this.random(false), remaining = this.total - (excluded?.weight ?? 0);+ let lo: number;+ if (excluded && remaining <= this.total * Number.EPSILON * 8) lo = this.sampleWithoutLast(unit);+ else {+ let point = unit * remaining;+ if (excluded && point >= excluded.end - excluded.weight) point += excluded.weight;+ lo = 0; let hi = this.groups.length - 1;+ while (lo < hi) { const mid = (lo + hi) >>> 1; if (point < this.groups[mid].end) hi = mid; else lo = mid + 1; }+ if (excluded && lo === this.last) lo = this.sampleWithoutLast(unit);+ }+ this.last = lo; slot = this.groups[lo].slot;+ }+ return { selection: { clip: this.asset.clips[slot].clip, slot,+ volume: this.sampleRange(this.asset.volume), playbackRate: this.sampleRange(this.asset.playbackRate) } };+ }++ /** Rescale after excluding a dominant weight so subtraction cannot erase the remaining choices. */+ private sampleWithoutLast(unit: number): number {+ let scale = 0, total = 0, fallback = 0;+ for (let i = 0; i < this.groups.length; ++i) if (i !== this.last) scale = Math.max(scale, this.groups[i].scale);+ for (let i = 0; i < this.groups.length; ++i) if (i !== this.last) total += this.groups[i].scale / scale * this.groups[i].sum;+ let point = unit * total;+ for (let i = 0; i < this.groups.length; ++i) {+ if (i === this.last) continue;+ fallback = i;+ point -= this.groups[i].scale / scale * this.groups[i].sum;+ if (point < 0) return i;+ }+ return fallback;+ }++ private sampleRange(bounds: [number, number]): number {+ const unit = this.random(true);+ return Math.min(bounds[1], Math.max(bounds[0], bounds[0] * (1 - unit) + bounds[1] * unit));+ }++ private random(parameter: boolean): number {+ const state = ((parameter ? this.parameterState : this.choiceState) + 0x6d2b79f5) | 0;+ if (parameter) this.parameterState = state; else this.choiceState = state;+ let value = Math.imul(state ^ (state >>> 15), state | 1);+ value ^= value + Math.imul(value ^ (value >>> 7), value | 61);+ return ((value ^ (value >>> 14)) >>> 0) / 4294967296;+ }+}diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.tsindex 3535f6a94..1c538bcb8 100644--- a/sdk/src/audio/index.ts+++ b/sdk/src/audio/index.ts@@ -1,6 +1,8 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamexport { Audio, AudioAPI, type AudioBufferStats } from './Audio';+export { parseSoundEvent, SoundEventSelector, type SoundEventAsset, type SoundEventClip,+ type SoundEventMode, type SoundEventSelection, type SoundEventSelectionResult } from './SoundEvent';export { AudioBus, type AudioBusConfig } from './AudioBus';export { AudioMixer, BUILTIN_AUDIO_BUSES, builtinBusVolume, type AudioMixerConfig, type BusDuckRule } from './AudioMixer';export {diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 21c3a9a8c..22b600551 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -659,6 +659,13 @@ export {AudioPool,parseBusEffects,parseAudioProjectConfig,+ parseSoundEvent,+ SoundEventSelector,+ type SoundEventAsset,+ type SoundEventClip,+ type SoundEventMode,+ type SoundEventSelection,+ type SoundEventSelectionResult,applyAudioProjectConfig,type AudioProjectConfig,type AudioBusDecl,diff --git a/sdk/tests/sound-event-loader.test.ts b/sdk/tests/sound-event-loader.test.tsnew file mode 100644index 000000000..b91424313--- /dev/null+++ b/sdk/tests/sound-event-loader.test.ts@@ -0,0 +1,47 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it, vi } from 'vitest';+vi.mock('../src/wasm/resourceManager', () => ({ requireResourceManager: () => ({}), evictTextureDimensions: vi.fn() }));+import { SoundEventAssetLoader } from '../src/asset/loaders/SoundEventAssetLoader';+import type { LoadContext } from '../src/asset/AssetLoader';+import { Assets } from '../src/asset/Assets';+import { getAssetTypeEntry, getCustomExtensions } from '../src/assetTypes';+import { SoundEventSelector, type SoundEventAsset } from '../src/audio/SoundEvent';++const document = { version: 1, mode: 'sequence', clips: [{ clip: 'a.wav' }, { clip: 'b.wav' }] };+const makeContext = (text: string) => ({ catalog: { getBuildPath: () => 'cooked/hash.esaudioevent' },+ loadText: vi.fn(async () => text), acquireAsset: vi.fn(), getAudio: vi.fn() }) as unknown as LoadContext;++describe('sound event asset loading', () => {+ it('reads the cooked path, validates the definition, and leaves clips unloaded', async () => {+ const ctx = makeContext(JSON.stringify(document));+ const data = await new SoundEventAssetLoader().load('steps.esaudioevent', ctx);+ expect(ctx.loadText).toHaveBeenCalledWith('cooked/hash.esaudioevent');+ expect(ctx.acquireAsset).not.toHaveBeenCalled(); expect(ctx.getAudio).not.toHaveBeenCalled();+ const selector = new SoundEventSelector(data);+ expect(selector.next().selection?.clip).toBe('a.wav'); expect(selector.next().selection?.clip).toBe('b.wav');+ });++ it('reports both the event path and the broken candidate slot', async () => {+ const ctx = makeContext(JSON.stringify({ version: 1, clips: [{ clip: 'a.wav' }, {}] }));+ await expect(new SoundEventAssetLoader().load('steps.esaudioevent', ctx)).rejects.toThrow('steps.esaudioevent: soundEvent.clips[1].clip');+ await expect(new SoundEventAssetLoader().load('steps.esaudioevent', makeContext('{'))).rejects.toThrow('steps.esaudioevent:');+ });++ it('loads through the registered Assets lifetime and cache', async () => {+ const fetchText = vi.fn(async () => JSON.stringify(document));+ const backend = { fetchText, fetchBinary: async () => new ArrayBuffer(0), resolveUrl: (path: string) => path,+ setBaseUrl: () => {} } as unknown as import('../src/asset/Backend').Backend;+ const assets = Assets.create({ backend, module: null });+ expect(assets.getLoader('sound-event')).toBeInstanceOf(SoundEventAssetLoader);+ const first = await assets.load<SoundEventAsset>('sound-event', 'steps.esaudioevent');+ const second = await assets.load<SoundEventAsset>('sound-event', 'steps.esaudioevent');+ expect(first).toBe(second); expect(fetchText).toHaveBeenCalledOnce();+ expect(first.mode).toBe('sequence');+ });++ it('declares JSON dependencies and the minigame package read whitelist', () => {+ expect(getAssetTypeEntry('steps.esaudioevent')).toMatchObject({ contentType: 'json', addressableType: 'json', hasTransitiveDeps: true });+ expect(getCustomExtensions()).toContain('.esaudioevent');+ });+});diff --git a/sdk/tests/sound-event.test.ts b/sdk/tests/sound-event.test.tsnew file mode 100644index 000000000..ade4a943a--- /dev/null+++ b/sdk/tests/sound-event.test.ts@@ -0,0 +1,119 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { parseSoundEvent, SoundEventSelector } from '../src/audio/SoundEvent';+import { AttenuationModel } from '../src/audio/SpatialAudio';++const asset = (extra: Record<string, unknown> = {}) => parseSoundEvent({+ version: 1, clips: [{ clip: 'a.wav' }, { clip: 'b.wav' }, { clip: 'c.wav' }], ...extra,+});+const choices = (selector: SoundEventSelector, count: number) =>+ Array.from({ length: count }, () => selector.next().selection!.clip);++describe('sound event documents', () => {+ it('preserves authored references and applies explicit defaults', () => {+ expect(asset()).toMatchObject({ mode: 'no-repeat', bus: 'sfx', volume: [1, 1], playbackRate: [1, 1],+ maxInstances: 0, cooldown: 0, priority: 0, clips: [{ clip: 'a.wav', weight: 1 }, { clip: 'b.wav', weight: 1 }, { clip: 'c.wav', weight: 1 }] });+ });++ it.each([+ [{ version: 2 }, 'version'], [{ clips: null }, 'clips'], [{ clips: [null] }, 'clips[0]'],+ [{ clips: [{ clip: '' }] }, 'clips[0].clip'], [{ clips: [{ clip: 'a.wav', weight: -1 }] }, 'clips[0].weight'],+ [{ clips: [{ clip: 'a.wav', weight: Infinity }] }, 'clips[0].weight'],+ [{ mode: 'shuffle' }, 'mode'], [{ volume: [2, 1] }, 'volume[1]'], [{ volume: [0, NaN] }, 'volume[1]'],+ [{ playbackRate: [0, 1] }, 'playbackRate'], [{ playbackRate: [1] }, 'playbackRate'],+ [{ bus: '' }, 'bus'], [{ maxInstances: 1.5 }, 'maxInstances'], [{ maxInstances: -1 }, 'maxInstances'],+ [{ cooldown: -1 }, 'cooldown'], [{ priority: NaN }, 'priority'],+ [{ spatial: { model: 8 } }, 'spatial.model'],+ [{ spatial: { model: 1, refDistance: 0 } }, 'spatial.refDistance'],+ [{ spatial: { model: 1, refDistance: 100, maxDistance: 50 } }, 'spatial.maxDistance'],+ ])('rejects malformed parameters at their authored path: %j', (raw, path) => {+ expect(() => asset(raw)).toThrow(path);+ });++ it('rejects non-document input and names a later missing clip slot', () => {+ for (const raw of [null, [], '']) expect(() => parseSoundEvent(raw)).toThrow('soundEvent');+ expect(() => asset({ clips: [{ clip: 'a.wav' }, {}] })).toThrow('clips[1].clip');+ });++ it('round-trips spatial attenuation and rate rules through JSON', () => {+ const original = asset({ volume: [.5, 1.5], playbackRate: [.8, 1.2], maxInstances: 4, cooldown: .1, priority: 5,+ spatial: { model: AttenuationModel.Inverse, refDistance: 50, maxDistance: 500, rolloff: 2 } });+ expect(parseSoundEvent(JSON.parse(JSON.stringify(original)))).toEqual(original);+ });+});++describe('compiled sound event selection', () => {+ it('distinguishes empty pools from disabled, zero-weight pools', () => {+ expect(new SoundEventSelector(asset({ clips: [] })).next()).toEqual({ selection: null, reason: 'empty' });+ expect(new SoundEventSelector(asset({ clips: [{ clip: 'a.wav', weight: 0 }] })).next())+ .toEqual({ selection: null, reason: 'zero-weight' });+ });++ it.each(['random', 'no-repeat', 'sequence'])('plays a single enabled clip repeatedly in %s mode', mode => {+ const selector = new SoundEventSelector(asset({ mode, clips: [{ clip: 'a.wav', weight: 0 }, { clip: 'b.wav' }] }));+ expect(choices(selector, 12)).toEqual(Array(12).fill('b.wav'));+ });++ it('cycles authored slots in sequence order and skips zero weights', () => {+ const selector = new SoundEventSelector(asset({ mode: 'sequence', clips: [+ { clip: 'a.wav' }, { clip: 'b.wav', weight: 0 }, { clip: 'c.wav', weight: 4 }, { clip: 'a.wav' },+ ] }));+ expect(choices(selector, 6)).toEqual(['a.wav', 'c.wav', 'a.wav', 'a.wav', 'c.wav', 'a.wav']);+ });++ it('reproduces clip choices independently of volume and playback-rate ranges', () => {+ const first = asset({ mode: 'random' }), second = asset({ mode: 'random', volume: [.3, 1.4], playbackRate: [.5, 2] });+ expect(choices(new SoundEventSelector(first, 123), 128)).toEqual(choices(new SoundEventSelector(second, 123), 128));+ expect(choices(new SoundEventSelector(first, 123), 128)).not.toEqual(choices(new SoundEventSelector(first, 124), 128));+ });++ it('honors weights over a deterministic high-frequency trigger stream', () => {+ const selector = new SoundEventSelector(asset({ mode: 'random', clips: [{ clip: 'a.wav', weight: 1 }, { clip: 'b.wav', weight: 3 }] }), 42);+ const count = choices(selector, 100_000).filter(clip => clip === 'b.wav').length;+ expect(count / 100_000).toBeCloseTo(.75, 2);+ });++ it('avoids consecutive audio identity even when it occupies duplicate slots', () => {+ const selector = new SoundEventSelector(asset({ clips: [{ clip: 'a.wav', weight: 5 }, { clip: 'a.wav', weight: 8 }, { clip: 'b.wav' }] }), 9);+ const clips = choices(selector, 512);+ for (let i = 1; i < clips.length; ++i) expect(clips[i]).not.toBe(clips[i - 1]);+ });++ it('treats UUID reference spellings as the same candidate identity', () => {+ const uuid = '01010101-0101-4101-8101-01010101010a';+ const selector = new SoundEventSelector(asset({ clips: [{ clip: `@uuid:${uuid}` }, { clip: uuid.toUpperCase() }, { clip: 'b.wav' }] }), 5);+ const clips = choices(selector, 64).map(clip => clip === 'b.wav' ? 'b' : 'a');+ for (let i = 1; i < clips.length; ++i) expect(clips[i]).not.toBe(clips[i - 1]);+ });++ it('keeps no-repeat choices valid for extreme weights in either slot order', () => {+ for (const clips of [[{ clip: 'a.wav', weight: Number.MAX_VALUE }, { clip: 'b.wav', weight: Number.MIN_VALUE }],+ [{ clip: 'b.wav', weight: Number.MIN_VALUE }, { clip: 'a.wav', weight: Number.MAX_VALUE }]]) {+ const selected = choices(new SoundEventSelector(asset({ clips }), 17), 128);+ for (let i = 1; i < selected.length; ++i) expect(selected[i]).not.toBe(selected[i - 1]);+ }+ });++ it('normalizes duplicate maximal weights without overflowing the cumulative table', () => {+ const selector = new SoundEventSelector(asset({ mode: 'random', clips: [+ { clip: 'a.wav', weight: Number.MAX_VALUE }, { clip: 'a.wav', weight: Number.MAX_VALUE }, { clip: 'b.wav', weight: Number.MAX_VALUE },+ ] }), 52);+ const selected = choices(selector, 10_000);+ expect(selected.filter(clip => clip === 'a.wav').length / selected.length).toBeCloseTo(2 / 3, 1);+ });++ it('owns a snapshot and keeps sampled parameters finite and inside their ranges', () => {+ const original = asset({ volume: [.3, 1.2], playbackRate: [.6, 1.5] }), selector = new SoundEventSelector(original);+ original.clips[0].clip = 'edited.wav'; original.clips.length = 0; original.volume[0] = 999;+ for (let i = 0; i < 100; ++i) {+ const selected = selector.next().selection!;+ expect(selected.clip).not.toBe('edited.wav');+ expect(selected.volume).toBeGreaterThanOrEqual(.3); expect(selected.volume).toBeLessThanOrEqual(1.2);+ expect(selected.playbackRate).toBeGreaterThanOrEqual(.6); expect(selected.playbackRate).toBeLessThanOrEqual(1.5);+ }+ const extreme = new SoundEventSelector(asset({ volume: [Number.MAX_VALUE, Number.MAX_VALUE] }));+ expect(Number.isFinite(extreme.next().selection!.volume)).toBe(true);+ expect(() => new SoundEventSelector(asset(), Infinity)).toThrow('seed');+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 36ee074ac..f48b72d27 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(audio): add deterministic sound event definitions':+ { note: 'Sound event definitions share deterministic selection.' },+ 'feat(editor): recognize sound event definitions':+ { note: 'Sound event definitions share deterministic selection.' },'fix(editor): retain audio settings when editing mixer buses':{ note: "Mixer bus edits retain the project's voice budget." },'fix(physics): preserve unchanged joint projections':