闪枢库

闪枢库

Thunderbolt_lib 是 AE2 Lightning Tech 的附加组件 API 和运行时桥接库。

基础库

AE2 Lightning Tech (AE2LT) 的插件 API 与运行时桥接库。让你可以在完全不接触其内部类的情况下,将自己的模组与 AE2LT 的闪电能源网络深度集成。

Thunderbolt_lib 是任何用于扩展、修改或挂钩 AE2LT 闪电系统的第三方插件的必需依赖。它本身不提供任何物品、方块或配方——只提供冻结的公共 API、NeoForge 能力契约、配方构建器,以及一个在 AE2LT 缺失时能优雅降级的反射运行时桥接。

为什么下载它?

  • 玩家 / 整合包作者 —— 如果某个模组或整合包将 ae2lt_api 列为依赖,请将此 jar 与 AE2 Lightning Tech 一同安装。
  • 插件开发者 —— 依赖此库,即可访问 AE2LT 的机器、配方类型与闪电能源能力,而无需耦合到 AE2LT 的内部类。

重要: 只有在同一 Minecraft 实例中安装了 AE2 Lightning Tech 时,Thunderbolt_lib 才会做有意义的工作。两个模组必须同时存在。

目标

Minecraft 1.21.1
加载器 NeoForge 21.1.x
Java 21
目标 AE2 Lightning Tech(自 AE2LT 引入其闪电网络以来向后兼容)
运行时模组 ID ae2lt_api

该项目以 Thunderbolt_lib 之名呈现,但注册为 ae2lt_api,因此现有的插件依赖声明不受影响。

它提供了什么

闪电能源能力

让你的方块和物品成为 AE2LT 闪电网络的一等公民。ILightningEnergyHandler 通过两个 NeoForge 能力暴露——LIGHTNING_ENERGY_BLOCK(按面)和 LIGHTNING_ENERGY_ITEM(无面)——实现该接口并注册即可参与读写。所有数量均以 long 表示,可干净地从单台机器扩展到全网络记账。

闪电能源等级

一个统一的双电压定义,可在各 API 表面之间无损流转。LightningEnergyTier 是一个双值枚举(HIGH_VOLTAGE / EXTREME_HIGH_VOLTAGE),并附带:

  • CODEC —— Mojang 的 Codec<LightningEnergyTier>
  • STREAM_CODEC —— 原版的 StreamCodec<RegistryFriendlyByteBuf, LightningEnergyTier>
  • fromOrdinal(int) —— 基于序号的静态解码器

它与 AE2LT 自己的 LightningTier 共享线路格式,因此数据包与 NBT 可在两个 API 之间干净地往返,无需任何手写适配器。

反射运行时桥接

AE2LT 缺失时不会崩溃——只会优雅降级。此库不在加载时硬引用 AE2LT 的类,而是在运行时反射探测它们,并将闪电能源能力挂接到 AE2LT 公开注册的五个并网方块实体上:

  • ae2lt:lightning_collector
  • ae2lt:lightning_simulation_room
  • ae2lt:lightning_assembly_chamber
  • ae2lt:overload_processing_factory
  • ae2lt:tesla_coil

ae2lt:crystal_catalyzer 仅以 FE 运行,不参与闪电能源网络,故被有意排除在外。

冻结的 ID 常量

无需将 AE2LT 的主 jar 拖入编译路径,即可引用其注册表 ID。两组 ResourceLocation 常量集将所有内容集中在一处:

  • AE2LTBlockEntityIds —— AE2LT 的方块实体 ID,外加 LIGHTNING_GRID_MEMBERS(上述五个并网机器的列表)
  • AE2LTRecipeIds —— AE2LT 的配方类型 ID

两者均位于 com.qianchang.ae2lt_api.api.ids。如果 AE2LT 日后重命名任何内部资源,补丁会落在此处,插件无需追查。

原生 API 检测桥接

让你的模组中两种 API 表面共存,由你掌控调用哪一个。com.qianchang.ae2lt_api.api.bridge.AE2LTNativeBridge 会在运行时检查 AE2LT 的第一方 API 包(com.moakiee.ae2lt.api,命名空间 ae2lt)是否已加载。

表面 本库 AE2LT 第一方
Java 包 com.qianchang.ae2lt_api.api.* com.moakiee.ae2lt.api.*
命名空间 ae2lt_api ae2lt
能力 ID ae2lt_api:lightning_energy ae2lt:lightning_energy

两种 API 表面刻意在命名空间上区分;此库不执行它们之间的任何隐式转换,因此调用方须明确选择使用哪一侧。

事件

拦截闪电收集并应用你自己的条件逻辑。当 AE2LT 收集器拾取闪电能源时,会触发 LightningCollectedEvent。该事件可取消,并暴露 isNaturalWeather()(用于区分真实雷暴与机器引发的雷击)以及对应的 5 参数构造函数;原始的 4 参数构造函数被保留,naturalWeather 默认为 false,因此迁移毫无痛楚。

配方构建器

为全部六种 AE2LT 配方类型生成符合 schema 的 JSON——直接放入你的数据生成管线:

构建器 配方类型
LightningAssemblyRecipeBuilder ae2lt:lightning_assembly
LightningTransformRecipeBuilder ae2lt:lightning_transform
LightningSimulationRecipeBuilder ae2lt:lightning_simulation
OverloadProcessingRecipeBuilder ae2lt:overload_processing
CrystalCatalyzerRecipeBuilder ae2lt:crystal_catalyzer
LightningStrikeRecipeBuilder ae2lt:lightning_strike

CrystalCatalyzerRecipeBuilder 额外支持 dustMode() 和 outputTag(...),匹配 AE2LT 的 crystal_catalyzer/dust/*.json schema。

插件加载与 API 门面

统一的注册回调,无需手写 NeoForge 生命周期接线。插件发现通过 @AE2LTPlugin、IAE2LTPlugin 和 Java ServiceLoader 运行;静态门面 AE2LTAPI 将 API 版本、能力句柄和桥接工具集中到单一入口点,只需一次 import static 即可引入,并在整个代码库中以最少的样板代码使用。

添加为依赖

插件开发者——在 neoforge.mods.toml 中将 ae2lt_api(本库)和 ae2lt(主模组)都声明为必需:

[[dependencies.your_mod_id]]
    modId = "ae2lt_api"
    type = "required"
    versionRange = "[1.0.0,)"
    ordering = "AFTER"
    side = "BOTH"

[[dependencies.your_mod_id]]
    modId = "ae2lt"
    type = "required"
    versionRange = "[1.0.0,)"
    ordering = "AFTER"
    side = "BOTH"

将 versionRange 的下界设为你的插件实际支持的最低版本。

反馈

欢迎在项目问题追踪器上提交 bug 报告和建议。报告问题时,请附上你运行的 Minecraft、NeoForge、AE2 Lightning Tech 和 Thunderbolt_lib 版本——这能大大加快复现与分类。

源码、变更日志、发布

致谢

由 QianChang 维护与开发。

特别感谢 AE2 Lightning Tech 团队——MOAKIEE、CystrySU、gjmhmm8、_leng、TedXenon 和 MHanHanBing——发布了清晰、稳定的注册表 ID 和配方 schema,使此桥接成为可能。

同样感谢 Applied Energistics 2 团队——没有 AE2 就没有 AE2LT,也就没有此桥接存在的理由。

免责声明

此名称仅用于非商业性的社区用途。若任何权利持有人认为该名称构成侵权或不妥,请联系维护者,将及时更改。

完整声明 —— DISCLAIMER.md