通知
由于 Modrinth 的政策,本模组将不再更新;如果被下架,也不会尝试重新上架。不过,本模组将继续在其 GitHub 仓库中提供并更新:。访问该仓库时,也请查看我的另一个模组 Ceres,它旨在帮助进行农业活动,但从未被允许在 Modrinth 上列出。
Poseidon
一个客户端 Fabric 模组,用于自动化钓鱼——抛竿、等待咬钩、收杆和再次抛竿,所有操作均具有可配置的人类化时间间隔。
以希腊海神波塞冬命名。
运行需要 PlayerAPI 和 YetAnotherConfigLib。
ModMenu 是可选的——它为模组列表添加了一个设置按钮。
功能
智能咬钩检测
Poseidon 扫描附近的文本,查找服务器在您浮标咬钩时发送的 !!! 信号。检测到后,它会在可配置的人类反应延迟后收杆,并可选地加入随机性,使时间间隔看起来不机械。
自动重抛
每次捕获后,鱼竿会自动重新抛出。可配置的决策窗口允许服务器聊天消息到达后再提交,这样抑制或停止重抛的触发器总能及时触发。重抛延迟可独立配置(最小/最大毫秒),也可以完全禁用。
基于延迟的决策窗口
决策窗口——Poseidon 在重抛前等待聊天触发的时间长度——作为玩家设置暴露出来,以便您根据连接情况进行调整。
聊天触发器
定义匹配传入聊天消息的关键字触发器。每个触发器可以:
- 播放自定义声音
- 在屏幕上显示标题
- 抑制下一次自动重抛
- 完全停止机器人(HUD 保持打开)
追踪实体警告
Poseidon 追踪您钓起的实体,并强制执行可配置的区域上限。达到上限时会提醒您。存活时间过长(可配置,默认约 5 分钟)的实体会触发消失警告,以便您在它们消失前采取行动。
浮标漂移检测
如果您的挂钩附着在一个移动的实体上,浮标会偏离落点。Poseidon 在短暂的稳定期后检测超出可配置半径的漂移,然后收杆并重抛——防止机器人在移动目标上停滞。
实时 HUD
游戏内叠加层(可切换快捷键)显示:
- 机器人激活/非激活状态
- 浮标状态——灰色:无浮标,黄色:检测到咬钩信号,绿色:浮标空闲
- 上次捕获信息和活跃实体计数
- 存在咬钩信号时的实时倒计时文本
完全可配置
所有时间间隔、阈值、声音和开关都通过 YACL 配置屏幕暴露。您可以从 ModMenu、/poseidon 命令或快捷键打开它。无需编辑文件。
控制
所有快捷键均可在选项 → 控制 → Poseidon中重新绑定。
| 动作 |
默认键 |
| 切换钓鱼 |
Y |
| 切换 HUD |
H |
| 打开配置 |
(未绑定) |
在聊天中输入 /poseidon 可直接打开配置屏幕。
安装
- 为 Minecraft 1.21.11 安装 Fabric Loader
- 安装 Fabric API
- 安装 PlayerAPI
- 安装 YetAnotherConfigLib
- 安装 ModMenu (可选)
- 将
poseidon-*.jar 放入您的 mods 文件夹
兼容性
| Minecraft |
Fabric Loader |
Java |
| 1.21.11 |
≥ 0.18.4 |
21 |
许可证
保留所有权利
面向开发者
Poseidon — 设计与文档
版本: 当前(配置架构 v6)
平台: Fabric 1.21.11, Java 21
依赖项: PlayerAPI, Fabric API, YACL v3, ModMenu (可选)
模组 ID: poseidon
入口点: com.poseidon.PoseidonMod
配置文件: <game_dir>/config/poseidon/config.json
日志文件: <game_dir>/config/poseidon/poseidon.log
目录
- 目的与范围
- 架构概述
- 包结构
- FishingState — 状态枚举
- FishingManager — 核心状态机
- FishingConfig — 配置
- PoseidonHudRenderer — HUD 叠加层
- PoseidonConfigScreen — YACL 配置 UI
- MouseClickMixin — 右键点击保护
- PoseidonLogger — 日志记录
- PoseidonMod — 入口点与事件接线
- 聊天触发器系统
- 海洋生物追踪系统
- 钩子卡住检测
- AlarmSound 数据类
- 配置架构与迁移历史
- 快捷键与命令
- HUD 引用
- 配置引用(所有设置)
- 时间间隔引用
- 设计决策与备注
1. 目的与范围
Poseidon 是一个专为 Hypixel Skyblock 设计的客户端钓鱼自动化模组。它自动化了完整的钓鱼循环:
- 抛竿(手动或自动重抛)
- 观察服务器的“现在收杆”信号(浮标附近的
!!! 实体)
- 以人类化的随机延迟响应并收杆
- 可选择在可配置延迟后重抛
- 可选择追踪每次捕获后生成的海洋生物
- 在配置的聊天模式上触发声音警报和标题叠加
Poseidon 依赖 PlayerAPI 来处理所有 Minecraft 交互与调度。它从不直接调用 Minecraft API 来处理玩家输入——所有内容均通过 MovementActions、Scheduler、TabListInfo、SoundActions、DisplayActions 和 PlayerAPIEvents 进行。
2. 架构概览
PoseidonMod (入口点)
├── 注册按键绑定 (Y, H, 无默认值)
├── 注册 /poseidon 命令
├── 订阅 PlayerAPIEvents.TICK → onTick()
├── 订阅 PlayerAPIEvents.CHAT_RECEIVED → onChatReceived()
└── 注册 HudRenderCallback → PoseidonHudRenderer.render()
每个游戏刻执行的 onTick():
├── 如果设置了 openConfigNextTick 标志,则打开配置界面
├── FishingManager.tick() — 核心状态机
└── handleKeybinds() — 轮询按键按下事件
onChatReceived(sender, message):
└── 将消息与 FishingConfig.getTriggerLevels() 进行比对
└── 第一个匹配项:播放音效,显示标题,并调用 FishingManager.notifyTriggerFired()
FishingManager.tick()(仅在激活时执行):
├── IDLE 状态: 等待浮标出现 → 转换为 WAITING
├── WAITING 状态: 每个游戏刻运行 detectBite()
│ ├── 发现咬钩 → 保存浮标位置,→ BITING,调度收线
│ └── 未咬钩:更新附近文本,运行 checkHookStuck()
├── BITING 状态: 等待调度的收线;对浮标丢失做出反应
└── REELING 状态: 等待浮标消失
├── Scheduler 触发(延迟后):发送“使用”按键,扫描生物
└── Scheduler 触发(10 个游戏刻):重置为 IDLE,触发重新抛竿决策
线程模型: 所有内容均在主 Minecraft 客户端线程上运行。PlayerAPIEvents.TICK 在客户端游戏刻时触发。Scheduler 回调也在客户端线程上执行。除了 PoseidonLogger 中的文件 I/O 外,不使用任何后台线程。
3. 包结构
com.poseidon
├── PoseidonMod.java — ClientModInitializer,事件连接,按键绑定,命令
├── core/
│ ├── FishingState.java — 枚举:IDLE, WAITING, BITING, REELING
│ ├── FishingManager.java — 单例状态机,所有钓鱼逻辑
│ ├── FishingConfig.java — 单例配置,持久化,迁移
│ └── PoseidonLogger.java — 单例日志记录器,内存环形缓冲区 + 文件输出
├── gui/
│ ├── PoseidonHudRenderer.java — 每帧绘制的 HUD 覆盖层
│ └── PoseidonConfigScreen.java — YACL 配置界面构建器
├── mixin/
│ └── MouseClickMixin.java — 在活跃投掷期间阻止右键点击
└── modmenu/
└── PoseidonModMenuPlugin.java — ModMenu 集成
4. FishingState — 状态枚举
com.poseidon.core.FishingState
钓鱼循环的四种状态:
| 状态 |
含义 |
IDLE |
机器人处于非活动状态,或处于活动状态但尚未抛出鱼竿。没有浮标存在。 |
WAITING |
浮标在水中。每个游戏刻扫描以查找 !!! 咬钩信号实体。同时监控附近的倒计时文本和鱼钩漂移。 |
BITING |
检测到 !!! 信号。反应延迟计时器正通过 Scheduler 倒数。尚未发送收线指令。 |
REELING |
已发送 tapKey("use", 100) 指令以收线。等待浮标实体消失,这标志着捕获完成。 |
状态转换:
IDLE → WAITING 当 hasBobber 变为 true 时
WAITING → BITING 当 detectBite() 返回 true 时
WAITING → IDLE 如果在监控期间浮标消失
BITING → REELING 当调度的收线触发时
BITING → IDLE 如果在收线触发前浮标消失
REELING → IDLE 经过 10 个游戏刻的重置后(或如果浮标消失)
5. FishingManager — 核心状态机
com.poseidon.core.FishingManager — 单例,通过 FishingManager.getInstance() 访问
激活
FishingManager.getInstance().setActive(true); // 开始监控
FishingManager.getInstance().setActive(false); // 停止,重置为 IDLE
FishingManager.getInstance().toggle(); // 切换活动状态
setActive(false) 还会清除 pendingSuppressRecast 和 pendingStopBot 标志,并将状态重置为 IDLE。
tick() — 由 PoseidonMod 在每个游戏刻调用
如果 !active,该方法为空操作。它运行状态机切换,然后:
- 每 40 个游戏刻(2 秒)从标签列表刷新当前区域
- 如果启用了追踪,则每 40 个游戏刻运行海洋生物清理
咬钩检测
detectBite(MinecraftClient mc) 扫描浮标当前位置周围的盒子:
- 盒子尺寸:XZ 方向为
±detectionRadius,Y 方向为 -1 到 +detectionRadius+2
- 检查该盒子内的每个实体是否存在
hasReelNowSignal(entity):
- 检查
entity.getCustomName().getString().contains("!!!")
- 对于现代显示实体,还检查
TextDisplayEntity.getText().getString().contains("!!!")
!!! 信号由 Hypixel 服务器放置在浮标附近(在捕获窗口期间),它是一个盔甲架(旧系统)或文本显示实体(新系统)。它通常只出现几个游戏刻。
反应延迟与收线
一旦检测到咬钩,就会快照浮标位置(lastBobberX/Y/Z),因为当收线触发时,浮标可能已经消失。
scheduleReelIn() 在 reactionDelayMinMs 和 reactionDelayMaxMs 之间选择一个随机延迟,并通过 Scheduler.scheduleMs() 进行调度。当回调触发时:
- 转换为
REELING
MovementActions.tapKey("use", 100) — 按住右键 100 毫秒以收线
- 如果启用了海洋生物追踪:在
SCAN_DELAY_TICKS(5 个游戏刻)处调度 scanForNewCreatures()
- 清除重新抛竿标志(
pendingSuppressRecast, pendingStopBot)
- 记录重新抛竿决策窗口的开始
- 在
recastDecisionTicks(默认 10 个游戏刻)处调度重新抛竿决策
- 在 10 个游戏刻处调度状态重置(
REELING → IDLE)
重新抛竿决策窗口
收杆后,波塞冬会等待 recastDecisionTicks 的时间,然后再决定是否重新抛竿。设置这个窗口期是为了让捕获后的聊天消息有足够的时间到达并触发其逻辑(这些逻辑可以设置 pendingSuppressRecast 或 pendingStopBot)。
决策逻辑(按优先级顺序):
- 如果
!active → 中止
- 如果
pendingStopBot → 调用 setActive(false) → 结束
- 如果
!autoRecast || pendingSuppressRecast → 不重新抛竿(等待手动抛竿)
- 否则 → 使用介于
recastDelayMinMs 和 recastDelayMaxMs 之间的随机延迟执行 scheduleRecast(cfg)
如果状态已返回 WAITING(服务器已为我们重新抛竿)或 BITING(在重新抛竿触发前又发生了咬钩),则 scheduleRecast() 会跳过重新抛竿。
notifyTriggerFired(boolean dontRecast, boolean stopBot)
当捕获期间匹配到触发器时,从 PoseidonMod.onChatReceived() 调用此方法。它设置了决策窗口检查的重新抛竿标志。这些标志会在每次收杆开始时重置。
Nearby Text
处于 WAITING 状态时,scanNearbyText() 会在相同的检测范围内扫描任何实体文本,条件为:
- 不为空
- 不包含
!!!(咬钩信号)
- 不包含
⚓(海洋生物名字板)
第一个匹配项(截断至 20 个字符)将存储为 nearbyText 并显示在 HUD 浮标行中。这用于捕获 Hypixel 在咬钩窗口开启前显示的黄色倒计时计时器。
公共 Getter
| 方法 |
返回值 |
isActive() |
机器人当前是否启用 |
getState() |
当前的 FishingState |
getTrackedCount() |
当前追踪的海洋生物数量 |
getCurrentArea() |
来自标签页列表的区域字符串,或 "" |
getNearbyText() |
倒计时/附近实体文本,或 "" |
shouldBlockRightClick() |
当应抑制右键点击时返回 True(处于 WAITING 或 BITING 状态时) |
6. FishingConfig — 配置
com.poseidon.core.FishingConfig —— 单例模式,通过 FishingConfig.getInstance() 访问
配置以 JSON 格式存储在 config/poseidon/config.json 中。仅在 onInitializeClient() 时加载一次。每个 setter 都会立即调用 save()。
已知区域
FishingConfig.KNOWN_AREAS = List.of(
"Backwater Bayou", "Crimson Isle", "Galatea",
"Hub", "Jerry's Workshop", "The Park"
)
这些是 Hypixel Skyblock 中具有基于区域的海洋生物上限设定的岛屿。对于不在该列表中的任何岛屿,Hub 将作为默认的上限。
配置组
检测
detectionRadius — 围绕浮标的 !!! 扫描半径(默认值 4.0)
hookStuckDetectionEnabled — 是否检查浮标漂移(默认值 true)
hookStuckMaxDistance — 水平漂移阈值(方块单位)(默认值 1.5)
hookStuckSound — 检测到鱼钩卡住时播放的声音
反应 / 重抛
reactionDelayMinMs / reactionDelayMaxMs — 收杆反应的随机时间窗口
autoRecast — 是否在每次捕获后自动重抛(默认 true)
recastDelayMinMs / recastDelayMaxMs — 重抛的随机时间窗口
recastDecisionTicks — 在决定重抛之前等待聊天触发信号的时间(以刻为单位)
海洋生物追踪
trackSeaCreatures — 总开关(默认 true)
creatureScanRadius — 每次收杆后的扫描范围半径(默认 12.0)
seaCreatureCapByArea — 各岛屿的上限映射,所有值默认均为 10
seaCreatureCapSound — 达到上限时播放的声音
despawnWarningEnabled — 是否发出关于生物年龄的警告(默认 true)
despawnWarningMinutes — 警告的年龄阈值(默认 5)
despawnWarningSound — 当生物即将消失时播放的声音
触发器
triggerLevels — 包含 5 个 TriggerLevel 对象的列表(默认全部禁用)
biteAlertSound — 首次检测到 !!! 时播放的声音(默认关闭,durationSeconds=0)
开发者
debugMode — 详细日志记录标志
logLevel — 最低日志级别(LEVEL_WARN = 2,默认)
getCapForArea(String area)
返回指定区域字符串的上限值。对于未列出的区域,回退到中心枢纽(Hub)的上限。如果中心枢纽本身没有条目,则回退到 10。返回值的最小值为 1。
getDespawnWarningTicks()
将 despawnWarningMinutes 转换为游戏刻数:分钟数 × 60 × 20。
7. PoseidonHudRenderer — HUD 覆盖层
com.poseidon.gui.PoseidonHudRenderer
可见性状态: 存储为静态布尔值 hudVisible,默认值为 false。由 H 键绑定控制。当机器人处于活动状态时关闭 HUD 会自动调用 setActive(false)。
渲染方法: render(DrawContext ctx, RenderTickCounter tick) —— 通过 HudRenderCallback.EVENT 注册。如果 !hudVisible 或玩家为空,则不绘制任何内容。
面板布局
主面板始终位于屏幕位置 (4, 4),宽度为 200 像素。高度根据显示的各行动态调整。
头部: “Poseidon” 标签左对齐;状态标签右对齐;左侧边缘带有彩色强调条。
按顺序显示的各行:
| 行 |
标签 |
值 |
颜色逻辑 |
| 1 |
Active |
Yes / No |
激活时为绿色,未激活时为红色 |
| 2 |
State |
State name |
与强调栏颜色匹配 |
| 3 |
Bobber |
None / Detected / <倒计时文本> |
灰色=无,绿色=已检测到,黄色=可见倒计时 |
| 4 |
Area |
Island name |
灰色 — 仅在启用追踪且区域已知时显示 |
| 5 | SC | count / cap | 灰色=0,橙色>0,红色≥上限 —— 仅在启用追踪时显示 |
状态对应的侧边栏(左侧边缘)颜色:
| 状态 |
颜色 |
| IDLE (active=false) |
红色 0xFFEE4444 |
| IDLE (active=true) |
橙色 0xFFFFAA00 |
| WAITING |
绿色 0xFF44EE44 |
| BITING |
黄色 0xFFFFFF44 |
| REELING |
蓝色 0xFF44AAFF |
标题栏中的状态标签也使用了相同的颜色。
日志面板
当 PoseidonLogger 有条目时,直接显示在主面板下方。展示最近的 5 条日志行(每条截断为 50 个字符)。已去除 [HH:mm:ss] [LEVEL] 前缀,仅显示消息内容。
8. PoseidonConfigScreen — YACL 配置界面
com.poseidon.gui.PoseidonConfigScreen
通过 /poseidon 命令、Open Config(打开配置)快捷键(无默认值)或 ModMenu 打开。共有五个选项卡:
选项卡 1 — 检测 (Detection)
控制 Poseidon 如何识别咬钩以及处理鱼钩卡住的情况。
| 设置 |
类型 |
默认值 |
范围 |
| Armor Stand Radius |
double slider |
4.0 |
1.0 – 10.0, step 0.5 |
| Hook Stuck Detection |
boolean |
true |
— |
| Max Drift Distance (blocks) |
double slider |
1.5 |
0.5 – 5.0, step 0.25 |
| Hook Stuck Sound |
string |
minecraft:entity.villager.no |
sound ID |
| Hook Stuck Volume |
double slider |
1.0 |
0.1 – 2.0, step 0.05 |
| Hook Stuck Pitch |
double slider |
1.2 |
0.5 – 2.0, step 0.05 |
| Hook Stuck Duration |
int slider |
2s |
0 – 30s |
| Hook Stuck Interval |
int slider |
10 ticks |
5 – 60 ticks |
选项卡 2 — 反应延迟 (Reaction Delay)
控制人类反应延迟和自动重抛行为。
| 设置 |
类型 |
默认值 |
范围 |
| Min Delay (ms) |
int slider |
180 |
50 – 2000, step 10 |
| Max Delay (ms) |
int slider |
700 |
50 – 3000, step 10 |
| Auto Recast |
boolean |
true |
— |
| Recast Delay Min (ms) |
int slider |
200 |
100 – 3000, step 50 |
| Recast Delay Max (ms) |
int slider |
600 |
100 – 5000, step 50 |
| Trigger Wait (ticks) |
int slider |
10 |
2 – 40, step 1 |
Trigger Wait 滑块使用自定义格式化器:"N ticks (N×50 ms)"。
描述中显示的 Ping 建议:
- Low ping (<80 ms): 5–10 ticks
- Medium ping (80–200 ms): 10–15 ticks
- High ping (200+ ms): 20–30 ticks
选项卡 3 — 海洋生物追踪 (Sea Creature Tracking)
| 设置 |
类型 |
默认值 |
范围 |
| Enable Tracking |
boolean |
true |
— |
| Scan Radius |
double slider |
12.0 |
5.0 – 30.0, step 1.0 |
| Backwater Bayou Cap |
int slider |
10 |
1 – 50 |
| Crimson Isle Cap |
int slider |
10 |
1 – 50 |
| Galatea Cap |
int slider |
10 |
1 – 50 |
| Hub Cap (default) |
int slider |
10 |
1 – 50 |
| Jerry's Workshop Cap |
int slider |
10 |
1 – 50 |
| The Park Cap |
int slider |
10 |
1 – 50 |
| Cap Alert Sound |
string |
minecraft:entity.player.levelup |
sound ID |
| Cap Alert Volume |
double slider |
1.0 |
0.1 – 2.0 |
| Cap Alert Pitch |
double slider |
0.8 |
0.5 – 2.0 |
| Cap Alert Duration |
int slider |
10s |
0 – 30s |
| Cap Alert Interval |
int slider |
20 ticks |
5 – 60 ticks |
| Enable Despawn Warning |
boolean |
true |
— |
| Warning At (minutes) |
int slider |
5 |
1 – 6, formatter: "N min" |
| Despawn Warning Sound |
string |
minecraft:block.bell.use |
sound ID |
| Despawn Warning Volume |
double slider |
1.0 |
0.1 – 2.0 |
| Despawn Warning Pitch |
double slider |
0.8 |
0.5 – 2.0 |
| Despawn Warning Duration |
int slider |
5s |
0 – 30s |
| Despawn Warning Interval |
int slider |
20 ticks |
5 – 60 ticks |
注意:Hub Cap 标记为 "Hub Cap §7(default)" —— Hub 是列表中任何岛屿未指定时的备用上限。
选项卡 4 — 聊天触发器 (Chat Triggers)
包含一个解释触发器语法的标题标签,然后是五个 OptionGroup 块(每个触发器槽位一个),底部是 Bite Alert 声音。
每个触发器组包含:
| 设置 |
类型 |
默认值 |
| Enabled |
boolean |
false |
| Name |
string |
"" |
| Patterns |
string |
"" (逗号分隔的子字符串) |
| Action |
string |
"" (未使用,保留) |
| Show Title |
boolean |
false |
| Title Text |
string |
"" (如果为空则回退到 Name) |
| Don't Recast |
boolean |
false |
| Stop Bot |
boolean |
false |
| Sound (5 fields) |
AlarmSound |
defaultBite defaults |
Bite Alert(位于所有触发器之后,在底部):
| 设置 |
默认值 |
| Bite Alert Sound |
minecraft:entity.experience_orb.pickup |
| Volume |
1.0 |
| Pitch |
1.5 |
| Duration |
0s (默认关闭 — 设置为大于 0 以启用) |
| Interval |
15 ticks |
咬钩警报默认为静音 (durationSeconds=0)。如果持续时间为 0,AlarmSound.play() 方法会提前返回。
选项卡 5 — 开发者 (Developer)
| 设置 |
类型 |
默认值 |
| Debug Mode |
boolean |
false |
| Log Level |
cycling list (DEBUG/INFO/WARN/ERROR) |
WARN |
9. MouseClickMixin — 右键点击防护
com.poseidon.mixin.MouseClickMixin
@Mixin(Mouse.class)
public class MouseClickMixin {
@Inject(method = "onMouseButton", at = @At("HEAD"), cancellable = true)
private void poseidon$blockRightClickWhenFishing(
long window, MouseInput mouseInput, int action, CallbackInfo ci)
功能说明: 在 Mouse.onMouseButton() 的最开始处注入,并在满足以下条件时取消事件(阻止右键点击到达游戏):
- 鼠标动作为
GLFW_PRESS(非释放或重复)
- 按钮为
GLFW_MOUSE_BUTTON_RIGHT
FishingManager.shouldBlockRightClick() 返回 true
当 shouldBlockRightClick() 为 true 时: 机器人处于活动状态且状态为 WAITING 或 BITING。
为何需要此功能: 在 Minecraft 中钓鱼时,如果浮标在水中,右键点击鱼竿会将线收回(与有意的收线操作相同)。如果没有此防护,在 WAITING 期间任何意外的右键点击都会取消当前的抛投,导致机器人卡住。该 mixin 在尽可能低的层级防止了这种情况——在输入到达 ClientPlayerInteractionManager 之前。
此 mixin 有意设计得较为狭窄。它不会在 REELING 状态下阻止右键点击(收线指令已发送)或 IDLE 状态下阻止(没有活跃的抛投)。
10. PoseidonLogger — 日志记录
com.poseidon.core.PoseidonLogger — 单例,通过 PoseidonLogger.getInstance() 访问
日志级别
| 常量 |
值 |
用途 |
LEVEL_DEBUG |
0 |
详细的检测输出 |
LEVEL_INFO |
1 |
正常的事件运行 |
LEVEL_WARN |
2 |
意外情况(默认) |
LEVEL_ERROR |
3 |
故障和异常 |
默认级别在构造时设为 LEVEL_INFO,随后在配置加载时被覆盖为 LEVEL_WARN。
输出
- 内存环形缓冲区: 保留最近 50 行日志于
ArrayDeque<String> 中,通过 getRecentLines() 访问。由 PoseidonHudRenderer 用于日志面板。通过 synchronized 实现线程安全。
- 文件输出: 每次日志调用时追加写入
config/poseidon/poseidon.log。文件在构造时以 APPEND(追加)模式打开一次。启用自动刷新。
行格式
[HH:mm:ss] [LEVEL] message
示例:[14:32:07] [INFO] Bobber detected — watching for !!!
11. PoseidonMod — 入口点与事件连接
com.poseidon.PoseidonMod — 实现 ClientModInitializer
初始化序列 (onInitializeClient)
- 记录日志 "Poseidon initialising..."
FishingConfig.getInstance().load() — 从磁盘加载配置(或创建默认值)
registerKeybinds() — 注册 Y、H 以及无默认值的配置按键
registerCommands() — 注册 /poseidon 命令及 ALLOW_COMMAND 回退机制
HudRenderCallback.EVENT.register(PoseidonHudRenderer::render)
PlayerAPIEvents.TICK.register(this::onTick)
PlayerAPIEvents.CHAT_RECEIVED.register(this::onChatReceived)
- 记录日志 "Poseidon ready."
/poseidon 命令
通过 Fabric 的 ClientCommandRegistrationCallback 注册。设置 openConfigNextTick = true,这会导致配置屏幕在下一个游戏刻打开。延迟一个游戏刻是为了避免与聊天屏幕关闭时的竞态条件。
还通过 ClientSendMessageEvents.ALLOW_COMMAND 注册了一个回退机制,用于处理那些覆盖客户端命令树的服务端。如果 poseidon 命令通过此路径到达,它将设置标志并返回 false(阻止消息发送至服务器)。
onTick()
每个游戏刻运行一次:
- 守卫检查:
if (!PlayerInfo.isInWorld()) return
- 如果
openConfigNextTick:清除标志,打开 PoseidonConfigScreen
FishingManager.getInstance().tick()
handleKeybinds()
handleKeybinds()
轮询三个按键绑定是否有按下操作:
Y (切换钓鱼):
- 如果处于激活状态:
setActive(false)
- 如果未激活且 HUD 可见:
setActive(true)
- 如果未激活且 HUD 不可见:记录警告 ("Open the HUD first (H) before starting")
- 这强制执行工作流程:先打开 HUD → 再开启,而不是允许处于不可见的激活状态。
H (切换 HUD):
- 翻转
PoseidonHudRenderer.hudVisible
- 如果 HUD 刚刚被关闭且机器人处于激活状态:调用
setActive(false) 并记录日志 "HUD closed — fishing stopped"
配置按键(无默认值):
- 立即打开
PoseidonConfigScreen
onChatReceived(String sender, String message)
按顺序遍历 FishingConfig.getTriggerLevels()。对于第一个匹配的消息触发器(level.matches(message)):
- 记录该匹配
level.sound.play()
- 如果
level.showTitle:调用 showTitle(level)(见下文)
FishingManager.getInstance().notifyTriggerFired(level.dontRecast, level.stopBot)
- Break — 仅第一个匹配的触发器会生效
showTitle(TriggerLevel level):
使用 PlayerAPI 中的 DisplayActions.showTitle(text, "")。标题文本为:
level.titleText(如果不为空)
- 否则为
level.name
- 否则为硬编码的回退文本
"Trigger Fired"
DisplayActions 是 PlayerAPI 的一个类,它封装了 Minecraft 的 InGameHud.setTitle() / setSubtitle(),用于显示大型 Minecraft 标题覆盖层。
12. 聊天触发器系统
概述
Poseidon 拥有 5 个可配置的触发器槽位。每个触发器监控传入的聊天消息以进行关键词匹配。当找到匹配项时,它可以:
- 播放警报声音
- 显示 Minecraft 标题覆盖层
- 抑制自动重新抛竿(以便你可以处理引起你注意的事物)
- 完全停止机器人(HUD 保持打开)
触发器按槽位 1 到 5 的顺序进行检查。第一个匹配获胜 —— 同一条消息不会触发后续的触发器。
TriggerLevel 字段
public String name // 显示标签(显示在配置组标题和日志中)
public boolean enabled // 此触发器是否处于活动状态
public String patterns // 逗号分隔的匹配子串,不区分大小写
public AlarmSound sound // 匹配时播放的声音
public String action // 未使用(预留供将来使用,请留空)
public boolean dontRecast // 在此捕获后抑制自动重新抛竿
public boolean stopBot // 在此捕获后停用机器人
public boolean showTitle // 显示 MC 标题覆盖层
public String titleText // 标题文本(如果为空则使用 `name`)
模式匹配
TriggerLevel.matches(String chatText):
- 如果
!enabled 或 patterns 为空,返回 false
- 按逗号拆分 patterns,修剪每部分,并将两者都转换为小写
- 如果任何非空模式作为子串出现在聊天文本中,返回
true
- 不区分大小写的子串匹配,而非正则表达式
Hypixel Skyblock 海怪事件的示例模式:"appeared, emerged"。
与重新抛竿决策窗口的交互
聊天消息相对于收杆动作异步到达。recastDecisionTicks 是收杆动作与重新抛竿决策之间的窗口期。如果触发器在此窗口期内触发,其 dontRecast/stopBot 标志将被决策回调看到。
如果触发器在决策窗口关闭之后触发,这些标志将被忽略。增加 recastDecisionTicks(或其关联的毫秒等效值)可以为高延迟服务器提供更多时间。
13. 海怪追踪系统
概述
每次收杆后,Poseidon 扫描锚点位置附近带有 ⚓ 锚字符(U+2693)的实体。这是 Hypixel 在海怪名称牌上使用的前缀。新的海怪会被添加到 List<TrackedSeaCreature> 中,包含其实体 ID、名称和生成游戏刻。
检测机制
isSeaCreatureDisplay(Entity entity):
- 检查盔甲架/生物名称牌的
entity.getCustomName().getString().contains("⚓")
- 检查文本显示实体的
TextDisplayEntity.getText().getString().contains("⚓")
extractCreatureName(Entity entity):
- 读取原始实体文本
- 查找
⚓ 字符,截取其后的所有内容(并去除首尾空格)
- 从第一个数字开始截断(即 HP 值的起始位置)
- 返回处理后的名称,如果解析失败则返回
"Unknown"
- Hypixel 使用的完整格式:
"[LvN] ⚓ CreatureName HP/MaxHP❤"
扫描时机
收杆后经过 SCAN_DELAY_TICKS = 5 刻才执行扫描。此延迟是有意为之:鱼漂实体通常在按下 use 键后的 1–2 刻内消失。将扫描锚定在保存的 lastBobberX/Y/Z 位置而非当前鱼漂位置(该位置可能已不存在),可确保扫描始终在正确的位置运行。
清理
cleanupDeadCreatures(MinecraftClient mc) 每 CLEANUP_PERIOD_TICKS = 40 刻(2 秒)运行一次:
- 消失警告:如果启用了
despawnWarningEnabled,检查每个追踪生物的年龄。如果 (currentTick - spawnTick) >= despawnWarningTicks,且警报尚未触发,则播放 despawnWarningSound 并记录警告日志。
- 移除死亡生物:
tracked.removeIf(t -> mc.world.getEntityById(t.entityId) == null) —— 移除任何实体已从世界中消失的生物。
- 上限重置:如果在移除操作后追踪数量低于上限,则重置
capAlertFired = false,以便下次再次触发警报。
上限警报
每次扫描发现新生物后调用 checkCapAlert()。如果 tracked.size() >= cap 且 !capAlertFired,则播放 seaCreatureCapSound 并将 capAlertFired 设置为 true。使用的上限由 cfg.getCapForArea(currentArea) 确定。
TrackedSeaCreature (内部类)
final int entityId // 用于存活检查的 MC 实体 ID
final String name // 提取的显示名称
final long spawnTick // 检测时的 Scheduler.getCurrentTick()
boolean despawnAlertFired // 防止重复触发消失警告
14. 钩子卡住检测
问题
当在怪物附近抛竿时,钓鱼钩可能会附着在怪物身上而不是落入水中。此时鱼漂实体存在且有效,因此正常的状态机会无限期等待永远不会到来的咬钩事件。钩子会随怪物移动,永远无法触发 !!!。
检测机制
鱼漂着陆后,会运行 1 秒的稳定期(BOBBER_SETTLE_TICKS = 20)。在此期间,initialBobberX/Z 会持续更新为当前鱼漂的 XZ 位置(因此我们测量的是从最终静止位置开始,而非抛物线顶点)。
稳定期结束后,每一刻执行以下操作:
- 计算水平位移:
dx = bobber.X - initialBobberX, dz = bobber.Z - initialBobberZ
- 计算欧几里得距离:
dist = sqrt(dx² + dz²)
- 如果
dist > hookStuckMaxDistance(默认 1.5):
- 设置
hookStuckFired = true(防止对同一次抛竿重复发送警报)
- 播放
hookStuckSound
- 转换到
REELING 状态,调用 MovementActions.tapKey("use", 100)
- 调度 10 刻后重置状态,如果启用了
autoRecast 则调度重新抛竿
为何仅检测水平方向?
正常漂浮在水面上的钓鱼鱼漂会进行垂直方向的上下浮动。其垂直振幅通常小于 0.5 格。对于漂浮在水面上的鱼漂来说,水平漂移几乎不会发生。通过仅检查 XZ 位移,系统避免了因正常的浮标动画而产生误报。
配置项
hookStuckDetectionEnabled (布尔值, 默认 true) — 总开关
hookStuckMaxDistance (双精度浮点数, 默认 1.5 格) — 漂移阈值,范围 0.5–5.0
hookStuckSound (AlarmSound, 默认: minecraft:entity.villager.no)
15. AlarmSound 数据类
FishingConfig.AlarmSound —— FishingConfig 的公共静态内部类
表示单个重复播放的声音警报。Poseidon 中所有声音均使用此类。
字段
| 字段 |
类型 |
含义 |
soundId |
String |
Minecraft 声音 ID ("namespace:sound.path") |
volume |
double |
0.1(安静)– 2.0(响亮),1.0 = 正常音量 |
pitch |
double |
0.5(慢/低沉)– 2.0(快/高亢),1.0 = 正常音调 |
durationSeconds |
int |
警报播放的总秒数;0 = 播放一次,若咬钩警报设为 0 则静音 |
intervalTicks |
int |
每次重复之间的间隔刻数(20 刻 = 1 秒) |
默认实例
AlarmSound.defaultBite()
// soundId=minecraft:entity.experience_orb.pickup, vol=1.0, pitch=1.5, dur=0, interval=15
// 注意:dur=0 表示默认静音。需将 duration 设置为大于 0 的值以启用。
AlarmSound.defaultAlert()
// soundId=minecraft:entity.player.levelup, vol=1.0, pitch=1.0, dur=8, interval=20
play()
public void play() {
if (soundId == null || soundId.isBlank() || durationSeconds <= 0) return;
int times = Math.max(1, (durationSeconds * 20) / Math.max(1, intervalTicks));
SoundActions.playByIdRepeated(soundId, (float) volume, (float) pitch, times, intervalTicks);
}
根据持续时间计算重复次数。如果处于静音状态(持续时间 ≤ 0)则提前返回。
mergeFrom(AlarmSound src, AlarmSound defaults)
在加载配置时使用,用于将文件中的值合并到默认值上,同时防止零值或空字段被错误应用:
- 如果
src.soundId 非空白则使用它,否则使用 defaults.soundId
- 如果
src.volume/pitch 大于 0 则使用它,否则使用默认值
- 如果
src.durationSeconds/intervalTicks 大于 0 则使用它,否则使用默认值
这意味着配置文件不能将音量设置为恰好为 0.0(它将回退到默认值)。这是为了防止意外生成静音配置的有意保护措施。
16. 配置架构与迁移历史
配置文件包含一个 configVersion 整数。加载时,migrate() 方法按顺序链接所有版本,自动将旧配置向前迁移。
迁移链
v0 → v1:扁平化的 biteAlert* 字段 → biteAlertSound AlarmSound 对象;添加 triggerLevels
v1 → v2:单个 seaCreatureCap int → seaCreatureCapByArea Map(所有区域获得旧的上限值)
v2 → v3:添加 autoRecast(GSON 默认将布尔值设为 false;迁移过程为旧配置注入 true)
v3 → v4:添加 recastDecisionTicks(旧代码中硬编码为 40,现在默认为 10)
v4 → v5:添加 despawnWarningEnabled、despawnWarningMinutes
v5 → v6:添加 hookStuckDetectionEnabled、hookStuckMaxDistance
GSON 布尔值默认值注意事项: GSON 通过绕过构造函数来创建对象。任何添加到 FishingConfig 中且应默认为 true 的新布尔字段,必须在迁移步骤中进行注入,而不能仅作为 Java 字段初始化器添加,因为对于缺失的字段,GSON 会生成 false。Poseidon 通过迁移正确处理了这一点(v2→v3 用于 autoRecast,v4→v5 用于 despawnWarningEnabled,v5→v6 用于 hookStuckDetectionEnabled)。
KNOWN_AREAS 静态初始化顺序
FishingConfig.KNOWN_AREAS 被声明为第一个静态字段,这是因为紧随其后的 INSTANCE = new FishingConfig() 行会触发构造函数,而 defaultCapsByArea() 会迭代 KNOWN_AREAS。如果 INSTANCE 先于它声明,则在调用构造函数时 KNOWN_AREAS 将为 null。字段的顺序至关重要。
17. 按键与命令
按键
所有按键均在 Minecraft 的按键设置中注册在 Poseidon Controls 类别下。
| 按键 |
默认值 |
操作 |
| Y |
Y |
切换钓鱼 — 启动机器人(如果 HUD 已打开)或停止它 |
| H |
H |
切换 HUD — 显示/隐藏 HUD 覆盖层;如果活动状态下关闭 HUD,也会停止机器人 |
| (无) |
未绑定 |
打开配置 — 直接打开 YACL 配置界面 |
启动流程: 如果 HUD 不可见,Y 键将拒绝启动机器人。预期的流程是:按 H 打开 HUD,然后按 Y 开始钓鱼。
命令
| 命令 |
效果 |
/poseidon |
打开 YACL 配置界面 |
该命令使用 tick 延迟技巧 (openConfigNextTick) 来避免竞争条件,即配置界面试图在聊天界面仍在关闭时打开的情况。
通过 ClientSendMessageEvents.ALLOW_COMMAND 的回退机制处理这种情况:当服务器重写客户端命令树并在 Fabric 的 ClientCommandManager 能够处理之前拦截 /poseidon 时。
18. HUD 参考
何时显示?
仅在 PoseidonHudRenderer.hudVisible == true 时显示。启动时默认为 false。按 H 键进行切换。
主面板
位置:左上角 (4, 4)。
宽度:200 像素。
高度:动态 — 标题栏 (13 px) + 分隔线 (1 px) + 内边距 (5 px) + 行数 × 11 px + 底部内边距 (5 px)。
┌── Poseidon ─────────── [STATE] ──┐ ← 彩色强调栏 + 标题
│ │ ← 分隔线
│ Active Yes / No │
│ State IDLE / WAITING / ... │
│ Bobber None / Detected / .. │
│ Area Hub (opt)│
│ SC 4 / 10 (opt)│
└───────────────────────────────────┘
仅当启用海生物追踪且 currentArea 不为空时,才显示 Area 行。
仅当启用海生物追踪时,才显示 SC 行。
日志面板
立即出现在主面板下方(间隔 3 px)。显示最后 5 条日志行。格式:仅消息文本(前缀已剥离)。每行最多 50 个字符,超出部分以 … 截断。
状态 → 颜色映射
| 机器人活跃 |
FishingState |
颜色 |
标题标签 |
| false |
IDLE |
红色 0xFFEE4444 |
OFF |
| true |
IDLE |
橙色 0xFFFFAA00 |
IDLE |
| true |
WAITING |
绿色 0xFF44EE44 |
WAITING |
| true |
BITING |
黄色 0xFFFFFF44 |
BITING |
| true |
REELING |
蓝色 0xFF44AAFF |
REELING |
当 active=false 时,标题标签显示 "OFF" 而不是 "IDLE"。
浮标行颜色
| 条件 |
颜色 |
值 |
| 无浮标 |
灰色 0xFF888888 |
"None" |
| 有浮标,附近无文本 |
绿色 0xFF44EE44 |
"Detected" |
| 有浮标,找到附近文本 |
黄色 0xFFFFCC00 |
倒计时文本(≤20 字符) |
SC 行颜色
| 条件 |
颜色 |
| 达到或超过上限 |
红色 0xFFFF4444 |
| 追踪数量 > 0 |
橙色 0xFFFFAA00 |
| 追踪数量 = 0 |
灰色 0xFF888888 |
19. 配置参考(所有设置)
所有设置均位于 config/poseidon/config.json 中。键名与 Java 字段名称匹配。
检测
| 键 |
类型 |
默认值 |
备注 |
detectionRadius |
double |
4.0 |
围绕浮标的扫描框半尺寸,用于检测 !!! 信号 |
hookStuckDetectionEnabled |
bool |
true |
启用水平漂移检查 |
hookStuckMaxDistance |
double |
1.5 |
漂移阈值(方块数) |
hookStuckSound |
AlarmSound |
villager.no, 1.0, 1.2, 2s, 10t |
— |
反应与重新抛竿
| 键 |
类型 |
默认值 |
备注 |
reactionDelayMinMs |
int |
180 |
最小反应延迟(毫秒) |
reactionDelayMaxMs |
int |
700 |
最大反应延迟(毫秒) |
autoRecast |
bool |
true |
每次捕获后自动重新抛竿 |
recastDelayMinMs |
int |
200 |
最小重新抛竿延迟(毫秒) |
recastDelayMaxMs |
int |
600 |
最大重新抛竿延迟(毫秒) |
recastDecisionTicks |
int |
10 |
在做出重新抛竿决定之前等待触发的刻数 |
海生物追踪
| 键 |
类型 |
默认值 |
备注 |
trackSeaCreatures |
bool |
true |
主开关 |
creatureScanRadius |
double |
12.0 |
每次收杆后的扫描半径 |
seaCreatureCapByArea |
Map<String,Integer> |
all 10 |
每座岛屿的上限;Hub 为后备方案 |
seaCreatureCapSound |
AlarmSound |
levelup, 1.0, 0.8, 10s, 20t |
— |
despawnWarningEnabled |
bool |
true |
— |
despawnWarningMinutes |
int |
5 |
消失警告的年龄阈值 |
despawnWarningSound |
AlarmSound |
bell.use, 1.0, 0.8, 5s, 20t |
— |
触发器
| 键 |
类型 |
默认值 |
备注 |
triggerLevels |
List<TriggerLevel> |
5个空/禁用项 |
— |
biteAlertSound |
AlarmSound |
orb.pickup, 1.0, 1.5, 0s, 15t |
持续时间为 0 表示禁用 |
开发者
| 键 |
类型 |
默认值 |
备注 |
debugMode |
bool |
false |
— |
logLevel |
int |
2 (WARN) |
0=DEBUG, 1=INFO, 2=WARN, 3=ERROR |
configVersion |
int |
6 |
请勿手动编辑 |
20. 计时参考
| 常量 |
值 |
位置 |
用途 |
SCAN_DELAY_TICKS |
5 |
FishingManager |
收杆后扫描新海洋生物的延迟时间 |
CLEANUP_PERIOD_TICKS |
40 |
FishingManager |
检查已消失生物的频率(2秒) |
AREA_REFRESH_TICKS |
40 |
FishingManager |
从标签列表重新读取“Area:”的频率(2秒) |
BOBBER_SETTLE_TICKS |
20 |
FishingManager |
在开始检测鱼漂卡住漂移之前的稳定窗口期(1秒) |
| 状态重置延迟 |
10 ticks |
FishingManager |
收杆触发后,REELING→IDLE 转换前的等待时间 |
recastDecisionTicks |
10 (可配置) |
FishingConfig |
在进行重新投掷决策前等待聊天触发的时间 |
reactionDelayMinMs |
180 (可配置) |
FishingConfig |
最小人类反应延迟 |
reactionDelayMaxMs |
700 (可配置) |
FishingConfig |
最大人类反应延迟 |
recastDelayMinMs |
200 (可配置) |
FishingConfig |
最小重新投掷延迟 |
recastDelayMaxMs |
600 (可配置) |
FishingConfig |
最大重新投掷延迟 |
despawnWarningMinutes |
5 (可配置) |
FishingConfig |
触发消失警告的生物年龄阈值 |
20 ticks = 1 秒。1 tick ≈ 50 ms。
21. 设计决策与说明
为什么钩子卡住检测需要设置稳定期?
在抛竿弧线过程中,鱼漂在空中飞行直至落地。在此弧线期间,其 XZ 坐标会发生剧烈变化。如果没有稳定期,每次抛竿都会立即触发鱼漂卡住的警报,因为鱼漂刚从玩家位置飞到水中。1秒的稳定窗口(20 ticks)会等待鱼漂在水中到达最终静止位置后再测量漂移情况。
为什么在收杆前保存鱼漂位置?
鱼漂实体 (fishHook) 可能在发送收杆动作后的 1–2 ticks 内消失。当 Scheduler.schedule(SCAN_DELAY_TICKS, ...) 回调触发时,mc.player.fishHook 几乎肯定为 null。因此,鱼漂的 XZ/Y 坐标会在检测到 !!! 信号的那一刻被捕获,并将这些保存的坐标作为参数传递给延迟的海洋生物扫描。
为什么使用 ALLOW_COMMAND 作为后备方案?
在 Hypixel 等服务器上,服务器会向客户端推送一个自定义命令树,其中可能不包含 /poseidon。在这种情况下,Fabric 的 ClientCommandManager 不会在消息发送给服务器之前拦截 /poseidon。ALLOW_COMMAND 事件会在消息通过网络发送之前触发,从而捕捉这种情况。处理器返回 false(阻止发送)并设置标志位。
为什么要有 REELING 状态下的鱼漂保护?
scheduleRecast() 在 state == FishingState.WAITING || state == FishingState.BITING 时会跳过执行。WAITING 检查处理的是服务器自动重新投掷钓竿的情况(某些 Hypixel 模式会这样做)——如果在重新投掷触发时鱼漂已经出现,则无需再次投掷。BITING 检查处理的是一个边缘情况:新的咬钩信号出现得极快。
为什么只有 5 个触发槽位?
触发槽位在配置 JSON 中序列化为固定长度的列表,YACL UI 会为每个槽位生成一组控件。选择固定的 5 个槽位是因为 Hypixel Skyblock 钓鱼通常只需要 2–3 个实用触发器(例如,“海洋生物出现”、“稀有生物出现”、“特殊掉落停止”)。五个槽位提供了余量,同时不会使配置界面显得臃肿。该列表在内部并非硬性限制——getTriggerLevels() 返回列表中包含的任何内容——但 UI 和默认设置始终生成恰好 5 个。
为什么 shouldBlockRightClick() 仅在 WAITING 和 BITING 状态下为真?
在 IDLE 状态下:没有活动的抛竿,因此右键点击应正常工作(它会投掷钓竿)。
在 REELING 状态下:收杆指令已经发送,因此右键点击保护会阻止第二次收杆。收杆发送与 IDLE 重置之间的 10-tick 窗口很短,在实践中这不成问题。如果保护在 REELING 期间生效,玩家在机器人发送按键后手动点击收杆将被阻止。
DisplayActions (PlayerAPI)
Poseidon 使用 PlayerAPI 中的 DisplayActions.showTitle(title, subtitle)。此类添加到 PlayerAPI 中以封装 Minecraft 的 InGameHud 标题显示功能。它允许 Poseidon 在聊天触发时显示大型屏幕 MC 标题,而无需直接导入 Minecraft 的 InGameHud。
Area 作为后备键
seaCreatureCapByArea 映射表使用从 Hypixel 标签列表“Area:”行读取的区域字符串。对于任何无法识别的字符串,映射表会回退到 Hub 的限制值。这意味着如果 Hypixel 更改了岛屿的显示名称,受影响的岛屿将无声地回退到 Hub 的限制值,而不是崩溃。Hub 本身在未在映射表中找到时,会回退到硬编码的 10。
线程安全
PoseidonLogger.recentLines 是同步的,因为 getRecentLines() 从渲染线程调用,而 log() 从游戏线程调用。所有其他状态(FishingManager, FishingConfig)仅在主客户端线程上操作(通过 TICK 事件和 Scheduler 回调),因此那里不需要同步。
NOTICE because of Modrinth's policies, this mod will no longer be updated, and relisting will not be attempted if it is taken down. However, this mod will continue to be available and updated at its GitHub repo . While you are there, please check out my other mod Ceres, aimed to help with farming but was never allowed to be listed on Modrinth.
Poseidon
A client-side Fabric mod that automates rod fishing — cast, wait for the bite, reel in, and recast, all with configurable human-like timing.
Named after the Greek god of the sea.
Requires PlayerAPI and YetAnotherConfigLib to run.
ModMenu is optional — it adds a settings button to the mod list.
Features
Smart Bite Detection
Poseidon scans nearby text for the !!! signal servers send when your bobber gets a bite. When detected, it reels in after a configurable human reaction delay with optional randomness so the timing never looks mechanical.
Auto-Recast
After every catch the rod is recast automatically. A configurable decision window gives server chat time to arrive before committing, so triggers that suppress or stop the recast always fire in time. Recast delay is independently configurable (min/max ms) and can be disabled entirely.
Ping-Aware Decision Window
The decision window — how long Poseidon waits for a chat trigger before recasting — is exposed as a player setting so you can tune it to match your connection.
Chat Triggers
Define keyword triggers that match incoming chat messages. Each trigger can:
- Play a custom sound
- Show a title on screen
- Suppress the next auto-recast
- Stop the bot entirely (HUD stays open)
Tracked Entity Warnings
Poseidon tracks entities you fish up and enforces configurable per-area caps. When you hit the cap it alerts you. Entities that have been alive too long (configurable, default ~5 min) trigger a despawn warning so you can act before they vanish.
Bobber Drift Detection
If your hook attaches to a moving entity the bobber drifts away from where it landed. Poseidon detects drift beyond a configurable radius after a short settle period, reels in, and recasts — keeping the bot from stalling on a moving target.
Live HUD
An in-game overlay (toggleable keybind) shows:
- Bot active/inactive state
- Bobber status — grey: no bobber, yellow: bite signal detected, green: bobber idle
- Last catch info and active entity count
- Live countdown text when a bite signal is present
Fully Configurable
All timings, thresholds, sounds, and toggles are exposed through a YACL config screen. Open it from ModMenu, the /poseidon command, or a keybind. No file editing required.
Controls
All keybinds are rebindable in Options → Controls → Poseidon.
| Action |
Default Key |
| Toggle Fishing |
Y |
| Toggle HUD |
H |
| Open Config |
(unbound) |
Type /poseidon in chat to open the config screen directly.
Installation
- Install Fabric Loader for Minecraft 1.21.11
- Install Fabric API
- Install PlayerAPI
- Install YetAnotherConfigLib
- Install ModMenu (optional)
- Drop
poseidon-*.jar into your mods folder
Compatibility
| Minecraft |
Fabric Loader |
Java |
| 1.21.11 |
≥ 0.18.4 |
21 |
License
All Rights Reserved
For Developers
Poseidon — Design & Documentation
Version: current (config schema v6)
Platform: Fabric 1.21.11, Java 21
Dependencies: PlayerAPI, Fabric API, YACL v3, ModMenu (optional)
Mod ID: poseidon
Entry point: com.poseidon.PoseidonMod
Config file: <game_dir>/config/poseidon/config.json
Log file: <game_dir>/config/poseidon/poseidon.log
Table of Contents
- Purpose and Scope
- Architecture Overview
- Package Structure
- FishingState — State Enum
- FishingManager — Core State Machine
- FishingConfig — Configuration
- PoseidonHudRenderer — HUD Overlay
- PoseidonConfigScreen — YACL Config UI
- MouseClickMixin — Right-click Guard
- PoseidonLogger — Logging
- PoseidonMod — Entry Point & Event Wiring
- Chat Triggers System
- Sea Creature Tracking System
- Hook Stuck Detection
- AlarmSound Data Class
- Config Schema & Migration History
- Keybinds & Commands
- HUD Reference
- Configuration Reference (All Settings)
- Timing Reference
- Design Decisions & Notes
1. Purpose and Scope
Poseidon is a client-side fishing automation mod designed for Hypixel Skyblock. It automates the full fishing loop:
- Cast the rod (manual or auto-recast)
- Watch for the server's "reel now" signal (
!!! entity near the bobber)
- React with a human-like random delay and reel in
- Optionally recast after a configurable delay
- Optionally track sea creatures that spawn after each catch
- Fire sound alerts and title overlays on configured chat patterns
Poseidon depends on PlayerAPI for all Minecraft interaction and scheduling. It never calls Minecraft APIs directly for player input — everything goes through MovementActions, Scheduler, TabListInfo, SoundActions, DisplayActions, and PlayerAPIEvents.
2. Architecture Overview
PoseidonMod (entry point)
├── registers keybinds (Y, H, no-default)
├── registers /poseidon command
├── subscribes to PlayerAPIEvents.TICK → onTick()
├── subscribes to PlayerAPIEvents.CHAT_RECEIVED → onChatReceived()
└── registers HudRenderCallback → PoseidonHudRenderer.render()
onTick() each game tick:
├── opens config screen if openConfigNextTick flag set
├── FishingManager.tick() — core state machine
└── handleKeybinds() — polls keybind presses
onChatReceived(sender, message):
└── checks message against FishingConfig.getTriggerLevels()
└── first match: plays sound, shows title, calls FishingManager.notifyTriggerFired()
FishingManager.tick() (only when active):
├── IDLE state: waits for bobber to appear → transitions to WAITING
├── WAITING state: runs detectBite() every tick
│ ├── bite found → saves bobber position, → BITING, schedules reel-in
│ └── no bite: updates nearbyText, runs checkHookStuck()
├── BITING state: waits for scheduled reel-in; reacts to bobber loss
└── REELING state: waits for bobber to disappear
├── Scheduler fires (delayed): sends "use" key, scans for creatures
└── Scheduler fires (10 ticks): resets to IDLE, triggers recast decision
Threading model: Everything runs on the main Minecraft client thread. PlayerAPIEvents.TICK fires on the client tick. Scheduler callbacks also execute on the client thread. No background threads are used other than the file I/O in PoseidonLogger.
3. Package Structure
com.poseidon
├── PoseidonMod.java — ClientModInitializer, event wiring, keybinds, commands
├── core/
│ ├── FishingState.java — enum: IDLE, WAITING, BITING, REELING
│ ├── FishingManager.java — singleton state machine, all fishing logic
│ ├── FishingConfig.java — singleton config, persistence, migrations
│ └── PoseidonLogger.java — singleton logger, in-memory ring buffer + file output
├── gui/
│ ├── PoseidonHudRenderer.java — HUD overlay drawn each frame
│ └── PoseidonConfigScreen.java — YACL config screen builder
├── mixin/
│ └── MouseClickMixin.java — blocks right-click during active cast
└── modmenu/
└── PoseidonModMenuPlugin.java — ModMenu integration
4. FishingState — State Enum
com.poseidon.core.FishingState
The four states of the fishing loop:
| State |
Meaning |
IDLE |
Bot inactive, or active but no rod has been cast yet. No bobber present. |
WAITING |
Bobber is in the water. Scanning every tick for the !!! bite signal entity. Also watching for nearby countdown text and hook drift. |
BITING |
The !!! signal was detected. The reaction delay timer is counting down via Scheduler. Reel-in has not been sent yet. |
REELING |
The tapKey("use", 100) command has been sent to reel in. Waiting for the bobber entity to disappear, which signals the catch is complete. |
Transitions:
IDLE → WAITING when hasBobber becomes true
WAITING → BITING when detectBite() returns true
WAITING → IDLE if bobber disappears while watching
BITING → REELING when scheduled reel-in fires
BITING → IDLE if bobber disappears before reel-in fires
REELING → IDLE after 10-tick reset (or if bobber disappears)
5. FishingManager — Core State Machine
com.poseidon.core.FishingManager — singleton, accessed via FishingManager.getInstance()
Activation
FishingManager.getInstance().setActive(true); // start watching
FishingManager.getInstance().setActive(false); // stop, reset to IDLE
FishingManager.getInstance().toggle(); // flip active state
setActive(false) also clears both pendingSuppressRecast and pendingStopBot flags and resets state to IDLE.
tick() — Called every game tick by PoseidonMod
The method is a no-op if !active. It runs the state machine switch, then:
- Refreshes the current area from the tab list every 40 ticks (2 seconds)
- Runs sea creature cleanup every 40 ticks if tracking is enabled
Bite Detection
detectBite(MinecraftClient mc) scans a box around the bobber's current position:
- Box dimensions:
±detectionRadius in XZ, -1 to +detectionRadius+2 in Y
- Checks every entity in that box for
hasReelNowSignal(entity):
- Checks
entity.getCustomName().getString().contains("!!!")
- Also checks
TextDisplayEntity.getText().getString().contains("!!!") for modern display entities
The !!! signal is placed by the Hypixel server as an armor stand (older system) or text display entity (newer system) near the bobber during the catch window. It typically appears for only a few ticks.
Reaction Delay & Reel-in
Once a bite is detected, the bobber position is snapshotted (lastBobberX/Y/Z) because the bobber may have despawned by the time the reel-in fires.
scheduleReelIn() picks a random delay between reactionDelayMinMs and reactionDelayMaxMs and schedules via Scheduler.scheduleMs(). When the callback fires:
- Transitions to
REELING
MovementActions.tapKey("use", 100) — right-click held for 100ms to reel in
- If sea creature tracking is on: schedules
scanForNewCreatures() at SCAN_DELAY_TICKS (5 ticks)
- Clears recast flags (
pendingSuppressRecast, pendingStopBot)
- Logs the recast decision window start
- Schedules the recast decision at
recastDecisionTicks (default 10 ticks)
- Schedules a state reset at 10 ticks (
REELING → IDLE)
Recast Decision Window
After reeling in, Poseidon waits recastDecisionTicks before deciding whether to recast. This window exists so that post-catch chat messages have time to arrive and fire their triggers (which can set pendingSuppressRecast or pendingStopBot).
Decision logic (in priority order):
- If
!active → abort
- If
pendingStopBot → call setActive(false) → done
- If
!autoRecast || pendingSuppressRecast → do not recast (wait for manual cast)
- Otherwise →
scheduleRecast(cfg) with random delay between recastDelayMinMs and recastDelayMaxMs
scheduleRecast() skips the recast if the state has returned to WAITING (server already recast for us) or BITING (another bite started before recast fired).
notifyTriggerFired(boolean dontRecast, boolean stopBot)
Called from PoseidonMod.onChatReceived() when a trigger matches during a catch. Sets the recast flags that the decision window checks. The flags are reset at the start of each reel-in.
Nearby Text
While in WAITING state, scanNearbyText() scans the same detection box for any entity text that:
- Is not blank
- Does not contain
!!! (the bite signal)
- Does not contain
⚓ (a sea creature name plate)
The first match (truncated to 20 characters) is stored as nearbyText and shown in the HUD Bobber row. This captures the yellow countdown timers that Hypixel displays before a bite window opens.
Public Getters
| Method |
Returns |
isActive() |
Whether the bot is currently enabled |
getState() |
Current FishingState |
getTrackedCount() |
Number of currently tracked sea creatures |
getCurrentArea() |
Area string from tab list, or "" |
getNearbyText() |
Countdown/nearby entity text, or "" |
shouldBlockRightClick() |
True when right-click should be suppressed (WAITING or BITING state) |
6. FishingConfig — Configuration
com.poseidon.core.FishingConfig — singleton, accessed via FishingConfig.getInstance()
Config is stored as JSON at config/poseidon/config.json. Loaded once on onInitializeClient(). Every setter immediately calls save().
Known Areas
FishingConfig.KNOWN_AREAS = List.of(
"Backwater Bayou", "Crimson Isle", "Galatea",
"Hub", "Jerry's Workshop", "The Park"
)
These are the Hypixel Skyblock islands that have per-area sea creature caps in the config. Hub is the fallback cap for any island not in this list.
Config Groups
Detection
detectionRadius — radius around bobber for !!! scan (default 4.0)
hookStuckDetectionEnabled — whether to check for bobber drift (default true)
hookStuckMaxDistance — horizontal drift threshold in blocks (default 1.5)
hookStuckSound — played when hook stuck is detected
Reaction / Recast
reactionDelayMinMs / reactionDelayMaxMs — random window for reel-in reaction
autoRecast — whether to automatically recast after each catch (default true)
recastDelayMinMs / recastDelayMaxMs — random window for recast
recastDecisionTicks — how long to wait for chat triggers before deciding to recast
Sea Creature Tracking
trackSeaCreatures — master toggle (default true)
creatureScanRadius — scan box radius after each reel-in (default 12.0)
seaCreatureCapByArea — per-island cap map, all default 10
seaCreatureCapSound — played when cap is reached
despawnWarningEnabled — whether to warn about creature age (default true)
despawnWarningMinutes — age threshold for the warning (default 5)
despawnWarningSound — played when a creature approaches despawn
Triggers
triggerLevels — list of 5 TriggerLevel objects (all disabled by default)
biteAlertSound — played when !!! is first detected (off by default, durationSeconds=0)
Developer
debugMode — verbose logging flag
logLevel — minimum log level (LEVEL_WARN = 2 by default)
getCapForArea(String area)
Returns the cap for the given area string. Falls back to the Hub cap for any unlisted area. Falls back to 10 if Hub itself has no entry. Minimum returned value is 1.
getDespawnWarningTicks()
Converts despawnWarningMinutes to game ticks: minutes × 60 × 20.
7. PoseidonHudRenderer — HUD Overlay
com.poseidon.gui.PoseidonHudRenderer
Visibility state: Stored as a static boolean hudVisible, default false. Controlled by the H keybind. Closing the HUD while the bot is active automatically calls setActive(false).
Render method: render(DrawContext ctx, RenderTickCounter tick) — registered via HudRenderCallback.EVENT. Draws nothing if !hudVisible or player is null.
Panel Layout
The main panel is always at screen position (4, 4), width 200 pixels. Height is dynamic based on which rows appear.
Header: "Poseidon" label left-aligned; state label right-aligned; colored accent bar on the left edge.
Rows displayed (in order):
| Row |
Label |
Value |
Color Logic |
| 1 |
Active |
Yes / No |
Green if active, red if not |
| 2 |
State |
State name |
Matches accent bar color |
| 3 |
Bobber |
None / Detected / <countdown text> |
Grey=none, Green=detected, Yellow=countdown visible |
| 4 |
Area |
Island name |
Grey — only shown if tracking enabled AND area is known |
| 5 |
SC |
count / cap |
Grey=0, Orange=>0, Red=at or over cap — only shown if tracking enabled |
Accent bar (left edge) color by state:
| State |
Color |
| IDLE (active=false) |
Red 0xFFEE4444 |
| IDLE (active=true) |
Orange 0xFFFFAA00 |
| WAITING |
Green 0xFF44EE44 |
| BITING |
Yellow 0xFFFFFF44 |
| REELING |
Blue 0xFF44AAFF |
The state label in the header also uses the same color.
Log Panel
Appears directly below the main panel when PoseidonLogger has entries. Shows the last 5 log lines (truncated to 50 characters each). The [HH:mm:ss] [LEVEL] prefix is stripped, showing only the message.
8. PoseidonConfigScreen — YACL Config UI
com.poseidon.gui.PoseidonConfigScreen
Opened via /poseidon command, the Open Config keybind (no default), or ModMenu. Has five tabs:
Tab 1 — Detection
Controls how Poseidon identifies a bite and handles stuck hooks.
| Setting |
Type |
Default |
Range |
| Armor Stand Radius |
double slider |
4.0 |
1.0 – 10.0, step 0.5 |
| Hook Stuck Detection |
boolean |
true |
— |
| Max Drift Distance (blocks) |
double slider |
1.5 |
0.5 – 5.0, step 0.25 |
| Hook Stuck Sound |
string |
minecraft:entity.villager.no |
sound ID |
| Hook Stuck Volume |
double slider |
1.0 |
0.1 – 2.0, step 0.05 |
| Hook Stuck Pitch |
double slider |
1.2 |
0.5 – 2.0, step 0.05 |
| Hook Stuck Duration |
int slider |
2s |
0 – 30s |
| Hook Stuck Interval |
int slider |
10 ticks |
5 – 60 ticks |
Tab 2 — Reaction Delay
Controls the human reaction delay and auto-recast behaviour.
| Setting |
Type |
Default |
Range |
| Min Delay (ms) |
int slider |
180 |
50 – 2000, step 10 |
| Max Delay (ms) |
int slider |
700 |
50 – 3000, step 10 |
| Auto Recast |
boolean |
true |
— |
| Recast Delay Min (ms) |
int slider |
200 |
100 – 3000, step 50 |
| Recast Delay Max (ms) |
int slider |
600 |
100 – 5000, step 50 |
| Trigger Wait (ticks) |
int slider |
10 |
2 – 40, step 1 |
The Trigger Wait slider uses a custom formatter: "N ticks (N×50 ms)".
Ping guidance shown in the description:
- Low ping (<80 ms): 5–10 ticks
- Medium ping (80–200 ms): 10–15 ticks
- High ping (200+ ms): 20–30 ticks
Tab 3 — Sea Creature Tracking
| Setting |
Type |
Default |
Range |
| Enable Tracking |
boolean |
true |
— |
| Scan Radius |
double slider |
12.0 |
5.0 – 30.0, step 1.0 |
| Backwater Bayou Cap |
int slider |
10 |
1 – 50 |
| Crimson Isle Cap |
int slider |
10 |
1 – 50 |
| Galatea Cap |
int slider |
10 |
1 – 50 |
| Hub Cap (default) |
int slider |
10 |
1 – 50 |
| Jerry's Workshop Cap |
int slider |
10 |
1 – 50 |
| The Park Cap |
int slider |
10 |
1 – 50 |
| Cap Alert Sound |
string |
minecraft:entity.player.levelup |
sound ID |
| Cap Alert Volume |
double slider |
1.0 |
0.1 – 2.0 |
| Cap Alert Pitch |
double slider |
0.8 |
0.5 – 2.0 |
| Cap Alert Duration |
int slider |
10s |
0 – 30s |
| Cap Alert Interval |
int slider |
20 ticks |
5 – 60 ticks |
| Enable Despawn Warning |
boolean |
true |
— |
| Warning At (minutes) |
int slider |
5 |
1 – 6, formatter: "N min" |
| Despawn Warning Sound |
string |
minecraft:block.bell.use |
sound ID |
| Despawn Warning Volume |
double slider |
1.0 |
0.1 – 2.0 |
| Despawn Warning Pitch |
double slider |
0.8 |
0.5 – 2.0 |
| Despawn Warning Duration |
int slider |
5s |
0 – 30s |
| Despawn Warning Interval |
int slider |
20 ticks |
5 – 60 ticks |
Note: Hub Cap is labelled "Hub Cap §7(default)" — Hub is the fallback cap for any island not in the list.
Tab 4 — Chat Triggers
Contains a header label explaining trigger syntax, then five OptionGroup blocks (one per trigger slot), followed by the Bite Alert sound at the bottom.
Each trigger group has:
| Setting |
Type |
Default |
| Enabled |
boolean |
false |
| Name |
string |
"" |
| Patterns |
string |
"" (comma-separated substrings) |
| Action |
string |
"" (unused, reserved) |
| Show Title |
boolean |
false |
| Title Text |
string |
"" (falls back to Name if blank) |
| Don't Recast |
boolean |
false |
| Stop Bot |
boolean |
false |
| Sound (5 fields) |
AlarmSound |
defaultBite defaults |
Bite Alert (at bottom, after all triggers):
| Setting |
Default |
| Bite Alert Sound |
minecraft:entity.experience_orb.pickup |
| Volume |
1.0 |
| Pitch |
1.5 |
| Duration |
0s (off by default — set above 0 to enable) |
| Interval |
15 ticks |
The bite alert is silent by default (durationSeconds=0). The AlarmSound.play() method returns early if duration is 0.
Tab 5 — Developer
| Setting |
Type |
Default |
| Debug Mode |
boolean |
false |
| Log Level |
cycling list (DEBUG/INFO/WARN/ERROR) |
WARN |
9. MouseClickMixin — Right-click Guard
com.poseidon.mixin.MouseClickMixin
@Mixin(Mouse.class)
public class MouseClickMixin {
@Inject(method = "onMouseButton", at = @At("HEAD"), cancellable = true)
private void poseidon$blockRightClickWhenFishing(
long window, MouseInput mouseInput, int action, CallbackInfo ci)
What it does: Injects at the very start of Mouse.onMouseButton() and cancels the event (preventing the right-click from reaching the game) when all of the following are true:
- The mouse action is
GLFW_PRESS (not release or repeat)
- The button is
GLFW_MOUSE_BUTTON_RIGHT
FishingManager.shouldBlockRightClick() returns true
When shouldBlockRightClick() is true: The bot is active AND the state is WAITING or BITING.
Why this is needed: When fishing in Minecraft, right-clicking the rod while a bobber is in the water reels it in (the same action used for the intentional reel-in). Without this guard, any accidental right-click during the WAITING period would cancel the active cast, leaving the bot stuck. The mixin prevents that at the lowest possible level — before the input reaches ClientPlayerInteractionManager.
This mixin is intentionally narrow. It does not block right-click in REELING state (the reel-in has already been sent) or IDLE state (no cast is active).
10. PoseidonLogger — Logging
com.poseidon.core.PoseidonLogger — singleton, accessed via PoseidonLogger.getInstance()
Log Levels
| Constant |
Value |
Usage |
LEVEL_DEBUG |
0 |
Verbose detection output |
LEVEL_INFO |
1 |
Normal operational events |
LEVEL_WARN |
2 |
Unexpected situations (default) |
LEVEL_ERROR |
3 |
Failures and exceptions |
Default level is LEVEL_INFO on construction, then overridden to LEVEL_WARN when config loads.
Output
- In-memory ring buffer: Last 50 lines kept in a
ArrayDeque<String>, accessed via getRecentLines(). Used by PoseidonHudRenderer for the log panel. Thread-safe via synchronized.
- File output: Appended to
config/poseidon/poseidon.log on every log call. File is opened once at construction in APPEND mode. Auto-flush enabled.
Line Format
[HH:mm:ss] [LEVEL] message
Example: [14:32:07] [INFO] Bobber detected — watching for !!!
11. PoseidonMod — Entry Point & Event Wiring
com.poseidon.PoseidonMod — implements ClientModInitializer
Initialization Sequence (onInitializeClient)
- Log "Poseidon initialising..."
FishingConfig.getInstance().load() — load config from disk (or create defaults)
registerKeybinds() — register Y, H, and the no-default config key
registerCommands() — register /poseidon and the ALLOW_COMMAND fallback
HudRenderCallback.EVENT.register(PoseidonHudRenderer::render)
PlayerAPIEvents.TICK.register(this::onTick)
PlayerAPIEvents.CHAT_RECEIVED.register(this::onChatReceived)
- Log "Poseidon ready."
/poseidon Command
Registered via Fabric's ClientCommandRegistrationCallback. Sets openConfigNextTick = true, which causes the config screen to open on the next tick. The tick delay avoids a race condition with the chat screen closing.
A fallback is also registered via ClientSendMessageEvents.ALLOW_COMMAND for servers that override the client command tree. If the command poseidon arrives via this path, it sets the flag and returns false (block the message from being sent to the server).
onTick()
Runs every game tick:
- Guard:
if (!PlayerInfo.isInWorld()) return
- If
openConfigNextTick: clear flag, open PoseidonConfigScreen
FishingManager.getInstance().tick()
handleKeybinds()
handleKeybinds()
Polls three keybinds for presses:
Y (Toggle Fishing):
- If active:
setActive(false)
- If inactive AND HUD visible:
setActive(true)
- If inactive AND HUD not visible: log warning ("Open the HUD first (H) before starting")
- This enforces the workflow: open HUD → toggle on, rather than allowing an invisible active state.
H (Toggle HUD):
- Flips
PoseidonHudRenderer.hudVisible
- If HUD was just closed AND bot is active: calls
setActive(false) and logs "HUD closed — fishing stopped"
Config key (no default):
- Opens
PoseidonConfigScreen immediately
onChatReceived(String sender, String message)
Iterates FishingConfig.getTriggerLevels() in order. For the first trigger that matches (level.matches(message)):
- Logs the match
level.sound.play()
- If
level.showTitle: calls showTitle(level) (see below)
FishingManager.getInstance().notifyTriggerFired(level.dontRecast, level.stopBot)
- Break — only the first matching trigger fires
showTitle(TriggerLevel level):
Uses DisplayActions.showTitle(text, "") from PlayerAPI. The title text is:
level.titleText if not blank
- Otherwise
level.name
- Otherwise the hardcoded fallback
"Trigger Fired"
DisplayActions is a PlayerAPI class that wraps Minecraft's InGameHud.setTitle() / setSubtitle() to display the big MC title overlay.
12. Chat Triggers System
Overview
Poseidon has 5 configurable trigger slots. Each trigger watches incoming chat messages for keyword matches. When a match is found, it can:
- Play an alarm sound
- Show a Minecraft title overlay
- Suppress the automatic recast (so you can deal with whatever caught your attention)
- Stop the bot entirely (HUD stays open)
Triggers are checked in order from slot 1 to slot 5. The first match wins — later triggers do not fire for the same message.
TriggerLevel Fields
public String name // display label (shown in config group header and logs)
public boolean enabled // whether this trigger is active
public String patterns // comma-separated match substrings, case-insensitive
public AlarmSound sound // sound to play on match
public String action // unused (reserved for future use, leave blank)
public boolean dontRecast // suppress auto-recast after this catch
public boolean stopBot // deactivate the bot after this catch
public boolean showTitle // show a MC title overlay
public String titleText // title text (uses `name` if blank)
Pattern Matching
TriggerLevel.matches(String chatText):
- Returns
false if !enabled or patterns is blank
- Splits patterns on commas, trims each part, lowercases both
- Returns
true if any non-empty pattern is found as a substring of the chat text
- Case-insensitive substring match, not regex
Example patterns for Hypixel Skyblock sea creature events: "appeared, emerged".
Interaction with Recast Decision Window
Chat messages arrive asynchronously relative to the reel-in. recastDecisionTicks is the window between the reel-in action and the recast decision. If a trigger fires within this window, its dontRecast/stopBot flags will be seen by the decision callback.
If a trigger fires after the decision window closes, the flags are ignored. Increasing recastDecisionTicks (or the associated millisecond equivalent) allows more time for high-latency servers.
13. Sea Creature Tracking System
Overview
After each reel-in, Poseidon scans for entities near the bobber position bearing the ⚓ anchor character (U+2693). This is the prefix Hypixel uses on sea creature name plates. New creatures are added to a List<TrackedSeaCreature> with their entity ID, name, and spawn tick.
Detection Mechanism
isSeaCreatureDisplay(Entity entity):
- Checks
entity.getCustomName().getString().contains("⚓") for armor stands / mob name plates
- Checks
TextDisplayEntity.getText().getString().contains("⚓") for text display entities
extractCreatureName(Entity entity):
- Reads raw entity text
- Finds the
⚓ character, takes everything after it (trimmed)
- Strips from the first digit onward (start of the HP value)
- Returns the resulting name, or
"Unknown" if parsing fails
- Full format Hypixel uses:
"[LvN] ⚓ CreatureName HP/MaxHP❤"
Scan Timing
The scan runs SCAN_DELAY_TICKS = 5 ticks after the reel-in. This delay is intentional: the bobber entity typically despawns within 1–2 ticks of the use key press. Anchoring the scan to the saved lastBobberX/Y/Z position rather than the current bobber position (which may be gone) ensures the scan always runs at the right place.
Cleanup
cleanupDeadCreatures(MinecraftClient mc) runs every CLEANUP_PERIOD_TICKS = 40 ticks (2 seconds):
- Despawn warnings: If
despawnWarningEnabled, checks each tracked creature's age. If (currentTick - spawnTick) >= despawnWarningTicks, and the alert hasn't fired yet, plays despawnWarningSound and logs a warning.
- Dead removal:
tracked.removeIf(t -> mc.world.getEntityById(t.entityId) == null) — removes any creature whose entity is no longer in the world.
- Cap reset: If the tracked count falls below the cap after removal, resets
capAlertFired = false so the alert can fire again next time.
Cap Alert
checkCapAlert() is called after each scan finds new creatures. If tracked.size() >= cap and !capAlertFired, plays seaCreatureCapSound and sets capAlertFired = true. The cap used is cfg.getCapForArea(currentArea).
TrackedSeaCreature (inner class)
final int entityId // MC entity ID for alive-check
final String name // extracted display name
final long spawnTick // Scheduler.getCurrentTick() at detection time
boolean despawnAlertFired // prevents duplicate despawn warnings
14. Hook Stuck Detection
Problem
When casting near mobs, the fishing hook can attach to the mob instead of landing in water. The bobber entity exists and is valid, so the normal state machine would wait indefinitely for a bite that will never come. The hook moves with the mob, never triggering !!!.
Detection Mechanism
After the bobber lands, a 1-second settle period (BOBBER_SETTLE_TICKS = 20) runs. During this window, initialBobberX/Z is continuously updated to the current bobber XZ position (so we measure from the final resting place, not the arc peak).
Once the settle period ends, every tick:
- Compute horizontal displacement:
dx = bobber.X - initialBobberX, dz = bobber.Z - initialBobberZ
- Compute Euclidean distance:
dist = sqrt(dx² + dz²)
- If
dist > hookStuckMaxDistance (default 1.5):
- Set
hookStuckFired = true (prevents alert spam for the same cast)
- Play
hookStuckSound
- Transition to
REELING, call MovementActions.tapKey("use", 100)
- Schedule state reset after 10 ticks, then schedule recast if
autoRecast
Why Horizontal Only?
Normal fishing bobbers bob vertically as they float on water. The vertical amplitude is typically < 0.5 blocks. Horizontal drift essentially never occurs for a bobber floating in water. By checking only XZ displacement, the system avoids false positives from the normal bobbing animation.
Configuration
hookStuckDetectionEnabled (bool, default true) — master toggle
hookStuckMaxDistance (double, default 1.5 blocks) — drift threshold, range 0.5–5.0
hookStuckSound (AlarmSound, default: minecraft:entity.villager.no)
15. AlarmSound Data Class
FishingConfig.AlarmSound — public static inner class of FishingConfig
Represents a single repeating sound alert. Used for all sounds throughout Poseidon.
Fields
| Field |
Type |
Meaning |
soundId |
String |
Minecraft sound ID ("namespace:sound.path") |
volume |
double |
0.1 (quiet) – 2.0 (loud), 1.0 = normal |
pitch |
double |
0.5 (slow/deep) – 2.0 (fast/high), 1.0 = normal |
durationSeconds |
int |
Total seconds the alarm plays; 0 = play once, silent if 0 for bite alert |
intervalTicks |
int |
Ticks between each repeat (20 ticks = 1 second) |
Default Instances
AlarmSound.defaultBite()
// soundId=minecraft:entity.experience_orb.pickup, vol=1.0, pitch=1.5, dur=0, interval=15
// Note: dur=0 means silent by default. Set duration > 0 to enable.
AlarmSound.defaultAlert()
// soundId=minecraft:entity.player.levelup, vol=1.0, pitch=1.0, dur=8, interval=20
play()
public void play() {
if (soundId == null || soundId.isBlank() || durationSeconds <= 0) return;
int times = Math.max(1, (durationSeconds * 20) / Math.max(1, intervalTicks));
SoundActions.playByIdRepeated(soundId, (float) volume, (float) pitch, times, intervalTicks);
}
Calculates repeat count from duration and interval. Returns early if silent (duration ≤ 0).
mergeFrom(AlarmSound src, AlarmSound defaults)
Used during config load to merge file values over defaults while protecting against zeroed/null fields:
- Uses
src.soundId if non-blank, else defaults.soundId
- Uses
src.volume/pitch if > 0, else defaults
- Uses
src.durationSeconds/intervalTicks if > 0, else defaults
This means a config file cannot set volume to exactly 0.0 (it would fall back to the default). This is an intentional safeguard against silent-by-mistake configs.
16. Config Schema & Migration History
The config file includes a configVersion integer. On load, the migrate() method chains through all versions in order, bringing old configs forward automatically.
Migration Chain
v0 → v1: flat biteAlert* fields → biteAlertSound AlarmSound object; triggerLevels added
v1 → v2: single seaCreatureCap int → seaCreatureCapByArea Map (all areas get the old cap value)
v2 → v3: autoRecast added (GSON defaults bool to false; migration injects true for old configs)
v3 → v4: recastDecisionTicks added (was hardcoded 40 in old code, default now 10)
v4 → v5: despawnWarningEnabled, despawnWarningMinutes added
v5 → v6: hookStuckDetectionEnabled, hookStuckMaxDistance added
GSON boolean default caveat: GSON creates objects by bypassing constructors. Any new boolean field added to FishingConfig that should default to true must be injected in the migration step, not just added as a Java field initializer, because GSON will produce false for a missing field. Poseidon handles this correctly via migrations (v2→v3 for autoRecast, v4→v5 for despawnWarningEnabled, v5→v6 for hookStuckDetectionEnabled).
KNOWN_AREAS Static Init Order
FishingConfig.KNOWN_AREAS is declared as the first static field specifically because the INSTANCE = new FishingConfig() line (which comes just after) triggers the constructor, and defaultCapsByArea() iterates KNOWN_AREAS. If INSTANCE were declared first, KNOWN_AREAS would be null during the constructor call. The field order is load-bearing.
17. Keybinds & Commands
Keybinds
All registered under the Poseidon Controls category in Minecraft's keybind settings.
| Key |
Default |
Action |
| Y |
Y |
Toggle Fishing — starts the bot (if HUD is open) or stops it |
| H |
H |
Toggle HUD — shows/hides the HUD overlay; also stops the bot if HUD is closed while active |
| (none) |
Unbound |
Open Config — opens the YACL config screen directly |
Start workflow: The Y key will refuse to start the bot if the HUD is not visible. The intended flow is: H to open HUD, then Y to start fishing.
Commands
| Command |
Effect |
/poseidon |
Opens the YACL configuration screen |
The command uses a tick-delay trick (openConfigNextTick) to avoid a race where the config screen tries to open while the chat screen is still closing.
A fallback via ClientSendMessageEvents.ALLOW_COMMAND handles the case where a server overrides the client command tree and intercepts /poseidon before Fabric's ClientCommandManager can handle it.
18. HUD Reference
When is it shown?
Only when PoseidonHudRenderer.hudVisible == true. Default is false on launch. H key toggles it.
Main Panel
Position: top-left (4, 4).
Width: 200 pixels.
Height: dynamic — header (13 px) + divider (1 px) + padding (5 px) + rows × 11 px + bottom padding (5 px).
┌── Poseidon ─────────── [STATE] ──┐ ← colored accent bar + header
│ │ ← divider line
│ Active Yes / No │
│ State IDLE / WAITING / ... │
│ Bobber None / Detected / .. │
│ Area Hub (opt)│
│ SC 4 / 10 (opt)│
└───────────────────────────────────┘
Area row only appears if sea creature tracking is enabled AND currentArea is not blank.
SC row only appears if sea creature tracking is enabled.
Log Panel
Appears immediately below the main panel (3 px gap). Shows last 5 log lines. Format: message text only (prefix stripped). Max 50 characters per line, truncated with ….
State → Color Mapping
| Bot Active |
FishingState |
Color |
Header Label |
| false |
IDLE |
Red 0xFFEE4444 |
OFF |
| true |
IDLE |
Orange 0xFFFFAA00 |
IDLE |
| true |
WAITING |
Green 0xFF44EE44 |
WAITING |
| true |
BITING |
Yellow 0xFFFFFF44 |
BITING |
| true |
REELING |
Blue 0xFF44AAFF |
REELING |
When active=false, the header label shows "OFF" rather than "IDLE".
Bobber Row Color
| Condition |
Color |
Value |
| No bobber |
Grey 0xFF888888 |
"None" |
| Bobber present, no nearby text |
Green 0xFF44EE44 |
"Detected" |
| Bobber present, nearby text found |
Yellow 0xFFFFCC00 |
The countdown text (≤20 chars) |
SC Row Color
| Condition |
Color |
| At or over cap |
Red 0xFFFF4444 |
| Tracked > 0 |
Orange 0xFFFFAA00 |
| Tracked = 0 |
Grey 0xFF888888 |
19. Configuration Reference (All Settings)
All settings live in config/poseidon/config.json. Keys match the Java field names.
Detection
| Key |
Type |
Default |
Notes |
detectionRadius |
double |
4.0 |
Scan box half-size around bobber for !!! signal |
hookStuckDetectionEnabled |
bool |
true |
Enable horizontal drift check |
hookStuckMaxDistance |
double |
1.5 |
Drift threshold in blocks |
hookStuckSound |
AlarmSound |
villager.no, 1.0, 1.2, 2s, 10t |
— |
Reaction & Recast
| Key |
Type |
Default |
Notes |
reactionDelayMinMs |
int |
180 |
Min reaction delay in ms |
reactionDelayMaxMs |
int |
700 |
Max reaction delay in ms |
autoRecast |
bool |
true |
Auto-recast after each catch |
recastDelayMinMs |
int |
200 |
Min recast delay in ms |
recastDelayMaxMs |
int |
600 |
Max recast delay in ms |
recastDecisionTicks |
int |
10 |
Ticks to wait for triggers before recast decision |
Sea Creature Tracking
| Key |
Type |
Default |
Notes |
trackSeaCreatures |
bool |
true |
Master toggle |
creatureScanRadius |
double |
12.0 |
Scan radius after each reel-in |
seaCreatureCapByArea |
Map<String,Integer> |
all 10 |
Per-island cap; Hub is fallback |
seaCreatureCapSound |
AlarmSound |
levelup, 1.0, 0.8, 10s, 20t |
— |
despawnWarningEnabled |
bool |
true |
— |
despawnWarningMinutes |
int |
5 |
Age threshold for despawn warning |
despawnWarningSound |
AlarmSound |
bell.use, 1.0, 0.8, 5s, 20t |
— |
Triggers
| Key |
Type |
Default |
Notes |
triggerLevels |
List<TriggerLevel> |
5 empty/disabled |
— |
biteAlertSound |
AlarmSound |
orb.pickup, 1.0, 1.5, 0s, 15t |
Duration 0 = disabled |
Developer
| Key |
Type |
Default |
Notes |
debugMode |
bool |
false |
— |
logLevel |
int |
2 (WARN) |
0=DEBUG, 1=INFO, 2=WARN, 3=ERROR |
configVersion |
int |
6 |
Do not edit manually |
20. Timing Reference
| Constant |
Value |
Location |
Purpose |
SCAN_DELAY_TICKS |
5 |
FishingManager |
Delay after reel-in before scanning for new sea creatures |
CLEANUP_PERIOD_TICKS |
40 |
FishingManager |
How often to check for despawned creatures (2 seconds) |
AREA_REFRESH_TICKS |
40 |
FishingManager |
How often to re-read "Area:" from tab list (2 seconds) |
BOBBER_SETTLE_TICKS |
20 |
FishingManager |
Settle window before hook stuck drift check starts (1 second) |
| State reset delay |
10 ticks |
FishingManager |
After reel-in fires, time before REELING→IDLE transition |
recastDecisionTicks |
10 (configurable) |
FishingConfig |
Wait for chat triggers before recast decision |
reactionDelayMinMs |
180 (configurable) |
FishingConfig |
Min human reaction delay |
reactionDelayMaxMs |
700 (configurable) |
FishingConfig |
Max human reaction delay |
recastDelayMinMs |
200 (configurable) |
FishingConfig |
Min recast delay |
recastDelayMaxMs |
600 (configurable) |
FishingConfig |
Max recast delay |
despawnWarningMinutes |
5 (configurable) |
FishingConfig |
Age at which despawn warning fires |
20 ticks = 1 second. 1 tick ≈ 50 ms.
21. Design Decisions & Notes
Why a Settle Period for Hook Stuck Detection?
During the cast arc, the bobber travels through the air before landing. Its XZ position changes dramatically during this arc. Without the settle period, every cast would immediately trigger a hook stuck alert because the bobber just flew from the player position to the water. The 1-second settle window (20 ticks) waits for the bobber to reach its final resting position in the water before measuring drift.
Why Save the Bobber Position Before Reeling In?
The bobber entity (fishHook) can despawn within 1–2 ticks of the reel-in action being sent. By the time the Scheduler.schedule(SCAN_DELAY_TICKS, ...) callback fires, mc.player.fishHook is almost certainly null. The bobber XZ/Y coordinates are therefore captured at the moment the !!! signal is detected, and those saved coordinates are passed as parameters to the delayed sea creature scan.
Why Use ALLOW_COMMAND as a Fallback?
On servers like Hypixel, the server pushes a custom command tree to the client that may not include /poseidon. In that case, Fabric's ClientCommandManager would not intercept /poseidon before it is sent to the server. The ALLOW_COMMAND event fires before the message is sent over the network, catching this case. The handler returns false (blocking the send) and sets the flag.
Why the Bobber-in-REELING Guard?
scheduleRecast() skips if state == FishingState.WAITING || state == FishingState.BITING. The WAITING check handles the case where the server automatically recasts the rod (some Hypixel modes do this) — if a bobber has already appeared by the time the recast fires, there is no need to cast again. The BITING check handles an edge case where a new bite signal appears extremely quickly.
Why Only 5 Trigger Slots?
Trigger slots are serialized as a fixed-length list in the config JSON and the YACL UI generates one group per slot. A fixed count of 5 was chosen because Hypixel Skyblock fishing typically needs only 2–3 practical triggers (e.g., "sea creature appeared", "rare creature appeared", "stop on special drop"). Five slots gives margin without making the config screen unwieldy. The list is not hard-limited internally — getTriggerLevels() returns whatever the list contains — but the UI and defaults always produce exactly 5.
Why is shouldBlockRightClick() Only True for WAITING and BITING?
In IDLE state: no cast is active, so right-click should work normally (it casts the rod).
In REELING state: the reel-in has already been sent, so the right-click guard would block a second reel-in. The 10-tick window between the reel-in send and the IDLE reset is short enough that this is not a problem in practice. If the guard were active during REELING, a player who clicked to reel in manually after the bot sent the key would be blocked from doing so.
DisplayActions (PlayerAPI)
Poseidon uses DisplayActions.showTitle(title, subtitle) from PlayerAPI. This class was added to PlayerAPI to wrap Minecraft's InGameHud title display functionality. It lets Poseidon show a large on-screen MC title when a chat trigger fires, without importing Minecraft's InGameHud directly.
Area as Fallback Key
The seaCreatureCapByArea map uses the area string exactly as read from the Hypixel tab list "Area:" line. The map falls back to the Hub cap for any unrecognised string. This means if Hypixel changes an island's display name, the affected island silently falls back to Hub's cap rather than crashing. Hub itself falls back to hardcoded 10 if not in the map.
Thread Safety
PoseidonLogger.recentLines is synchronized because getRecentLines() is called from the render thread while log() is called from the game thread. All other state (FishingManager, FishingConfig) is only touched on the main client thread (via TICK event and Scheduler callbacks), so no synchronization is needed there.
评论 0
登录后参与评分
还没有评论,来抢沙发吧