1.2 安装与依赖配置¶

BallisticsFramework 是一个纯粹的库模组，它不提供任何游戏内物品或方块——玩家只需要将它放入 mods 文件夹；开发者则需要在自己的项目中正确声明编译依赖和运行时依赖。

环境要求¶

Minecraft 版本：1.21.1
NeoForge 版本：21.1.219 及以上
Java 版本：21 或更高

前置模组¶

BallisticsFramework 没有额外的前置模组——它只依赖 NeoForge 本身。无需安装其他运行时库。

作为玩家安装¶

将 BallisticsFramework 的 jar 文件放入模组文件夹（.minecraft/mods/ 或服务器的 mods/）。启动游戏后可以在模组列表中找到 "Terminal Ballistics"。单独安装此模组不会对游戏产生任何可见变化——它仅为依赖它的其他模组提供服务。

作为开发者引入¶

方式一：本地 jar 依赖（推荐）¶

将 ballistics_framework-1.21.1-1.0-SNAPSHOT.jar 放入项目的 libs/ 目录，然后在 build.gradle 中声明：

repositories {
    mavenLocal()
}

dependencies {
    implementation files("libs/ballistics_framework-1.21.1-1.0-SNAPSHOT.jar")
}

方式二：源集依赖¶

如果 BallisticsFramework 的源码与你的项目位于同一工作空间，可以将它作为子项目引入：

implementation project(":BallisticsFramework")

方式三：Maven 发布（未来）¶

当 BallisticsFramework 发布到 Maven 仓库后，可以直接通过依赖坐标引入。此方式将在正式发布后更新说明。

声明模组依赖关系¶

引入 jar 只是让编译通过。要让 NeoForge 在加载时正确识别依赖关系，还需要在自己的 neoforge.mods.toml 中声明对 BallisticsFramework 的依赖：

[[dependencies."你的modid"]]
    modId = "ballistics_framework"
    type = "required"
    versionRange = "[1.0,)"

这里的 type 可以是 required（强制依赖）、optional（可选依赖，运行时做 null 检查）或 discouraged（不推荐但允许同时安装）。对于使用协议 API 的模组，通常应使用 required。如果你需要兼容没有安装 BallisticsFramework 的环境（如降级为原版伤害），则使用 optional 并在代码中对 API 调用做 null guard。

依赖的 API 包¶

代码中只需 import io.github.sweetzonzi.ballistics_framework.api 包下的类。该包中的所有类和接口均为公开 API，保证跨版本兼容性。切勿 import internal 或 mixin 包下的类——它们不构成 API，行为可能在任何版本中改变。

最常用的 import 包括：

import io.github.sweetzonzi.ballistics_framework.api.BFDamageApi;
import io.github.sweetzonzi.ballistics_framework.api.BFDamageContext;
import io.github.sweetzonzi.ballistics_framework.api.BFHurtTarget;
import io.github.sweetzonzi.ballistics_framework.api.BFDamageHandler;
import io.github.sweetzonzi.ballistics_framework.api.ArmorLevel;
import io.github.sweetzonzi.ballistics_framework.api.PenetrationResult;
import io.github.sweetzonzi.ballistics_framework.api.BFDamageExtensions;

确认加载成功¶

启动客户端或服务器后，在日志中搜索 ballistics_framework，能看到类似的加载信息：

[main/INFO] [ne.mi.fm.lo.ImmediateWindowHandler/]: Loading mod: ballistics_framework

如果依赖声明了 type = "required" 但 lib 未安装，NeoForge 会在启动时抛出缺失依赖的错误并阻止游戏加载。如果一切正常，你可以开始编写代码了——下一节将分别从武器侧和护甲侧的角度展示最简示例。