# OverEnchanted 重写需求文档

## 1. 项目定位

OverEnchanted 是一个对 Minecraft 原版附魔系统进行最小扩展的 Paper 插件。

插件增加一种特殊物品“超限附魔模板”，使玩家能够在保留原版附魔结合逻辑的基础上突破附魔等级上限。

插件还增加一种特殊物品“祛魔模板”，使玩家能够祛除原物品上某个装备的某个附魔。

## 2. 核心概念：超限附魔模板 & 祛魔模板

“超限附魔模板”是一种特殊消耗品。

模板本身只能携带一个附魔及其等级。

模板有两种主要状态：

- 空白模板：尚未携带附魔。
- 已附魔模板：携带恰好一个附魔及其等级。

此外还有一种模板：
- 祛魔模板：不需要管理它的附魔，仅在使用时查看它的名称

模板是一次性物品。

模板不能通过普通 Minecraft 机制无限复制。

模板的视觉表现与逻辑识别相互分离。逻辑上使用 PDC 等稳定数据识别模板，不依赖名称或 Lore；具体外观使用 `item_model` 等资源包机制实现。

模板材质、名称、模型标识等具体外观均在代码中硬编码，不提供外观配置项。

两类附魔模板均使用 `ItemType.ENCHANTED_BOOK` 作为原料，超限附魔模板外观为下界合金升级模板，祛魔模板外观为龙息，并需要加上一个固定的附魔用于提示其用途。

超限附魔模板最终以 `DataComponentTypes.STORED_ENCHANTMENTS` 直接储存附魔，祛魔模板的附魔同样使用该组件。

祛魔模板的占位附魔使用如下方式获得（所需方法已经在插件基础库里定义）：

```
val disenchantEnch: Enchantment = requireEnchantment(SV, "disenchant")
```

## 3. 基本规则

插件仅改变附魔的等级上限。

- 物品必须能够接受对应附魔。
- 附魔等级按照原版升级规则推进。

唯一核心变化：

> **附魔等级可以超过原版定义的最大等级。**

例如：

`Sharpness V + Sharpness V → Sharpness VI`

`Sharpness VI + Sharpness VI → Sharpness VII`

依此类推。

祛魔模板则需要玩家通过铁砧，将模板重命名为需要祛除的附魔完整 `NamespacedKey` ，例如 `minecraft:sharpness` ，不能省略其中的`namespace` 。

## 4. 铁砧交互

所有操作通过原版铁砧完成。

所有超限附魔交互均需要花费 `附魔的 anvilCost` * `附魔的原始等级` 等级的经验，如果是祛魔操作，则花费 `附魔的 anvilCost + 1` * `附魔的原始等级 + 1` 等级的经验。

不需要考虑铁砧的过于昂贵机制，已通过其他方式去除。

### 4.1 空白模板 + 附魔书

输入：

- 左侧：空白超限附魔模板
- 右侧：附魔书

限制：

- 附魔书必须恰好包含一个附魔。
- 不允许包含多个附魔的附魔书。
- 模板必须为空白。

结果：

- 模板获得附魔书中的唯一附魔及等级。
- 附魔书被消耗。
- 输出为一个已附魔的超限附魔模板。

该操作只是将普通附魔引入超限体系，不提升附魔等级。

### 4.2 超限模板 + 超限模板

输入：

- 左侧：超限附魔模板
- 右侧：超限附魔模板

两个模板必须同时满足：

- 均为已附魔模板。
- 均恰好拥有一个附魔。
- 附魔种类完全一致。
- 附魔等级完全一致。

只有满足全部条件时才允许合并。

结果：

`Enchantment(level) + Enchantment(level) → Enchantment(level + 1)`

输出等级 + 1 的超限模板

### 4.3 目标物品 + 超限模板

输入：

- 左侧：目标物品
- 右侧：超限附魔模板

目标物品可以拥有任意数量的其他附魔。

但必须满足：

- 模板为已附魔模板。
- 目标物品已经拥有一个与模板完全一致等级的附魔，或者不含有该附魔。
- 对应附魔必须能够应用于该物品，但不考虑是否兼容。

目标物品上的其他附魔保持不变。

模板被消耗。

如果原始物品不含有该附魔，则将模板的唯一附魔添加到原始物品，如果原始物品已经含有该附魔且等级相同，则将原始物品的对应附魔等级 + 1。

这里允许目标物品携带多个附魔，因为模板只负责提升其中一个已经存在的附魔，或者往上添加一个不兼容但可用的附魔。

物品是否能够接受对应附魔，使用 Paper API 的 `Enchantment#canEnchantItem(ItemStack)` 判断，而不自行维护材料类型列表。

### 4.4 目标物品 + 祛魔模板

输入：

- 左侧：目标物品
- 右侧：已重命名的祛魔模板

限制：

- 左侧物品必须包含右侧模板的名字对应的附魔。

输出：

- 不含有该附魔的左侧物品
- 同时在玩家的位置掉落一本被祛除附魔（包含原等级）的附魔书

若左侧物品不含有对应附魔，拒绝操作

## 5. 等级规则

超限系统严格遵循“相同附魔、相同等级才能升级”的原则。

不存在跨级升级，仅当向物品打上一个原本不存在的附魔时允许跨级。

不存在使用低等级附魔补足高等级附魔的机制。

不存在通过一次操作连续提升多级的机制。

因此每提升一级，都必须真实支付对应等级的两个输入。

例如：

`V + V → VI`

`VI + VI → VII`

`VII + VII → VIII`

这使超限等级形成自然的指数级资源成本，而无需额外增加等级费用体系。

## 6. 模板获取方式

模板拥有三种来源。

### 6.1 配方合成

超限附魔模板可以通过主动收集资源进行稳定生产。

超限附魔有序合成配方使用：

- 4 个青金石块(L)
- 1 个附魔台(T)
- 2 个龙息(D)
- 1 个回响碎片(S)
- 1 个末影之眼(E)

配方：

- LSL
- DTD
- LEL

祛魔模板有序合成配方使用：

- 4 个青金石块(L)
- 1 个下界合金锭(N)
- 2 个龙息(D)
- 1 个回响碎片(S)
- 1 个末影之眼(E)

配方：

- LSL
- DND
- LEL

### 6.2 战利品箱

任意战利品容器均有一定概率（默认 0.005 ）生成空白超限附魔模板，祛魔模板默认不会从战利品容器中生成，除非手动配置个别战利品表的概率。

战利品箱的默认生成概率放在配置文件中，并支持按完整战利品表标识（如 `minecraft:chests/ancient_city`， 战利品表名不会含有`.`）配置 override。

命中 override 时直接使用该值替代默认概率，不与默认概率相加或相乘；未配置 override 时使用默认概率。override 为 0 表示该战利品表不生成模板。每次符合条件的箱子战利品生成只进行一次概率判定，成功时额外生成 1 个空白模板。

探索获取的主要意义是提供不可预期的额外模板，而不是成为唯一可靠来源。

### 6.3 特定生物

可掉落超限附魔模板的实体种类及各自掉落概率均放在配置文件中。默认实体名单为唤魔者与幻术师（均为 0.01 ），管理员可以通过配置增删实体种类。

祛魔模板默认只会从幻术师掉落，默认概率 0.005 ，同样可以使用配置文件增删实体种类。

未配置的实体不掉落模板；已配置实体在被玩家击杀死亡掉落时按其概率判定一次，成功时掉落 1 个空白模板。概率为 0 表示禁用该实体的模板掉落。

## 7. 附魔兼容性

尽可能复用 Minecraft/Paper 原版附魔规则。

插件只负责延伸等级上限，不重写，不判断附魔兼容性，只判断可用性。

目标物品是否属于该附魔能够作用的物品类型，通过：

`Enchantment#canEnchantItem(ItemStack)`

进行判断。

## 8. 多附魔限制

超限模板始终只允许存在零个或一个附魔。

但目标物品可以拥有多个附魔。

模板只寻找其中一个与自身 `Enchantment + Level` 完全一致的目标附魔，然后将该附魔提升一级，如果不符合要求则拒绝操作。

祛魔模板不需要拥有其他附魔，通过名字来获取需要祛除的附魔，理论上祛魔模板的附魔可以被 Lore 替代（但不要这么做）。

## 9. 设计目标

重写版本最终应让玩家仅通过理解三个对象之间的关系，就能够理解整个插件：

**附魔书 → 超限附魔模板 → 目标物品**

以及：

**同附魔 + 同等级 → 更高一级**

以及：

**附魔 + 重命名祛魔模板 → 不带有附魔的物品 + 附魔书**
系统不要求玩家学习额外的成功率、概率、符文类型、核心数量或特殊机器规则。

玩家第一次看到超限模板时，应该能够通过尝试铁砧自然理解它的用途。

## 10. 配置范围

当前配置文件仅承载模板获取概率相关设置：

| 配置项 | 含义 |
| --- | --- |
| `entity-drops` | 实体种类到掉落概率的映射；默认包含唤魔者与幻术师 |
| `loot-chests.default-chance` | 战利品箱生成空白模板的默认概率 |
| `loot-chests.overrides` | 完整战利品表标识到覆盖概率的映射 |

所有概率使用 0–1 的数值，0 表示不生成，1 表示必定生成。读取配置时**不需要**战利品表是否存在。

具体初始概率仍待确定，但必须通过配置文件提供，不能作为不可调整的业务常量硬编码。

外观与配方材料、数量、排布暂时硬编码。特殊附魔限制、超限显示修正及操作成功率不设配置项；合法铁砧操作仍然确定成功。

## 11. 实现结构与命令系统

### 12.1 插件主类

插件主类保持精简使用 `object` 声明，在Bootstrap 中重写 `createPlugin` 方法，直接返回该 `object` ，同样也不需要将插件主类作为参数到处传递。

尽可能使用 Kotlin `object` 组织具有单例语义的功能模块，例如模板管理、配置读取、配方注册、铁砧监听、掉落监听和命令注册。

### 12.2 命令系统

使用 Paper 的 Brigadier 命令系统完成命令构建与注册，参数解析、权限判断及建议补全统一基于该系统实现。

具体命令及子命令的功能范围在实现时确定。

## 13. 核心一句话

> **超限附魔模板是一种一次性附魔载体：它可以承载一个附魔，并允许两个完全相同的附魔等级继续向上结合，从而突破 Minecraft 原版的附魔等级上限。**

> **祛魔模板是一种一次性的附魔载体：通过铁砧重命名为附魔的完整 NamespacedKey，从而将物品的某个附魔从物品上剥离成附魔书。**