meta data for this page

📚 Client/Audio

在沙盘引擎的音频系统中，所有的实例默认是以uuid: string的形式作为存储介质的。

除此之外，也可以根据情况使用tag\id绑定及查询功能。

tag适用于所有匹配的音频标签（例如StopSoundByTag("Test")将会停止所有正在播放的Tag: Test音频）

id适用于所有匹配的声音文件ID（例如StopSoundByID(10)将会停止所有正在播放的ID: 10音频）

除此之外，通常使用以下方法进行存储音频实例： 

let mySound = Audio.PlaySound(10); //播放声音并储存到变量mySound（返回：字符串UUID）
Audio.StopSound(mySound); //停止播放声音

音频系统主要分为Sound、Music、Natural三个主要类型，并且遵循《沙盘引擎》客户端的音量设置规范。

《沙盘引擎》设置界面共有4项音量设置：全局音量（所有声音）、音效音量、音乐音量、背景音量。

使用不同轨道（API）播放的声音，将受到对应轨道的游戏音量控制。

📒 World Audio

为了丰富World端的开发实用性，World/Player增加了类似player.PlaySound()等方法映射（为某个联机玩家单独播放声音\音乐等），这些方法的参数及用法与本文档内容基本一致，唯一的区别是可以从World脚本直接为某个玩家播放\停止声音。

需要注意的是，由于World端的服务器同步性，绝大多数World端下的音频控制并不能取得返回数据，这就导致World端音频控制更多只能【播放、暂停、继续、停止】（而不能直接：获取音量、检查声音是否正在播放等），从而并不能完全使用Client/Audio下的所有功能。

World/Player下的音频控制脚本，相当于给Client/Audio部分函数做了一个联网映射。

如有实际的更多特殊需求，可以考虑使用【自定义函数\数据传输】的方式来扩展。

📒 Static Function

📘 Audio.PlaySound()

播放一段音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。 

function Audio.PlaySound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string
/*
	audioID：声音ID
	loop: 是否循环播放
	volume：自身相对音量（0.0~1.0），而非全局控制音量
	tag：设定标签（可空）
*/

📘 Audio.PlayPureSound()

播放一段纯净音效\声音（2D），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能），此方法播放的声音将屏蔽音频空间效果（更适合人声等音频）。 

function Audio.PlayPureSound( audioID: int, loop: bool = false, volume: float = 1, tag: string = null ): string
/*
	audioID：声音ID
	loop: 是否循环播放
	volume：自身相对音量（0.0~1.0），而非全局控制音量
	tag：设定标签（可空）
*/

📘 Audio.Play3DSound()

播放一段音效\声音（3D空间），通过音效轨道（根据音频管理规范，相对较短声音建议使用此功能）。

参数中volume为自身相对音量（0.0~1.0），而非全局控制音量。 

function Audio.Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, volume: float = 1, tag: string = null ): string
/*
	audioID：声音ID
	pos：3D坐标
	radius：3D声音范围
	loop: 是否循环播放
	volume：自身相对音量（0.0~1.0），而非全局控制音量
	tag：设定标签（可空）
*/

📘 Audio.StopSound()

停止播放指定声音实例。

fadeTime表示过渡时间，默认为0（直接停止），文档后续参数同理。 

function Audio.StopSound( uuid: string, fadeTime: float = 0 )

📘 Audio.StopSoundByID()

停止播放指定声音实例，通过音频ID（所有匹配的）。 

function Audio.StopSoundByID( audioID: int, fadeTime: float = 0 )

📘 Audio.StopSoundByTag()

停止播放指定声音实例，通过实例Tag（所有匹配的）。 

function Audio.StopSoundByTag( tag: string, fadeTime: float = 0 )
Audio.PlaySound( 10, false, 1, "TempSound" );
Audio.PlaySound( 15, false, 1, "TempSound" );
Audio.PlaySound( 18, false, 1, "TempSound" );
 
//以上三个实例全部会被停止播放
Audio.StopSoundByTag("TempSound");

📘 Audio.StopAllSound()

停止播放全部音效声音（不包括Music和Natural轨道）。 

function Audio.StopAllSound( fadeTime: float = 0 )

📘 Audio.ExistSound()

检查某个声音实例是否存在（正在播放）。 

function Audio.ExistSound( uuid: string ): bool

📘 Audio.ExistSoundByID()

检查某个声音实例是否存在（正在播放）。 

function Audio.ExistSoundByID( audioID: int ): bool

📘 Audio.ExistSoundByTag()

检查某个声音实例是否存在（正在播放）。 

function Audio.ExistSoundByTag( tag: string ): bool

📘 Audio.PlayMusic()

播放一段音效\声音（2D），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能），此方法播放的声音将屏蔽音频空间效果。

音乐轨道是全局唯一的，同一时间只能存在一个声音。 

function Audio.PlayMusic( audioID: int, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string
/*
	audioID：声音ID
	loop：是否循环播放
	fadeTime：过渡时间（秒）
	volume：自身相对音量（0.0~1.0），而非全局控制音量
*/

📘 Audio.Play3DMusic()

播放一段音效\声音（3D空间），通过音乐轨道（根据音频管理规范，音乐播放建议使用此功能）。

音乐轨道是全局唯一的，同一时间只能存在一个声音。 

function Audio.Play3DSound( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, fadeTime: float = 3, volume: float = 1 ): string
/*
	audioID：声音ID
	pos：3D坐标
	radius：3D声音范围
	loop：是否循环播放
	fadeTime：过渡时间（秒）
	volume：自身相对音量（0.0~1.0），而非全局控制音量
*/

📘 Audio.StopMusic()

停止播放并销毁当前音乐实例。

fadeTime表示过渡时间，如果为0则表示直接停止，文档后续参数同理。 

function Audio.StopMusic( fadeTime: float = 3 )

📘 Audio.PauseMusic()

暂停播放当前音乐。 

function Audio.PauseMusic( fadeTime: float = 3 )

📘 Audio.ResumeMusic()

继续播放当前音乐，仅通过PauseMusic()暂停的音乐可使用。 

function Audio.ResumeMusic( fadeTime: float = 3 )

📘 Audio.GetPlayingMusic()

获取当前正在播放的声音ID（而非实例UUID），如无正在播放内容则返回-1。 

function Audio.GetPlayingMusic(): int

📘 Audio.PlayNatural()

播放一段音效\声音（2D），通过自然\背景音轨道（根据音频管理规范，持续背景声音播放建议使用此功能）。

背景音轨道理论支持无数个，通常适用于背景自然声音等场景。 

function Audio.PlayNatural( audioID: int, channel: int = 0, loop: bool = true, fadeTime: float = 3 ): string
/*
	audioID：声音ID
	channel：音轨ID（自定义数字）
	loop：是否循环播放
	fadeTime：过渡时间（秒）
*/

📘 Audio.StopNatural()

停止播放并销毁指定背景音轨道实例。

fadeTime表示过渡时间，如果为0则表示直接停止，文档后续参数同理。 

function Audio.StopNatural( channel: int = 0, fadeTime: float = 3 )
/*
	channel：音轨ID（指定播放的音轨）
	fadeTime：过渡时间（秒）
*/
Audio.PlayNatural(10, 0); //假设：0号音轨播放的是城市喧嚣背景
Audio.PlayNatural(20, 3); //假设：3号音轨
 
Audio.StopNatural(0); //停止0号音轨的播放声音，3号音轨不会受到影响

📘 Audio.StopAllNatural()

停止播放全部背景音轨声音。 

function Audio.StopAllNatural( fadeTime: float = 3 )

📘 Audio.SetWorldNaturalActive()

设置世界内置环境声音开关（例如：不同天气的环境声音）。

通常适用于希望实现一个环境安静的世界，或者希望完全手动控制环境声音。 

function Audio.SetWorldNaturalActive( active: bool )

📘 Audio.GetWorldNaturalActive()

获取世界内置环境声音开关。 

function Audio.GetWorldNaturalActive(): bool

📘 Audio.GetTotalVolume()

获取全局游戏音量1~100（只读）。

游戏音量数值是不允许通过代码修改的（只读），游戏音量完全遵循【玩家设置界面】的设定数值。 

function Audio.GetTotalVolume(): int

📘 Audio.GetSoundVolume()

获取游戏音效音量（通过PlaySound）1~100（只读）。 

function Audio.GetSoundVolume(): int

📘 Audio.GetMusicVolume()

获取游戏音乐音量（通过PlayMusic）1~100（只读）。 

function Audio.GetMusicVolume(): int

📘 Audio.GetNaturalVolume()

获取游戏音效（通过PlayNatural）音量1~100（只读）。 

function Audio.GetNaturalVolume(): int