附魔师之信

附魔信函

附魔信函 是一个支持 Minecraft 1.21.1 / 1.20.1 的模组，分为 NeoForge / Forge / Fabric 四个分支。它添加了一组可成长、可自定义的 附魔信函 和 信函活页夹：只需将其放在物品栏、饰品槽或活页夹中，即可获得伤害加成和防御属性——无需手持。

• 所有四个分支功能同步；仅底层实现有所不同。
• 无强制模组依赖。UsefulMagic、Curios、Accessories、Terra Curio 等均为可选的、基于反射的集成。
• 默认作用于 usefulmagic:magic 伤害，可通过配置和命令扩展至任何已注册的伤害类型。

---

功能概述

1. 信函类型与成长

每封信函都有等级（Lv）。等级越高，加成越强；通过进行相应的活动可自动获得等级：

信函	升级条件（默认）	每级伤害加成
经验信函	获得 1,000 点经验	+10%
杀戮信函	击杀 50 只怪物	+10%
钓鱼信函	钓到 100 条鱼	+10%
旅行信函	行走 5,000 格 / 飞行 20,000 格	+10%
宝藏信函	打开 20 个自然生成的宝箱	+10%
时间信函	世界运行 3,600 秒	+10%
坚韧信函	承受 10,000 点伤害	+10%
英雄信函	赢得 1 次袭击	低级时 +10%，4 级起 +20%
舞台信函	固定倍率，无成长	100% – 1000%（可配置）
自定义信函	始终为 0 级	直接读取物品数据；不参与成长/配置

以上所有数值均为配置默认值，可调整（自定义信函除外）。

2. 伤害加成规则

• 信函在 物品栏、饰品槽或信函活页夹 中即视为携带——无需手持。
• 默认提升 usefulmagic:magic 伤害。可通过 default_bonus_damage_types 添加任意已注册的伤害类型。
• 实际倍率 = 信函等级 × 每级加成。物品提示框和 HUD 会显示当前的实际倍率。
• 支持堆叠规则：allow_multiple_letters（多封信函是否叠加）和 allow_same_letters（相同信函是否各自生效）。

3. 绑定系统

• 潜行 + 长按右键约 2 秒 手持信函（或空活页夹）即可绑定/解除绑定。
• 已绑定的信函仅对绑定的玩家生效。若被其他人拾取，将被自动"弹出"为物品实体。
• 物品栏、饰品槽和信函活页夹中的内容均会被持续检测。

4. 物品实体保护

掉落状态的信函和活页夹：

• 免疫所有伤害，包括爆炸和仙人掌；
• 无重力、不受水流推动、始终零速度；
• 无法被漏斗/漏斗矿车吸入。

5. 信函活页夹

• 功能类似原版收纳袋：右键存取、支持物品栏交互、悬停预览内容。
• 信函不可堆叠，每封占一个槽位；活页夹原生最多容纳 64 封信函。
• 活页夹内的信函视为"携带"，参与伤害加成和弹出检测。
• 空活页夹可以绑定；非空活页夹在潜行右键时会一次性弹出所有内容。

6. 魔法转化附魔（magic_conversion）

• 附魔后，信函不再使用默认伤害类型，而是针对指定伤害类型进行解析。
• 使用 /letterdamage <伤害类型> 设置转化类型。
• 在创造模式下，可右键附魔书打开客户端界面，直接输入伤害类型 ID。
• 相同类型的转化伤害会合并并以延迟刻解析；不同转化类型互不干扰。

7. 饰品槽兼容性

• NeoForge：兼容 Curios API，包括 Terra Curio 等第三方槽位。
• Fabric：兼容 Accessories 和 Curios（Fabric）。
• 所有集成均为反射实现，未安装对应模组时无任何影响。

8. HUD 显示

• 在左上角显示当前生效的信函：物品名称、等级和实际倍率；已转化的信函还会显示其伤害类型。
• 按 N（默认）循环切换显示：伤害加成 → 护甲值 → 护甲韧性 → 抗性 → 关闭。
• 灰色文字表示"当前未生效"（被更高倍率压制）；白色文字表示生效中。

9. 防御属性

所有信函在携带时提供三项防御属性：

• 护甲值：直接以原版属性修饰符形式增加护甲值，在护甲条上可见。
• 护甲韧性：直接增加护甲韧性。
• 抗性：按百分比减少受到的伤害（在护甲计算之前）。默认关闭；服务器上限默认 80%，可通过 /letterresistance limit 修改。
• 当 allow_multiple_letters 关闭时，每项属性独立取所有信函中的最高值；开启时则累加。
• 防御属性不受 magic_conversion 附魔影响。

10. 附魔系统

• 发光：可附魔在信函/活页夹上，使携带者发光。发光颜色由 /lettercolor 控制；也支持生物。
• 魔法绑定（magic_binding）：死亡时保留物品，重生后归还；饰品槽物品会尽可能恢复到原槽位。
• 消失诅咒（vanishing_curse）：该模组物品可接受原版消失诅咒，死亡时销毁。使用 /lettervanish 启用强制消失。

11. 生物持握与管理命令

• 当生物在主手、副手、护甲或饰品槽中携带信函时，其造成的所有伤害 都会获得加成（玩家仍严格遵循配置的伤害类型）。
• /letterstorage 可捕获实体、与其主手/副手/护甲槽交换物品，以及导出其 NBT。
• 同时提供管理命令，如 /letterback（取回掉落物品）、/letterclean（定时清理）和 /letterbinding（弹出白名单）。

---

版本与分支

目录	Minecraft	加载器/运行环境	Java	物品数据存储	伤害修改方式
neoforge-1.21.1	1.21.1	NeoForge 21.1.x	Java 21	数据组件	事件（LivingIncomingDamageEvent + LivingDamageEvent.Pre）
fabric-1.21.1	1.21.1	Fabric Loader 0.16.10 + Fabric API 0.110.0+1.21.1	Java 21	数据组件	Mixin 修改 LivingEntity.hurt() 中的伤害参数
forge-1.20.1	1.20.1	Forge 47.1.x	Java 17（可使用 JDK 21 构建 release 17）	NBT	事件（LivingHurtEvent）
fabric-1.20.1	1.20.1	Fabric Loader 0.15.11 + Fabric API 0.92.2+1.20.1	Java 17（可使用 JDK 21 构建 release 17）	NBT	Mixin 修改 LivingEntity.hurt() 中的伤害参数

物品、机制、配置、命令、HUD、绑定/弹出、物品实体保护、魔法转化和附魔 在四个分支中完全一致。请选择与你加载器和 Minecraft 版本对应的目录。

---

1.20.1 与 1.21.1 的区别

两个版本均功能完整且同步；主要区别在于底层实现：

方面	1.21.1（NeoForge / Fabric）	1.20.1（Forge / Fabric）
数据存储	数据组件	NBT
伤害计算	NeoForge 使用事件；Fabric 使用 Mixin	Forge 使用 LivingHurtEvent；Fabric 使用 Mixin
Curios 物品标签路径	data/curios/tags/item/（单数）	data/curios/tags/items/（复数）
活页夹容量实现	BundleContents.getWeight 返回 Fraction；Mixin 将其改为 1/64	BundleItem.getWeight 返回 int；Mixin 将其改为 1
Forge 移植适配	不需要	自动兼容 MesdagPortLib，将增幅伤害同步到其 PortDamageContainer
Fabric 第三方兼容性	常规 Accessories 集成	额外处理 Accessories beta.48 的无条件 Sodium 依赖崩溃（注册空渲染器）

针对开发者的 API 差异（属性注册、ResourceLocation、AttributeModifier、Mixin 映射等），请参阅各分支中的源码注释和开发文档。

---

命令参考

所有模组命令需要权限等级 2/3/4：

命令	描述
/lettermulti [true false]	切换多封信函同时生效
/lettersame [true false]	切换相同信函各自生效
/letterset <类型> <参数> <值>	修改信函成长/倍率/防御属性
/lettertype [add delete] <伤害类型>	添加/移除默认加成伤害类型
/letterentity [add delete] <实体类型>	添加/移除魔法转化黑名单实体
/letterdamage <伤害类型>	设置手持转化信函的伤害类型
/letterback [玩家]	取回玩家的绑定信函/活页夹物品实体
/lettercolor [red green blue]	查询/设置发光颜色
/letterenchanted [true|false|glowing <p>|binding <p>|conversion <p>]	查询/切换附魔书注入并调整三种附魔概率
/letterclean ...	查询/切换/配置定时清理（包括 allbinding/allnormal 批量清理）
/letterdelay [tick]	查询/设置重生归还延迟
/letterresistance ...	查询/切换/设置抗性上限
/lettervanish ...	查询/切换强制消失机制
/letterbinding ...	管理绑定白名单及修改绑定 UUID
/letterstorage ...	捕获实体、交换物品、导出 NBT