音效

索引

---

接口		描述
DisableOriginMusic	客户端	停止原生背景音乐
PlayCustomMusic	客户端	播放场景音效，包括原版音效及自定义音效
PlayCustomUIMusic	客户端	播放UI音效，包括原版音效及自定义音效
PlayGlobalCustomMusic	客户端	播放背景音乐
SetCustomMusicLoop	客户端	设定指定音乐是否循环播放，包括场景音效与背景音乐
SetCustomMusicLoopById	客户端	设定指定音乐是否循环播放
StopCustomMusic	客户端	停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件
StopCustomMusicById	客户端	停止场景音效

DisableOriginMusic

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  停止原生背景音乐

• 参数

  参数名	数据类型	说明
  disable	bool	True表示停止，False表示恢复

• 返回值

  数据类型	说明
  bool	设置是否成功

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.DisableOriginMusic(True)

PlayCustomMusic

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  播放场景音效，包括原版音效及自定义音效

• 参数

  参数名	数据类型	说明
  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参数为相对于实体的坐标

• 返回值

  数据类型	说明
  str	音乐播放id，可用于控制音乐的停止和循环

• 备注

  • 当播放音乐错误时，将返回相应的错误id

    错误	错误描述
    -1	无法在服务端播放音效
    -2	播放位置错误
    -3	已有同名背景音乐正在播放
    -4	播放失败
    -5	绑定实体不存在
    -6	位置距离本地玩家距离大于16格，跳过音效播放（绑定实体的音效不受此限制）

  • 当背景音乐在播放的时候，请不要播放同名的场景音效
  • 针对比较大的音乐，请将load_on_low_memory和stream设为true。但使用stream的音频无法同时播放两个音效实例，多次调用的效果是从头播放音频（不使用stream的音频，多次调用会同时播放多个）
  • 该接口触发PlaySoundClientEvent
  • 与示例对应的sound_definitions.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
          }
        ]
      }
    }
    

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
musicId = comp.PlayCustomMusic("music.global0", (1,1,1), 1, 1, False, None)

PlayCustomUIMusic

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  播放UI音效，包括原版音效及自定义音效

• 参数

  参数名	数据类型	说明
  name	str	音效名称
  volume	float	音量倍率，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小
  pitch	float	播放速度，范围0-256，1表示原速，可以从json文件里进行修改
  loop	bool	是否循环播放

• 返回值

  数据类型	说明
  str	音乐播放id，可用于控制音乐的停止和循环

• 备注

  • 当播放音乐错误时，将返回相应的错误id

    错误	错误描述
    -1	无法在服务端播放音效
    -2	播放失败
    -3	已有同名背景音乐正在播放

  • 当背景音乐在播放的时候，请不要播放同名的场景音效
  • 该接口触发PlaySoundClientEvent

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
musicId = comp.PlayCustomUIMusic("mob.cat.beg", 1, 1, False)

PlayGlobalCustomMusic

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  播放背景音乐

• 参数

  参数名	数据类型	说明
  name	str	音乐名称
  volume	float	音量大小，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小
  loop	bool	是否循环播放

• 返回值

  数据类型	说明
  bool	播放是否成功

• 备注

  • 背景音乐同时仅能播放一个，当播放背景音乐时，会停止掉当前播放的音乐。这个规则也包括原版的背景音乐，所以为了避免原版背景音乐覆盖掉自定义背景音乐，建议先使用DisableOriginMusic屏蔽原版背景音乐。
  • 背景音乐的优先级大于场景音效，当背景音乐在播放时，会让同名场景音效播放失败
  • 背景音乐的播放速度需要从配置json里进行修改
  • 针对比较大的背景音乐，请将load_on_low_memory和stream设为true
  • 背景音乐需要在json里定义category为music
  • 该接口触发PlayMusicClientEvent
  • 与示例对应的sound_definitions.json配置：

    {
      "Gsound001": {
        "category": "music",
        "sounds": [
          {
            "name": "sounds/testaudio/Music001",
            "load_on_low_memory": true,
            "stream": true,
            "pitch": 1,
            "volume": 1
          }
        ]
      }
    }
    

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.PlayGlobalCustomMusic("Gsound001", 1, False)

SetCustomMusicLoop

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  设定指定音乐是否循环播放，包括场景音效与背景音乐

• 参数

  参数名	数据类型	说明
  name	str	音乐名称
  loop	bool	True则循环播放，False则停止循环，停止会持续到播放到本次结束

• 返回值

  数据类型	说明
  bool	停止是否成功

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.SetCustomMusicLoop("soundName", True)

SetCustomMusicLoopById

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  设定指定音乐是否循环播放

• 参数

  参数名	数据类型	说明
  musicId	str	音乐id，播放指定音乐获取的音乐id
  loop	bool	True则循环播放，False则停止循环，停止会持续到播放到本次结束

• 返回值

  数据类型	说明
  bool	停止是否成功

• 示例

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

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件

• 参数

  参数名	数据类型	说明
  name	str	音乐名称
  fadeOutTime	float	停止的淡出时间，单位为秒，如果剩余时间小于淡出时间，将以剩余时间为准

• 返回值

  数据类型	说明
  bool	停止是否成功

• 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.StopCustomMusic("music.global0", 0)

StopCustomMusicById

客户端

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

• 描述

  停止场景音效

• 参数

  参数名	数据类型	说明
  musicId	str	音乐id，播放指定音乐获取的音乐id
  fadeOutTime	float	停止的淡出时间，单位为秒

• 返回值

  数据类型	说明
  bool	停止是否成功

• 示例

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)