enchatlib

enchatlib

一款提供高阶附魔系统简化解决方案的模组

EnchantLib

英文 | 中文

面向 Minecraft 26.2 (Fabric) 的纯服务端自定义附魔库。让模组开发者用一套简洁 API 完成附魔的注册、互斥组、获取途径、事件回调与客户端资源分发，无需手写数据包、Mixin 或资源包逻辑。

  • 版本：26.2-1.0.1
  • 环境：Minecraft 26.2 · Fabric Loader ≥ 0.19.3 · Fabric API · Java 25
  • 运行侧：纯服务端（客户端无需安装，资源由内置 HTTP 服务器自动推送）
  • 许可证：MIT

为什么需要 EnchantLib

在 MC 26.2 原生附魔系统下，自定义附魔需要手写大量胶水代码：运行时数据包注入、装备附魔扫描的事件分发、互斥组标签、战利品表修改、村民交易注入、客户端语言文件分发……EnchantLib 把这些都封装成声明式 API，你只需实现一个 entrypoint 接口即可。

核心能力一览：

能力 说明
附魔注册 EnchantmentBuilder 链式构建，注入运行时数据包，完全复用原生附魔系统
互斥组 声明附魔互斥关系，支持引用原版 7 个互斥组 + 自定义互斥组
战利品注入 把附魔书/已附魔物品注入原版 60+ 战利品表
村民交易 加入 #minecraft:tradeable 自动出售，或注册自定义定价交易（13 种职业）
事件系统 11 种 per-enchantment 事件（攻击/tick/弹射物/方块/交互…）+ 2 种全局事件
触发策略 按攻击充能门控与等级缩放，平衡生存服体验
玩家分类 EntityCategory 把玩家标记为亡灵/节肢/灾厄/水生，让对应怪物不攻击
实体计数器 EntityCounter 命名空间隔离的线程安全计数器，玩家离线自动清理
资源分发 自动合并跨模组语言文件，内置 HTTP 服务器推送资源包
配置定义附魔 管理员通过 TOML 配置文件定义附魔，无需改代码
运维指令 /enchantlib list / give / groups / dump / reload / debug

性能设计：BuiltInEvents 使用位掩码短路，未安装实现模组时零开销；LIVING_ENTITY_TICK 懒挂载，无回调时不订阅 ServerTickEvents；单附魔回调异常自动隔离，不影响其他附魔与原版逻辑。

安装

玩家（服务端使用者）

把 enchantlib-26.2-1.0.1.jar 放入服务端 mods/ 目录。客户端无需安装，玩家加入时 EnchantLib 会自动推送本地化资源包（如服务器开启了资源分发）。

依赖：Minecraft 26.2、Fabric Loader、Fabric API。

开发者（模组作者）

  1. 添加依赖（在你的 build.gradle）：
dependencies {
    modImplementation "com.enchantlib:enchantlib:26.2-1.0.1"
}
  1. 声明 entrypoint（在你的 fabric.mod.json）：
{
  "entrypoints": {
    "enchantlib:enchantments": ["com.mymod.MyModEnchantments"]
  }
}
  1. 实现入口接口（完整最小示例）：
package com.mymod;

import com.enchantlib.api.*;

public class MyModEnchantments implements EnchantmentEntrypoint {

    @Override
    public void onRegisterEnchantments(EnchantmentRegistrar registrar) {
        registrar.register(EnchantmentBuilder.create("mymod:leech")
            .description("Leech")
            .supportedItems("#minecraft:enchantable/sharp_weapon")
            .weight(5).maxLevel(3)
            .minCost(5, 8).maxCost(20, 8).anvilCost(2)
            .slots("mainhand"));
    }
}

启动服务端，执行 /enchantlib list 即可看到 mymod:leech。

本 README 已涵盖常用用法（注册、配置、命令、部署）。完整 API 参考（事件系统、互斥组、战利品注入、村民交易、触发策略、EntityCategory、EntityCounter、资源分发等）见 GitHub 仓库内 docs/developer-guide.md，CurseForge 用户可至 GitHub 仓库查阅。

从源码构建 EnchantLib 本身

若你克隆了本仓库想自行构建 EnchantLib（而非作为依赖引入），需注意：构建脚本通过 libs/ 目录的本地 jar 引用 Fabric API（flatDir 仓库），这些 jar 因体积与惯例未纳入仓库。

运行时只需 1 个 jar：fabric-api-26.2.jar 是 JarJar 容器，META-INF/jars/ 内已嵌套全部子模块（fabric-api-base、fabric-loot-api-v3、fabric-lifecycle-events-v1 等 42 个）。但编译期 javac 不会解析 JarJar 嵌套 jar，外层容器顶层不含 .class，因此 build.gradle 额外显式引用了 7 个子模块 jar 作为编译类源。故从源码构建需把以下 8 个 jar 放入 libs/：

libs/
  fabric-api-26.2.jar              # 运行时容器(JarJar,内嵌全部子模块)
  fabric-api-base-2.0.4.jar        # 编译类源:Event 基类
  fabric-command-api-v2-3.1.0.jar  # 编译类源:CommandRegistrationCallback
  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）。然后执行 ./gradlew build。普通模组开发者无需此步骤（通过 maven 引入 EnchantLib 即可）。

配置文件

EnchantLib 在 config/enchantlib/ 下读取三组配置：

acquisition.toml（全局开关）

loot_injection_enabled = true        # 战利品注入总开关
villager_trade_enabled = true        # 村民交易总开关
resource_distribution_enabled = true # 客户端资源分发总开关
http_server_port = 8765              # 资源包 HTTP 服务器端口
http_server_host = ""                # 对外完整网址(公网部署必填,可含端口;留空仅局域网可用)
debug_enabled = false                # 调试日志开关
entity_tick_interval = 20            # ENTITY_TICK 触发间隔(单位 tick)

trigger.toml（触发策略覆盖）

按附魔 ID 覆盖代码注册的 TriggerPolicy，优先级高于代码：

force_threshold_min = 0.0            # 全局默认阈值

["mymod:leech"]
mode = "THRESHOLD_SCALED"            # IGNORE / THRESHOLD / SCALED / THRESHOLD_SCALED
threshold = 0.7                      # 充能阈值 0.0~1.0

enchantments/*.toml（配置文件定义附魔）

管理员无需改代码即可定义附魔，详见开发者手册第 13 节。

运维指令

指令 用途
/enchantlib list 列出所有已注册附魔
/enchantlib give <enchantment> [level] 手持物品直接附魔（测试用）
/enchantlib groups 列出所有互斥组
/enchantlib dump <enchantment> 输出附魔完整定义（JSON）
/enchantlib reload 重载 acquisition.toml 配置
/enchantlib debug status 查看调试状态与系统统计
/enchantlib debug toggle 切换运行时调试开关
/enchantlib debug info <enchantment> 查看指定附魔详细信息

公网部署提示

资源分发默认监听 0.0.0.0:8765，但推送给客户端的下载 URL 主机地址由 http_server_host 决定。公网部署必须配置此项为对外完整网址（域名或公网 IP，可含端口），否则客户端收到的下载 URL 指向局域网地址，无法下载资源包：

http_server_host = "play.example.com"   # 走 80/反代不带端口;直连非 80 端口写 "play.example.com:8080"

http_server_port（默认 8765）只是本地监听端口（服务端绑定用），不进对外 URL。对外端口由 http_server_host 决定：走 80/反代时 host 不带端口；直连非 80 端口时把端口写在 host 里（如 play.example.com:8080）。

若不需要客户端本地化（例如纯生存服不显示附魔名），可设 resource_distribution_enabled = false 关闭整个资源分发系统。

文档

以下文档位于 GitHub 仓库内，CurseForge 项目页不展示，请前往 GitHub 仓库查阅：

  • 开发者手册 — 完整 API 参考（注册、事件系统、互斥组、战利品、交易、触发策略、EntityCategory、EntityCounter、资源分发）
  • 玩家指南 — 面向服主与玩家
  • 管理指南 — 面向服主运维

示例模组

示例 mod 已拆为独立仓库（enchantlib-examplemod），实现 12 个附魔展示 API 的完整用法。详见独立仓库的 README。

技术栈

  • Minecraft 26.2 原生附魔系统（运行时数据包注入）
  • Fabric Loader + Fabric API
  • 10 个 Mixin（事件桥接、玩家分类拦截、运行时数据包注入）
  • NightConfig TOML（配置解析）
  • 内置 HTTP 服务器（资源包分发）

作者

liluo23 · MIT License