Effective Instruments

有效乐器

奏响音乐。强化盟友。或诅咒敌人。有效乐器为你喜爱的乐器模组加入了魔法光环系统，让演奏者在演奏时为附近的玩家和驯服的宠物施加药水效果；如果选择负极性变体，则会对附近的生物施加减益效果。每种乐器都有独特的正向和攻击性光环——拿起一把风之歌竖琴，感受微风让你的步伐更加轻快（正向）；或者召来呼啸的狂风，减缓范围内所有敌人的速度并削弱它们（攻击性）。

1.5.0 版本新增内容：

• Genshin Instruments 现在是可选项！有效乐器可与 Genshin Instruments（基于屏幕、原地演奏的乐器）、Immersive Melodies（可移动演奏的被动乐器）或两者同时搭配使用。选择你偏好的后端即可——模组会自动适配。
• 独立的 Immersive Melodies 模式——只安装 IM 和有效乐器即可，无需 GI；移动光环等级也会按预期生效。
• /effectiveinstruments diagnose 现在会优先报告后端可用情况，管理员无需查看日志即可确认检测到了哪些后端。
• 依赖隔离——GI 的类加载已通过兼容层完全隔离。缺少 GI 时不会出现 NoClassDefFoundError。

1.4.x 版本新增内容：

• 攻击性（负向）光环——每种乐器都有对应的减益变体（凋零、中毒、缓慢、失明等）。选择带红色边框的图标，即可随时切换极性。
• 乐器耐久度——乐器现在会在使用时磨损（每件乐器的 NBT 耐久度独立计算），并可在铁砧上修复。每个乐器栏位下方都会显示原版风格的耐久条。攻击性光环会加快乐器磨损。
• 42 种乐器，各有独一无二的光环，一一对应。每种 GI、EMI（包括全部 16 种音符盒变体）和 Immersive Melodies 乐器都有各自独特的正向与攻击性光环组合——总计加入 84 种独特光环。
• 默认广泛攻击目标——负向光环会命中范围内的所有生物，但演奏者本人、演奏者自己的宠物以及其他玩家的宠物除外。管理员也可以按需切换为更精细的分类控制。
• 诊断命令——/effectiveinstruments diagnose 会显示光环生效流程中的每一道检查，让“为什么我的光环没有触发？”只需一条命令即可查明。

1.3.0 版本起：可选支持 Immersive Melodies！手持 IM 乐器边走边演奏，即可获得较弱的被动增益——无需打开屏幕。

---

运作方式

原地演奏等级（Genshin Instruments / Even More Instruments）

1. 打开 Genshin Instruments（或 Even More Instruments）中的任意乐器。
2. 乐器的默认增益光环会自动选中。每种乐器都对应一个默认光环，无需手动选择。
3. 弹奏一个音符，光环就会立即对范围内所有有效目标生效。持续演奏时，效果会不断刷新；彩色音符粒子会向外飘散，显示光环的作用范围。
4. 点击右上角带红色边框的图标，切换到该乐器的攻击型变体。受影响的生物身上出现非环境粒子，表示减益效果已生效。
5. 停止演奏后，光环会在短暂的宽限时间后停用（可配置，默认 5 秒）。效果会自然消退。
6. 关闭乐器界面后，光环会清除。在本次游戏期间重新打开同一乐器时，会记住你上次的选择。

移动档位（Immersive Melodies — 可选）

与 Effective Instruments 一同安装 Immersive Melodies 时：

1. 手持 IM 乐器并开始演奏旋律（自动播放），或使用自由演奏模式。
2. 自由走动——每次脉冲时（默认每秒一次），你和附近的盟友都会获得被动光环增益。光环生效期间，演奏者周围会飘浮彩色音符。
3. 暂停或切换乐器——效果会短暂持续，随后清除。
4. 点击带红色边框的图标，切换为当前手持乐器对应的移动档位攻击型光环。

为保持平衡，移动光环的效果比固定光环更弱（单一效果、较短的范围和持续时间）。如果两个档位都会对同一名玩家生效，默认优先采用固定档位。

1.4.3 版本已加入自由演奏支持。打开 IM 界面即可激活光环，无需开启自动播放。（耐久度只会在自动播放或实际演奏音符时消耗，浏览旋律列表时不会消耗。）

---

乐器光环

每种乐器都有独特且契合主题的光环：

Genshin Instruments

乐器	光环	效果
风之歌竖琴	和风祝福	速度 I
复古竖琴	远古回响	生命恢复 I
花之筝	繁花帷幕	伤害吸收 I + 饱和度 I
荣耀之鼓	战吼节奏	力量 I + 抗性 I
夜风号角	月光之径	夜视 + 缓降
尤克里里	阳光小夜曲	幸运 I
杰姆杰姆鼓	大地之韵	急迫 I + 跳跃提升 I

Even More Instruments

乐器	光环	效果
吉他	流浪者赞歌	速度 I + 跳跃提升 I
键盘	谐波共鸣	生命恢复 I + 急迫 I
古筝	静谧之流	水下呼吸 + 海豚的恩惠
琵琶	丝路活力	速度 I + 力量 I
萨克斯	烟熏魅惑	村庄英雄 I
三味线	幽焰	抗火 + 力量 I
长号	壁垒号角	抗性提升 I + 伤害吸收 II
小提琴	心弦咏叹	生命恢复 I + 伤害吸收 I

音符盒乐器变体（底鼓、贝斯、铃铛等）也映射到主题匹配的光环——完整列表请参阅配置文件夹中的 _README_INSTRUMENTS.txt。

Immersive Melodies（移动被动层级）

IM 乐器	被动光环	效果
长笛	风步	速度 I
鲁特琴	旅者低吟	幸运 I
钢琴	节拍有度	急迫 I
维奥尔琴	炉边之歌	生命恢复 I
迪吉里杜管	大地脉动	跳跃提升 I
风笛	坚定低鸣	抗性提升 I
小号	黄铜召唤	力量 I
小鼓	行进节拍	速度 I
三角铁	清亮叮鸣	夜视
手碟	静水	水下呼吸
末影贝斯	暗影共鸣	抗火

所有光环均可自由自定义、禁用或删除。通过创建新的 JSON 文件来添加你自己的光环。

---

完全数据驱动的光环系统

每个光环都由配置文件夹中的一个简单 JSON 文件定义：

config/effective_instruments/auras/

首次启动时，模组会生成 84 个默认光环 JSON 文件（31 个固定正面 + 31 个固定攻击 + 11 个移动正面 + 11 个移动攻击）以及一份 _README.txt 参考指南。此后，你拥有完全的控制权：

• 编辑任何默认光环——更改其效果、持续时间、半径、颜色、名称或描述
• 通过设置 "enabled": false 禁用光环——它会保留在磁盘上，但不会在游戏中出现
• 删除默认光环文件——它不会被重新生成
• 通过向文件夹中添加你自己的 .json 文件来创建新光环

光环 JSON 格式

{
  "displayName": "Fire Ward",
  "description": "Fire Resistance to nearby allies",
  "color": "FF4400",
  "enabled": true,
  "durationTicks": 200,
  "radius": 12,
  "sortOrder": 10,
  "effects": [
    { "effect": "minecraft:fire_resistance", "amplifier": 0 }
  ]
}

1.3.0 新增：两个可选字段用于控制层级支持：

• "tiers" — "stationary"、"mobile" 或两者组成的数组。若省略，则默认为 ["stationary"]，因此现有文件无需修改。
• "showInSelector" — true/false。固定式预设默认为 true，仅移动式预设默认为 false。

字段：

字段	类型	说明
displayName	字符串	按钮工具提示中显示的名称
description	字符串	工具提示中的描述文字
color	字符串	十六进制颜色代码（例如 "FF8800"）——用于粒子效果和 UI 高亮
enabled	布尔值	此灵气是否显示在选择器中
durationTicks	整数	效果持续时间（20 刻 = 1 秒）
radius	整数	灵气范围，单位为方块。使用 -1 可继承服务器的全局默认值
sortOrder	整数	UI 中按钮的排序顺序（数值越小，位置越靠左）
effects	数组	要施加的药水效果列表（见下文）
tiers	数组	（可选）适用的层级：["stationary"]、["mobile"] 或两者
showInSelector	布尔值	（可选）是否显示在固定式选择器 UI 中
icon	字符串	（可选）按钮图标纹理的资源位置
iconSelected	字符串	（可选）选中状态图标纹理的资源位置

effects 数组中的每个条目包含：

• "effect" — 药水效果的注册名称（例如 "minecraft:regeneration"、"minecraft:speed"）
• "amplifier" — 效果等级减 1（0 = I 级，1 = II 级，依此类推）

若省略 icon/iconSelected，按钮会以显示名称的首字母作为后备显示，因此自定义灵气无需制作任何纹理。

---

乐器-灵气映射

固定式映射

文件 config/effective_instruments/instrument_auras.json 用于控制每种乐器可使用哪些灵气，以及打开时自动选中哪一种。

每个条目支持两种格式：

字符串简写 — 单个灵气，也是默认且唯一的选项：

"genshinstrument:windsong_lyre": "zephyrs_blessing"

对象格式 — 默认灵气，以及选择器中允许使用的其他灵气：

"genshinstrument:windsong_lyre": {
  "default": "zephyrs_blessing",
  "allowed": ["zephyrs_blessing", "echoes_of_antiquity", "bloom_veil"]
}

• 如果某件乐器未列出，则会显示所有已启用的灵气（向后兼容）
• 默认灵气会自动加入允许列表

移动式映射（1.3.0 新增）

文件 config/effective_instruments/mobile_instrument_auras.json 将 Immersive Melodies 乐器 ID 映射到移动式灵气预设。每个条目都是一个简单的字符串（每件乐器对应一种灵气，不提供选择器）：

"immersive_melodies:flute": "windstep_mobile"

使用 /effectiveinstruments reload 可应用任一映射文件中的更改，无需重启。

---

命令

命令	权限	说明
/effectiveinstruments reload	OP（等级 2）	重新加载所有光环预设和乐器映射（固定 + 移动）
/effectiveinstruments status [player]	OP（等级 2）	显示玩家当前的光环状态（安装 IM 时显示两个层级）
/effectiveinstruments durability {get|set <n>|repair}	OP（等级 2）	查看或修改手持乐器的耐久度
/effectiveinstruments diagnose	所有人	转储处理流程状态（为什么我的光环没有触发？）
/effectiveinstruments reset-mappings	OP（等级 2）	删除并根据规范的一对一表重新生成乐器-光环映射
/effectiveinstruments help	所有人	显示配置文件位置和命令摘要

---

配置

所有配置文件都位于同一个文件夹中：config/effective_instruments/。

服务器配置（server.toml）

常规设置：

设置	默认值	说明
enabled	true	所有光环效果的总开关
noteWindowTicks	100	最后一个音符播放后，光环停用前的刻数（100 = 5 秒）
auraTickIntervalTicks	10	光环效果对目标刷新的频率（以刻为单位）
defaultRadius	16	默认光环范围（方块数；预设半径为 -1 时使用）

目标设置：

设置	默认值	说明
allowSelfBuff	true	演奏者是否会受到自己的光环效果
includeOtherPlayers	true	范围内的其他玩家是否会受到效果
includeTamedPets	true	范围内被驯服的动物是否会受到效果
petEntityTypeAllowlist	[]	额外指定为宠物的实体类型 ID（例如 ["alexsmobs:crow"]）

移动层级设置（1.3.0 新增）：

未安装 Immersive Melodies 时，这些设置不会生效。

设置	默认值	说明
enabled	true	移动效果层的总开关
pulseIntervalTicks	20	移动效果的刷新间隔（单位：刻；20 = 1 秒）
lingerTicks	60	玩家停止演奏后，效果持续的时间
defaultRadius	8	当 JSON 半径为 -1 时，移动光环的范围
maxTargetsPerTick	16	每次脉冲中，每位移动演奏者可影响的实体数量上限
allowSelfBuff	true	演奏者也会获得自己的移动效果
includeOtherPlayers	true	范围内的其他玩家会获得移动效果
includeTamedPets	false	驯服的宠物会获得移动效果（为平衡性考虑，默认关闭）
suppressWhenStationaryActive	true	同一玩家的固定效果层会抑制移动效果

客户端配置（client.toml）

设置	默认值	说明
showOverlay	true	在乐器界面显示光环选择按钮
overlayScale	1.0	叠加层按钮的缩放比例（0.5 – 2.0）
compactMode	false	使用紧凑的按钮布局
particlesMode	ALL	漂浮音符粒子的显示模式：ALL、MINIMAL 或 NONE
reducedMotion	false	减弱粒子的飘动和脉动效果（无障碍选项）
screenClassAllowlist	[]	其他模组中乐器界面的完整类名，这些界面未继承 Genshin Instruments 的 InstrumentScreen

---

视觉效果

光环激活时，彩色的漂浮音符粒子会在光环效果范围内生成，覆盖整个作用半径。粒子的颜色与光环配置的颜色相匹配——例如，Zephyr’s Blessing 对应青绿色飘动音符，Warcry Cadence 对应深红色，Moonlit Passage 对应紫罗兰色，依此类推。粒子会缓缓上升、飘动、脉动变大变小，最后渐渐消散。

粒子渲染完全由客户端处理。如果粒子导致性能问题，可使用客户端配置选项 particlesMode 减少或关闭粒子效果。

---

智能增益效果处理

• 效果等级取高：如果目标已从其他来源（例如信标或药水）获得同种效果的更强版本，光环不会覆盖该效果。
• 切换干净利落：更换光环时，会立即移除所有目标身上由旧光环施加的效果。模组会精确追踪自己对哪些实体施加了哪些效果，因此只会移除自身施加的效果。
• 关闭时清理：关闭乐器界面时，会清除光环并移除已追踪的效果。下次打开时，会自动选择该乐器的默认光环。
• 层级优先级：当静止和移动层级都可能对同一名玩家生效时，静止层级优先，并会抑制移动层级（可配置）。
• 环境效果：光环施加的效果会使用环境标记（产生较淡的环绕粒子），以便与药水效果区分，同时减少视觉杂乱。
• 每种乐器单独记忆：如果你更改了某种乐器的默认光环，本次游戏会话中会记住你的选择（登出后不再保留）。

---

兼容性

• Genshin Instruments（可选，1.5.0 起）——启用基于界面的静止乐器光环。所有乐器界面都会通过反射桥接自动检测，无需在编译时引用 GI。
• Even More Instruments（可选，需要 GI）——所有 EMI 界面都继承自 Genshin Instruments 的乐器界面，因此会自动获得支持，包括全部 16 种音符盒乐器变体。
• Immersive Melodies（可选，1.3.0 起）——启用移动被动层级。不导入 IM 类、不使用反射，也不使用混入。未安装 IM 时，兼容层不会产生任何额外开销。
• 其他乐器模组——使用客户端配置项 screenClassAllowlist，为未继承自 Genshin Instruments 乐器界面基类的模组界面添加支持。

后端要求：Effective Instruments 至少需要一个受支持的后端（Genshin Instruments 和/或 Immersive Melodies）才能提供游戏功能。若两者都未安装，模组仍可正常加载并记录警告，但不会触发任何光环。

其他模组提供的效果（药水效果、信标效果等）绝不会被移除或覆盖，除非光环提供的效果等级更高或相同。

---

运行要求

• Minecraft 1.20.1
• Forge 47+
• 以下至少安装一种：
  • Genshin Instruments 5.0+（基于界面的静止乐器）
  • Immersive Melodies 0.6.0+（移动被动乐器）
• 可选：Even More Instruments 6.0+（需要 Genshin Instruments）

---

快速入门

1. 安装本模组，并至少搭配一个受支持的后端——Genshin Instruments（静止）、Immersive Melodies（移动）或两者同时安装。
2. 静止层级（GI）：在游戏中打开任意乐器。它对应的专属光环会自动选中，右上角也会出现相应按钮。开始演奏后，附近的队友就会获得增益效果。
3. 移动层级（IM）：手持 Immersive Melodies 乐器并开始演奏旋律（或使用自由演奏模式）。每次脉冲都会对你和附近的队友施加被动光环增益。
4. 如需自定义光环，请编辑 config/effective_instruments/auras/ 中的 JSON 文件。
5. 如需更改乐器映射，请编辑 config/effective_instruments/ 中的映射文件。
6. 使用 /effectiveinstruments reload 应用更改，无需重启。
7. 运行 /effectiveinstruments diagnose，确认服务器检测到了哪些后端。