meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:client:audio [2023/11/29 17:57] – bibiboxsscripting:client:audio [2025/08/02 23:24] (当前版本) – bibiboxs
行 23: 行 23:
 > 使用不同轨道（API）播放的声音，将受到对应轨道的游戏音量控制。 > 使用不同轨道（API）播放的声音，将受到对应轨道的游戏音量控制。
  
-**==注意：音频系统中`Music`是完全独立的，在场景\世界切换后，正在播放的音乐不会被停止，其他类型的音频则会自动停止（`Sound\Natural`）。==** 
  
-## World端音频控制+ 
 +## World Audio 
 为了丰富World端的开发实用性，[World/Player](scripting/world/player)增加了类似`player.PlaySound()`等方法映射*（为某个联机玩家单独播放声音\音乐等）*，这些方法的参数及用法与本文档内容基本一致，唯一的区别是可以从World脚本直接为某个玩家播放\停止声音。 为了丰富World端的开发实用性，[World/Player](scripting/world/player)增加了类似`player.PlaySound()`等方法映射*（为某个联机玩家单独播放声音\音乐等）*，这些方法的参数及用法与本文档内容基本一致，唯一的区别是可以从World脚本直接为某个玩家播放\停止声音。
  
行 35: 行 36:
  
  
-## Function 
  
-### PlaySound()+ 
 +## Static Function 
 + 
 +### Audio.PlaySound()
  
 > 播放一段音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。 > 播放一段音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。
行 43: 行 46:
  
 ```javascript ```javascript
-function PlaySound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string+function Audio.PlaySound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 54: 行 57:
  
  
-### PlayPureSound()+### Audio.PlayPureSound()
  
 > 播放一段纯净音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能），**此方法播放的声音将屏蔽音频空间效果（更适合人声等音频）**。 > 播放一段纯净音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能），**此方法播放的声音将屏蔽音频空间效果（更适合人声等音频）**。
行 60: 行 63:
  
 ```javascript ```javascript
-function PlayPureSound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string+function Audio.PlayPureSound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 71: 行 74:
  
  
-### Play3DSound()+### Audio.Play3DSound()
  
 > 播放一段音效\声音（3D空间），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。 > 播放一段音效\声音（3D空间），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。
行 78: 行 81:
  
 ```javascript ```javascript
-function Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, volume: float = 1, tag: string = null ): string+function Audio.Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, volume: float = 1, tag: string = null ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 91: 行 94:
  
  
-### StopSound()+### Audio.StopSound()
  
 > 停止播放指定声音实例。 > 停止播放指定声音实例。
行 98: 行 101:
  
 ```javascript ```javascript
-function StopSound( uuid: string, fadeTime: float = 0 )+function Audio.StopSound( uuid: string, fadeTime: float = 0 )
 ``` ```
  
  
  
-### StopSoundByID()+### Audio.StopSoundByID()
  
 > 停止播放指定声音实例，通过音频ID（所有匹配的）。 > 停止播放指定声音实例，通过音频ID（所有匹配的）。
  
 ```javascript ```javascript
-function StopSoundByID( audioID: int, fadeTime: float = 0 )+function Audio.StopSoundByID( audioID: int, fadeTime: float = 0 )
 ``` ```
  
  
  
-### StopSoundByTag()+### Audio.StopSoundByTag()
  
 > 停止播放指定声音实例，通过实例Tag（所有匹配的）。 > 停止播放指定声音实例，通过实例Tag（所有匹配的）。
  
 ```javascript ```javascript
-function StopSoundByTag( tag: string, fadeTime: float = 0 )+function Audio.StopSoundByTag( tag: string, fadeTime: float = 0 )
 ``` ```
  
 ```javascript ```javascript
-PlaySound( 10, false, 1, "TempSound" ); +Audio.PlaySound( 10, false, 1, "TempSound" ); 
-PlaySound( 15, false, 1, "TempSound" ); +Audio.PlaySound( 15, false, 1, "TempSound" ); 
-PlaySound( 18, false, 1, "TempSound" );+Audio.PlaySound( 18, false, 1, "TempSound" );
  
 //以上三个实例全部会被停止播放 //以上三个实例全部会被停止播放
-StopSoundByTag("TempSound");+Audio.StopSoundByTag("TempSound");
 ``` ```
  
  
  
-### StopAllSound()+### Audio.StopAllSound()
  
 > 停止播放全部音效声音（不包括Music和Natural轨道）。 > 停止播放全部音效声音（不包括Music和Natural轨道）。
  
 ```javascript ```javascript
-function StopAllSound( fadeTime: float = 0 )+function Audio.StopAllSound( fadeTime: float = 0 )
 ``` ```
  
  
  
-### ExistSound()+### Audio.ExistSound()
  
 > 检查某个声音实例是否存在（正在播放）。 > 检查某个声音实例是否存在（正在播放）。
  
 ```javascript ```javascript
-function ExistSound( uuid: string ): bool+function Audio.ExistSound( uuid: string ): bool
 ``` ```
  
  
  
-### ExistSoundByID()+### Audio.ExistSoundByID()
  
 > 检查某个声音实例是否存在（正在播放）。 > 检查某个声音实例是否存在（正在播放）。
  
 ```javascript ```javascript
-function ExistSoundByID( audioID: int ): bool+function Audio.ExistSoundByID( audioID: int ): bool
 ``` ```
  
  
  
-### ExistSoundByTag()+### Audio.ExistSoundByTag()
  
 > 检查某个声音实例是否存在（正在播放）。 > 检查某个声音实例是否存在（正在播放）。
  
 ```javascript ```javascript
-function ExistSoundByTag( tag: string ): bool+function Audio.ExistSoundByTag( tag: string ): bool
 ``` ```
  
  
  
-### PlayMusic()+### Audio.PlayMusic()
  
 > 播放一段音效\声音（2D），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能），**此方法播放的声音将屏蔽音频空间效果**。 > 播放一段音效\声音（2D），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能），**此方法播放的声音将屏蔽音频空间效果**。
行 179: 行 182:
  
 ```javascript ```javascript
-function PlayMusic( audioID: int, loop: bool = false, fadeTime: float = 3 ): string+function Audio.PlayMusic( audioID: int, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string
 /* /*
  audioID：声音ID  audioID：声音ID
  loop：是否循环播放  loop：是否循环播放
  fadeTime：过渡时间（秒）  fadeTime：过渡时间（秒）
 + volume：自身相对音量（0.0~1.0），而非全局控制音量
 */ */
 ``` ```
行 189: 行 193:
  
  
-### Play3DMusic()+### Audio.Play3DMusic()
  
 > 播放一段音效\声音（3D空间），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能）。 > 播放一段音效\声音（3D空间），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能）。
行 196: 行 200:
  
 ```javascript ```javascript
-function Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, fadeTime: float = 3 ): string+function Audio.Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 203: 行 207:
  loop：是否循环播放  loop：是否循环播放
  fadeTime：过渡时间（秒）  fadeTime：过渡时间（秒）
 + volume：自身相对音量（0.0~1.0），而非全局控制音量
 */ */
 ``` ```
行 208: 行 213:
  
  
-### StopMusic()+### Audio.StopMusic()
  
 > 停止播放并销毁当前音乐实例。 > 停止播放并销毁当前音乐实例。
行 215: 行 220:
  
 ```javascript ```javascript
-function StopMusic( fadeTime: float = 3 )+function Audio.StopMusic( fadeTime: float = 3 )
 ``` ```
  
  
  
-### PauseMusic()+### Audio.PauseMusic()
  
 > 暂停播放当前音乐。 > 暂停播放当前音乐。
  
 ```javascript ```javascript
-function PauseMusic( fadeTime: float = 3 )+function Audio.PauseMusic( fadeTime: float = 3 )
 ``` ```
  
  
  
-### ResumeMusic()+### Audio.ResumeMusic()
  
 > 继续播放当前音乐，仅通过`PauseMusic()`暂停的音乐可使用。 > 继续播放当前音乐，仅通过`PauseMusic()`暂停的音乐可使用。
  
 ```javascript ```javascript
-function ResumeMusic( fadeTime: float = 3 )+function Audio.ResumeMusic( fadeTime: float = 3 )
 ``` ```
  
  
  
-### GetPlayingMusic()+### Audio.GetPlayingMusic()
  
 > 获取当前正在播放的**声音ID**（而非实例UUID），如无正在播放内容则返回`-1`。 > 获取当前正在播放的**声音ID**（而非实例UUID），如无正在播放内容则返回`-1`。
  
 ```javascript ```javascript
-function GetPlayingMusic(): int+function Audio.GetPlayingMusic(): int
 ``` ```
  
  
  
-### PlayNatural()+### Audio.PlayNatural()
  
 > 播放一段音效\声音（2D），通过自然\背景音轨道（根据音频管理规范，持续背景声音播放建议使用此功能）。 > 播放一段音效\声音（2D），通过自然\背景音轨道（根据音频管理规范，持续背景声音播放建议使用此功能）。
 > >
-> 背景音轨道理论支持无数个，通常适用于背景自然声音等场景，通常情况下不建议同时超过8个音轨。+> 背景音轨道理论支持无数个，通常适用于背景自然声音等场景。
  
 ```javascript ```javascript
-function PlayNatural( audioID: int, channel: int, loop: bool = true, fadeTime: float = 3 ): string+function Audio.PlayNatural( audioID: int, channel: int = 0, loop: bool = true, fadeTime: float = 3 ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 268: 行 273:
  
  
-### StopNatural()+### Audio.StopNatural()
  
 > 停止播放并销毁指定**背景音轨道实例**。 > 停止播放并销毁指定**背景音轨道实例**。
行 275: 行 280:
  
 ```javascript ```javascript
-function StopNatural( channel: int, fadeTime: float = 3 )+function Audio.StopNatural( channel: int = 0, fadeTime: float = 3 )
 /* /*
  channel：音轨ID（指定播放的音轨）  channel：音轨ID（指定播放的音轨）
行 291: 行 296:
  
  
-### StopAllNatural()+### Audio.StopAllNatural()
  
 > 停止播放全部背景音轨声音。 > 停止播放全部背景音轨声音。
  
 ```javascript ```javascript
-function StopAllNatural( fadeTime: float = 3 )+function Audio.StopAllNatural( fadeTime: float = 3 )
 ``` ```
  
  
  
-### GetTotalVolume()+### Audio.SetWorldNaturalActive() 
 + 
 +> 设置世界内置环境声音开关（例如：不同天气的环境声音）。 
 +> 
 +> 通常适用于希望实现一个环境安静的世界，或者希望完全手动控制环境声音。 
 + 
 +```javascript 
 +function Audio.SetWorldNaturalActive( active: bool ) 
 +``` 
 + 
 + 
 + 
 +### Audio.GetWorldNaturalActive() 
 + 
 +> 获取世界内置环境声音开关。 
 + 
 +```javascript 
 +function Audio.GetWorldNaturalActive(): bool 
 +``` 
 + 
 + 
 + 
 +### Audio.GetTotalVolume()
  
 > 获取全局游戏音量`1~100`（只读）。 > 获取全局游戏音量`1~100`（只读）。
行 308: 行 335:
  
 ```javascript ```javascript
-function GetTotalVolume(): int+function Audio.GetTotalVolume(): int
 ``` ```
  
  
  
-### GetSoundVolume()+### Audio.GetSoundVolume()
  
 > 获取游戏音效音量（通过`PlaySound`）`1~100`（只读）。 > 获取游戏音效音量（通过`PlaySound`）`1~100`（只读）。
  
 ```javascript ```javascript
-function GetSoundVolume(): int+function Audio.GetSoundVolume(): int
 ``` ```
  
  
  
-### GetMusicVolume()+### Audio.GetMusicVolume()
  
 > 获取游戏音乐音量（通过`PlayMusic`）`1~100`（只读）。 > 获取游戏音乐音量（通过`PlayMusic`）`1~100`（只读）。
  
 ```javascript ```javascript
-function GetMusicVolume(): int+function Audio.GetMusicVolume(): int
 ``` ```
  
  
  
-### GetNaturalVolume()+### Audio.GetNaturalVolume()
  
 > 获取游戏音效（通过`PlayNatural`）音量`1~100`（只读）。 > 获取游戏音效（通过`PlayNatural`）音量`1~100`（只读）。
  
 ```javascript ```javascript
-function GetNaturalVolume(): int+function Audio.GetNaturalVolume(): int
 ``` ```
 +
 +
 +
 +### Audio.SetAudioReverbInternal()
 +
 +> 设置游戏**声音混响效果**（建筑内部），默认为`3`（房间）。
 +>
 +> 枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。
 +
 +```javascript
 +function Audio.SetAudioReverbInternal( type: int ) //Room
 +```
 +
 +
 +
 +### Audio.GetAudioReverbInternal()
 +
 +> 设置游戏**声音混响效果**（建筑内部）。
 +
 +```javascript
 +function Audio.GetAudioReverbInternal(): int
 +```
 +
 +
 +
 +### Audio.SetAudioReverbExternal()
 +
 +> 设置游戏**声音混响效果**（建筑外部），默认为`16`（森林）。
 +>
 +> 枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。
 +
 +```javascript
 +function Audio.SetAudioReverbExternal( type: int ) //Forest
 +```
 +
 +
 +
 +### Audio.GetAudioReverbExternal()
 +
 +> 设置游戏**声音混响效果**（建筑外部）。
 +
 +```javascript
 +function Audio.GetAudioReverbExternal(): int
 +```
 +
 +
 +
 +
 +
 +
 +
 +
 +