EnchantLib Example Mod

English | 中文

The official example mod for EnchantLib, fully demonstrating EnchantLib API usage with 12 custom enchantments. Can be used directly as a mod development template.

• Mod ID: enchantlib-examplemod
• Version: 1.0.1
• Dependencies: Minecraft 26.2 · Fabric Loader ≥ 0.19.3 · Fabric API · EnchantLib ≥ 1.0.1
• License: MIT

---

What is this

This mod does not aim for gameplay balance; instead, it demonstrates each type of EnchantLib API with a concrete enchantment: from the simplest "register one enchantment" to advanced "Display entity rotation visuals + mark detonation". Developers can read the source code to understand each API's usage, or directly copy the source structure as a starting point for a new mod.

The source code is split "one file per enchantment"; the entry only does dispatch, making it easy to read one by one:

examplemod/
  ExampleModEnchantments.java     # Entry: delegates to sub-modules + exclusive sets/loot/villager trades
  enchantment/
    DisguiseEnchantments.java     # 4 disguises combined + EntityCategory + LIVING_ENTITY_TICK
    AutoSmeltEnchantment.java     # MODIFY_BLOCK_DROPS + SmeltingLookup
    SlimeSlayerEnchantment.java   # MODIFY_DAMAGE + POST_ATTACK AoE splash
    ExecutionerEnchantment.java   # MODIFY_DAMAGE conditional damage add/subtract
    RetributionEnchantment.java   # AFTER_DAMAGE listening + MODIFY_DAMAGE
    SilentPactEnchantment.java    # FOOD_REGEN suppression + AFTER_DEATH kill heal
    HeartburnEnchantment.java     # POST_ATTACK mark + LIVING_ENTITY_TICK continuous damage
    EchoMarkEnchantment.java      # PROJECTILE_HIT mark + AFTER_DAMAGE detonate
    FrostEnchantment.java         # POST_ATTACK visuals + Display entity rotation

---

12 enchantments at a glance

Name	Level	Applicable items	Effect	Demonstrated API
Undead Disguise undead_disguise	I	Helmet	When worn, the player is marked as undead; undead mobs no longer target the player	EntityCategory + LIVING_ENTITY_TICK
Aquatic Disguise aquatic_disguise	I	Helmet	Player is marked as aquatic; aquatic mobs no longer attack	Same (4 disguises share the same file, sharing the tick callback)
Illager Disguise illager_disguise	I	Helmet	Player is marked as illager; illagers no longer attack	Same
Arthropod Disguise arthropod_disguise	I	Helmet	Player is marked as arthropod; arthropods no longer attack	Same
Auto Smelt auto_smelt	I	Pickaxe/Shovel	Breaking blocks directly drops smelting products, with smelting XP bonus	MODIFY_BLOCK_DROPS + SmeltingLookup
Slime Slayer slime_slayer	V	Sword/Axe	+2.5 damage per level against slime-type mobs; splash hits level+1 targets within a 20-block radius	MODIFY_DAMAGE + POST_ATTACK splash
Executioner executioner	III	Sword/Axe	Reduces damage at high HP / increases damage at low HP; threshold scales with level	MODIFY_DAMAGE conditional branch
Retribution retribution	II	Sword/Axe	Within 5 seconds of being hit, the next attack deals +30%/+50% of original damage	AFTER_DAMAGE global listening + EntityCounter + MODIFY_DAMAGE
Silent Pact silent_pact	II	Chest armor	Suppresses natural regen; kills restore 2×level HP	FOOD_REGEN interception + AFTER_DEATH
Heartburn heartburn	II	Sword	Attacks apply a continuous true damage mark (2%/3% maxHP per second) + flame particles	POST_ATTACK mark + LIVING_ENTITY_TICK continuous damage
Echo Mark echo_mark	II	Bow	Arrow hits leave a 4-second mark; next hit detonates for 50% of missing health damage	PROJECTILE_HIT + AFTER_DAMAGE detonate
Frost frost	II	Sword	Applies Slowness + 3 ice block display entities rotating irregularly + snowflake particles	POST_ATTACK + LIVING_ENTITY_TICK + Display entity

---

Acquisition paths demo

The example mod also demonstrates EnchantLib's acquisition APIs, allowing enchantments to actually enter the player's gameplay flow:

Path	Enchantments involved	Demonstrated API
Simple Dungeon / Mineshaft (30%)	Slime Slayer, Executioner	LootInjectionBuilder multi-table injection
Desert Pyramid / Jungle Temple (25%)	Retribution, Undead Disguise, Arthropod Disguise	Multi-enchantment merged injection
End City Treasure (40%)	Heartburn, Frost	High-rarity injection
Woodland Mansion (30%)	Echo Mark	Single-enchantment injection
Ancient City (35%)	Silent Pact	Treasure enchantment (only this path; not open to trades and enchanting table)
Shipwreck Supply (20%)	Auto Smelt	Tool-type enchantment injection
Shipwreck Treasure / Ocean Ruin (30%)	Aquatic Disguise	Distributed to corresponding structures by category
Pillager Outpost (25%)	Illager Disguise	Same
Librarian auto-sell	7 combat/tool enchantments	TradeableEnchantmentsBuilder adds to #minecraft:tradeable
Weaponsmith Lv3	Heartburn (enchanted diamond sword)	VillagerTradeBuilder custom trade
Weaponsmith Lv4	Executioner (enchanted diamond sword)	Same
Cartographer Lv3	Echo Mark (enchanted book)	Same
Leatherworker Lv2	Auto Smelt (enchanted book)	Same
Cleric Lv4	Frost (enchanted book)	Same
Armorer Lv2	4 disguises (enchanted iron helmet, 1 of 4)	Multi-enchantment random trade

Exclusive sets: The 4 disguise enchantments are mutually exclusive (cannot coexist on the same helmet); Heartburn is exclusive with the vanilla Flame enchantment.

---

How to run

This project is a standalone Fabric mod project. You need to first build the prerequisite EnchantLib to get the jar, then place it in libs/ before compiling and running.

1. Build the prerequisite EnchantLib

git clone <enchantlib-repo>
cd enchantlib
.\gradlew build                   # produces build/libs/enchantlib-26.2-1.0.1.jar

The Fabric API local jars required by EnchantLib's build are described in the prerequisite repo's README.

2. Prepare local dependencies

Copy the following jars to this project's libs/ directory:

libs/
  enchantlib-26.2-1.0.1.jar       # output of the previous step
  fabric-api-26.2.jar              # Fabric API runtime container (JarJar, embeds all submodules)
  fabric-api-base-2.0.4.jar        # compile class source (transitive dependency of EnchantLib API)
  fabric-command-api-v2-3.1.0.jar
  fabric-entity-events-v1-5.0.5.jar
  fabric-events-interaction-v0-5.2.6.jar
  fabric-lifecycle-events-v1-4.1.3.jar
  fabric-loot-api-v3-3.0.17.jar
  fabric-permission-api-v1-1.0.3.jar

These jars can be extracted from the Fabric API 0.155.2+26.2 release package (runtime container + flattened sub-module jars).

3. Build and run

cd example-mod
.\gradlew runServer               # start the example mod server
.\gradlew runClient               # start the example mod client (connecting to local server)
.\gradlew build                   # produces build/libs/enchantlib-examplemod-1.0.1.jar

After the server starts, players receive the resource pack automatically upon joining (enchantment localization names). Use /enchantlib list to view all 12 enchantments, and /enchantlib give <id> [level] to enchant the held item directly for testing.

The packaged artifact enchantlib-examplemod-1.0.1.jar must be placed in the server's mods/ directory alongside enchantlib-26.2-1.0.1.jar.

---

As a development template

If you want to write your own enchantment mod based on the example mod, you can reference this project's structure as a template:

1. Rename ExampleModEnchantments to your entry class, and delete unwanted enchantment sub-modules
2. Keep the resolveEnchantment public helper and the MOD_ID constant
3. Add new files per enchantment following the enchantment/XxxEnchantment.java pattern: register for registration, registerCallbacks to bind events, and private static methods to implement callbacks

Each enchantment file is self-contained: its own ID constant, Holder field, event callbacks, mutually independent, easy to read and maintain.

---

Related documentation

• EnchantLib developer manual — see the prerequisite enchantlib repo's docs/developer-guide.md (complete API reference)

Author

liluo23 · MIT License

---

中文

EnchantLib 官方示例模组,用 12 个自定义附魔完整展示 EnchantLib API 的用法,可直接作为模组开发模板。

• Mod ID:enchantlib-examplemod
• 版本:1.0.1
• 依赖:Minecraft 26.2 · Fabric Loader ≥ 0.19.3 · Fabric API · EnchantLib ≥ 1.0.1
• 许可证:MIT

---

这是什么

本模组不追求游戏性平衡,而是把 EnchantLib 每一类 API 都用一个具体附魔演示一遍:从最简单的「注册一个附魔」到高级的「Display 实体旋转视觉 + 标记引爆」。开发者可以对照源码理解每个 API 的用法,也可以直接复制源码结构作为新模组的起点。

源码已按「每个附魔一个文件」拆分,入口仅做调度,便于逐个阅读:

examplemod/
  ExampleModEnchantments.java     # 入口:委托各子模块 + 互斥组/战利品/村民交易
  enchantment/
    DisguiseEnchantments.java     # 4 伪装合一 + EntityCategory + LIVING_ENTITY_TICK
    AutoSmeltEnchantment.java     # MODIFY_BLOCK_DROPS + SmeltingLookup
    SlimeSlayerEnchantment.java   # MODIFY_DAMAGE + POST_ATTACK 范围溅射
    ExecutionerEnchantment.java   # MODIFY_DAMAGE 条件增减伤
    RetributionEnchantment.java   # AFTER_DAMAGE 监听 + MODIFY_DAMAGE
    SilentPactEnchantment.java    # FOOD_REGEN 压制 + AFTER_DEATH 击杀回血
    HeartburnEnchantment.java     # POST_ATTACK 标记 + LIVING_ENTITY_TICK 持续伤害
    EchoMarkEnchantment.java      # PROJECTILE_HIT 标记 + AFTER_DAMAGE 引爆
    FrostEnchantment.java         # POST_ATTACK 视觉 + Display 实体旋转

---

12 个附魔一览

名称	等级	适用物品	效果	演示的 API
亡灵伪装 undead_disguise	I	头盔	穿戴时玩家被标记为亡灵,亡灵不再锁定玩家	EntityCategory + LIVING_ENTITY_TICK
深海伪装 aquatic_disguise	I	头盔	玩家被标记为水生生物,水生生物不再攻击	同上(4 伪装同文件,共享 tick 回调)
灾厄伪装 illager_disguise	I	头盔	玩家被标记为灾厄村民,灾厄不再攻击	同上
节肢伪装 arthropod_disguise	I	头盔	玩家被标记为节肢动物,节肢不再攻击	同上
自动烧炼 auto_smelt	I	镐/铲	破坏方块直接掉落熔炼产物,补充熔炼经验	MODIFY_BLOCK_DROPS + SmeltingLookup
粘液杀手 slime_slayer	V	剑/斧	对粘液类每级 +2.5 伤害;溅射半径 20 格内 等级+1 个目标	MODIFY_DAMAGE + POST_ATTACK 溅射
处刑人 executioner	III	剑/斧	高血减伤/低血增伤,阈值随等级变化	MODIFY_DAMAGE 条件分支
回敬 retribution	II	剑/斧	受击 5 秒内下次攻击 +30%/+50% 原伤害	AFTER_DAMAGE 全局监听 + EntityCounter + MODIFY_DAMAGE
静默契约 silent_pact	II	胸甲	压制自然回血;击杀回 2×等级 HP	FOOD_REGEN 拦截 + AFTER_DEATH
焚心 heartburn	II	剑	攻击施加持续真伤标记(每秒 2%/3% maxHP)+ 火焰粒子	POST_ATTACK 标记 + LIVING_ENTITY_TICK 持续伤害
音痕 echo_mark	II	弓	箭命中留 4 秒标记,再次受击引爆已损失生命 50% 伤害	PROJECTILE_HIT + AFTER_DAMAGE 引爆
冰霜 frost	II	剑	施加缓慢 + 3 个冰方块展示实体不规律自转 + 雪花粒子	POST_ATTACK + LIVING_ENTITY_TICK + Display 实体

---

获取途径演示

示例模组同样演示了 EnchantLib 的获取途径 API,让附魔能真正进入玩家的游戏流程:

途径	涉及附魔	演示的 API
简单地下城 / 废弃矿道(30%)	粘液杀手、处刑人	LootInjectionBuilder 多表注入
沙漠神殿 / 丛林神庙(25%)	回敬、亡灵伪装、节肢伪装	多附魔合并注入
末地城宝藏(40%)	焚心、冰霜	高稀有度注入
林地府邸(30%)	音痕	单附魔注入
远古城市(35%)	静默契约	宝藏附魔(仅此途径,不开放交易与附魔台)
沉船补给(20%)	自动烧炼	工具类附魔注入
沉船宝藏 / 海底废墟(30%)	深海伪装	按分类分散到对应结构
掠夺者前哨站(25%)	灾厄伪装	同上
图书管理员自动出售	7 个战斗/工具附魔	TradeableEnchantmentsBuilder 加入 #minecraft:tradeable
武器匠 Lv3	焚心(附魔钻石剑)	VillagerTradeBuilder 自定义交易
武器匠 Lv4	处刑人(附魔钻石剑)	同上
制图师 Lv3	音痕(附魔书)	同上
皮匠 Lv2	自动烧炼(附魔书)	同上
牧师 Lv4	冰霜(附魔书)	同上
盔甲匠 Lv2	4 伪装(附魔铁头盔 4 选 1)	多附魔随机交易

互斥组:4 个伪装附魔互斥(同一头盔不可并存);焚心与原版火焰附加互斥。

---

如何运行

本项目是独立 Fabric mod 项目,需先构建前置 EnchantLib 获得 jar,再放入 libs/ 才能编译运行。

1. 构建前置 EnchantLib

git clone <enchantlib-repo>
cd enchantlib
.\gradlew build                   # 产出 build/libs/enchantlib-26.2-1.0.1.jar

EnchantLib 构建所需的 Fabric API 本地 jar 见前置仓库 README 说明。

2. 准备本地依赖

把以下 jar 复制到本项目的 libs/ 目录:

libs/
  enchantlib-26.2-1.0.1.jar       # 上一步构建产出
  fabric-api-26.2.jar              # Fabric API 运行时容器(JarJar,内嵌全部子模块)
  fabric-api-base-2.0.4.jar        # 编译类源(EnchantLib API 传递依赖)
  fabric-command-api-v2-3.1.0.jar
  fabric-entity-events-v1-5.0.5.jar
  fabric-events-interaction-v0-5.2.6.jar
  fabric-lifecycle-events-v1-4.1.3.jar
  fabric-loot-api-v3-3.0.17.jar
  fabric-permission-api-v1-1.0.3.jar

这些 jar 可从 Fabric API 0.155.2+26.2 发布包中提取(运行时容器 + 各子模块平铺 jar)。

3. 构建运行

cd example-mod
.\gradlew runServer               # 启动示例 Mod 服务端
.\gradlew runClient               # 启动示例 Mod 客户端(连本地服务端)
.\gradlew build                   # 产出 build/libs/enchantlib-examplemod-1.0.1.jar

服务端启动后,玩家加入即自动获得资源包(附魔本地化名称)。可用 /enchantlib list 查看全部 12 个附魔,/enchantlib give <id> [level] 手持物品直接附魔测试。

打包产物 enchantlib-examplemod-1.0.1.jar 需与 enchantlib-26.2-1.0.1.jar 一并放入服务端 mods/ 目录。

---

作为开发模板

如果你想基于示例模组写自己的附魔模组,可参考本项目结构作为模板:

1. 把 ExampleModEnchantments 改名为你的入口类,删掉不需要的附魔子模块
2. 保留 resolveEnchantment 公共助手与 MOD_ID 常量
3. 每个附魔按 enchantment/XxxEnchantment.java 的模式新增文件:register 注册、registerCallbacks 绑事件、私有静态方法实现回调

每个附魔文件都是自包含的:自己的 ID 常量、Holder 字段、事件回调,互不干扰,便于阅读和维护。

---

相关文档

• EnchantLib 开发者手册 — 见前置 enchantlib 仓库的 docs/developer-guide.md(完整 API 参考)

作者

liluo23 · MIT License