MeowsEnchants
中文版
MeowsEnchants 是一个用于 Paper/Folia 的自定义附魔插件,允许通过 YAML 声明附魔,并在 Paper 插件引导阶段将其注册到原版附魔注册表中。
1. 概述
MeowsEnchants 将自定义附魔像原版附魔一样注册到服务器中,而不是像许多传统自定义附魔插件那样通过 NBT、PersistentDataContainer 数据或物品描述(lore)来模拟附魔效果。
与常见的基于 NBT 或物品描述的自定义附魔插件相比,本插件在以下几个方面有所不同:
- 自定义附魔被注册到原版注册表中。它们表现得如同真实的原版附魔,可以直接通过 Bukkit API 访问,因此本插件无需提供单独的 API。
- 已注册的附魔可以直接从创造模式物品栏、原版
/minecraft:enchant 命令或其他插件的 /enchant 命令中获得,并且可以正确读取其属性。
- 已注册的附魔支持原版风格的冲突机制、适用物品、铁砝成本以及其他注册表属性,从而天然兼容其他基于附魔的插件。
- 附魔效果由触发器(triggers)、目标(targets)和操作(actions)组合声明式地定义,而不是为每个附魔硬编码独立的 Java 实现。
- 插件监听器独立控制每种附魔出现在村民交易和附魔台刷新中的逻辑与概率。
2. 兼容性
- 目标服务器:Paper/Folia
1.21.11 - 26.2+
- Java:
25
- 插件类型:使用
paper-plugin.yml 中 bootstrapper 字段的 Paper 插件
- Folia:完全支持
| 服务器 / 版本 |
兼容性 |
结果 |
Folia 1.21.11 - 26.2+ |
✅支持 |
主要目标环境;已针对 Folia 调度器模型进行适配。 |
Paper 1.21.11 - 26.2+ |
✅支持 |
回退至普通 Paper 调度器,但仍需要 Paper 插件引导程序和注册表 API 支持。 |
Paper/Folia 1.21.10 及更低版本 |
❌不支持 |
缺少插件使用的实验性 API:RegistryComposeEvent 和必需的 ItemTypeTagKeys。 |
| Spigot / CraftBukkit |
❌不支持 |
它们不提供 Paper 插件引导程序或 Paper 注册表修改 API。 |
| Paper 下游分支如 Purpur, Leaf, Leaves |
✅支持 |
如果分支保留了相应的实验性 Paper API,则受支持。 |
Paper 的注册表修改 API 是实验性的。未来的 Paper/Folia 更新可能会改变 API 结构;如果出现相关问题,请报告。
3. 工作原理
附魔注册
在引导阶段,插件会读取 plugins/MeowsEnchants/enchants/*.yml。
每个附魔都有自己独立的 YAML 文件,并声明:
- 附魔 ID、显示名称、最大等级、铁砧成本、适用物品标签以及冲突附魔
- 触发器,例如攻击、挖掘、右键点击、被动、潜行、重生等
- 目标,例如自身、玩家、生物或命中实体
- 操作,例如额外伤害、药水效果、爆炸、多块挖掘、重新种植、速度、命令等
- 独立的附魔台和图书管理员村民交易规则
每个有效的 YAML 文件会被解析为一个 EnchantConfig,然后通过 Paper 的 RegistryEvents.ENCHANTMENT.compose() 注册到原版附魔注册表中。注册设置包括:
- 附魔描述文本
- 适用物品标签
- 激活装备槽位
- 最大附魔等级
- 铁砧成本
- 附魔台最小和最大成本
- 冲突附魔集合
触发器 (Triggers)
插件监听 Bukkit/Paper 事件,并根据配置的触发器执行操作。常见的触发时机包括:
- 战斗:攻击实体、受到伤害、用盾牌格挡、击杀实体
- 方块:破坏方块、左键挖掘方块、放置方块、右键交互
- 投射物:投射物击中实体或方块
- 玩家状态:开始潜行、保持潜行、开始疾跑、保持疾跑、周期性被动触发
- 玩家生命周期和物品:死亡、重生、交换手持物品、消耗物品
- 钓鱼:捕获鱼或实体、鱼咬钩
目标 (Targets)
在执行操作之前,插件会根据配置的目标解析附魔目标。支持的目标含义包括:
操作 (Actions)
操作在 actions 列表中声明,并在附魔触发时按顺序执行。内置操作包括:
potion_effect, bonus_damage, healthsteal, teleport, explosion, velocity, shockwave, break_armor, drop_head, attribute_modifier, multi_break, vacuum_drops, replant, multi_arrow, repair, hook, feast, deflect, till, reflect_damage, command, block_break
详细的操作参数未在本 README 中记录。请参阅:
- English: docs/action_types_en.md
- 中文版:docs/action_types_zh.md
4. 用法
- 下载插件 jar 文件。
- 将插件 jar 放入服务器
plugins/ 目录。
- 启动服务器一次,让插件生成
plugins/MeowsEnchants/config.yml。
- 在
plugins/MeowsEnchants/enchants/ 下为每个自定义附魔创建一个 YAML 文件。
- 重启服务器。附魔配置更改需要完全重启服务器。自定义附魔只能在引导阶段注册,无法通过重载动态添加到服务器注册表中。
- 成功注册的自定义附魔可以直接在创造模式物品栏、JEI/REI 附魔列表以及配方查询视图中查看。
全局配置文件路径:plugins/MeowsEnchants/config.yml。它目前控制以下内容:
- Skyllia 兼容性逻辑,用于使附魔尊重岛屿保护机制
- 附魔台概率是否考虑玩家等级
- 书本概率平衡,使自定义附魔在书本上比在武器或装备上更难获得
附魔配置文件路径:
plugins/MeowsEnchants/enchants/<enchant_id>.yml
5. 构建
本项目使用 Maven。依赖项从 PaperMC Maven 仓库和 PlaceholderAPI 仓库解析。
项目当前使用 Java 25。构建前,请确保本地 JDK 与 Maven 使用的 Java 版本匹配。
使用正常的 Maven 安装:
mvn clean package
构建输出:
target/meowsenchants-0.1.jar
许可证
本项目采用 MIT 许可证授权。详见 LICENSE。
MeowsEnchants
中文版
MeowsEnchants is a Paper/Folia custom enchantment plugin for declaring enchantments in YAML and registering them into the vanilla enchantment registry during the Paper plugin bootstrap phase.
1. Overview
MeowsEnchants registers custom enchantments into the server like vanilla enchantments, instead of imitating enchantments through NBT, PersistentDataContainer data, or item lore like many traditional custom enchantment plugins.
Compared with common NBT- or lore-based custom enchantment plugins, this plugin is different in several ways:
- Custom enchantments are registered into the vanilla registry. They behave like real vanilla enchantments and can be accessed directly through the Bukkit API, so this plugin does not need to provide a separate API.
- Registered enchantments can be obtained directly from the creative inventory, vanilla
/minecraft:enchant, or other plugins' /enchant commands, and their properties can be read correctly.
- Registered enchantments support vanilla-style conflicts, applicable items, anvil costs, and other registry properties, making them naturally compatible with other enchantment-based plugins.
- Enchantment effects are composed declaratively with triggers, targets, and actions instead of hardcoding a separate Java implementation for each enchantment.
- Plugin listeners independently control the logic and probability for each enchantment to appear in villager trades and enchanting table rolls.
2. Compatibility
- Target server: Paper/Folia
1.21.11 - 26.2+
- Java:
25
- Plugin type: Paper plugin using the
bootstrapper field in paper-plugin.yml
- Folia: full support
| Server / Version |
Compatibility |
Result |
Folia 1.21.11 - 26.2+ |
✅Supported |
Primary target environment; adapted for the Folia scheduler model. |
Paper 1.21.11 - 26.2+ |
✅Supported |
Falls back to the normal Paper scheduler, but still requires Paper plugin bootstrapper and Registry API support. |
Paper/Folia 1.21.10 and lower |
❌Not supported |
Missing experimental APIs used by the plugin: RegistryComposeEvent and required ItemTypeTagKeys. |
| Spigot / CraftBukkit |
❌Not supported |
They do not provide the Paper plugin bootstrapper or Paper Registry Mutation API. |
| Paper downstreams such as Purpur, Leaf, Leaves |
✅Supported |
Supported if the fork keeps the corresponding experimental Paper API intact. |
Paper's Registry Mutation API is experimental. Future Paper/Folia updates may change the API shape; please report issues if they occur.
3. How It Works
Enchantment Registration
During the bootstrap phase, the plugin reads plugins/MeowsEnchants/enchants/*.yml.
Each enchantment has its own YAML file and declares:
- Enchantment ID, display name, maximum level, anvil cost, applicable item tag, and conflicting enchantments
- Trigger, such as attack, mining, right-click, passive, sneaking, respawn, and more
- Target, such as self, players, mobs, or hit entities
- Actions, such as bonus damage, potion effects, explosions, multi-block mining, replanting, velocity, commands, and more
- Independent enchanting table and librarian villager trade rules
Each valid YAML file is parsed into an EnchantConfig, then registered into the vanilla enchantment registry through Paper's RegistryEvents.ENCHANTMENT.compose(). Registration sets:
- Enchantment description text
- Applicable item tag
- Active equipment slots
- Maximum enchantment level
- Anvil cost
- Enchanting table minimum and maximum cost
- Conflicting enchantment set
Triggers
The plugin listens to Bukkit/Paper events and executes actions according to the configured trigger. Common trigger timings include:
- Combat: attacking entities, taking damage, blocking with a shield, killing entities
- Blocks: breaking blocks, left-click mining blocks, placing blocks, right-click interaction
- Projectiles: projectile hitting an entity or block
- Player states: starting sneaking, holding sneak, starting sprinting, holding sprint, periodic passive trigger
- Player lifecycle and items: death, respawn, swapping hands, consuming items
- Fishing: catching fish or entities, fish bite
Targets
Before actions execute, the plugin resolves the enchantment target according to the configured target. Supported target meanings include:
- The trigger player
- Target player
- Target mob
- All entities
- No target
Actions
Actions are declared in the actions list and executed in order when the enchantment triggers. Built-in actions include:
potion_effect, bonus_damage, healthsteal, teleport, explosion, velocity, shockwave, break_armor, drop_head, attribute_modifier, multi_break, vacuum_drops, replant, multi_arrow, repair, hook, feast, deflect, till, reflect_damage, command, block_break
Detailed action parameters are not documented in this README. See:
- English: docs/action_types_en.md
- 中文版:docs/action_types_zh.md
4. Usage
- Download the plugin jar.
- Put the plugin jar into the server
plugins/ directory.
- Start the server once and let the plugin generate
plugins/MeowsEnchants/config.yml.
- Create one YAML file for each custom enchantment under
plugins/MeowsEnchants/enchants/.
- Restart the server. Enchantment config changes require a full server restart. Custom enchantments can only be registered during bootstrap and cannot be dynamically added to the server registry through reload.
- Successfully registered custom enchantments can be viewed directly in the creative inventory, JEI/REI enchantment lists, and recipe lookup views.
Global config path: plugins/MeowsEnchants/config.yml. It currently controls:
- Skyllia compatibility logic, used to make enchantments respect island protection mechanics
- Whether enchanting table probability considers player level
- Book probability balancing, making custom enchantments harder to obtain on books than on weapons or equipment
Enchantment config file path:
plugins/MeowsEnchants/enchants/<enchant_id>.yml
5. Building
This project uses Maven. Dependencies are resolved from the PaperMC Maven repository and the PlaceholderAPI repository.
The project currently uses Java 25. Before building, make sure your local JDK matches the Java version used by Maven.
With a normal Maven installation:
mvn clean package
Build output:
target/meowsenchants-0.1.jar
License
This project is licensed under the MIT License. See LICENSE.
评论 0
登录后参与评分
还没有评论,来抢沙发吧