# 自定义音乐

# MC音频管理介绍

# 音频引擎

MC内置音频管理使用的是业界著名音频引擎 FMOD (opens new window)，MC中音频管理主要是通过 SoundSystemFMOD 类对FMOD的API进行封装和调用。

# 游戏音频

# 音频定义

在MC游戏中，音频资源文件定义在data\resource_packs\vanilla\sounds目录下的 music_definitions.json 和 sound_definitions.json 中。

music_definitions.json：定义了触发音乐的事件名和延迟信息
sound_definitions.json：定义了具体的音频内容，其中category字段设置改音乐的分类情况

# sound_definitions.json单项介绍

  "record.13": {
    "max_distance": 64.0,
    "sounds": [
      {
        "name": "sounds/music/game/records/13",
        "stream": true,
        "volume": 0.5,
        "load_on_low_memory": true
      }
    ]
  },
  //...
    "music.game.endboss": {
    "category": "music",
    "sounds": [
      {
        "name": "sounds/music/game/end/boss",
        "stream": true,
        "volume": 0.3,
        "load_on_low_memory": true
      }
    ]
  },

如代码所示，每个音乐项目可以有多个字段组成:

category：音乐的分类，同时可以作音频文件分类的文件夹目录
- ui：是否为UI分类
- music：是否为歌曲分类
- weather 等其他各种分类值
min_distance：最小距离，当选择在某个地点播放音乐时，触发音乐播放的最近距离
max_distance：最大距离，同上，触发音乐播放的最大距离
sounds：播放的音乐，数组定义
- name：音乐文件名称
- stream：是否为流式文件，设置为true时，可以减小内存占用，但该音频文件同一时间内只允许播放一个，建议较大的BGM音频使用。
- volume：声量大小
- load_on_low_memory：是否在低内存占用情况下加载

# music_definitions.json单项介绍

{
   "creative" : {//播放背景音乐的场景，这里的creative代表在创造模式下播放
      "event_name" : "music.game.creative",//触发播放音乐的事件名称
      "max_delay" : 180,
      "min_delay" : 60
   },
    //...其他定义
    //...其他定义
   "endboss" : {
      "event_name" : "music.game.endboss",
      "max_delay" : 180,
      "min_delay" : 60
   },

如代码所示，该json文件用于指定某些固定场景下播放的游戏背景音乐，包括如下字段

event_name：触发播放对应音乐的事件名称,即sound_definitions.json中每个音效定义项的键名，如上文中的music.game.endboss，支持填写自定义的键名
max_delay：触发该音乐播放事件时的最大延迟
min_delay：触发该音乐播放事件的最小延迟
此json文件支持填写的键名（如代码中的creative和endboss）由MC游戏固定，不支持自定义，目前版本支持填写的键名如下：

键名	含义
creative	创造模式
credits	终末之诗
crimson_forest	绯红森林
dripstone_caves	溶洞
end	末地
endboss	末影龙
frozen_peaks	冰封山峰
game	常规游戏
grove	雪地
hell	下界荒地
jagged_peaks	尖峭山峰
lush_caves	繁茂洞穴
meadow	草甸
menu	主菜单
nether	下界
snowy_slopes	积雪的山坡
soulsand_valley	灵魂沙峡谷
stony_peaks	裸岩山峰
water	水下

# 音频播放时机

Minecraft包含由C418创作的音乐。这些音乐在游戏的各个地方播放，包括主菜单、创造模式、下界以及在创作人员列表中。在基岩版中，音乐被归类为DLC 官方wiki (opens new window)。

同时使用物品也能发出声音：

唱片机 (opens new window)：播发游戏中所有可用的音乐唱片
音乐盒 (opens new window)：接收红石信号后发声，音乐盒发出的声音取决于音乐盒下面的方块材料，每次使用音符盒都会让其下一个发出音符的音高提高半阶。按照十二平均律，每个乐器有两个八度（24个半音）的音域可供选择。

# MOD自定义音频设置

在Mod中使用自定义音频一共有三种方式：addon 数据驱动、 Mod SDK接口和music指令。三种方式均需要在 Mod中添加对应的自定义音效资源配置。

# 音频资源设置

resource目录下创建sounds文件夹
新增sound_definitions.json
- 修改/新增一项音效资源参照MC游戏内置资源目录下的同名文件设置，设置对应情形下的音频文件内容。例如：
```
{
  "music.game.creative": {
    "category": "music",
    "sounds": [
      {
        "name": "sounds/music/game/creative/1",
        "stream": true,
        "volume": 0.1,
        "load_on_low_memory": true
      }
    ]
  }
}
```
  上述代码设置了创造模式下的BGM内容。该方式适合开发者想要继承原版游戏内音乐播放时机且想改变音乐内容时，不需要额外设置代码。
- 动态加载设置:
  
  当开发者使用ModSDK接口播放音乐时（详见 PlayCustomMusic接口），我们建议使用 dy_load_list 字段设置需要播放音乐(详见下面的音频动态加载设置)，因为这种情况下只有用到该音乐才会加载和播放，减小内存压力。
上一步json中新增定义中的目录下添加对应的音乐资源文件。

例如：sounds\music\game\中增加1.ogg文件

注意：当前版本音乐文件支持的格式为 .ogg ，常用 mp3 格式并不支持。

# 播放设置

Mod SDK接口播放：使用Mod SDK接口可以控制音乐的播放,简要介绍如下，详细内容可以查看MOD SDK中 customAudio 组件接口详细介绍

DisableOriginMusic 屏蔽原生音乐 PlayGlobalCustomMusic 播放全局自定义背景音乐，优先级最高 PlayCustomMusic 指定位置播放音乐

Music指令播放：可通过MC原生的music指令调用音效：详见音乐指令Wiki (opens new window)，music指令支持sound_definitions.json中定义的所有音效，包括原生音效键和自定义的音效键，如music.game.custom1。

# 音频动态加载设置

音频默认为启动时全部加载，当mod的音频资源较多时，建议控制启动时加载音频的数量。

控制方式如本文介绍的sound_definitions.json所示，在json文件中添加key值 dy_load_list，对应的value为list。该list中记录的sound在游戏启动的时候默认不加载，只有在用到的时候才会加载。可有效抑制由于音频资源占用内存过多造成的启动时的崩溃。

{
  "dy_load_list":[
    "sounds/music/game/creative/1",
    "sounds/customSound/2",
    "sounds/customSound/3",
    "sounds/customSound/4",
    "sounds/customSound/5"
],
# other code

当前引擎已经支持音频的LRU管理(一种内存管理算法)，所以当音频资源较多的时候，引擎会动态控制音频占用的内存资源。

# 示例DEMO介绍

示例demo为customMusicDemo，主要展示当前自定义音乐的两种设置形式：数据驱动的addon形式和mod sdk接口调用形式。其中接口调用有两种方法，一个是全局唯一BGM的播放，一个是指定位置音效的播放。

# 替换BGM

在``sound_definitions.json`中，mod替换了原版创造模式下的BGM

  "music.game.creative": {
    "category": "music",
    "sounds": [
      {
        "name": "sounds/music/game/creative/1",
        "stream": true,
        "volume": 0.1,
        "load_on_low_memory": true
      }
     
    ]
  },

# 根据位置变化切换BGM

DEMO中玩家如果进入

self.global0Area =[(0,0), (5,5)] # 即最小点的x，z坐标为(0,0)，最大点为(5,5)的矩形区域 self.global1Area =[(-5,-5), (0,0)]

两个区域，会调用PlayGlobalCustomMusic播放对应的BGM，在调用此函数之前需要调用DisableOriginMusic停止播放内置的BGM。

# 指定地点播放音乐

当玩家接近如下的圆形区域时

self.campPoint = (20,4,20)

self.campRadius = 5

会调用PlayCustomMusic在营地播放对应的音乐，该音乐的定义如下

  "music.custom": {
    "min_distance": 0.0,
    "max_distance": 5.0,
    "sounds": [
      {
        "name": "sounds/customSound/4",
        "pitch": 1,
        "volume": 1,
        "load_on_low_memory": true,
        "stream": true
      }
    ]
  }

可以指定因为的最小和最大播放范围，此时的音乐是3d效果，根据距离的远近音量发生变化

← 自定义状态效果微缩方块 →