谷神星 · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

Ceres

一个客户端 Fabric 模组，用于自动种植作物——跟随录制的航点路径、按住攻击键破坏作物、自动管理驱虫剂，并实时监控耕作数据的仪表板。以罗马农业女神命名。

GitHub： https://github.com/noname-mods/Ceres

运行需要 PlayerAPI 和 YetAnotherConfigLib。 ModMenu 是可选的——它会在模组列表中添加一个设置按钮。

功能

航点路径跟随

Ceres 在按住攻击键破坏作物的同时，会跟随一系列录制的航点。两个独立的路径槽位（主路径和辅助路径）让您可以定义不同的路线——例如去程和回程。每条路径都有独立的速度切换开关。路径通过在游戏中行走您的路线并按路径编辑器中的“在此添加”来录制。

智能档案自动加载

当您启动机器人时，Ceres 会读取您手持工具的显示名称并自动加载匹配的作物档案。小麦锄加载您的小麦档案；胡萝卜锄加载胡萝卜——即使是重铸过的工具也能正常工作，因为匹配是基于子字符串的。档案将完整的路径配置（两个槽位 + 速度设置）保存为命名的文件，您可以随时切换。

被动安全检查器

耕作时，四个独立的监控器持续运行：

检查器	行为
物品栏	监控您的快捷栏是否有物品变化。如果 6 秒内无变化，机器人假定被卡住并停止。
工具	检测您手中物品是否从初始状态改变并记录警告。不会停止机器人——其他系统会正常切换物品。
偏航/俯仰	检测外力是否意外旋转相机。播放警报音效并显示标题覆盖层，但继续耕作——机器人仍在运行。
害虫	从玩家列表读取实时害虫数量。当达到您设定的阈值时播放警报音效。不会停止机器人。

无论检查器开关状态如何，区域检查始终激活：如果玩家列表显示您已离开花园，机器人会立即停止并将完全控制权交还给您。

驱虫剂管理器

读取来自 Hypixel 玩家列表的“驱虫剂：”计时器。当读到“无”时，Ceres 会暂停机器人，切换到您快捷栏中的驱虫剂，使用它，等待玩家列表更新，然后恢复耕作——全程无需您动手。适用于所有驱虫剂等级。

实时 HUD 覆盖

一个可配置的覆盖面板，显示多达 14 行直接从 Hypixel 玩家列表提取的耕作数据：

机器人状态、当前激活的档案和当前区域
玩家坐标和相机视角
实时害虫数量与您的警报阈值
地块、喷雾、驱虫剂计时器、奖励、冷却时间和奖励害虫几率
路径类型和航点进度（运行时）
每秒方块数——一个 30 秒滚动平均值，显示您的耕作速率
下一个航点坐标

在配置界面中，每一行都可以单独显示或隐藏。主 HUD 下方的一个小型日志面板显示最近 5 条机器人消息。

每秒方块数（BPS）追踪

Ceres 会计算每个被破坏的作物方块，并维护一个 30 秒的滚动窗口。HUD 中的实时 BPS 数值反映您的实际吞吐量，为您提供一个一致的数值来比较不同路径和作物。

完全可配置

所有设置都通过一个包含七个选项卡的 YACL 配置界面公开。可以通过 ModMenu、/ceres 命令或快捷键打开。无需编辑文件。

控制

所有快捷键均可通过 选项 → 控制 → Ceres 重新绑定。

动作	默认按键
启动主路径	O
启动辅助路径	U
暂停	P
恢复	J
停止	K
切换 HUD	；
打开路径编辑器	I
打开配置	(无绑定)

在聊天中输入 /ceres 可直接打开配置界面。

安装

为 Minecraft 26.1.2 安装 Fabric Loader
安装 Fabric API
安装 PlayerAPI
安装 YetAnotherConfigLib
安装 ModMenu (可选)
将 ceres-*.jar 放入您的 mods 文件夹

兼容性

Minecraft	Fabric Loader	Java
26.1.2	≥ 0.19.2	21

Minecraft 版本支持

本模组一次只支持一个 Minecraft 版本。 当它更新到新的 Minecraft 版本时，之前的版本将不再获得任何进一步的支持——没有向后移植，没有错误修复，并且永远不会为同时支持多个 Minecraft 版本而发布版本。

想要最新功能？您必须使用该模组当前支持的 Minecraft 版本。
想留在旧的 Minecraft 版本上？请保留在该版本的最后一个版本上——它不会更新。

游戏内的更新检查器能感知 Minecraft 版本：如果最新版本针对的 Minecraft 版本与您正在运行的版本不同，它会告知您，而不是提示您安装不兼容的构建。

面向开发者

Ceres — 设计与参考文档

版本： 1.1.2 Minecraft： 26.1.2 (Fabric) 依赖： PlayerAPI 1.12.0+

AI 会话快速入门

如果您是在此文件夹中工作的新 Claude Code 会话，请先阅读此内容。

本模组是什么

Ceres 是一个用于 Hypixel Skyblock 的 客户端耕作自动化机器人。它沿着预先录制的航点路径移动玩家，按住攻击键破坏作物，自动使用驱虫剂，监控安全状况，并显示实时 HUD。它完全构建在 PlayerAPI 之上，从不直接导入 Minecraft 内部代码。

关键依赖

依赖	版本字段	位置
PlayerAPI	`gradle.properties` 中的 `playerapi_version`	`C:\Users\willi\Documents\completeMods\PlayerAPI`

构建顺序： 如果您更改了 PlayerAPI，请先在那里运行 ./gradlew publishToMavenLocal，然后再构建 Ceres。

源码布局（各部分位置）

src/main/java/com/ceres/
├── CeresMod.java                  — 入口点、事件绑定、快捷键处理
├── core/
│   ├── BotState.java              — 枚举：STOPPED / PAUSED / RUNNING
│   ├── BotStateManager.java       — 中央单例：所有实时状态、玩家列表数据、BPS追踪
│   ├── BotConfig.java             — 所有持久化设置、JSON配置、版本化迁移
│   └── BotLogger.java             — 环形缓冲区记录器 + 文件输出
├── path/
│   ├── Waypoint.java              — record(x, y, z, pathType)
│   ├── PathType.java              — 枚举：PRIMARY / SECONDARY / EVACUATION
│   ├── PathConfig.java            — 内存中的路径模型（航点 + 循环标志）
│   ├── PathManager.java           — 每 tick 行走路径（移动 + 攻击）
│   ├── ProfileManager.java        — 加载/保存命名的 .json 档案文件
│   └── CropToolMapper.java        — 将工具物品 ID 映射到档案名称（自动加载）
├── tablist/
│   └── CeresTabListReader.java    — 每 tick 解析 Hypixel 玩家列表 → BotStateManager 字段
├── checkers/
│   ├── CheckerController.java     — 编排所有检查器，随机重置间隔
│   ├── InventoryChecker.java      — 检测物品栏停滞（作物没有变化）
│   ├── ToolChecker.java           — 验证手中持有正确的工具
│   ├── YawPitchChecker.java       — 检测意外的视角方向变化
│   └── PestChecker.java           — 当害虫数量达到阈值时停止机器人
├── repellent/
│   └── PestRepellentManager.java  — 检测驱虫剂到期，自动从物品栏使用
└── gui/
    ├── BotHudRenderer.java        — 所有 HUD 渲染（主面板 + 日志面板）
    ├── CeresConfigScreen.java     — YACL 配置界面（5 个选项卡）
    └── PathEditorScreen.java      — 路径录制/编辑 GUI

配置文件（位于 `<game>/config/ceres/`）

文件	内容
`config.json`	所有 `BotConfig` 设置（模式版本化，自动迁移）
`paths.json`	当前的航点数据（主路径 + 辅助路径 + 撤离路径）
`profiles/<name>.json`	每个已保存的档案一个文件（格式与 paths.json 相同）
`ceres.log`	追加的日志输出

BotConfig 模式版本 — 当前：4

当添加一个默认值为 true（布尔值）的新配置字段时，您必须添加一个迁移步骤——GSON 默认将缺失的布尔值设为 false。模式：

提升 CURRENT_VERSION
添加 migrateVn() 方法
在 migrate() 中调用它
将字段添加到 load() 中的手动复制块

如果 INSTANCE 需要在构造函数中迭代一个新的静态列表，请在类中的 INSTANCE 之前声明该列表——静态字段按声明顺序初始化，否则会导致 NullPointerException（这是一个真实出现的错误）。

HUD 行键（全部 14 个，用于 BotConfig.hudLines 映射）

"profile"、"area"、"xyz"、"look"、"pests"、"plots"、"spray"、"repellent"、"bonus"、"cooldown"、"pest_chance"、"path"、"bps"、"target"

这些键是事实来源。BotConfig.ALL_HUD_LINES 是权威列表。配置界面、HUD 渲染器和迁移都源于此。

PlayerAPI 使用版本

Ceres 当前使用 PlayerAPI 1.12.0。此处使用的最新版本中的关键新增功能：

TabListInfo.isLineStrikethrough(String substring) — 用于检测被划掉的“奖励害虫几率”行
PlayerAPIEvents.BLOCK_BROKEN — 用于 BPS（每秒方块数）追踪
SoundActions.playByIdRepeated() — 用于所有警报音效
UpdateChecker — 共享更新检查器（1.12.0）；替换了 Ceres 自己的副本
DisplayActions — 未在 Ceres 中使用（在 Poseidon 中使用）

您可能需要修改的常见事项

添加新的 HUD 行：

将键字符串添加到 BotConfig.ALL_HUD_LINES
提升 BotConfig.CURRENT_VERSION 并添加迁移
将开关添加到 CeresConfigScreen（使用 hudLineOption() 辅助函数）
在 BotHudRenderer 中添加渲染调用（使用 cfg.isHudLineVisible("key") 作为门控）
如果值来自玩家列表，在 CeresTabListReader 中添加解析，并在 BotStateManager 中添加字段和 getter

添加新的配置设置：

向 BotConfig 添加字段和 getter/setter
添加到 BotConfig.load() 中的手动复制块
将 YACL 选项添加到 CeresConfigScreen 中的相应选项卡
如果它是一个默认值为 true 的新布尔值：添加迁移

更改玩家列表解析：

所有玩家列表逻辑都在 CeresTabListReader.java 中
值通过 setter 写入 BotStateManager
TabListInfo 是所使用的 PlayerAPI 类（静态方法，无需实例化）

关键设计规则

Ceres 从不导入 net.minecraft.*，除非在 BotHudRenderer（仅渲染）和 CeresMod（快捷键注册 + Fabric 钩子）中。所有玩家交互、世界查询和调度都通过 PlayerAPI 类进行。

概述与目的
架构
安装
配置文件
机器人生命周期 — 状态
路径系统
安全检查器
驱虫剂管理器
玩家列表读取器
BotStateManager
BotConfig — 所有设置
HUD 覆盖
GUI 界面
- 13.1 配置界面
- 13.2 路径编辑器界面
快捷键
游戏内命令
BotLogger
已知行为与设计决策

1. 概述与目的

Ceres 是一个用于 Minecraft 26.1.2 的 客户端 Fabric 耕作自动化模组。它沿着预先录制的路径移动玩家，按住攻击键破坏作物，并管理一套支持系统：驱虫剂自动使用、安全检查器、实时 HUD 覆盖层以及用于编辑路径和配置的 GUI。

Ceres 完全构建在 PlayerAPI 之上——它从不直接导入 Minecraft 内部代码。所有玩家移动、物品栏访问、交互和世界查询都通过 PlayerAPI 的抽象层进行。

Ceres 能做什么：

遵循用户定义的航点路径（两条路径：主路径和辅助路径），同时按住攻击键，破坏玩家触及范围内的作物。
在驱虫剂到期时自动重新使用。
监控意外情况（离开耕作区域、物品栏无变化、视角方向变化、害虫数量阈值）并相应地停止或发出警报。
每 tick 读取服务器的玩家列表，以在 HUD 覆盖层中显示实时耕作指标。
保存和加载命名的档案，以便玩家可以即时在作物配置之间切换。
根据机器人启动时手持的工具自动检测要加载的档案。

Ceres 不能做什么：

导航到耕作区域（它假设您已经在那里）。
处理战斗、钓鱼、采矿或任何非耕作活动。
修改服务器端数据。

2. 架构

CeresMod (入口点)
│
├── onTick() — 每 tick 通过 PlayerAPIEvents.TICK 调用
│   ├── CeresTabListReader.update()          — 将玩家列表数据拉取到状态中
│   ├── PestRepellentManager.tick()          — 检查并应用驱虫剂
│   ├── PathManager.tick()      [RUNNING]    — 推进航点跟随
│   ├── CheckerController.tick() [RUNNING]   — 运行所有安全检查器
│   ├── MovementActions.pressKey("attack")   — 心跳，每 20 ticks
│   └── handleKeybinds()                     — 处理按键
│
├── BotStateManager (单例)              — 所有运行时状态的唯一事实来源
│
├── BotConfig (单例)                    — 持久化设置 (config.json)
│
├── PathConfig (单例)                   — 持久化航点 (paths.json)
│
├── ProfileManager                      — 命名的档案 (profiles/<name>.json)
│
├── BotHudRenderer                      — 通过 HudRenderCallback 绘制的 HUD 覆盖层
│
├── CeresConfigScreen                   — YACL 配置 GUI (/ceres)
│
├── PathEditorScreen                    — 航点编辑器 GUI (I 键)
│
└── BotLogger                           — 内存环形缓冲区 + 文件日志

Tick 流程

PlayerAPIEvents.TICK (主游戏线程，每 tick)
    │
    ├─ CeresTabListReader.update()
    │      读取所有玩家列表行 → 将值推送到 BotStateManager
    │
    ├─ PestRepellentManager.tick()
    │      如果驱虫剂计时器 = "None" 且冷却时间已过 → 暂停机器人，应用，恢复
    │
    ├─ [if RUNNING] PathManager.tick()
    │      向下一航点前进；在每个周期结束时：循环或停止并发出警报
    │
    ├─ [if RUNNING] CheckerController.tick()
    │      每 60–100 ticks：重置检查器基线
    │      在重置之间：运行所有四个检查器
    │
    ├─ [if RUNNING] pressKey("attack") 每 20 ticks
    │      心跳以防止攻击键被释放
    │
    ├─ [if PAUSED] releaseAll()
    │      安全：确保暂停时没有按住移动键
    │
    └─ handleKeybinds()
           处理来自此 tick 的任何按键按下

3. 安装

为 Minecraft 26.1.2 安装 Fabric Loader 0.19.2。
安装 Fabric API 0.149.1+26.1.2。
将 PlayerAPI playerapi-1.12.0.jar 放入您的 mods 文件夹。
将 Ceres ceres-1.1.1.jar 放入您的 mods 文件夹。
（可选）安装 ModMenu 以在模组列表中获取“配置”按钮。

Ceres 在首次启动时会在 .minecraft/config/ceres/ 生成其配置文件。

4. 配置文件

所有 Ceres 数据都位于 .minecraft/config/ceres/：

文件 / 目录	内容
`config.json`	所有机器人设置（模式版本化，自动迁移）。
`paths.json`	当前加载的主路径和辅助路径的航点。
`alias.json`	命令别名（名称 → 命令字符串映射）。
`ceres.log`	只追加日志文件。所有 INFO/WARN/ERROR 消息都在此处。
`profiles/`	命名的档案文件目录，每个档案一个 `.json` 文件。
`profiles/<name>.json`	一个档案：两种路径类型的航点 + 速度设置。

档案与 paths.json 完全分开。 在路径编辑器中加载档案会将其数据复制到实时编辑缓冲区中。单击“完成”会将该缓冲区保存到 paths.json。如果您未单击“完成”就关闭编辑器，更改将被丢弃，paths.json 保持不变。

5. 机器人生命周期 — 状态

机器人始终处于三种状态之一，由 BotStateManager.getCurrentState() 跟踪：

STOPPED ──startBot()──► RUNNING ──pauseBot()──► PAUSED
   ▲                        │                      │
   └──────stopBot()──────────┘◄──resumeBot()────────┘

STOPPED

模组加载时的默认状态。
没有按住移动键。
没有运行检查器。
驱虫剂管理器仍在运行（它也监控 PAUSED 状态）。
HUD 以红色显示状态标签。

RUNNING

PathManager 每 tick 向前推进航点。
CheckerController 运行所有四项安全检查。
攻击键被按住（每 20 ticks 有一个心跳重新按下，以防松开）。
HUD 以绿色显示状态标签。

PAUSED

每 tick 释放所有移动键（在 tick 循环中强制执行）。
PathManager 不运行。
CheckerController 不运行。
驱虫剂管理器继续运行——它可以在已暂停时触发暂停→应用→恢复序列。
HUD 以 橙色/黄色 显示状态标签。

启动机器人

startBot(PathType) 按顺序执行以下操作：

验证玩家是否在“花园”区域内（除非启用旁路或设置了 checksBypassed）。
将状态设置为 RUNNING。
将手持物品记录为 ToolChecker 的“初始工具”。
清除 BPS 滑动窗口并记录运行开始 tick。
调用 MovementActions.setActive(true)。

停止机器人

stopBot() 执行以下操作：

将状态设置为 STOPPED。
释放所有移动键。
调用 MovementActions.setActive(false)。
调用 Scheduler.cancelAll() — 清除所有待处理的计划任务。
清除 BPS 滑动窗口。

启动时自动加载

当通过 O（主路径）或 U（辅助路径）快捷键启动机器人时，autoLoadAndStart() 首先运行：

调用 CropToolMapper.resolveProfile() 以识别手持工具。
如果找到匹配的档案，并且启用了该作物的自动加载（在 BotConfig 中），则在调用 startBot() 之前将档案加载到 PathConfig 中。
设置 HUD 中显示的当前档案名称。
如果未找到档案或禁用了自动加载，则使用当前在 PathConfig 中的任何路径启动。

6. 路径系统

6.1 航点

Waypoint 是机器人必须在路径上到达的单个点。

class Waypoint {
    double x;
    double y;              // Y 被记录但不用于移动（仅限 2D 导航）
    double z;
    List<String> forcedKeys;  // 在此航点和下一个航点之间要按住哪些移动键
}

forcedKeys 精确确定机器人如何移向此航点：

如果列表为空，则机器人不按住任何方向键，并等待航点进入 0.5 个方块范围内（适用于静止航点或基于传送的移动）。
如果存在按键，则每 tick 按住这些键，直到到达航点。
速度是在不论设置什么键的基础上添加的，由每条路径的速度设置控制——它不是强制键。

forcedKeys 的有效键名： "forward"、"back"、"left"、"right"、"sneak"、"jump"。（"sprint" 由速度开关单独处理。）

航点到达阈值： 0.5 个方块（X/Z 平面上的 2D 距离）。Y 坐标在到达检测中被忽略。

6.2 PathType

恰好有两种路径类型：

枚举值	默认快捷键	典型用途
`PRIMARY`	O	主要耕作路线
`SECONDARY`	U	辅助或返回路线

每种路径类型在 PathConfig 中都有其独立的航点列表和速度设置。

6.3 PathConfig

存储当前激活的航点列表。持久化到 config/ceres/paths.json。

{
  "version": 2,
  "sprint": {
    "PRIMARY": true,
    "SECONDARY": false
  },
  "paths": {
    "PRIMARY": [
      { "x": 100.5, "y": 64.0, "z": -200.5, "forcedKeys": ["forward"] },
      { "x": 110.5, "y": 64.0, "z": -200.5, "forcedKeys": ["forward"] }
    ],
    "SECONDARY": []
  }
}

PathConfig 是机器人实际运行的实时文件。档案是分开的——加载档案仅在您在路径编辑器中按下“完成”时才将数据复制到 PathConfig 中。

6.4 PathManager

在机器人处于 RUNNING 状态时，每 tick 驱动移动。

航点跟随循环：

tick()
  → 如果尚未跟随：startPathFollowing()
  → 如果 messUpTimer > 0：释放所有按键，倒计时（反检测暂停）
  → 否则：followPathStep()
      → 计算到当前航点的 2D 距离
      → 如果在 0.5 个方块内：前进索引，记录“到达航点 N”
      → 否则：应用 forcedKeys（+ 速度如果启用）
      → attemptMessUp()：每 tick 约 1/180,000 概率暂停 10–30 ticks

周期完成（索引到达列表末尾）：

单次循环模式： 停止机器人并播放周期完成警报音效。
正常模式： 重置索引为 0，发送周期开始命令（如果配置），开始新循环。

周期开始命令： 在每个周期开始时（包括第一次）和每次循环重置后发送的命令（默认："warp garden"）。发送时带有 5 tick 延迟以允许状态稳定。如果意外包含前导的 /，则会被去除。

速度： 当 PathConfig.isSprintEnabled(currentPathType) 为 true 时，在 forcedKeys 之上应用速度。速度是每条路径独立的，并且为主路径和辅助路径单独切换。

路径开始时潜行： 如果 BotConfig.isSneakOnPathStart() 为 true，则机器人在每次路径开始时短暂按下潜行 5 ticks（250 毫秒），以在移动前锁定朝向。

6.5 ProfileManager

管理保存在 config/ceres/profiles/ 中的命名档案。

一个档案包含：

主路径和辅助路径的航点列表。
两种路径类型的速度设置。

档案通过文件名（不带 .json 扩展名）标识。文件名经过清理——\ / : * ? " < > | 中的任何字符都被替换为下划线。

档案操作：

操作	结果
保存档案	将当前编辑器状态写入 `profiles/<name>.json`。不触碰 `paths.json`。
加载档案	读取 `profiles/<name>.json`，返回一个 `ProfileData` 记录。调用者将其应用于 PathConfig。
删除档案	删除 `profiles/<name>.json`。
列出档案	返回档案目录中所有 `.json` 文件名按字母顺序排序的列表。
打开档案文件夹	打开操作系统文件浏览器到档案目录。

档案文件格式：

{
  "version": 2,
  "sprint": { "PRIMARY": true, "SECONDARY": false },
  "paths": {
    "PRIMARY": [ { "x": 100.0, "y": 64.0, "z": -200.0, "forcedKeys": ["forward"] } ],
    "SECONDARY": []
  }
}

6.6 CropToolMapper

将玩家手持工具的显示名称映射到档案名称。仅在机器人启动时由 autoLoadAndStart() 使用。

匹配基于子字符串且不区分大小写。 键碎片（例如 "wheat hoe"）只需要出现在完整显示名称的某处，因此重铸或升级的物品如 "Blessed Euclid's Wheat Hoe Mk. II" 也能正确匹配。

完整的工具 → 档案映射：

工具名称子字符串	解析到的档案
`"cactus knife"`	`Cactus`
`"carrot hoe"`	`Carrot`
`"cocoa chopper"`	`Cocoa Beans`
`"fungi cutter"`	`Mushroom`
`"melon dicer"`	`Melon`
`"nether wart hoe"`	`Nether Wart`
`"potato hoe"`	`Potato`
`"pumpkin dicer"`	`Pumpkin`
`"sugar cane hoe"`	`Sugarcane`
`"wheat hoe"`	`Wheat`
`"wild rose hoe"`	`Wild Rose`
`"eclipse hoe"`	见下文

Eclipse 锄特殊情况： Eclipse 锄同时用于向日葵和月光花（它们是同一种植物，但在一天中的不同时间开花）。解析优先级：

磁盘上同时存在 Sunflower 和 Moonflower 档案 → 解析为 "Sunflower"。
仅存在一个 → 解析为该档案。
两者都不存在 → 返回 null（不自动加载；机器人以当前路径启动）。

ALL_CROPS——CropToolMapper 可以解析到的完整档案名称列表，按字母顺序排序。由 BotConfig 用于构建每个作物的开关存储，并由配置界面用于构建 UI：

Cactus, Carrot, Cocoa Beans, Melon, Moonflower, Mushroom,
Nether Wart, Potato, Pumpkin, Sugarcane, Sunflower, Wheat, Wild Rose

7. 安全检查器

所有检查器都由 CheckerController 协调。它们仅在机器人处于 RUNNING 状态时运行。每个检查器可以在 BotConfig 中单独启用/禁用。

7.1 CheckerController

在 RUNNING 状态下每 tick 运行。在 每隔 60–100 ticks（3–5 秒）随机间隔 交替的两个阶段中运行：

重置阶段： 将当前玩家状态快照为所有检查器的新基线。随机间隔可防止可检测的模式。

检查阶段： 针对当前状态运行所有四个检查器。每个检查器返回 true（正常）或 false（问题）。

区域检查（始终开启，无论检查器开关状态如何）： 如果玩家列表区域已知（非空）并且不是 "Garden"，则机器人立即停止并播放停止警报音效。这是唯一不能通过检查器开关绕过的硬停止。

旁路模式： 如果 BotStateManager.isChecksBypassed() 为 true，则跳过整个检查器 tick。这在开发和路径录制期间很有用。不会在标准配置界面中公开——可通过编程方式或通过调试命令切换。

7.2 InventoryChecker

目的： 检测机器人何时卡住——如果 6 秒（120 ticks）内没有物品进入或离开快捷栏，则耕作很可能已停止。

工作原理：

重置时：快照当前的快捷栏（ItemSnapshot 列表）。
检查时：将当前快捷栏与上一个快照进行比较。
- 如果不同：更新快照并记录该 tick。
- 如果未改变：如果自上次更改以来已过 120 ticks，则返回 false。

失败时： 停止机器人并播放停止警报音效。

重要提示： 120 tick 窗口是根据上次更改 检查的，而不是上次重置。如果物品栏频繁变化但随后冻结，则检查器会在 6 秒无变化后正确触发——即使最近发生了重置。

7.3 ToolChecker

目的： 检测玩家手持物品是否从机器人启动时的物品发生改变。

工作原理：

重置时：记录 BotStateManager.getInitialTool()（调用 startBot() 时手持物品的显示名称）。
检查时：将当前手持物品的显示名称与初始工具进行比较（不区分大小写）。

失败时： 记录警告并继续。不会停止机器人。这是有意为之——其他系统（包括驱虫剂管理器）会合法地切换物品，机器人应无论如何继续耕作。

7.4 YawPitchChecker

目的： 检测外部力量（另一个模组、玩家或服务器端传送）是否意外改变了玩家的视角方向。

工作原理：

重置时：记录当前的偏航和俯仰作为基线。
检查时：计算当前值与基线之间的角度差。
- 偏航差经过环绕校正（处理 0°/360° 边界）。
- 如果偏航变化超过 1.0° 或俯仰变化超过 1.0°，则发出警报。
- 始终将基线更新为当前值，以便跟踪渐进的漂移而不会重复警报。

失败时： 显示屏幕标题（§c⚠ LOOK CHANGED / §eBot is still running）并播放警告警报音效。不会停止机器人——耕作不受中断地继续。目的是提醒玩家，以便他们可以在需要时手动干预。

7.5 PestChecker

目的： 当玩家列表中的实时害虫数量达到配置的最低阈值时发出警报。

工作原理：

读取 BotStateManager.getPestCount() 并与 BotConfig.getMinPestCount() 进行比较。
如果 pestCount >= minPestCount，返回 false。
速率限制：每 600 ticks（30 秒）最多警报一次，以避免警报刷屏。

失败时： 播放警告警报音效。不会停止机器人。 警报是信息性的——是否停止并处理害虫由玩家决定。

8. 驱虫剂管理器

在驱虫剂到期时自动使用。无论机器人状态如何（RUNNING、PAUSED 或 STOPPED——但不在 STOPPED 状态时），每 tick 运行。

检测触发： 监视 BotStateManager.getPestRepellentTimerText()。当此值等于 "None"（不区分大小写，去除空格）时，驱虫剂已到期。

冷却时间： 使用间隔至少 1200 ticks（60 秒）。这可以防止在使用驱虫剂后玩家列表更新缓慢时快速重新使用。

使用序列：

如果机器人正在 RUNNING → 暂停它。
在快捷栏中搜索显示名称以 "Pest Repellent" 开头的物品（匹配所有等级：I、II、MAX 等）。如果未找到，记录警告，跳过并恢复。
切换到驱虫剂槽位。
等待 5 ticks（250 毫秒）以使槽位切换生效。
使用该物品（右键单击）。
等待 1200 ticks（60 秒）的内部冷却时间。
如果机器人在暂停前正在 RUNNING →

Ceres

功能

航点路径跟随

智能档案自动加载

被动安全检查器

驱虫剂管理器

实时 HUD 覆盖

每秒方块数（BPS）追踪

完全可配置

控制

安装

兼容性

Minecraft 版本支持

面向开发者

Ceres — 设计与参考文档

AI 会话快速入门

本模组是什么

关键依赖

源码布局（各部分位置）

配置文件（位于 <game>/config/ceres/）

BotConfig 模式版本 — 当前：4

HUD 行键（全部 14 个，用于 BotConfig.hudLines 映射）

PlayerAPI 使用版本

您可能需要修改的常见事项

关键设计规则

目录

1. 概述与目的

2. 架构

Tick 流程

3. 安装

4. 配置文件

5. 机器人生命周期 — 状态

STOPPED

RUNNING

PAUSED

启动机器人

停止机器人

启动时自动加载

6. 路径系统

6.1 航点

6.2 PathType

6.3 PathConfig

6.4 PathManager

6.5 ProfileManager

6.6 CropToolMapper

7. 安全检查器

7.1 CheckerController

7.2 InventoryChecker

7.3 ToolChecker

7.4 YawPitchChecker

7.5 PestChecker

8. 驱虫剂管理器

评论

配置文件（位于 `<game>/config/ceres/`）