YSM 文档与教程

简体中文

English

外观

添加音频

约 1978 字大约 7 分钟

2025-01-28

2.3.0 版本起，Yes Steve Model 模组支持在动画里调用音频了，但是有一些注意事项：

  • 音频文件可以内置于模型包内，也支持调用原版游戏的音频。
  • 默认情况下，内置的音频需要放置在目录下的 sounds 文件夹里。
  • 需要使用新版的文件结构才能使用音频，旧版结构无法使用。
  • 音频必须为 ogg 格式。建议使用单声道，这样游戏内才能听到立体声效果。
  • 单个音频不允许超过 4M，整个模型文件不允许超过 66M。

我该如何转换音频？

音频转换的工具很多，常用的有格式工厂和 Adobe Audition。格式工厂简单易用，方便新手使用。

格式工厂下载：官网 腾讯软件中心

Adobe Audition 是专业音频制作软件，上手有门槛，但是功能更为强大！

当然，您也可以使用其他转换工具，例如：Audacity、FFmpeg 等，只要能转换为 ogg 格式即可。

添加步骤

  1. 新建音频文件夹

    文件夹名为固定名称：sounds

    1.png

  2. 添加 .ogg 文件

    仅能使用 ogg 格式，其他格式（wav 或者 mp3 等需要转换）

    4.png

  3. 在 BlockBench 内为动画添加音频

    3.png

音频名如何书写？

内置音频

如果你的音频路径是 sounds/啊哈哈哈.ogg，那么你只需要在基岩版动画的音频关键帧里填写 啊哈哈哈 即可，不需要加 sounds 前缀和 ogg 后缀。

我想换个文件夹放音频，能自定义么？

可以，首先你需要给你的 ysm.json 的 files 字段中新增 sound_path 字段，填写你想放置音频的文件夹路径。

写法参考如下：

ysm.json
{
    "files": {
        // 支持任意字符
        // 后续基岩版动画里音频关键帧填写的名称和上述一致，不需要添加此文件夹前缀和 ogg 后缀
        "sound_path": "声音文件夹"
    }
}

原版游戏音频

如果你在基岩版动画的音频关键帧里填写的是原版音频的 ID（类似于：minecraft:block.anvil.hit），那么会调用原版音频进行播放。

原版资源包也可以添加额外的音频文件，并且支持音频随机播放和权重设置，详情可查看官方相关教程：

提示

我们强烈建议您使用原版资源包来添加音频，这样可以减少模型文件的大小，还能避免在某些情况下可能出现的版权问题。

2.5.3 版本音频系统更新

本节说明 2.5.3 之后音频系统的两个关键变化：

  1. 更多位置可以触发音频：例如动画控制器的音效、进入时/退出时。
  2. 新增“播放上下文”：声音会被归属到某个上下文中，决定它什么时候会被自动停止，以及 stop 默认能停止哪一类声音。

动画控制器音效

BlockBench 中在动画控制器里附加的音效已支持。 音效会在进入该状态时触发：先执行“进入时”的 Molang，再开始播放该音效。

动画控制器音效

播放上下文

从 2.5.3 起，每个播放实例都会归属到某个播放上下文，并按对应规则自动停止。

你可以把每一次播放理解为创建了一个“播放实例”。

动画上下文

由以下方式触发的音频属于动画上下文：

  • 动画内的音效关键帧
  • 动画内的命令关键帧 Molang
  • 脚本控制器 Molang

自动停止时机：动画结束或进入下一轮循环时自动停止。

动画上下文示意

动画控制器上下文

由以下方式触发的音频属于动画控制器上下文：

  • 动画控制器里配置的音效
  • 动画控制器“进入时/退出时” Molang 创建的播放实例

自动停止时机：当前动画控制器切换到其他状态时自动停止。

全局上下文

由以下方式触发的音频属于全局上下文：

  • 轮盘 Molang
  • 游戏指令执行 Molang
  • 其他 Molang 事件

自动停止时机：不会自动停止。
但在以下情况会强制停止所有播放实例：切换模型、实体被移除、传送到其他维度。

常见注意事项

  • 脚本控制器里需要在 set_animation 或 reset 之后再创建播放实例，否则播放实例可能会立刻被重置。
  • 使用 ysm.sync 触发 sync 事件创建的播放实例属于全局上下文（不属于 ysm.sync 调用点所在的上下文）。

主动停止

除了“播放完毕后停止”和“上下文自动停止”之外，还可以使用 Molang 主动停止：ysm.stop_sound 与 ysm.stop_all_sounds。

从 2.5.3 起，这两个函数默认只会停止当前上下文内的播放实例（对其他上下文无效）。

  • ysm.stop_sound(id, global?)
  • ysm.stop_all_sounds(global?)

其中可选参数 global：

  • global = 1：停止全局上下文的播放实例
  • global = 0 或不写：停止当前上下文的播放实例

示例：

ysm.stop_sound('fx', 1)
ysm.stop_all_sounds(0)
ysm.stop_all_sounds

Molang 相关改动（2.5.3）

旧版本音频相关 Molang 如下表所示；2.5.3 在保持兼容的同时扩展了参数能力：

Molang描述
ysm.play_sound('id', 'sound_name', boolean, volume, pitch)播放音频，id为该音频的标识
ysm.stop_sound('id')停止音频，id为该音频的标识
ysm.stop_all_sounds停止所有 molang 添加而播放的音频

播放参数：从 boolean 变为 flags（整数）

ysm.play_sound(id, name, flags?) 的第三个参数在旧版本常被当作 boolean（0/1）。
从 2.5.3 起，它更准确的含义是 flags（整数标志位，可叠加）：

  • +1：强制重播（有同名播放实例时，停止旧的并创建新的）
  • +2：按全局上下文创建播放实例（忽略当前上下文）
  • +4：循环播放

你可以只取其中一项，也可以叠加：

ysm.play_sound('fx', 'sample', 1) // 强制重播
ysm.play_sound('fx', 'sample', 2) // 全局上下文
ysm.play_sound('fx', 'sample', 4) // 循环播放
ysm.play_sound('fx', 'sample', 7) // 1+2+4：强制 + 全局 + 循环

音频 id：支持数字

ysm.play_sound 的 id 参数旧版本只能是字符串；新版本也可以是不小于 0 的数值：

ysm.play_sound(1, 'sample') // 创建并命名为 1
ysm.stop_sound(1)           // 停止 id 为 1 的播放实例

匿名播放实例：id = 0

2.5.3 引入“匿名播放实例”：当 id = 0 时，每次调用都会创建新的播放实例，允许多个同名声音同时存在（此时“强制重播”无效）。

注意：

  • 匿名播放实例仍然受“播放上下文”影响。
  • ysm.stop_sound 无法停止匿名播放实例。
  • ysm.stop_all_sounds 会停止所有匿名播放实例。
  • 动画音效关键帧、动画控制器音效创建的都是匿名播放实例。

Opus 音频

2.5.3 改进了 Opus 解码器，以获得更好的播放效果。

Opus 相比常见的 Vorbis 通常能在相同体积下提供更好的音质。你可以在这里下载适用于 YSM 的 Opus 编码工具（仍然输出为 .ogg 文件）：

ysm_sound_converter_v1.1.zip2.11 MB