MC 开发者文档

# 自定义音乐

# MC音频管理介绍

# 音频引擎

MC内置音频管理使用的是业界著名音频引擎 FMOD，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：是否在低内存占用情况下加载

# 音频播放时机

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

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

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

# MOD自定义音频设置

在Mod中使用自定义音频一共有两种方式：addon 数据驱动 和 Mod SDK 接口。两种方式均需要在 Mod中添加对应的json配置。

# 音频动态加载设置

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

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

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

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

# 音频资源设置

  1. resource目录下创建sounds文件夹

  2. 新增sound_definitions.json

    • 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内容。该方式适合开发者想要继承原版游戏内音乐播放时机且想改变音乐内容时，不需要额外设置代码。

    • Mod SDK接口调用:

      查看服务端systemAudio接口。通常情况下如果开发者通过 SDK接口来调用播放音乐时，我们建议使用 dy_load_list 字段设置需要播放音乐，因为这种情况下只有用到该音乐才会加载和播放，减小内存压力。

  3. 上一步json中新增定义中的目录下添加对应的音乐资源文件。

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

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

# 播放设置

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

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

# 示例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效果，根据距离的远近音量发生变化

← 微缩方块 →