战斗音乐

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）

分区	选项	默认值	说明
client	enableMod	false	总开关；关闭时完全不拦截原版音乐
client	fadeInDuration	3.0	淡入时长（秒）
client	fadeOutDuration	3.0	淡出时长（秒）
client	resumeTimeout	10.0	脱战后挂起等待时间（秒）
client	combatCooldown	0.0	曲目播放间隔（0 = 循环当前曲目）
client	raidMusic	""	袭击专属战斗音乐（留空 = 关闭）
client	clientSideDetection	true	原版服务器下客户端自行检测
client	clientDetectionRange	32.0	客户端检测范围（格）
client	clientDetectionFrequency	10	客户端检测频率（Tick）
client	debugLogging	false	在聊天栏显示状态切换/握手调试信息
server	trackingFrequency	20	服务端实体验证频率（Tick）
biome_map	—	—	群系 → 音乐文件映射（可增删、可热加载）

⌨️ 命令

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

🤝 兼容性与说明

• 网络通道已注册为可选，模组客户端可正常进入原版服务器，并自动回退到客户端自行检测。
• 若群系无映射且无 default，则不播放音乐（静音）；配置错误绝不会导致崩溃，而是回退默认值并输出警告。
• 服务端检测基于 Tick 且按玩家作用域，绝不遍历全图实体。
• 联机时：两端都装模组时由服务端驱动战斗状态，客户端负责播放音乐。

📜 开源许可

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