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

Acquisition paths demo

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

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 个附魔一览

获取途径演示

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

互斥组: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