用途:AudioAnalysis 是 Decentraland SDK7 的组件,附着在已含 AudioSource、AudioStream 或 VideoPlayer 的实体上,由渲染器逐帧分析音频缓冲并把结果写回组件,供场景读取以驱动可视化、节拍响应几何体、音频联动灯光等。
主要能力:输出 amplitude(0..约1,随模式而定)与 band0..band7 共 8 个频段,band0 为最低频、band7 为最高频。输入项包括 mode(MODE_RAW=0 原始 FFT 幅度;MODE_LOGARITHMIC=1 对数映射,推荐)、amplitudeGain(默认 5.0)、bandsGain(默认 0.05),后两者仅在 MODE_LOGARITHMIC 下生效。
使用方式:音频源实体放在 main-entities.ts,AudioAnalysis 需在 src/index.ts 运行时通过 getEntityOrNullByName 附加,用 AudioAnalysis.createAudioAnalysis(entity, mode?, amplitudeGain?, bandsGain?) 创建;读取用 readIntoView 或 tryReadIntoView 写入预先分配的 AudioAnalysisView = { amplitude: number, bands: number[] },bands 必须预置长度为 8,视图应在场景初始化时分配一次并复用。
限制:实体必须同时含音频发射组件,否则无数据;音频暂停、静音或未加载时输出为 0,且无 ready 事件;仅 Unity 版 explorer 实现,Bevy 与移动端 Godot 会忽略该组件,需设计不依赖振幅的降级方案;数值为无界浮点,高增益或大音量可超过 1,需自行 clamp;渲染器按帧时间预算节流,负载下可能跳帧,建议用 dt 插值;多音频源场景需各自附加,无全局混音;未创建组件前调用 readIntoView 会抛错。权限方面除音频组件本身所需外无额外要求,流式音频仍需在 scene.json 配置 ALLOW_MEDIA_HOSTNAMES。