README(简体中文）

OverEnchanted（超限附魔）

这是一个面向有开发能力的 Paper 服主的插件原型，提供“超限附魔”玩法：用魔法符文 + 超限魔法核心 + 一堆材料，在专门的“超限附魔台”上将物品打上不兼容/超出最大等级限制的附魔/在此基础上继续提升某项附魔等级。

本插件并非开箱即用 — 它假定你你的主世界最低高度低于-64并且玩家有能力进入并在那里放置方块（或者你可以自己修改这里的逻辑，详见“重要限制与开发提示”）。

玩法：

玩家手持附魔台，右键一个满级的，有效果的，激活的信标，获得一个超限附魔台物品
将超限附魔台放置到Y<-64的位置，然后右键打开超限附魔台界面
在此界面中可以消耗指定的材料与**魔法符文（通过在高炉中熔炼附魔书获得）与超限附魔核心（通过打开某些战利品箱子或者玩家击杀某些怪物概率获得）**对物品进行超限附魔

主要功能

GUI 栈式配置界面：基于字符串布局创建箱子菜单，支持点击切换附魔、实时检查兼容性、显示材料需求与成功率。
魔法符文（Rune）：通过熔炼附魔书（高炉/BlastingRecipe + 事件处理）得来，保存其附魔（附魔原生展示，不隐藏），并保留符文等级（PDC）。
超限魔法核心（Core）：通过战利品/生物掉落插入，可配置概率；物品材质为木炭（Charcoal），带 glint。
超限附魔台（放置型）：把超限附魔台物品放置到世界后，会把 ItemStack 的 PDC 转储到方块 TileState 中；右键该方块打开 GUI（要求玩家处于 Y < -64）。
磨石净化：可用磨石移除符文上的附魔（但符文等级与标识保留）。
战利品注入与生物掉落：通过配置控制容器 loot table 与指定生物的掉落概率（使用 setLoot/EntityDeathEvent）。
安全与 UX：
- GUI 关闭时会把玩家放入的所有物品返还（优先塞背包，背包满则掉落脚下）。
- 阻止把附魔书塞进目标物品槽。
- shift-click 等行为被限制以避免绕过校验。
外观：所有特殊物品在 editMeta{} 中设置 it.setEnchantmentGlintOverride(true)（强制光效）；魔法符文原生显示附魔，lore 仅写符文等级。

适用环境/要求

服务器：PaperMC （建议 1.21.x 及以上，不兼容spigot）。
JDK版本：>= 21。
极重要（必须注意）：世界最低高度需要小于-64
- 如果你的地图/服务端无法把玩家带到 Y < -64，你必须修改代码或配置（见下方“开发者提示”）。
本插件面向有开发能力的服主：若你不知道或者不愿意增加世界高度上下限或改代码，请慎用。

GUI/插件玩法细节

界面布局：

###ABC###
# #   # #
#R##I##S#
         
         
####O####

（空格代表空格槽位）

槽位说明：
- ITEM（左上空位，主要物品槽）—— 放入要被超限附魔的物品（不允许附魔书）
- RUNES（中上3个空位）—— 放魔法符文
- CORE（右上空位）—— 放超限魔法核心（即使没有符文，也至少需要 1 个核心）
- MATERIALS（下方所有槽位）—— 放需要消耗的材料（I 槽会显示需求）
信息显示：
- R（附魔列表）—— 列出物品与（有附魔的）符文上的附魔，左键循环选中
- A/B/C（检查位）—— 显示兼容性检查（Green/Red 标示，每多一条不兼容，所有材料消耗数量增加）
- S（核心需求）—— 显示当前需要的核心数量（每次界面刷新/点击都会更新）
- O（结算）—— 显示成功率并用于尝试结算（点击时会再次进行完整检查）
成功率计算：
- 每个 1 级符文 +2.5%，每个 2 级符文 +5%，每个 3 级符文 +7.5%；
- 每个超限魔法核心 +2.5%；
- 每满足一种材料需求 +2%；
- 上限 100%。
结算行为：
成功：消耗全部材料，应用超限结果：

若选中来自符文的附魔，则强制把符文上的附魔写到物品上

若选中物品上附魔，则该附魔等级 +1

失败：保留原物品与一半超限魔法核心，其他材料全部消耗
其他 UX：
- 放入物品后关闭界面，不会丢失物品：所有投入在关闭时会返还玩家（若背包满则掉落在玩家脚下）。
- 符文在磨石（Grindstone）可以净化（移除附魔但保留符文等级 & PDC），净化后的符文仍然提供核心需求/成功率，但不会贡献可选附魔项（R 列表会忽略无附魔的符文）。
- 特殊物品都已在 editMeta{} 中设置 it.setEnchantmentGlintOverride(true)（强制光效）；魔法符文会原生显示附魔（无隐藏），lore 只显示符文等级。

开发者提示

本插件强依赖“世界最低高度小于-64且玩家能到达”，如果你的世界无法把玩家带到该高度，下面是常见的三种处理方式（任选一种）：

A. 增加一个调整世界高度下限的数据包（最简单）

B. 修改代码并重新编译（去掉或调整高度检查）

修改 me.axiumyu.overEnchanted.table.OverEnchantedTableBlockListener 中的检查：

// 当前代码（严格要求 y < -64）
if (p.location.y >= -64.0) {
    p.sendMessage(MM.c("<red>需要在深层（Y < -64）使用 <aqua>超限附魔台</aqua></red>"))
    return
}

// 把 `-64.0` 改成你服务器的可达高度。（或者直接注释掉这四行）
/* // remove or change threshold
// if (p.location.y >= -64.0) { ... }
*/

C. 为没有开发经验的服主：请找会 Kotlin/Java 的同伴帮忙

如果你不会改代码但想要在标准世界里用此插件，找一个熟悉 Paper 插件的小伙伴会比反复折腾配置来得快。

热重载配置示例

插件内部有 LootConfig.reload() 方法，因为我没有这样的需求，所以当前没有暴露成命令。你可以快速加一个命令来调用它，例如在 onEnable() 中注册一个简单的 /overenchanted reload（示例伪代码）：

// 伪代码：在 plugin.onEnable()
getCommand("oereload")?.setExecutor { sender, _, _, _ ->
    LootConfig.reload()
    sender.sendMessage("OverEnchanted config reloaded")
    true
}

文件/类一览（供开发者定位修改）

me.axiumyu.overEnchanted.OverEnchantedPlugin — 主类（onEnable 注册）
me.axiumyu.overEnchanted.items.OEItems — 魔法符文 / 核心 / 台的 ItemStack 工厂
me.axiumyu.overEnchanted.items.RuneSmeltListener — 高炉熔炼附魔书 -> 符文（配合 Recipes.register）
me.axiumyu.overEnchanted.items.RuneGrindstoneListener — 磨石净化符文
me.axiumyu.overEnchanted.recipes.Recipes — 注册 BlastingRecipe（占位）
me.axiumyu.overEnchanted.menu.OEMenu* — 菜单视图与监听、逻辑（S/R/ABC/O 等）
me.axiumyu.overEnchanted.table.OverEnchantedTableBlockListener — 放置台时把 PDC 写入 TileState；右键打开 GUI（含 Y 检查）
me.axiumyu.overEnchanted.loot.* — LootConfig / LootInsertListener / CoreMobDropListener
me.axiumyu.overEnchanted.util.MM — 文本序列化（自动在最前面加 <!i> 以取消斜体）

常见问题

Q：玩家丢失放入的物品？ A：已修复 —— 界面关闭（玩家主动关闭 / 断线需另加处理）时会把投入物品返还或掉落脚下。

Q：为什么高炉熔炼附魔书不起作用？ A：插件在 onEnable() 注册了一个 BlastingRecipe（占位），并在 FurnaceSmeltEvent 中把真正的符文/附魔转移到符文上。若你在一个极端化的服务端实现下（自定义 Furnace 行为），可能需要检查服务器日志或自定义适配。

Q：我不想要 Y < -64 限制 A：见“开发者提示”，修改 OverEnchantedTableBlockListener.onRightClick 中的高度判断。

Q：为什么不使用现成的第三方库 A：因为我服用不到，未来如果需要可能会考虑重写，目前没有打算

面向服主的免责声明

本插件默认设计为需要能访问 Y < -64 的世界。如果你的服务器世界不可达该高度，请自行修改代码或征求开发者帮助。
插件目前为一个功能完整且偏向个人使用，但仍需测试与调优的实现；针对服主有开发能力，建议在测试服充分测试后再放到生产服。

README(English)

OverEnchanted is a prototype Paper plugin aimed at server owners with development ability. It implements an “over-enchanting” system: use Magic Runes + OverEnchanted Cores + a pile of materials on a special OverEnchanted Table to apply incompatible or over-maxed enchants, or to further raise an existing enchant’s level.

Not plug-and-play. The plugin assumes your overworld minimum height is below Y = -64 and that players can access and place blocks there (or you can modify the code). See the Developer Notes section.

How to play

Right click an activated, effect chosen and full-level beacon with an enchanting table to obtain an OverEnchanted Table
Place OverEnchanted Table under world Y level -64, right click it to open GUI
consume some materials, enchantment rune(get by blasting any enchantment book in blast furance) and OverEnchant Core(can be found in any configurated loot chests or mob that killed by player) to upgrade enchantments of item

Highlights/Features

GUI menu (inventory) created from a string layout — click to cycle enchants, run compatibility checks, show required materials and success chance.
Magic Runes: created by smelting enchanted books (BlastingRecipe + event). Runes keep their enchants (shown natively, not hidden) and have a rune level saved in PDC.
OverEnchanted Cores: inserted into loot or dropped by configured mobs; material = CHARCOAL, with forced glint.
OverEnchanted Table (placeable): when placed, the ItemStack PDC is stored into the block’s TileState. Right-clicking that placed block opens the GUI. (Requires player Y < -64.)
Grindstone purification: grindstone can strip enchants from a rune while preserving rune level and PDC.
Loot injection & mob drops: controlled via config; container loot uses setLoot, mobs use EntityDeathEvent.

Safety & UX:

Items placed into the GUI are returned when the GUI is closed (tries to put them back into the player inventory; drops on ground if full).
Enchanted books cannot be placed into the target item slot.
Shift-click behaviors are restricted to avoid bypassing checks.

Visuals: all special items set it.setEnchantmentGlintOverride(true) in editMeta{} (forced glint); Magic Runes display enchants natively and show rune level in lore only.

Requirements / Environment

Server: PaperMC (recommended 1.21.x+). Uses Paper APIs (e.g. Enchantment.getAnvilCost() and TileState/PDC).
Build: Kotlin + Gradle (project sources are Kotlin).
Important runtime requirement: players must be able to reach Y < -64 (strictly less than -64). The plugin strictly checks player Y before allowing the OverEnchanted Table GUI to open.
If your world does not allow this, you can simply add a datapack that allow this,or modify the code (see Developer Notes).
This plugin is designed for server owners who can modify code or server data. If you cannot modify world settings or code, this plugin may not suit you.

GUI / Gameplay Details

Layout:

###ABC###
# #   # #
#R##I##S#
         
         
####O####

Slot summary

ITEM — main item slot (target item). No enchanted books allowed.
RUNES (3 slots) — place Magic Runes (purified runes still keep rune level & PDC).
CORE (1 slot) — OverEnchanted Cores (even with no runes, a minimum of 1 core is required).
MATERIALS (lower slots) — other required materials; I slot shows the required list.
R — enchant list compiled from the item and any runes that have enchants; left-click rotates selection.
A / B / C — compatibility checks (green/red indicators).
S — core requirement display (updates every refresh / click).
O — resolution/execute button (shows success chance; clicking performs final verification and attempts the enchant).

Success chance calculation

Each rune: level 1 → +2.5%; level 2 → +5%; level 3 → +7.5%.

Each OverEnchanted Core → +2.5%.

Each material requirement satisfied → +2%.

Max 100%.

Resolution outcome

Success: consume all materials, apply the over-enchant:

if selected enchant is from rune, that rune’s enchants are applied to the item forcely

if selected enchant is from item, that enchant’s level is incremented by 1)

Failure: original item is kept; half of the cores (rounded down) remain; all other materials are consumed

Other behavior

Items put into the GUI are returned when the GUI is closed. If player inventory is full, they drop at the player’s feet.

Grindstone can purify runes (removes enchants but keeps rune level and PDC); purified runes still affect core requirement and success chance, but do not contribute enchants to the R list.

Special items have forced glint (setEnchantmentGlintOverride(true)). Magic Runes natively display enchants; lore only shows rune level.

Developer Notes

The plugin depends on players being able to go to Y < -64. This is a deliberate design / safety choice. If that is not possible on your server, you have these options:

A. install a datapack that allows building under -64.

You can just search datapacks like height

B. Modify the code (remove or change height check)

Edit me.axiumyu.overEnchanted.table.OverEnchantedTableBlockListener where the plugin checks player Y:

// Current (strict Y < -64 requirement) if (p.location.y >= -64.0) { p.sendMessage(MM.c("需要在深层（Y < -64）使用超限附魔台")) return }

// Change -64.0 to the height you want, or remove the four lines entirely to disable the check.

(You may prefer to make the threshold configurable via config.yml.)

C. If you cannot code: ask a Kotlin/Java developer for help

If you’re not comfortable changing plugin code and your world can’t reach Y < -64, get help, this plugin is aimed at server owners who can adapt it.

Hot-reload example

The plugin exposes LootConfig.reload() internally. If you want a quick reload command, add something like:

// pseudo-code in plugin.onEnable() getCommand("oereload")?.setExecutor { sender, _, _, _ -> LootConfig.reload() sender.sendMessage("OverEnchanted config reloaded") true }

(Implement command handling according to your command framework.)

Files / Classes

me.axiumyu.overEnchanted.OverEnchantedPlugin — main class (onEnable registers components)

me.axiumyu.overEnchanted.items.OEItems — factories for Magic Runes / Cores / Table ItemStacks

me.axiumyu.overEnchanted.items.RuneSmeltListener — blasting smelt of enchanted books → runes (works with Recipes.register())

me.axiumyu.overEnchanted.items.RuneGrindstoneListener — grindstone purification of runes

me.axiumyu.overEnchanted.recipes.Recipes — registers the BlastingRecipe placeholder

me.axiumyu.overEnchanted.menu.OEMenu* — menu view, listener, logic (R / A B C / S / I / O)

me.axiumyu.overEnchanted.table.OverEnchantedTableBlockListener — stores ItemStack PDC into TileState when placing table; right-click to open GUI (with Y check)

me.axiumyu.overEnchanted.loot.* — LootConfig, LootInsertListener, CoreMobDropListener

me.axiumyu.overEnchanted.util.MM — text serializer (prepends to cancel italics)

FAQ

Q: Items placed in the GUI are disappearing — fixed? A: Yes — GUI close now refunds items. (If you want refunds on player quit or plugin disable, add PlayerQuitEvent or onDisable handling.)

Q: Smelting enchanted books in a blast furnace does nothing? A: The plugin registers a BlastingRecipe placeholder in onEnable(). The real rune creation happens in FurnaceSmeltEvent. If your server has custom furnace behavior, adapt accordingly.

Q: I don’t want the Y < -64 restriction A: See Developer Notes B — edit OverEnchantedTableBlockListener.onRightClick to alter/remove the height check.

Q: Why no third-party libraries? A: Kept minimal for now; will consider external libs if needed later.

Disclaimer (for server owners)

This plugin assumes players can access Y < -64. If your server does not allow this, you must modify the code/config or get developer help.

The plugin is a feature-complete prototype but still requires testing and tuning. It’s intended for server owners who can edit and test code. Test on a staging server before deploying to production.

Over Enchant