Poseidon

模组

· 作者 NoName_

一个 Fabric 客户端模组,自动执行抛竿、等待咬钩、收线并重新抛竿,所有操作均支持可配置的人类风格时间间隔。

0 本站下载 0 关注 更新于 6 个月前

需要前置:PlayerAPI、另一个配置库 (YACL)

最新 1.0.0 · 1.21.11 · Fabric

一键开服(送7天)

通知

由于 Modrinth 的政策,本模组将不再更新;如果被下架,也不会尝试重新上架。不过,本模组将继续在其 GitHub 仓库中提供并更新:。访问该仓库时,也请查看我的另一个模组 Ceres,它旨在帮助进行农业活动,但从未被允许在 Modrinth 上列出。

Poseidon

一个客户端 Fabric 模组,用于自动化钓鱼——抛竿、等待咬钩、收杆和再次抛竿,所有操作均具有可配置的人类化时间间隔。
以希腊海神波塞冬命名。

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


功能

智能咬钩检测

Poseidon 扫描附近的文本,查找服务器在您浮标咬钩时发送的 !!! 信号。检测到后,它会在可配置的人类反应延迟后收杆,并可选地加入随机性,使时间间隔看起来不机械。

自动重抛

每次捕获后,鱼竿会自动重新抛出。可配置的决策窗口允许服务器聊天消息到达后再提交,这样抑制或停止重抛的触发器总能及时触发。重抛延迟可独立配置(最小/最大毫秒),也可以完全禁用。

基于延迟的决策窗口

决策窗口——Poseidon 在重抛前等待聊天触发的时间长度——作为玩家设置暴露出来,以便您根据连接情况进行调整。

聊天触发器

定义匹配传入聊天消息的关键字触发器。每个触发器可以:

  • 播放自定义声音
  • 在屏幕上显示标题
  • 抑制下一次自动重抛
  • 完全停止机器人(HUD 保持打开)

追踪实体警告

Poseidon 追踪您钓起的实体,并强制执行可配置的区域上限。达到上限时会提醒您。存活时间过长(可配置,默认约 5 分钟)的实体会触发消失警告,以便您在它们消失前采取行动。

浮标漂移检测

如果您的挂钩附着在一个移动的实体上,浮标会偏离落点。Poseidon 在短暂的稳定期后检测超出可配置半径的漂移,然后收杆并重抛——防止机器人在移动目标上停滞。

实时 HUD

游戏内叠加层(可切换快捷键)显示:

  • 机器人激活/非激活状态
  • 浮标状态——灰色:无浮标,黄色:检测到咬钩信号,绿色:浮标空闲
  • 上次捕获信息和活跃实体计数
  • 存在咬钩信号时的实时倒计时文本

完全可配置

所有时间间隔、阈值、声音和开关都通过 YACL 配置屏幕暴露。您可以从 ModMenu、/poseidon 命令或快捷键打开它。无需编辑文件。


控制

所有快捷键均可在选项 → 控制 → Poseidon中重新绑定。

动作 默认键
切换钓鱼 Y
切换 HUD H
打开配置 (未绑定)

在聊天中输入 /poseidon 可直接打开配置屏幕。


安装

  1. 为 Minecraft 1.21.11 安装 Fabric Loader
  2. 安装 Fabric API
  3. 安装 PlayerAPI
  4. 安装 YetAnotherConfigLib
  5. 安装 ModMenu (可选)
  6. 将 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


目录

  1. 目的与范围
  2. 架构概述
  3. 包结构
  4. FishingState — 状态枚举
  5. FishingManager — 核心状态机
  6. FishingConfig — 配置
  7. PoseidonHudRenderer — HUD 叠加层
  8. PoseidonConfigScreen — YACL 配置 UI
  9. MouseClickMixin — 右键点击保护
  10. PoseidonLogger — 日志记录
  11. PoseidonMod — 入口点与事件接线
  12. 聊天触发器系统
  13. 海洋生物追踪系统
  14. 钩子卡住检测
  15. AlarmSound 数据类
  16. 配置架构与迁移历史
  17. 快捷键与命令
  18. HUD 引用
  19. 配置引用(所有设置)
  20. 时间间隔引用
  21. 设计决策与备注

1. 目的与范围

Poseidon 是一个专为 Hypixel Skyblock 设计的客户端钓鱼自动化模组。它自动化了完整的钓鱼循环:

  1. 抛竿(手动或自动重抛)
  2. 观察服务器的“现在收杆”信号(浮标附近的 !!! 实体)
  3. 以人类化的随机延迟响应并收杆
  4. 可选择在可配置延迟后重抛
  5. 可选择追踪每次捕获后生成的海洋生物
  6. 在配置的聊天模式上触发声音警报和标题叠加

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() 进行调度。当回调触发时:

  1. 转换为 REELING
  2. MovementActions.tapKey("use", 100) — 按住右键 100 毫秒以收线
  3. 如果启用了海洋生物追踪:在 SCAN_DELAY_TICKS(5 个游戏刻)处调度 scanForNewCreatures()
  4. 清除重新抛竿标志(pendingSuppressRecast, pendingStopBot)
  5. 记录重新抛竿决策窗口的开始
  6. 在 recastDecisionTicks(默认 10 个游戏刻)处调度重新抛竿决策
  7. 在 10 个游戏刻处调度状态重置(REELING → IDLE)

重新抛竿决策窗口

收杆后,波塞冬会等待 recastDecisionTicks 的时间,然后再决定是否重新抛竿。设置这个窗口期是为了让捕获后的聊天消息有足够的时间到达并触发其逻辑(这些逻辑可以设置 pendingSuppressRecast 或 pendingStopBot)。

决策逻辑(按优先级顺序):

  1. 如果 !active → 中止
  2. 如果 pendingStopBot → 调用 setActive(false) → 结束
  3. 如果 !autoRecast || pendingSuppressRecast → 不重新抛竿(等待手动抛竿)
  4. 否则 → 使用介于 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)

  1. 记录日志 "Poseidon initialising..."
  2. FishingConfig.getInstance().load() — 从磁盘加载配置(或创建默认值)
  3. registerKeybinds() — 注册 Y、H 以及无默认值的配置按键
  4. registerCommands() — 注册 /poseidon 命令及 ALLOW_COMMAND 回退机制
  5. HudRenderCallback.EVENT.register(PoseidonHudRenderer::render)
  6. PlayerAPIEvents.TICK.register(this::onTick)
  7. PlayerAPIEvents.CHAT_RECEIVED.register(this::onChatReceived)
  8. 记录日志 "Poseidon ready."

/poseidon 命令

通过 Fabric 的 ClientCommandRegistrationCallback 注册。设置 openConfigNextTick = true,这会导致配置屏幕在下一个游戏刻打开。延迟一个游戏刻是为了避免与聊天屏幕关闭时的竞态条件。

还通过 ClientSendMessageEvents.ALLOW_COMMAND 注册了一个回退机制,用于处理那些覆盖客户端命令树的服务端。如果 poseidon 命令通过此路径到达,它将设置标志并返回 false(阻止消息发送至服务器)。

onTick()

每个游戏刻运行一次:

  1. 守卫检查:if (!PlayerInfo.isInWorld()) return
  2. 如果 openConfigNextTick:清除标志,打开 PoseidonConfigScreen
  3. FishingManager.getInstance().tick()
  4. 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)):

  1. 记录该匹配
  2. level.sound.play()
  3. 如果 level.showTitle:调用 showTitle(level)(见下文)
  4. FishingManager.getInstance().notifyTriggerFired(level.dontRecast, level.stopBot)
  5. 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 秒)运行一次:

  1. 消失警告:如果启用了 despawnWarningEnabled,检查每个追踪生物的年龄。如果 (currentTick - spawnTick) >= despawnWarningTicks,且警报尚未触发,则播放 despawnWarningSound 并记录警告日志。
  2. 移除死亡生物:tracked.removeIf(t -> mc.world.getEntityById(t.entityId) == null) —— 移除任何实体已从世界中消失的生物。
  3. 上限重置:如果在移除操作后追踪数量低于上限,则重置 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 位置(因此我们测量的是从最终静止位置开始,而非抛物线顶点)。

稳定期结束后,每一刻执行以下操作:

  1. 计算水平位移:dx = bobber.X - initialBobberX, dz = bobber.Z - initialBobberZ
  2. 计算欧几里得距离:dist = sqrt(dx² + dz²)
  3. 如果 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 回调),因此那里不需要同步。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源