meta data for this page
  •  

📚 差别

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

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:client:audio [2025/05/20 21:19] – bibiboxsscripting:client:audio [2026/04/19 18:24] (当前版本) – bibiboxs
行 24: 行 24:
  
  
-## World端音频控制 + 
-为了丰富World端的开发实用性，[World/Player](scripting/world/player)增加了类似`player.PlaySound()`等方法映射*（为某个联机玩家单独播放声音\音乐等）*，这些方法的参数及用法与本文档内容基本一致，唯一的区别是可以从World脚本直接为某个玩家播放\停止声音。+## World Audio 
 + 
 +为了丰富World端的开发实用性，[World/Player](scripting/world/player)增加了类似`player.PlaySound()`等方法映射*（为联机玩家单独播放声音\音乐等）*，这些方法的参数及用法与本文档内容基本一致，唯一的区别是可以从World脚本直接为某个玩家播放\停止声音。
  
 需要注意的是，由于World端的服务器同步性，绝大多数**World端**下的音频控制并不能取得返回数据，这就导致World端音频控制更多只能【播放、暂停、继续、停止】（而不能直接：获取音量、检查声音是否正在播放等），从而并不能完全使用`Client/Audio`下的所有功能。 需要注意的是，由于World端的服务器同步性，绝大多数**World端**下的音频控制并不能取得返回数据，这就导致World端音频控制更多只能【播放、暂停、继续、停止】（而不能直接：获取音量、检查声音是否正在播放等），从而并不能完全使用`Client/Audio`下的所有功能。
行 34: 行 36:
  
  
-## Function 
  
-### PlaySound()+## Property 
 + 
 +### Audio.Volume 
 + 
 +> 获取（只读）游戏**全局音量**（`0~100`）。 
 +> 
 +> **==游戏音量数值是不允许通过代码修改的（只读），游戏音量完全遵循【玩家设置界面】的设定数值。==** 
 + 
 +```javascript 
 +Audio.Volume: int 
 +``` 
 + 
 + 
 +### Audio.SoundVolume 
 + 
 +> 获取（只读）游戏**音效类音量**（`0~100`）。 
 + 
 +```javascript 
 +Audio.SoundVolume: int 
 +``` 
 + 
 + 
 + 
 +### Audio.MusicVolume 
 + 
 +> 获取（只读）游戏**音乐音量**（`0~100`）。 
 + 
 +```javascript 
 +Audio.MusicVolume: int 
 +``` 
 + 
 + 
 + 
 +### Audio.NaturalVolume 
 + 
 +> 获取（只读）游戏**自然类音量**（`0~100`）。 
 + 
 +```javascript 
 +Audio.NaturalVolume: int 
 +``` 
 + 
 + 
 + 
 +### Audio.ReverbInternal 
 + 
 +> 设置游戏**声音混响效果**（建筑内部），默认为`3`（房间）。 
 +> 
 +> 枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。 
 + 
 +```javascript 
 +Audio.ReverbInternal = 3; 
 +``` 
 + 
 + 
 + 
 +### Audio.ReverbExternal 
 + 
 +> 设置游戏**声音混响效果**（建筑外部），默认为`16`（森林）。 
 +> 
 +> 枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。 
 + 
 +```javascript 
 +Audio.ReverbExternal = 16； 
 +``` 
 + 
 + 
 + 
 +### Audio.DryLevel 
 + 
 +> 设置游戏**干声等级**，范围限制`-10000.0~0.0`，默认为`0.0`。 
 +> 
 +> 此数值设置越低，可听到的细节越模糊（类似水下效果，但水下时不会受到此值影响）。 
 + 
 +```javascript 
 +Audio.DryLevel = 0； 
 +``` 
 + 
 + 
 + 
 + 
 +## Static Function 
 + 
 +### Audio.PlaySound()
  
 > 播放一段音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。 > 播放一段音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。
行 42: 行 125:
  
 ```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
行 53: 行 136:
  
  
-### PlayPureSound()+### Audio.PlayPureSound()
  
 > 播放一段纯净音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能），**此方法播放的声音将屏蔽音频空间效果（更适合人声等音频）**。 > 播放一段纯净音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能），**此方法播放的声音将屏蔽音频空间效果（更适合人声等音频）**。
行 59: 行 142:
  
 ```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
行 70: 行 153:
  
  
-### Play3DSound()+### Audio.Play3DSound()
  
 > 播放一段音效\声音（3D空间），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。 > 播放一段音效\声音（3D空间），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。
行 77: 行 160:
  
 ```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
行 90: 行 173:
  
  
-### StopSound()+### Audio.StopSound()
  
 > 停止播放指定声音实例。 > 停止播放指定声音实例。
行 97: 行 180:
  
 ```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），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能），**此方法播放的声音将屏蔽音频空间效果**。
行 178: 行 261:
  
 ```javascript ```javascript
-function PlayMusic( audioID: int, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string+function Audio.PlayMusic( audioID: int, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string
 /* /*
  audioID：声音ID  audioID：声音ID
行 189: 行 272:
  
  
-### Play3DMusic()+### Audio.Play3DMusic()
  
 > 播放一段音效\声音（3D空间），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能）。 > 播放一段音效\声音（3D空间），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能）。
行 196: 行 279:
  
 ```javascript ```javascript
-function Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): 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
行 209: 行 292:
  
  
-### StopMusic()+### Audio.StopMusic()
  
 > 停止播放并销毁当前音乐实例。 > 停止播放并销毁当前音乐实例。
行 216: 行 299:
  
 ```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
行 269: 行 352:
  
  
-### StopNatural()+### Audio.StopNatural()
  
 > 停止播放并销毁指定**背景音轨道实例**。 > 停止播放并销毁指定**背景音轨道实例**。
行 276: 行 359:
  
 ```javascript ```javascript
-function StopNatural( channel: int, fadeTime: float = 3 )+function Audio.StopNatural( channel: int = 0, fadeTime: float = 3 )
 /* /*
  channel：音轨ID（指定播放的音轨）  channel：音轨ID（指定播放的音轨）
行 292: 行 375:
  
  
-### StopAllNatural()+### Audio.StopAllNatural()
  
 > 停止播放全部背景音轨声音。 > 停止播放全部背景音轨声音。
  
 ```javascript ```javascript
-function StopAllNatural( fadeTime: float = 3 )+function Audio.StopAllNatural( fadeTime: float = 3 )
 ``` ```
  
  
  
-### GetTotalVolume()+### Audio.SetWorldNaturalActive()
  
-> 获取全局游戏音量`1~100`（只读）。+> 设置世界内置环境声音开关（例如：不同天气的环境声音）。
 > >
-> **==游戏音量数值是不允许通过代码修改的（只读），游戏音量完全遵循【玩家设置界面】的设定数值。==**+> 通常适用于希望实现一个环境安静的世界，或者希望完全手动控制环境声音。
  
 ```javascript ```javascript
-function GetTotalVolume(): int+function Audio.SetWorldNaturalActive( active: bool )
 ``` ```
  
  
  
-### GetSoundVolume()+### Audio.GetWorldNaturalActive()
  
-> 获取游戏音效音量（通过`PlaySound`）`1~100`（只读）。+> 获取世界内置环境声音开关。
  
 ```javascript ```javascript
-function GetSoundVolume(): int+function Audio.GetWorldNaturalActive(): bool
 ``` ```
  
  
  
-### GetMusicVolume() 
  
-> 获取游戏音乐音量（通过`PlayMusic`）`1~100`（只读）。 
  
-```javascript 
-function GetMusicVolume(): int 
-``` 
  
  
  
-### GetNaturalVolume() 
- 
-> 获取游戏音效（通过`PlayNatural`）音量`1~100`（只读）。 
- 
-```javascript 
-function GetNaturalVolume(): int 
-```