Fight Music

FightMusic

FightMusic 是一款适用于 NeoForge 1.21.1 的模组，会在你进入战斗时用激烈的战斗音乐替换原版背景音乐。

这是一款轻量级的“外壳”模组：不附带任何音频文件。你可以通过资源包提供自己的音乐，然后在配置文件中将生物群系（以及可选的袭击事件）映射到对应曲目。

✨ 功能

• 🎵 战斗音乐状态机 — IDLE → ACTIVE → PAUSED支持平滑淡入/淡出，并可在战斗快速恢复时从上次进度继续播放。
• 🌍 基于生物群系播放音乐 — 可将任意生物群系 ID 或生物群系标签（例如 #minecraft:is_forest）映射到一首或多首曲目；多首曲目会随机选择。
• ⚔️ 袭击音乐 — 可选专属曲目，在你身处袭击事件期间播放；若未设置或曲目缺失，则自动切换为普通战斗音乐。
• 🎚️ 平滑淡入淡出与音量 — 可配置淡入淡出时长；音量遵循原版“音乐”滑块设置。
• 🐉 原版音乐覆盖 — 战斗期间抑制原版背景音乐，但绝不会打断末影龙 Boss 音乐或终末字幕诗篇。
• 🛠️ 真正的热重载 — 编辑 config/fightmusic.toml、使用游戏内配置界面（或 Configured），或运行 /fightmusic reload — 所有更改都会立即生效，无需重启。
• 🤝 客户端与服务器端均可选装 — 两端都安装此模组时，可可靠地由服务器检测状态；加入原版服务器时则会自动进行客户端检测（数据包通道注册为可选，因此可以正常加入）。
• 🐛 调试模式 — 可选的聊天日志记录（默认关闭），用于查看状态转换和握手状态。

📋 运行要求

• Minecraft 1.21.1
• NeoForge 21.1.x
• Java 21

🚀 安装

1. 将模组 jar 文件放入mods文件夹。
2. 启动一次游戏 — 这会生成 config/fightmusic.toml。
3. 创建（或下载）一个包含战斗音乐的资源包（见下文）。
4. 启用资源包，在配置中设置 enableMod = true，即可开始使用。

🎵 创建音乐包

FightMusic 会直接从资源包中读取音乐文件——无需sounds.json。将你的 OGG Vorbis文件放在以下路径下：

assets/fightmusic/sounds/battle/<file>.ogg

然后在 config/fightmusic.toml 中将生物群系映射到文件：

biome_map = [
    "minecraft:plains=plains_theme.ogg",
    "#minecraft:is_forest=forest_combat.ogg",
    "minecraft:ocean=ocean1.ogg, ocean2.ogg, ocean3.ogg",
    "default=generic_battle.ogg",
]

• 键：生物群系 ID（minecraft:plains）、生物群系标签（#minecraft:is_forest）或回退项 default。
• 值：一个或多个文件，以 , 分隔（随机选择其中一首）。
• 袭击音乐（[client] raidMusic）：可选曲目，在你身处袭击事件期间播放。

💡 详细的中文教程请见 docs/resource-pack-guide.md。

⚙️ 配置（config/fightmusic.toml）

⌨️ 命令

• /fightmusic reload — 热加载配置（仅限 OP）。

🤝 兼容性与说明

• 网络通道注册为可选，因此安装模组的客户端可以正常加入原版服务器，并自动回退到客户端检测。
• 如果某个群系没有映射，也没有default条目，则不会播放音乐（保持静音）——无效配置不会导致游戏崩溃；系统会回退到默认值并记录警告。
• 服务端驱动的检测按刻运行，并针对每位玩家单独执行——不会遍历整个实体列表。
• 多人游戏：双方都安装模组时，由服务端驱动战斗状态，客户端播放音乐。

📜 许可证

本项目采用MIT 许可证。详情请见LICENSE。

FightMusic（中文介绍）

FightMusic 是一个基于 NeoForge 1.21.1 的模组：当玩家进入战斗时，将原版背景音乐替换为紧张刺激的战斗音乐。

这是一个轻量"空壳"模组：它不内置任何音频文件。你需要通过资源包提供自己的音乐，然后在配置文件中把群系（以及可选的袭击事件）映射到你的曲目。

✨ 功能特性

• 🎵 战斗音乐状态机 —— IDLE → ACTIVE → PAUSED，支持平滑淡入/淡出，快速重新接敌时从原进度续播。
• 🌍 群系驱动音乐 —— 可将任意群系 ID 或群系标签（如 #minecraft:is_forest）映射到一首或多首曲目；多首随机播放。
• ⚔️ 袭击音乐 —— 可选的专属曲目，在袭击事件范围内播放；未设置或文件缺失时自动回退到普通战斗音乐。
• 🎚️ 平滑淡入淡出与音量 —— 淡入淡出时长可配置；音量跟随原版"音乐"滑块。
• 🐉 原版音乐拦截 —— 战斗时抑制原版背景音乐，但绝不中断末影龙 Boss 战音乐与终末之诗。
• 🛠️ 真正的热加载 —— 修改 config/fightmusic.toml、使用游戏内配置界面（或 Configured）、或执行 /fightmusic reload，均无需重启即生效。
• 🤝 客户端/服务端均可选装 —— 两端都装时由服务端驱动检测（高效）；加入原版服务器时自动回退到客户端自行检测（网络通道已注册为可选，进服不受影响）。
• 🐛 调试模式 —— 可选聊天日志（默认关闭），用于观察状态切换与握手连接状态。

📋 环境要求

• Minecraft 1.21.1
• NeoForge 21.1.x
• Java 21

🚀 安装方法

1. 将模组 jar 放入 mods 文件夹。
2. 启动一次游戏，自动生成 config/fightmusic.toml。
3. 制作（或下载）一个包含战斗音乐文件的资源包（见下文）。
4. 启用资源包，并在配置中把 enableMod 设为 true，即可开玩。

🎵 制作音乐资源包

FightMusic 直接从资源包读取音乐文件——无需 sounds.json。将你的 OGG Vorbis 文件放到：

assets/fightmusic/sounds/battle/<文件名>.ogg

然后在 config/fightmusic.toml 中将群系映射到文件：

biome_map = [
    "minecraft:plains=plains_theme.ogg",
    "#minecraft:is_forest=forest_combat.ogg",
    "minecraft:ocean=ocean1.ogg, ocean2.ogg, ocean3.ogg",
    "default=generic_battle.ogg",
]

• 键：群系 ID（minecraft:plains）、群系标签（#minecraft:is_forest）或兜底 default。
• 值：一个或多个文件，用逗号和空格分隔（随机播放其中一首）。
• 袭击音乐（[client] raidMusic）：袭击事件范围内播放的专属曲目（可选）。

💡 更详细的教程见 docs/resource-pack-guide.md。

⚙️ 配置说明（config/fightmusic.toml）

⌨️ 命令

• /fightmusic reload —— 热重载配置文件（仅 OP 可用）。

🤝 兼容性与说明

• 网络通道已注册为可选，安装本模组的客户端可以正常加入原版服务器，并自动切换为客户端自行检测。
• 若群系没有映射，也没有 default，则不会播放音乐（静音）；配置错误绝不会导致崩溃，而是回退到默认值并输出警告。
• 服务端检测按 Tick 运行并限定在玩家范围内，绝不会遍历全图实体。
• 联机时：双方都安装本模组，则由服务端驱动战斗状态，客户端负责播放音乐。

📜 开源许可

本项目采用 MIT License 开源，详见 LICENSE。