360 lines
11 KiB
Markdown
360 lines
11 KiB
Markdown
---
|
||
sidebarDepth: 1
|
||
---
|
||
# 音效
|
||
|
||
# 索引
|
||
|
||
---
|
||
|
||
| 接口 | <div style="width: 3em"></div> | 描述 |
|
||
| --- | --- | --- |
|
||
| [DisableOriginMusic](音效.md#disableoriginmusic) | <span style="display:inline;color:#7575f9">客户端</span> | 停止原生背景音乐 |
|
||
| [PlayCustomMusic](音效.md#playcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 播放场景音效，包括原版音效及自定义音效 |
|
||
| [PlayCustomUIMusic](音效.md#playcustomuimusic) | <span style="display:inline;color:#7575f9">客户端</span> | 播放UI音效，包括原版音效及自定义音效 |
|
||
| [PlayGlobalCustomMusic](音效.md#playglobalcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 播放背景音乐 |
|
||
| [SetCustomMusicLoop](音效.md#setcustommusicloop) | <span style="display:inline;color:#7575f9">客户端</span> | 设定指定音乐是否循环播放，包括场景音效与背景音乐 |
|
||
| [SetCustomMusicLoopById](音效.md#setcustommusicloopbyid) | <span style="display:inline;color:#7575f9">客户端</span> | 设定指定音乐是否循环播放 |
|
||
| [StopCustomMusic](音效.md#stopcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件 |
|
||
| [StopCustomMusicById](音效.md#stopcustommusicbyid) | <span style="display:inline;color:#7575f9">客户端</span> | 停止场景音效 |
|
||
|
||
## DisableOriginMusic
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
停止原生背景音乐
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| disable | bool | True表示停止，False表示恢复 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 设置是否成功 |
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
comp.DisableOriginMusic(True)
|
||
```
|
||
|
||
|
||
|
||
## PlayCustomMusic
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
播放场景音效，包括原版音效及自定义音效
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| name | str | 音效名称 |
|
||
| pos | tuple(float,float,float) | 播放位置 |
|
||
| volume | float | 音量倍率，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小 |
|
||
| pitch | float | 播放速度，范围0-256，1表示原速，可以从json文件里进行修改 |
|
||
| loop | bool | 是否循环播放 |
|
||
| entityId | str | 绑定的实体id，默认为None，若有绑定的实体，则pos参数为相对于实体的坐标 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| str | 音乐播放id，可用于控制音乐的停止和循环 |
|
||
|
||
- 备注
|
||
- 当播放音乐错误时，将返回相应的错误id
|
||
| 错误 | 错误描述 |
|
||
| -- | -- |
|
||
| -1 | 无法在服务端播放音效 |
|
||
| -2 | 播放位置错误 |
|
||
| -3 | 已有同名背景音乐正在播放 |
|
||
| -4 | 播放失败 |
|
||
| -5 | 绑定实体不存在 |
|
||
| -6 | **位置距离本地玩家距离大于16格，跳过音效播放**（绑定实体的音效不受此限制） |
|
||
- 当背景音乐在播放的时候，请不要播放同名的场景音效
|
||
- 针对比较大的音乐，请将load_on_low_memory和stream设为true。但使用stream的音频无法同时播放两个音效实例，多次调用的效果是从头播放音频（不使用stream的音频，多次调用会同时播放多个）
|
||
- 该接口触发[PlaySoundClientEvent](../事件/音效.md#playsoundclientevent)
|
||
- 与示例对应的sound_definitions.json配置：
|
||
```json
|
||
{
|
||
"sound001": {
|
||
"min_distance": 0,
|
||
"max_distance": 20.0,
|
||
"sounds": [
|
||
{
|
||
"name": "sounds/testaudio/largeBlast1",
|
||
"load_on_low_memory": true,
|
||
"stream": true,
|
||
"pitch": 1,
|
||
"volume": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
musicId = comp.PlayCustomMusic("music.global0", (1,1,1), 1, 1, False, None)
|
||
```
|
||
|
||
|
||
|
||
## PlayCustomUIMusic
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
播放UI音效，包括原版音效及自定义音效
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| name | str | 音效名称 |
|
||
| volume | float | 音量倍率，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小 |
|
||
| pitch | float | 播放速度，范围0-256，1表示原速，可以从json文件里进行修改 |
|
||
| loop | bool | 是否循环播放 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| str | 音乐播放id，可用于控制音乐的停止和循环 |
|
||
|
||
- 备注
|
||
- 当播放音乐错误时，将返回相应的错误id
|
||
| 错误 | 错误描述 |
|
||
| -- | -- |
|
||
| -1 | 无法在服务端播放音效 |
|
||
| -2 | 播放失败 |
|
||
| -3 | 已有同名背景音乐正在播放 |
|
||
- 当背景音乐在播放的时候，请不要播放同名的场景音效
|
||
- 该接口触发[PlaySoundClientEvent](../事件/音效.md#playsoundclientevent)
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
musicId = comp.PlayCustomUIMusic("mob.cat.beg", 1, 1, False)
|
||
```
|
||
|
||
|
||
|
||
## PlayGlobalCustomMusic
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
播放背景音乐
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| name | str | 音乐名称 |
|
||
| volume | float | 音量大小，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小 |
|
||
| loop | bool | 是否循环播放 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 播放是否成功 |
|
||
|
||
- 备注
|
||
- 背景音乐同时仅能播放一个，当播放背景音乐时，会停止掉当前播放的音乐。这个规则也包括原版的背景音乐，所以为了避免原版背景音乐覆盖掉自定义背景音乐，建议先使用DisableOriginMusic屏蔽原版背景音乐。
|
||
- 背景音乐的优先级大于场景音效，当背景音乐在播放时，会让同名场景音效播放失败
|
||
- 背景音乐的播放速度需要从配置json里进行修改
|
||
- 针对比较大的背景音乐，请将load_on_low_memory和stream设为true
|
||
- 背景音乐需要在json里定义category为music
|
||
- 该接口触发[PlayMusicClientEvent](../事件/音效.md#playmusicclientevent)
|
||
- 与示例对应的sound_definitions.json配置：
|
||
```json
|
||
{
|
||
"Gsound001": {
|
||
"category": "music",
|
||
"sounds": [
|
||
{
|
||
"name": "sounds/testaudio/Music001",
|
||
"load_on_low_memory": true,
|
||
"stream": true,
|
||
"pitch": 1,
|
||
"volume": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
comp.PlayGlobalCustomMusic("Gsound001", 1, False)
|
||
```
|
||
|
||
|
||
|
||
## SetCustomMusicLoop
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
设定指定音乐是否循环播放，包括场景音效与背景音乐
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| name | str | 音乐名称 |
|
||
| loop | bool | True则循环播放，False则停止循环，停止会持续到播放到本次结束 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 停止是否成功 |
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
comp.SetCustomMusicLoop("soundName", True)
|
||
```
|
||
|
||
|
||
|
||
## SetCustomMusicLoopById
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
设定指定音乐是否循环播放
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| musicId | str | 音乐id，播放指定音乐获取的音乐id |
|
||
| loop | bool | True则循环播放，False则停止循环，停止会持续到播放到本次结束 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 停止是否成功 |
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
musicId = comp.PlayCustomMusic("sound001", (1,1,1), 1, 1, False, False)
|
||
comp.SetCustomMusicLoopById(musicId, True)
|
||
```
|
||
|
||
|
||
|
||
## StopCustomMusic
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| name | str | 音乐名称 |
|
||
| fadeOutTime | float | 停止的淡出时间，单位为秒，如果剩余时间小于淡出时间，将以剩余时间为准 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 停止是否成功 |
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
comp.StopCustomMusic("music.global0", 0)
|
||
```
|
||
|
||
|
||
|
||
## StopCustomMusicById
|
||
|
||
<span style="display:inline;color:#7575f9">客户端</span>
|
||
|
||
method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient
|
||
|
||
- 描述
|
||
|
||
停止场景音效
|
||
|
||
- 参数
|
||
|
||
| 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| musicId | str | 音乐id，播放指定音乐获取的音乐id |
|
||
| fadeOutTime | float | 停止的淡出时间，单位为秒 |
|
||
|
||
- 返回值
|
||
|
||
| <div style="width: 4em">数据类型</div> | 说明 |
|
||
| :--- | :--- |
|
||
| bool | 停止是否成功 |
|
||
|
||
- 示例
|
||
|
||
```python
|
||
import mod.client.extraClientApi as clientApi
|
||
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
|
||
musicId = comp.PlayCustomMusic("sound001", (1,1,1), 1, 1, False, False)
|
||
comp.StopCustomMusicById(musicId, 0)
|
||
```
|
||
|
||
|
||
|