# 音效

# 索引


接口
描述
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)