FightMusic

FightMusic is a NeoForge 1.21.1 mod that replaces the vanilla background music with intense battle music while you are in combat.

It is a lightweight "shell" mod: it ships no audio files. You provide your own music through a resource pack, then map biomes (and optionally raids) to your tracks via the config file.

---

✨ Features

• 🎵 Combat music state machine — IDLE → ACTIVE → PAUSED with smooth fade-in / fade-out and resume-from-progress when combat resumes quickly.
• 🌍 Biome-based music — map any biome ID or biome tag (e.g. #minecraft:is_forest) to one or more tracks; multiple tracks are chosen randomly.
• ⚔️ Raid music — an optional dedicated track played while you are inside a raid event; automatically falls back to normal battle music when unset or missing.
• 🎚️ Smooth fades & volume — configurable fade durations; volume follows the vanilla "Music" slider.
• 🐉 Vanilla music override — suppresses vanilla background music during combat, but never interrupts the Ender Dragon boss music or the end-credits poem.
• 🛠️ True hot reload — edit config/fightmusic.toml, use the in-game config screen (or Configured), or run /fightmusic reload — all applied without restarting.
• 🤝 Client & server optional — reliable server-driven detection when the mod is on both sides; automatic client-side detection when joining a vanilla server (payload channels are registered as optional, so joining works normally).
• 🐛 Debug mode — optional chat logging (off by default) to observe state transitions and handshake status.

📋 Requirements

• Minecraft 1.21.1
• NeoForge 21.1.x
• Java 21

🚀 Installation

1. Put the mod jar into the mods folder.
2. Launch the game once — this generates config/fightmusic.toml.
3. Create (or download) a resource pack containing your battle music (see below).
4. Enable the resource pack, set enableMod = true in the config, and you're ready.

🎵 Creating a Music Pack

FightMusic reads music files directly from resource packs — no sounds.json needed. Place your OGG Vorbis files under:

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

Then map biomes to files in 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",
]

• Key: a biome ID (minecraft:plains), a biome tag (#minecraft:is_forest), or the fallback default.
• Value: one or more files separated by , (one is chosen randomly).
• Raid music ([client] raidMusic): an optional track played while you are within a raid event.

💡 A detailed Chinese tutorial is available in docs/resource-pack-guide.md.

⚙️ Configuration (config/fightmusic.toml)

Section	Option	Default	Description
client	enableMod	false	Master switch; when off, vanilla music is never overridden
client	fadeInDuration	3.0	Fade-in duration (seconds)
client	fadeOutDuration	3.0	Fade-out duration (seconds)
client	resumeTimeout	10.0	Pause-wait after leaving combat (seconds)
client	combatCooldown	0.0	Gap between tracks (0 = loop the current track)
client	raidMusic	""	Dedicated raid battle music (empty = disabled)
client	clientSideDetection	true	Client-side combat detection for vanilla servers
client	clientDetectionRange	32.0	Client detection radius (blocks)
client	clientDetectionFrequency	10	Client detection interval (ticks)
client	debugLogging	false	Show state-transition / handshake debug messages in chat
server	trackingFrequency	20	Server entity-check interval (ticks)
biome_map	—	—	Biome → music file list (editable, hot-reloadable)

⌨️ Commands

• /fightmusic reload — hot-reload the config (OP only).

🤝 Compatibility & Notes

• Network channels are registered as optional, so modded clients can join vanilla servers normally and automatically fall back to client-side detection.
• If a biome has no mapping and no default entry, no music plays (silence) — invalid config never crashes the game; it falls back to defaults and logs a warning.
• Server-driven detection is tick-based and scoped per player — it never iterates the whole entity list.
• Multiplayer: when both sides run the mod, the server drives combat state; the client plays the music.

📜 License

This project is licensed under the MIT License. See LICENSE for details.

---

---

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。