法棍音乐

Boss Music

一款适用于 Minecraft 整合包的动态音频工具包。

自定义 Boss 与阶段音乐 • 语音登场 • 书籍旁白 • 结构配乐 • 基于条件的音频

Boss Music 让整合包作者能够控制玩家听到什么以及何时听到。将您自己的 Ogg Vorbis 文件放入配置文件夹，然后将它们连接到 Boss、阶段、书籍、结构、世界条件、玩家状态、命令或服务端事件。

该模组包含常见用例的简单 JSON 文件、用于复杂音景的高级规则引擎、游戏内音频工作室 (Audio Studio)，以及用于发现模组 Boss 如何表现其阶段的工具。它不附带受版权保护的歌曲，也不生成语音：您需要自己提供拥有分发权限的音频。

发布状态： 多加载器 2.1.0 版本已编译并通过自动化兼容性检查。使用真实音频、模组 Boss 和多人游戏的完整游戏内测试仍在进行中。在公开整合包中使用前，请备份您的实例并测试与您确切 Minecraft 版本和加载器匹配的构建版本。

✨ 亮点

功能	提供的特性
Boss 音乐	为任何已配置的实体分配自定义音乐，包括来自其他模组的 Boss。
Boss 阶段	根据生命值或同步实体数据更改音乐并播放新的语音。
语音登场	独立于主音轨播报 Boss 或新阶段。
书籍旁白	在打开匹配的成书或讲台上的书时播放录制的旁白。
结构音频	在已配置的原版或模组结构内播放音乐或发现旁白。
高级规则	组合实体、生物群系、维度、天气、时间、物品、效果、结构和服务器触发器。
播放控制	使用单次、循环或间隔播放，支持开头、主体、提示音和结尾。
混音	配置优先级、独占组、淡入淡出、类别、字幕和组闪避。
创作者工具	无需重建模组即可编辑、预览、验证、模拟、检查和记录战斗。

📦 支持的版本和加载器

Boss Music 2.1.0 为每个支持的 Minecraft 和模组加载器组合提供单独的构建版本。为您的实例选择恰好一个文件；这些文件不是通用的，也不可互换。

Minecraft	Java	加载器
1.20.1	Java 17	Forge, NeoForge, Fabric
1.21.1	Java 21	Forge, NeoForge, Fabric
1.21.11	Java 21	Forge, NeoForge, Fabric
26.1	Java 25	Forge, NeoForge, Fabric
26.1.1	Java 25	Forge, NeoForge, Fabric
26.1.2	Java 25	Forge, NeoForge, Fabric
26.2	Java 25	Forge, NeoForge, Fabric

• Fabric 构建版本需要 Fabric API。
• 针对 26.1 和 26.1.1 的 NeoForge 构建目前面向 NeoForge 测试版。
• 可选的 Configuration 集成并非在所有组合中都可用；Boss Music 的 JSON 文件和 Audio Studio 在没有它的情况下仍可正常工作。
• 当使用服务器端结构检测或服务器提示时，请在两端安装相同的 Minecraft、加载器和 Boss Music 构建版本。

🚀 快速开始

1. 安装与您确切的 Minecraft 版本和加载器匹配的 Boss Music 文件。
2. 对于 Fabric，请安装匹配的 Fabric API 版本。
3. 启动 Minecraft 一次以生成 config/bossmusic/。
4. 将您的 Ogg Vorbis .ogg 文件放入 config/bossmusic/music/。
5. 打开一个世界并按 F8，或运行 /bossmusic studio。
6. 创建或编辑规则，验证其音频路径，预览并保存。
7. 运行 /bossmusic validate 并在一个一次性世界中测试结果，然后再发布您的整合包。

Boss Music 会递归扫描音频文件夹，因此大型整合包可以保持文件井井有条：

config/bossmusic/
├── music/
│   ├── bosses/warden/intro.ogg
│   ├── bosses/warden/phase_1.ogg
│   ├── bosses/warden/phase_2.ogg
│   └── narration/ancient_city.ogg
├── tracks.json
├── books.json
├── structures.json
├── bossmusic-pack.schema.json
├── packs/
│   └── example.json
└── recordings/

JSON 中的路径相对于 music/ 目录，例如 bosses/warden/phase_1.ogg。Boss Music 在运行时创建一个虚拟资源包，因此用户无需为这些文件构建单独的 Minecraft 资源包。长音轨会从磁盘流式传输。

⚙️ 配置与功能

简单 Boss 配置

经典的 tracks.json 格式是添加 Boss 音乐、登场和阶段的最快方式：

{
  "tracks": [
    {
      "entity": "minecraft:warden",
      "music": [
        "bosses/warden/phase_1_a.ogg",
        "bosses/warden/phase_1_b.ogg"
      ],
      "voice": "bosses/warden/presentation.ogg",
      "radius": 48,
      "volume": 1.0,
      "category": "record",
      "music_mode": "loop",
      "voice_mode": "once",
      "fade_in": 40,
      "fade_out": 60,
      "mute_other_music": true,
      "require_line_of_sight": false,
      "phases": [
        {
          "health_below": 0.5,
          "music": "bosses/warden/phase_2.ogg",
          "voice": "bosses/warden/phase_2_intro.ogg"
        }
      ]
    }
  ]
}

在其配置半径内最近的匹配存活实体控制经典的 Boss 音轨。可选的视线检测可以要求玩家看到该实体。一个短暂的宽限期可防止传送或短暂卸载的 Boss 立即切断音乐。

music 和 voice 接受一个路径或备选路径列表。列表会为战斗选择一个备选项；它们不会同时播放每个文件。

检测 Boss 阶段

基于生命值的阶段使用从 0.0 到 1.0 的分数。许多模组 Boss 也通过 Minecraft 的同步实体数据暴露其真实阶段：

{
  "when": {
    "data_id": 17,
    "type": "int",
    "equals": "2"
  },
  "music": "bosses/example/final_phase.ogg",
  "voice": "bosses/example/final_phase_name.ogg"
}

每个 Minecraft Boss 没有通用的阶段值。使用扫描器或记录器来检查实际实体。优先使用稳定的布尔值或整数，避免连续变化的动画计数器。经典阶段只在同一次战斗中前进；治疗 Boss 不会将音轨移回较早的阶段。

书籍旁白

books.json 通过标题、作者、文本或其组合来匹配成书。旁白也适用于从讲台上打开的书。

{
  "books": [
    {
      "title": "The Lost Expedition",
      "author": "Archivist",
      "text_contains": "beneath the ancient city",
      "audio": "books/lost_expedition.ogg",
      "playback_mode": "once",
      "volume": 1.0,
      "category": "voice",
      "stop_on_close": true
    }
  ]
}

所有提供的匹配器都必须匹配。该模组播放您提供的录音；它不是文本转语音引擎。手持书籍时使用 /bossmusic book 检查其标题、作者和页数。

结构音乐与旁白

structures.json 可以将配乐和发现旁白附加到已注册的结构：

{
  "structures": [
    {
      "structure": "minecraft:ancient_city",
      "music": "structures/ancient_city.ogg",
      "narration": "structures/ancient_city_discovery.ogg",
      "music_mode": "loop",
      "narration_mode": "once",
      "volume": 0.8,
      "fade_in": 40,
      "fade_out": 60,
      "mute_other_music": true
    }
  ]
}

精确结构检测使用结构的真实边界，并且需要在逻辑服务器和客户端上都安装 Boss Music。服务器仅发送结构 ID；音频仍保留在每个玩家的本地。通过您的整合包在每个客户端安装音频和 JSON 文件。

高级模块化规则包

config/bossmusic/packs/*.json 中的文件提供了完整的规则引擎。它们按文件名顺序加载，并且可以包含任意数量的规则。每个包都有自己的命名空间和元数据，这使得分发不同模组的兼容包变得实用。

{
  "$schema": "../bossmusic-pack.schema.json",
  "pack": {
    "id": "my_pack",
    "name": "My Modpack Soundtrack",
    "author": "Pack Team",
    "version": "1.0.0",
    "license": "CC-BY-4.0",
    "enabled": true
  },
  "rules": [
    {
      "id": "warden_final_phase",
      "priority": 200,
      "exclusive_group": "main_music",
      "activation_delay_seconds": 1,
      "cooldown_seconds": 10,
      "minimum_active_seconds": 5,
      "when": {
        "all": [
          { "structure": "minecraft:ancient_city" },
          {
            "entity": "minecraft:warden",
            "radius": 48,
            "health_below": 0.5
          }
        ]
      },
      "audio": {
        "intro": "warden/phase_intro.ogg",
        "body": ["warden/final_a.ogg", "warden/final_b.ogg"],
        "stinger": "warden/phase_stinger.ogg",
        "outro": "warden/phase_outro.ogg",
        "mode": "loop",
        "shuffle": true,
        "fade_in": 40,
        "fade_out": 60,
        "volume": 1.0,
        "category": "record",
        "mute_other_music": true,
        "subtitle": "The Warden enters its final phase."
      }
    }
  ]
}

可用条件

分组	条件
实体	确切实体 ID、实体标签、模组命名空间、半径、生命值范围和同步数据。
世界	维度、生物群系、生物群系标签、结构、海拔、时间范围、降雨和雷暴。
玩家	已完成的进度、持有的物品或标签、装备的物品或标签以及激活的效果。
外部	通过命令或 Java API 触发的服务器触发器。
逻辑	嵌套的 all、any 和 not 条件树。

同一 exclusive_group 中的规则按优先级竞争，而不同组可以作为有意的音层播放。激活延迟可过滤闪烁的条件，最短激活时间窗口可防止快速切换，冷却时间可限制重复激活。

播放与混音

选项	行为
once	为当前激活播放一次。
loop	在规则保持激活状态时持续重新开始。
interval	在剪辑结束后等待 interval_seconds，然后再次播放。
intro	开篇剪辑，通常用于 Boss 播报。
body	由播放模式控制的主要音乐或旁白。
stinger	规则激活时触发的短效果音。
outro	规则结束或被替换时播放的收尾音。
duck_groups	在此规则激活时降低已配置的 Boss Music 组的音量。
subtitle	在 Minecraft 的动作栏区域显示无障碍文本。

支持的 Minecraft 音量类别为主音量、音乐、唱片、天气、方块、敌对生物、中立生物、玩家、环境及语音。当您希望自定义音乐拥有独立于原版背景音乐的音量滑块时，record 类别非常有用。

🎛️ 创作者工具

音频工作室 2.1 (Audio Studio)

在世界内按 F8 或运行 /bossmusic studio。引导式编辑器包含以下页面：

• 包标识、作者、许可证、规则 ID、优先级和组。
• 实体、检测半径、生命值阈值和同步数据。
• 开头、主体、提示音、结尾、播放模式和间隔。
• 音量、类别、淡入淡出、音乐静音和字幕。

您可以添加和移除阶段规则，验证 ID 和路径，预览可用音频，打开配置文件夹，并通过按钮或 Ctrl+S 保存。编辑器可能会在警告您后保存不完整的草稿，这在构建包时很有用。Audio Studio 配置播放；它不是音乐创作或波形编辑应用程序。

Boss 扫描仪与战斗记录器

当 Boss 的内部阶段系统未知时，直接看着它并使用这些工具：

/bossmusic debug scan
/bossmusic debug values
/bossmusic debug clear

/bossmusic record start
/bossmusic record mark
/bossmusic record status
/bossmusic record stop
/bossmusic record cancel

手动扫描仪会在可见转变前后比较同步值。记录器在战斗中跟随一个实体，并捕获生命值、同步数据、姿态、效果、无敌状态、附近的音效事件、附近的召唤物以及击败或失去追踪。

稳定变化优于噪声动画计数器。手动标记告诉分析器您何时观察到阶段转变。完成记录会创建：

• config/bossmusic/packs/recording_<boss>_<date>.json
• config/bossmusic/recordings/recording_<boss>_<date>.md

生成的包被有意禁用并使用占位音频路径。请审查每个检测器，添加真实音频，验证草稿，然后自行启用它。记录器提供候选建议；它不能保证内部值代表真实的游戏阶段。它记录事件和元数据，而非麦克风音频。

命令

客户端命令	用途
/bossmusic reload	重新扫描音频并重新加载配置。
/bossmusic studio	打开 Audio Studio。
/bossmusic here	列出附近的实体和已配置的经典音轨。
/bossmusic book	检查手持的成书。
/bossmusic structure	报告精确结构检测和当前配置的结构。
/bossmusic validate	查找格式错误的 JSON、无效 ID、缺失音频和重复规则。
/bossmusic debug audio	显示活动规则和第一个未满足的条件。
/bossmusic simulate <pack:rule>	临时强制加载本地规则。
/bossmusic stoprule	释放本地模拟的规则。

上一节中列出的记录和阶段调试命令也是客户端命令。格式错误的模块化包会被隔离开，以便有效的包可以继续加载；使用 /bossmusic validate 查看所有报告的问题。

服务器提示与整合包脚本

在服务器和客户端都安装了 Boss Music 的情况下，权限级别为 2 的命令可以为选定的玩家激活规则 ID：

/bossmusicserver play my_pack:quest_finale @a
/bossmusicserver play my_pack:danger @a[distance=..64]
/bossmusicserver stop my_pack:quest_finale @a

命令方块、数据包函数、任务系统、KubeJS、CraftTweaker 或其他脚本模组可以在不直接代码依赖 Boss Music 的情况下调用这些命令。执行服务器命令的确切方法取决于外部脚本模组和 Minecraft 版本。

Java API 也可用于服务器和客户端集成。服务器传输规则 ID 和共享的开始时间；每个客户端从本地包中解析实际的 Ogg 文件。不暴露可选的 Boss Music 网络通道的客户端将被跳过。

🔌 可选集成

当安装了兼容版本的 Configuration 模组时，Boss Music 可以注册一个传统的配置界面，其中包含针对 Boss、书籍和结构的经典槽位。packs/*.json 中的模块化文件保持独立，并且没有固定的槽位数量。

Minecraft	准备的集成
1.20.1 Forge / NeoForge	Configuration 3.1.0 旧版 Forge API
1.20.1 Fabric	未启用
1.21.1	对应加载器的 Configuration 3.1.1
1.21.11	对应加载器的 Configuration 4.1.0
26.x	未启用

注意： 不要仅为强制此集成而安装为另一个 Minecraft 版本构建的 Configuration。Boss Music 的 JSON 系统和 Audio Studio 不依赖 Configuration。

🖥️ 客户端与服务端安装

• 仅客户端： 本地 Boss 音乐、语音登场、书籍旁白、Audio Studio、扫描、记录和客户端条件。
• 客户端与服务端： 精确的已注册结构检测、同步的服务器提示，以及 /bossmusicserver。

网络通道对于普通连接是可选的，但服务端支持的功能需要双端兼容的通道。跨加载器网络尚未认证；请为这些功能在客户端和服务器上使用相同的加载器和构建版本。

🛠️ 故障排除与性能

没有音频播放

• 确认文件是真正的 Ogg Vorbis 格式，并带有小写的 .ogg 扩展名。
• 检查配置路径中的拼写、大小写、空格和子文件夹。
• 运行 /bossmusic reload，然后运行 /bossmusic validate。
• 检查规则类别所选的 Minecraft 音量滑块。
• 在 logs/latest.log 中查找被拒绝的声音或配置错误。

规则未激活

• 运行 /bossmusic debug audio。
• 检查报告为 false 的第一个条件。
• 检查优先级、独占组、激活延迟、最短激活时间和冷却时间。
• 使用 /bossmusic simulate pack:rule 来区分播放问题和触发问题。

Boss 阶段未改变

• 检查生命值阈值是否使用了预期的分数。
• 在可见阶段转变前后运行 /bossmusic debug scan。
• 记录完整的战斗并检查生成的 Markdown 时间线。
• 避免持续计数的动画刻度数据值。
• 请记住，经典阶段在同一次战斗中不会向后移动。

结构未被检测到

• 在客户端和服务器上安装匹配的 Boss Music 构建版本。
• 确保结构 ID 已注册并被规则引用。
• 使用 /bossmusic structure 检查当前状态。

性能建议

• 使用实用的实体半径，通常为 32 到 64 格。
• 为快速波动的条件添加激活延迟。
• 避免数百个具有非常大半径的无限制实体规则。
• 使用合理的 Ogg Vorbis 比特率；对于长时间背景音轨，无损质量的源音频是不必要的。
• 保持分层组在适中的音量，并使用闪避来处理重要的旁白。

📜 整合包使用与音频许可

Boss Music 专为整合包使用而设计。规则包可以按命名空间分离，重复的 ID 会被确定性地解析，后定义者替换先定义者并产生验证警告。

Boss Music 代码根据 MIT 许可证发布。该许可证不授予整合包作者添加的歌曲、表演或语音录音的权利。只分发您拥有或有权限使用的音频，保留所需的署名，并在包元数据中记录音频许可证。

将 Boss 战、发现、书籍、任务和整个维度转变为精心编排的音频体验。

通过 JSON 配置，使用 Audio Studio 可视化构建，或通过命令和代码驱动。