Phaser 3.60 空间音频Spatial Sound实战指南用 Web Audio 打造 3D 声场【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser导读空间音频Spatial Sound是 Phaser 3.60.0 引入的 Web Audio 能力借助浏览器原生的PannerNode游戏中的每个声音都可以被放置到 3D 空间中的任意坐标音量会随声源与听者listener之间距离的远近而衰减从而在 2D 游戏中营造出真实的三维声场。本文以 Phaser 3.60.0 更新日志中该特性的完整说明为骨架结合仓库中src/sound/的源码实现系统讲解SpatialSoundConfig全部配置项、setListenerPosition等新增 API 的用法、底层节点链原理与注意事项读完即可在场景中实现靠近变响、远离变轻、并可随角色移动的动态音频。功能来源与适用范围该特性由社区贡献者 alxwest 提交随 Phaser 3.60.0 一同发布完整记录见 SpatialSound.md 变更说明汇总于 3.60 版更新日志索引。需要明确两个使用前提仅 Web Audio 音频系统支持空间音频。Phaser 会根据浏览器能力自动选择音频后端支持 Web Audio API 时使用WebAudioSoundManager默认否则回退到HTML5AudioSoundManager。官方说明明确指出setListenerPosition在 HTML5Audio 下调用不做任何事情因此空间音频只在 Web Audio 后端下生效。依赖浏览器AudioContext.createPanner()能力。从源码看WebAudioSound构造时会判断manager.context.createPanner是否存在见 WebAudioSound.js只有存在才会创建空间音频节点测试用例也验证了当 context 支持 createPanner 时spatialNode会被创建这一行为见 WebAudioSound.test.js。快速上手最小可运行示例更新日志给出了官方最小示例它演示了空间音频的两个核心动作设置听者位置与播放一个带空间位置的声音this.music this.sound.add(theme); this.sound.setListenerPosition(400, 300); this.music.play({ loop: true, source: { x: 400, y: 300, refDistance: 50, follow: this.playerSprite } });逐行解读this.sound.add(theme)将音频缓存中 key 为theme的音频加入声音管理器返回一个WebAudioSound实例this.sound.setListenerPosition(400, 300)把空间音频听者放到游戏坐标 (400, 300)——听者代表玩家的耳朵play()的配置对象中新增了source字段它接受一个SpatialSoundConfig对象定义了这个声音在 3D 空间中的初始位置x: 400, y: 300、参考距离refDistance: 50并通过follow: this.playerSprite让声音自动跟随精灵移动。其中source字段是SoundConfig的组成部分定义于 SoundConfig.jssource是一个可选的SpatialSoundConfig对象默认值为null即普通声音不带空间属性。SpatialSoundConfig 配置项全解SpatialSoundConfig是 3.60.0 新增的类型定义完整声明位于 SpatialSoundConfig.js。它描述的是声音源而不是听者在空间中的状态底层直接映射到 Web Audio 标准PannerNode的对应属性。以下表格汇总全部配置项、类型、默认值与说明配置项类型默认值说明xnumber0声源在右手笛卡尔坐标系中的水平位置ynumber0声源在右手笛卡尔坐标系中的垂直位置znumber0声源在右手笛卡尔坐标系中的纵向前后位置panningModelequalpower|HRTFequalpower空间化算法equalpower计算量小、兼容性好HRTF基于头相关传输函数更逼真但开销更大distanceModellinear|inverse|exponentialinverse音量随距离衰减所采用的算法orientationXnumber0声源朝向向量的水平分量orientationYnumber0声源朝向向量的垂直分量orientationZnumber-1声源朝向向量的纵向分量refDistancenumber1音量开始衰减的参考距离超过该距离后按rolloffFactor与distanceModel衰减maxDistancenumber10000声源与听者的最大距离超过后音量不再继续衰减rolloffFactornumber1音量随距离衰减的快慢对所有距离模型生效coneInnerAnglenumber360锥形声束内角度锥内不衰减音量coneOuterAnglenumber0锥形声束外角度锥外按coneOuterGain恒定衰减coneOuterGainnumber0锥外音量的衰减量取值 01默认 0 表示锥外完全无声followPhaser.Types.Math.Vector2Like无让该声音自动跟踪某对象的 x/y 位置可以是 Phaser 游戏对象、Vec2 或任何暴露了公开 x/y 属性的对象几个关键配置项的深入解读refDistance是调音量的第一旋钮。官方注释见 WebAudioSound.js 中x/y属性的文档特别提醒如果发现声音远离听者后衰减过快、很快变得太轻就应该调大refDistance。它决定距离多大时开始衰减而非衰减到零的距离。maxDistance与衰减上界当声源与听者距离超过maxDistance后音量不再继续降低。三种distanceModel的衰减曲线不同linear呈线性、inverse呈反比、exponential呈指数其中inverse是符合真实听觉直觉的默认选择。朝向向量与锥形声束orientationX/Y/Z定义了声源朝向默认朝 -Z 方向配合coneInnerAngle/coneOuterAngle/coneOuterGain可以模拟指向性声源例如喇叭、角色面朝方向的说话声锥内正常、锥外按coneOuterGain衰减。默认coneInnerAngle360、coneOuterAngle0表示全向声源不启用锥形指向效果。新增 API听者与声源的位置控制WebAudioSoundManager.setListenerPosition(x, y)定义于 WebAudioSoundManager.js签名与行为如下setListenerPosition(x, y);两个参数均可省略。缺省时默认取游戏画布的中心点x this.game.scale.width / 2y this.game.scale.height / 2调用后会把坐标写入this.listenerPosition这个Vector2并返回管理器自身支持链式调用官方文档特别提示当镜头camera滚动时你需要每帧重新调用该方法重置听者位置否则听者会停留在旧坐标上空间感会错乱。典型做法是在Scene.update()中让听者跟随玩家或跟随this.cameras.main。BaseSoundManager.listenerPositionlistenerPosition是 3.60.0 在BaseSoundManager上新增的Phaser.Math.Vector2属性见 BaseSoundManager.js存储空间音频听者的位置仅 Web Audio 后端可用。它同时暴露了另一种改听者位置的方式不调用setListenerPosition而是直接修改该 Vector2 的x/y属性。对应测试见 BaseSoundManager.test.js验证了它初始化为原点 (0, 0)且setListenerPosition在基类上是可调用的占位方法。WebAudioSound上的新增属性每个声音实例上新增了四个与空间音频相关的成员spatialNode一个PannerNode负责在 3D 空间中对声音定位。它只在浏览器支持createPanner时被创建spatialSource一个Vector2Like引用保存follow指定的跟踪对象x/y读写属性直接读写spatialNode.positionX/positionY的当前值。注意官方说明只有当声音用SpatialSoundConfig即带source配置创建/播放时才有效。例如this.music.x 600; // 把该声音的 x 坐标移动到 600 this.music.y 200;follow让声音跟着对象跑follow是本特性中最实用的选项。它的工作方式不是快照而是每帧跟踪在applyConfig()中见 WebAudioSound.js如果配置了follow会把目标对象存入spatialSource此时x/y/z的初始值不再写入节点在WebAudioSound.update()中只要声音处于播放状态且存在spatialSource就会读取该对象的x/y属性并同步到spatialNode.positionX/positionY。因此任何暴露公开x/y属性的对象游戏对象、Phaser.Math.Vector2等都能被跟踪这也是玩家持有的手电筒、敌人发出的脚步声这类动态音效的标准实现方式。配合听者跟随相机即可实现完整闭环听者跟随镜头/玩家声源 follow 各自的游戏对象音量与声像随两者相对位置实时变化。底层原理空间音频的节点链与更新流程音频节点链从 WebAudioSound.js 的构造逻辑可以看出一个 Web Audio 声音的完整信号链为AudioBufferSourceNode → muteNode(Gain) → volumeNode(Gain) → spatialNode(Panner) → pannerNode(StereoPanner) → manager.destination其中spatialNodePannerNode承担全部 3D 定位职责位于音量节点之后、立体声平移节点之前若不支持createStereoPannerspatialNode直接连到manager.destination两者都不支持时退化为普通音量链管理器侧还有一个全局链路masterMuteNode → masterVolumeNode → context.destination见 WebAudioSoundManager.js所有声音共享用于全局静音与音量。配置如何落到 PannerNodeapplyConfig()见 WebAudioSound.js在每次play()时执行将source配置逐一写入PannerNode对应属性未提供的项使用与类型定义一致的默认值node.panningModel source.panningModel ?? equalpower; node.distanceModel source.distanceModel ?? inverse; node.orientationX.value source.orientationX ?? 0; node.orientationY.value source.orientationY ?? 0; node.orientationZ.value source.orientationZ ?? -1; node.refDistance source.refDistance ?? 1; node.maxDistance source.maxDistance ?? 10000; node.rolloffFactor source.rolloffFactor ?? 1; node.coneInnerAngle source.coneInnerAngle ?? 360; node.coneOuterAngle source.coneOuterAngle ?? 0; node.coneOuterGain source.coneOuterGain ?? 0;这意味着你可以在播放中途修改声音的x/y属性来动态移动声源而不必重新调用play()。听者位置如何进入 AudioListenersetListenerPosition只负责把坐标写入listenerPositionVector2真正的写入发生在每一帧的管理器update()见 WebAudioSoundManager.js优先走标准属性AudioListener.positionX/positionY仅当值变化时才写入避免无效赋值针对兼容性回退代码注释明确指出Firefox 目前未实现positionX/positionY/positionZ因此会回退到AudioListener.setPosition(x, y, z)方法z分量保持为 0游戏中 z 轴通常不使用声音与听者默认处于同一平面。实战建议与注意事项默认听者位置是画布中心setListenerPosition()不传参数即可归位到画布中心适合固定视角的游戏卷轴类游戏务必在每帧或镜头移动后重设听者例如this.sound.setListenerPosition(player.x, player.y)。refDistance决定衰减手感以像素为单位的游戏世界通常较大默认refDistance1会让声音走两步就消失。官方示例给出refDistance: 50实际项目中建议按游戏世界的规模从几十到几百起步调试。HRTF与性能panningModel默认equalpower开销小、兼容广追求更真实的定位感可尝试HRTF但需自行评估目标设备的性能。空间音效仅作用于 Web Audio在确认浏览器不支持的场景或使用 HTML5 Audio 后端下source配置会被静默忽略游戏仍可正常运行这是特性设计上对降级兼容的保证。跟随目标需持续存在follow是按帧读取目标x/y若目标对象被销毁需同步移除或更换spatialSource否则会产生空引用风险。相关仓库资源索引空间音频特性官方变更说明SpatialSoundConfig 类型定义含全部默认值SoundConfig 中 source 字段声明WebAudioSoundManagersetListenerPosition 与逐帧写入 AudioListenerWebAudioSound节点链、applyConfig 与 follow 跟踪BaseSoundManagerlistenerPosition Vector2相关测试listenerPosition 初始化与 setListenerPosition相关测试spatialNode 创建与销毁【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Phaser 3.60 空间音频（Spatial Sound）实战指南：用 Web Audio 打造 3D 声场
Phaser 3.60 空间音频Spatial Sound实战指南用 Web Audio 打造 3D 声场【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser导读空间音频Spatial Sound是 Phaser 3.60.0 引入的 Web Audio 能力借助浏览器原生的PannerNode游戏中的每个声音都可以被放置到 3D 空间中的任意坐标音量会随声源与听者listener之间距离的远近而衰减从而在 2D 游戏中营造出真实的三维声场。本文以 Phaser 3.60.0 更新日志中该特性的完整说明为骨架结合仓库中src/sound/的源码实现系统讲解SpatialSoundConfig全部配置项、setListenerPosition等新增 API 的用法、底层节点链原理与注意事项读完即可在场景中实现靠近变响、远离变轻、并可随角色移动的动态音频。功能来源与适用范围该特性由社区贡献者 alxwest 提交随 Phaser 3.60.0 一同发布完整记录见 SpatialSound.md 变更说明汇总于 3.60 版更新日志索引。需要明确两个使用前提仅 Web Audio 音频系统支持空间音频。Phaser 会根据浏览器能力自动选择音频后端支持 Web Audio API 时使用WebAudioSoundManager默认否则回退到HTML5AudioSoundManager。官方说明明确指出setListenerPosition在 HTML5Audio 下调用不做任何事情因此空间音频只在 Web Audio 后端下生效。依赖浏览器AudioContext.createPanner()能力。从源码看WebAudioSound构造时会判断manager.context.createPanner是否存在见 WebAudioSound.js只有存在才会创建空间音频节点测试用例也验证了当 context 支持 createPanner 时spatialNode会被创建这一行为见 WebAudioSound.test.js。快速上手最小可运行示例更新日志给出了官方最小示例它演示了空间音频的两个核心动作设置听者位置与播放一个带空间位置的声音this.music this.sound.add(theme); this.sound.setListenerPosition(400, 300); this.music.play({ loop: true, source: { x: 400, y: 300, refDistance: 50, follow: this.playerSprite } });逐行解读this.sound.add(theme)将音频缓存中 key 为theme的音频加入声音管理器返回一个WebAudioSound实例this.sound.setListenerPosition(400, 300)把空间音频听者放到游戏坐标 (400, 300)——听者代表玩家的耳朵play()的配置对象中新增了source字段它接受一个SpatialSoundConfig对象定义了这个声音在 3D 空间中的初始位置x: 400, y: 300、参考距离refDistance: 50并通过follow: this.playerSprite让声音自动跟随精灵移动。其中source字段是SoundConfig的组成部分定义于 SoundConfig.jssource是一个可选的SpatialSoundConfig对象默认值为null即普通声音不带空间属性。SpatialSoundConfig 配置项全解SpatialSoundConfig是 3.60.0 新增的类型定义完整声明位于 SpatialSoundConfig.js。它描述的是声音源而不是听者在空间中的状态底层直接映射到 Web Audio 标准PannerNode的对应属性。以下表格汇总全部配置项、类型、默认值与说明配置项类型默认值说明xnumber0声源在右手笛卡尔坐标系中的水平位置ynumber0声源在右手笛卡尔坐标系中的垂直位置znumber0声源在右手笛卡尔坐标系中的纵向前后位置panningModelequalpower|HRTFequalpower空间化算法equalpower计算量小、兼容性好HRTF基于头相关传输函数更逼真但开销更大distanceModellinear|inverse|exponentialinverse音量随距离衰减所采用的算法orientationXnumber0声源朝向向量的水平分量orientationYnumber0声源朝向向量的垂直分量orientationZnumber-1声源朝向向量的纵向分量refDistancenumber1音量开始衰减的参考距离超过该距离后按rolloffFactor与distanceModel衰减maxDistancenumber10000声源与听者的最大距离超过后音量不再继续衰减rolloffFactornumber1音量随距离衰减的快慢对所有距离模型生效coneInnerAnglenumber360锥形声束内角度锥内不衰减音量coneOuterAnglenumber0锥形声束外角度锥外按coneOuterGain恒定衰减coneOuterGainnumber0锥外音量的衰减量取值 01默认 0 表示锥外完全无声followPhaser.Types.Math.Vector2Like无让该声音自动跟踪某对象的 x/y 位置可以是 Phaser 游戏对象、Vec2 或任何暴露了公开 x/y 属性的对象几个关键配置项的深入解读refDistance是调音量的第一旋钮。官方注释见 WebAudioSound.js 中x/y属性的文档特别提醒如果发现声音远离听者后衰减过快、很快变得太轻就应该调大refDistance。它决定距离多大时开始衰减而非衰减到零的距离。maxDistance与衰减上界当声源与听者距离超过maxDistance后音量不再继续降低。三种distanceModel的衰减曲线不同linear呈线性、inverse呈反比、exponential呈指数其中inverse是符合真实听觉直觉的默认选择。朝向向量与锥形声束orientationX/Y/Z定义了声源朝向默认朝 -Z 方向配合coneInnerAngle/coneOuterAngle/coneOuterGain可以模拟指向性声源例如喇叭、角色面朝方向的说话声锥内正常、锥外按coneOuterGain衰减。默认coneInnerAngle360、coneOuterAngle0表示全向声源不启用锥形指向效果。新增 API听者与声源的位置控制WebAudioSoundManager.setListenerPosition(x, y)定义于 WebAudioSoundManager.js签名与行为如下setListenerPosition(x, y);两个参数均可省略。缺省时默认取游戏画布的中心点x this.game.scale.width / 2y this.game.scale.height / 2调用后会把坐标写入this.listenerPosition这个Vector2并返回管理器自身支持链式调用官方文档特别提示当镜头camera滚动时你需要每帧重新调用该方法重置听者位置否则听者会停留在旧坐标上空间感会错乱。典型做法是在Scene.update()中让听者跟随玩家或跟随this.cameras.main。BaseSoundManager.listenerPositionlistenerPosition是 3.60.0 在BaseSoundManager上新增的Phaser.Math.Vector2属性见 BaseSoundManager.js存储空间音频听者的位置仅 Web Audio 后端可用。它同时暴露了另一种改听者位置的方式不调用setListenerPosition而是直接修改该 Vector2 的x/y属性。对应测试见 BaseSoundManager.test.js验证了它初始化为原点 (0, 0)且setListenerPosition在基类上是可调用的占位方法。WebAudioSound上的新增属性每个声音实例上新增了四个与空间音频相关的成员spatialNode一个PannerNode负责在 3D 空间中对声音定位。它只在浏览器支持createPanner时被创建spatialSource一个Vector2Like引用保存follow指定的跟踪对象x/y读写属性直接读写spatialNode.positionX/positionY的当前值。注意官方说明只有当声音用SpatialSoundConfig即带source配置创建/播放时才有效。例如this.music.x 600; // 把该声音的 x 坐标移动到 600 this.music.y 200;follow让声音跟着对象跑follow是本特性中最实用的选项。它的工作方式不是快照而是每帧跟踪在applyConfig()中见 WebAudioSound.js如果配置了follow会把目标对象存入spatialSource此时x/y/z的初始值不再写入节点在WebAudioSound.update()中只要声音处于播放状态且存在spatialSource就会读取该对象的x/y属性并同步到spatialNode.positionX/positionY。因此任何暴露公开x/y属性的对象游戏对象、Phaser.Math.Vector2等都能被跟踪这也是玩家持有的手电筒、敌人发出的脚步声这类动态音效的标准实现方式。配合听者跟随相机即可实现完整闭环听者跟随镜头/玩家声源 follow 各自的游戏对象音量与声像随两者相对位置实时变化。底层原理空间音频的节点链与更新流程音频节点链从 WebAudioSound.js 的构造逻辑可以看出一个 Web Audio 声音的完整信号链为AudioBufferSourceNode → muteNode(Gain) → volumeNode(Gain) → spatialNode(Panner) → pannerNode(StereoPanner) → manager.destination其中spatialNodePannerNode承担全部 3D 定位职责位于音量节点之后、立体声平移节点之前若不支持createStereoPannerspatialNode直接连到manager.destination两者都不支持时退化为普通音量链管理器侧还有一个全局链路masterMuteNode → masterVolumeNode → context.destination见 WebAudioSoundManager.js所有声音共享用于全局静音与音量。配置如何落到 PannerNodeapplyConfig()见 WebAudioSound.js在每次play()时执行将source配置逐一写入PannerNode对应属性未提供的项使用与类型定义一致的默认值node.panningModel source.panningModel ?? equalpower; node.distanceModel source.distanceModel ?? inverse; node.orientationX.value source.orientationX ?? 0; node.orientationY.value source.orientationY ?? 0; node.orientationZ.value source.orientationZ ?? -1; node.refDistance source.refDistance ?? 1; node.maxDistance source.maxDistance ?? 10000; node.rolloffFactor source.rolloffFactor ?? 1; node.coneInnerAngle source.coneInnerAngle ?? 360; node.coneOuterAngle source.coneOuterAngle ?? 0; node.coneOuterGain source.coneOuterGain ?? 0;这意味着你可以在播放中途修改声音的x/y属性来动态移动声源而不必重新调用play()。听者位置如何进入 AudioListenersetListenerPosition只负责把坐标写入listenerPositionVector2真正的写入发生在每一帧的管理器update()见 WebAudioSoundManager.js优先走标准属性AudioListener.positionX/positionY仅当值变化时才写入避免无效赋值针对兼容性回退代码注释明确指出Firefox 目前未实现positionX/positionY/positionZ因此会回退到AudioListener.setPosition(x, y, z)方法z分量保持为 0游戏中 z 轴通常不使用声音与听者默认处于同一平面。实战建议与注意事项默认听者位置是画布中心setListenerPosition()不传参数即可归位到画布中心适合固定视角的游戏卷轴类游戏务必在每帧或镜头移动后重设听者例如this.sound.setListenerPosition(player.x, player.y)。refDistance决定衰减手感以像素为单位的游戏世界通常较大默认refDistance1会让声音走两步就消失。官方示例给出refDistance: 50实际项目中建议按游戏世界的规模从几十到几百起步调试。HRTF与性能panningModel默认equalpower开销小、兼容广追求更真实的定位感可尝试HRTF但需自行评估目标设备的性能。空间音效仅作用于 Web Audio在确认浏览器不支持的场景或使用 HTML5 Audio 后端下source配置会被静默忽略游戏仍可正常运行这是特性设计上对降级兼容的保证。跟随目标需持续存在follow是按帧读取目标x/y若目标对象被销毁需同步移除或更换spatialSource否则会产生空引用风险。相关仓库资源索引空间音频特性官方变更说明SpatialSoundConfig 类型定义含全部默认值SoundConfig 中 source 字段声明WebAudioSoundManagersetListenerPosition 与逐帧写入 AudioListenerWebAudioSound节点链、applyConfig 与 follow 跟踪BaseSoundManagerlistenerPosition Vector2相关测试listenerPosition 初始化与 setListenerPosition相关测试spatialNode 创建与销毁【免费下载链接】phaserPhaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.项目地址: https://gitcode.com/gh_mirrors/ph/phaser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考