Nudge-Aim

# Nudge

一款适用于 Fabric 的轻量级客户端瞄准辅助模组。Nudge 不会让镜头瞬间锁定目标，而是将准星轻轻拉向目标命中箱内的随机点，每个游戏刻都让准星再靠近一些。

专为 **Minecraft 26.3** 和 Fabric 加载器打造。仅限客户端使用 — 无需安装到服务器上。

## 工作原理

每个客户端游戏刻，Nudge 都会执行三个步骤：

1. **选择目标**（`AimAssistLogic.findBestTarget`）— 扫描当前世界中的所有玩家，跳过自己、已死亡和不可见的玩家。如果候选玩家超出 `maxRange` 范围，或位于视野方向周围 `fovThreshold` 锥形范围之外，就会被排除。在剩余玩家中，选择与准星角度偏差最小的目标。
2. **选择瞄准点**（`AimAssistLogic.getRandomHitboxPoint`）— 使用高斯分布在目标的包围盒内随机选取一点，让瞄准位置偏向目标躯干中心，而不是固定锁定某一点：水平偏移的标准差为包围盒宽度的 20%，垂直方向则偏向目标高度的 55% 处。该点会被限制在命中箱内；切换目标或每 10 个游戏刻都会重新随机选取。
3. **轻推准星**（根据 `aimMode`，使用 `AimAssistLogic.applyLogNudge` 或 `applyAggressiveNudge`）— 对瞄准点的角度偏差进行对数缩放：偏差较大时拉动更明显，偏差较小时则轻柔地微调，且不会过冲。修正幅度不会超过剩余偏差；当偏差小于半个鼠标网格步长时（最低不小于 0.05°），则忽略此次修正。每次修正还会乘以 0.98 到 1.02 之间的随机系数，避免连续游戏刻的调整完全一致。

随后，`MouseGridQuantizer` 会将每次轻推对齐到 Minecraft 的鼠标灵敏度网格，因此模组每个游戏刻应用的旋转幅度，都可以由当前灵敏度下的真实鼠标移动产生。有关如何保留小于一个步长的修正，请参阅[量化](#quantization)。

每个游戏刻，旋转变化都会直接写入玩家的 yaw 和 pitch，并将 pitch 限制在 ±90°。

## 瞄准模式

具体的拉动计算方式由配置值 `aimMode` 决定。

– **`LOG`**（默认）— 纯对数追踪：`log(1 + delta) * strength`。平滑而稳定；偏差越大，拉动幅度越大，但增长缓慢。
– **`NUDGE`** — 同样采用对数计算，但会先将输入偏差提升至 `nudgeJerkPower` 次幂：`log(1 + delta^nudgeJerkPower) * strength`。指数大于 1.0 时，超过一度的偏差会被放大，小于一度的偏差则会被削弱，因此准星偏离较大时会更快拉回，偏差较小时则能更柔和地稳定下来。对新目标的瞄准会更灵敏、更果断。指数恰好为 1.0 时，此模式的效果与 `LOG` 相同。

两种模式都采用相同的死区、过冲上限、拟人化噪声和量化机制。

## 量化

鼠标移动一个原始单位，镜头就会旋转 `(sensitivity * 0.6 + 0.2)^3 * 8 * 0.15` 度 — 默认灵敏度下约为 0.16°。如果将每次轻推都四舍五入到最接近的步长倍数，所有小于半个步长的修正都会被丢弃；而在 `strength` 较低时，大多数修正都属于这种情况。

为此，`MouseGridQuantizer` 会将小于一个步长的余量逐游戏刻保留下来：

– 每次返回的微调量都是网格步长的精确倍数，方向可正可负（包括反向，用于抵消累积误差）。
– 累计旋转总量仍然跟踪未量化的对数拉力，因为余数从未被丢弃。
– 偏航角和俯仰角各自保留独立的余数。
– 切换目标或范围内没有目标时，余数会被重置，因为累积误差是针对一个已不再适用的点测量的。它们会在同一目标的 10 tick 瞄准点重掷后保留，因此缓慢的累积不会被丢弃。

由于携带的余数会让微调量最多超出剩余误差半个步长，上方的死区被设定为足以清除该超出量。没有它，超出量每 tick 都会翻转符号，镜头会在原地抖动。

## 配置

设置存储在 Minecraft 实例内的 `config/nudge_config.json` 中。该文件在首次启动时以默认值创建。如果安装了 Cloth Config 和 Mod Menu，可以通过 Mod Menu 的设置界面在游戏内编辑相同的值。

– **瞄准辅助模式**（`aimMode`，默认 `LOG`）— `LOG` 用于平滑跟踪，`NUDGE` 用于上述更干脆的功率缩放变体。
– **最大范围**（`maxRange`，默认 `4.5`）— 以方块为单位的检测半径。超出此范围的候选者会被忽略。
– **FOV 阈值**（`fovThreshold`，默认 `35.0`）— 准星与候选者之间被视为目标的最大角度偏移（度）。范围 5–180。
– **微调强度**（`strength`，默认 `0.15`）— 对数拉力的乘数。值越高拉力越快。范围 0.01–1.0。
– **微调急动功率**（`nudgeJerkPower`，默认 `1.3`）— 在对数运算之前应用于误差增量的指数。仅影响 `NUDGE` 模式。范围 1.0–3.0；值越高，对远处目标的吸附越快。
– **对数底数**（`logBase`，默认 `2.0`）— 目前瞄准数学中未使用；保留供未来调优。游戏内没有对应的设置项。

较低的 `strength` 和 `fovThreshold` 值会产生更温和、更不易察觉的辅助。提高 `fovThreshold` 会扩大锥形范围，但会让辅助感觉更具侵入性。

## 构建

需要 **JDK 25**（项目目标为 Java 25，无法在更旧的 JDK 上编译）。

“`sh
./gradlew build
“`

编译后的模组会写入 `build/libs/modid-1.0.0.jar`。将其与 Fabric API 和 Cloth Config 一起放入你的 `mods` 文件夹。

要运行加载了该模组的开发客户端：

“`sh
./gradlew runClient
“`

## 要求

运行时依赖，如 `fabric.mod.json` 中所声明：

– Minecraft `~26.3`
– Fabric Loader `>=0.19.2`
– Java `>=25`
– Fabric API
– Cloth Config

Mod Menu 是可选的，仅在需要游戏内设置界面时才需要。

## 项目结构

– `src/main/java/com/psipheron/nudge/ModConfig.java` — 基于 JSON 的配置加载/保存，包括 `AimMode` 枚举。
– `src/client/java/com/psipheron/nudge/NudgeClient.java` — 客户端入口点；注册 tick 结束处理器并驱动瞄准循环。
– `src/client/java/com/psipheron/nudge/AimAssistLogic.java` — 目标选择、瞄准点随机化，以及两种瞄准模式的对数旋转数学。
– `src/client/java/com/psipheron/nudge/MouseGridQuantizer.java` — 按轴将修正量吸附到鼠标灵敏度网格上。
– `src/client/java/com/psipheron/nudge/ModMenuIntegration.java` — 接入 Mod Menu 的 Cloth Config 界面。

游戏逻辑代码位于 `client` 源集（Loom 的 `splitEnvironmentSourceSets`），因为该模组仅限客户端。模组 ID（`nudge`）和 Java 包（`com.psipheron.nudge`）与资源路径和 Gradle 项目名仍在使用的模板 `modid` 命名空间不匹配。

## 已知限制

– **仅针对玩家。** 目标扫描会遍历 `client.level.players()`，因此不会考虑生物或其他实体。
– **始终启用。** 没有按键绑定或开关；只要有效目标在范围内，辅助功能就会每个游戏刻运行一次。
– **不检查视线。** 只要目标在范围内且处于视野锥内，即使隔着墙也会被追踪。
– **量化后的视角旋转不会经过鼠标输入路径。** 应用的角度变化虽然与网格对齐，但它们是通过 `setYRot`/`setXRot` 写入的，因此客户端自身的鼠标增量处理不会接收到这些变化。量化只能让每刻的变化看起来合理，并不能让最终视角与网格对齐：由于起始基准角度本身没有对齐，累积后的旋转也不会对齐。任何检查原始鼠标增量的下游系统（例如服务端反作弊）都看不到这些变化。
– **目标距离以脚部位置为准。** `findBestTarget` 测量的是到实体底部位置的距离，而不是到其碰撞箱中心的距离，因此实际有效范围会略短于 `maxRange` 所显示的数值。

## 许可证

`fabric.mod.json` 中声明的许可证为 `LGPL-3.0-only`。

本仓库中的 `LICENSE` 文件仍然包含从 Fabric 示例模组继承而来的 CC0 模板文本，与声明的许可证不符。发布前，请将其替换为 LGPL-3.0 许可证文本，或修改 `fabric.mod.json` 中的许可证字段——两者应保持一致。