有效乐器

实用乐器

演奏音乐。强化盟友。或诅咒敌人。 实用乐器为您喜爱的乐器模组添加了一个魔法光环系统，让音乐家在演奏时能为附近的玩家和驯服的宠物提供药水效果——或者，如果他们选择负极变体，则对附近的生物施加负面效果。每件乐器都有其独特的正面和进攻性光环——拿起风琴竖琴，感受微风加快您的脚步（正面），或召唤呼啸的狂风，减速并削弱范围内的每一个敌人（进攻性）。

1.5.0 版本新内容：

• 原神乐器现在变为可选！ 实用乐器兼容 原神乐器（固定屏幕乐器）、沉浸旋律（移动被动乐器），或两者兼用。选择您偏好的后端——模组会自动适应。
• 独立沉浸旋律模式 ——仅安装 IM 和实用乐器即可，无需 GI，移动光环层级将按预期工作。
• /effectiveinstruments diagnose 现在会预先报告后端可用性，管理员无需阅读日志即可验证检测到了哪些后端。
• 依赖隔离 ——GI 的类加载已完全隔离在兼容层之后。当 GI 缺失时，不会出现 NoClassDefFoundError 错误。

1.4.x 版本新内容：

• 进攻性（负面）光环 ——每件乐器都会获得一个镜像的负面效果变体（凋零、中毒、缓慢、失明等）。选择红边框图标可即时切换极性。
• 乐器耐久度 ——乐器现在会随着使用而磨损（每个乐器独立的 NBT 耐久度），并可在铁砧上修复。每个乐器栏位下方显示原版风格的耐久度条。进攻性光环会更快损耗乐器。
• 42 件乐器匹配独一无二的光环。 每件 GI、EMI（包括所有 16 个音符盒变种）和沉浸旋律乐器都有其独特的正面+进攻性光环组合——总共提供了 84 个独特光环。
• 默认广范围进攻性目标选择 ——负面光环作用于范围内的所有生物，但不包括演奏者本人、其宠物以及其他玩家的宠物。管理员可以根据偏好切换到精细的按类别控制。
• 诊断命令 ——/effectiveinstruments diagnose 会显示光环管道的每个环节，一句话回答"我的光环为什么没触发？"的问题。

自 1.3.0 版本开始： 可选 沉浸旋律 支持！拿起 IM 乐器边走边演奏，获得较轻的被动增益——无需屏幕。

---

工作原理

固定层级（原神乐器 / 更多乐器）

1. 打开任何乐器 来自原神乐器（或更多乐器）。
2. 乐器的默认正面光环会自动选择。 每个乐器都有一个默认映射的光环——无需手动选择。
3. 弹奏一个音符，光环立即生效 作用于范围内所有有效目标。持续演奏时效果会刷新；彩色音符粒子向外飘散，显示光环的覆盖范围。
4. 选择右上角的红边框图标 切换到乐器的进攻性变体。受影响生物身上的非环境粒子表示负面效果已生效。
5. 停止演奏，光环会在短暂的宽限期后停用（可配置，默认为 5 秒）。效果会自然消失。
6. 关闭乐器，光环消失。再次打开同一乐器，它会记住您在该会话中的上次选择。

移动层级（沉浸旋律——可选）

当 沉浸旋律 与实用乐器一同安装时：

1. 手持 IM 乐器 并开始演奏旋律（自动播放）或使用自由演奏模式。
2. 自由行走——每次脉冲时（默认：每秒一次），被动光环增益会作用于您和附近的盟友。光环激活时，彩色音符会围绕演奏者漂浮。
3. 暂停或切换乐器——效果会短暂持续然后消失。
4. 选择红边框图标 切换为手持乐器的移动层级进攻性光环。

为了平衡性，移动层级光环有意比固定层级更弱（单一效果，范围更短，持续时间更短）。如果两个层级可能作用于同一玩家，默认情况下固定层级优先。

自由演奏支持于 1.4.3 版本推出。 打开 IM 屏幕即足以激活光环——无需自动播放。（耐久度仅在自动播放/实际音符播放时消耗，浏览旋律列表时不会消耗。）

---

乐器光环

每件乐器都拥有独特且主题相符的光环：

原神乐器

乐器	光环	效果
风琴竖琴	和风祝福	速度 I
古典竖琴	古代回响	再生 I
花卉古筝	繁花帷幕	吸收 I + 饱和 I
荣耀鼓	战吼节拍	力量 I + 抗性 I
夜风号角	月华之路	夜视 + 缓降
尤克里里	阳光小夜曲	幸运 I
金贝鼓	大地韵律	急迫 I + 跳跃提升 I

更多乐器

乐器	光环	效果
吉他	旅者颂歌	速度 I + 跳跃提升 I
键盘	谐波共鸣	再生 I + 急迫 I
古筝	宁静之流	水下呼吸 + 海豚的恩惠
琵琶	丝路活力	速度 I + 力量 I
萨克斯	烟雾魅力	村庄英雄 I
三味线	鬼火	抗火 + 力量 I
长号	堡垒号角	抗性 I + 吸收 II
小提琴	心弦咏叹调	再生 I + 吸收 I

音符盒乐器变种（低音鼓、贝斯、钟等）也映射到主题相符的光环——请参阅配置文件夹中的 _README_INSTRUMENTS.txt 以获取完整列表。

沉浸旋律（移动被动层级）

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": "火焰护盾",
  "description": "为附近盟友提供抗火效果",
  "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 将沉浸旋律乐器 ID 映射到移动层级的光环预设。每个条目是一个简单的字符串（每件乐器一个光环，无选择器）：

"immersive_melodies:flute": "windstep_mobile"

使用 /effectiveinstruments reload 在无需重启的情况下应用对任一映射的更改。

---

命令

命令	权限	描述
/effectiveinstruments reload	管理员（等级 2）	重新加载所有光环预设和乐器映射（固定 + 移动）
/effectiveinstruments status [player]	管理员（等级 2）	显示玩家的当前光环状态（当 IM 存在时，显示两个层级）
/effectiveinstruments durability {get|set <n>|repair}	管理员（等级 2）	检查或编辑手持乐器的耐久度
/effectiveinstruments diagnose	所有人	输出管道状态（我的光环为什么没触发？）
/effectiveinstruments reset-mappings	管理员（等级 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 版本新内容）：

当未安装沉浸旋律时，这些设置无效。

设置项	默认值	描述
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	[]	来自其他模组的乐器屏幕的完全限定类名，这些屏幕未继承原神乐器的 InstrumentScreen

---

视觉效果

当光环激活时，彩色的浮动音符粒子会在光环效果范围的整个半径内生成。粒子的颜色与光环配置的颜色相匹配——绿色漂移音符代表和风祝福，深红色代表战吼节拍，紫罗兰色代表月华之路，等等。它们会轻轻上升、漂移、脉动大小，然后淡出。

粒子渲染完全在客户端进行。如果粒子导致性能问题，请使用 particlesMode 客户端配置选项来减少或禁用它们。

---

智能增益处理

• 强者为王： 如果目标已拥有来自其他来源（例如信标或药水）的更强版本的同种效果，光环将不会覆盖它。
• 干净切换： 更改光环会立即将所有目标的旧光环效果移除。模组会精确记录它对哪些实体应用了哪些效果，并且只会移除其自己的效果。
• 干净关闭： 关闭乐器会清除光环并移除已追踪的效果。下次打开时，乐器的默认光环将自动选择。
• 层级优先级： 当固定和移动层级可能作用于同一玩家时，固定层级获胜并压制移动层级（可配置）。
• 环境效果： 光环应用的效果使用环境标志（微妙的漩涡粒子），以便与药水效果区分，并保持视觉简洁。
• 按乐器记忆： 如果您覆盖了乐器的默认光环，您的选择会在该会话中为该乐器保留（退出登录后忘记）。

---

兼容性

• 原神乐器（自 1.5.0 起可选）——启用固定屏幕乐器光环。所有乐器屏幕通过一个反射桥自动检测，该桥不需要任何编译时 GI 引用。
• 更多乐器（可选，需要 GI）——所有 EMI 屏幕都继承自原神乐器的乐器屏幕，并自动获得支持，包括所有 16 个音符盒乐器变种。
• 沉浸旋律（自 1.3.0 起可选）——启用移动被动层级。不导入 IM 类，不使用反射，不混入。当 IM 不存在时，兼容层是一个零成本的无操作。
• 其他乐器模组——使用 screenClassAllowlist 客户端配置，为那些未继承原神乐器乐器屏幕基类的模组屏幕添加支持。

后端要求： 实用乐器需要至少一个受支持的后端（原神乐器和/或沉浸旋律）来提供游戏玩法功能。如果没有，模组会干净加载并记录警告，但不会有任何光环触发。

来自其他模组的效果（药水效果、信标等）永远不会被移除或覆盖，除非光环提供了更强或同等的版本。

---

需求

• Minecraft 1.20.1
• Forge 47+
• 至少满足以下之一：
  • 原神乐器 5.0+（固定屏幕乐器）
  • 沉浸旋律 0.6.0+（移动被动乐器）
• 可选： 更多乐器 6.0+（需要原神乐器）

---

快速入门

1. 将模组与至少一个受支持的后端一起安装——原神乐器（固定）、沉浸旋律（移动）或两者。
2. 固定层级（GI）： 在游戏中打开任何乐器。其独特的光环会自动选择，相应的按钮会出现在右上角。开始演奏——附近的盟友将获得增益效果。
3. 移动层级（IM）： 手持沉浸旋律乐器并开始演奏旋律（或使用自由演奏模式）。每次脉冲时，被动光环增益会作用于您和附近的盟友。
4. 要自定义光环，请编辑 config/effective_instruments/auras/ 中的 JSON 文件。
5. 要更改乐器映射，请编辑 config/effective_instruments/ 中的映射文件。
6. 使用 /effectiveinstruments reload 在无需重启的情况下应用更改。
7. 运行 /effectiveinstruments diagnose 以确认服务器检测到了哪些后端。