HBLCore - 非侵入式玩家检查

HBLCore - 非侵入式玩家检查

静默检查玩家加入，并在不触及任何本地封禁数据的情况下，向工作人员通知已知的黑客、破坏者和不良行为者。为开发者提供了一个干净的事件API，以便他们可以挂钩到封禁状态检查中。

生活质量

HBLCore - 非侵入式玩家检查预览查看大图

如有问题或建议，请在 HBL Nexus Discord 中提出此处

在 ko-fi.com 上请我喝咖啡

HBLCore - Hytale 封禁名单核心

为 Hytale 服务器提供简单的被动封禁状态感知。准确知晓谁在加入以及他们在网络服务器中的历史记录——不应用封禁，不触碰本地数据。

如果你想在有已知不良行为者加入时获得游戏内通知，但又不想构建完整的封禁系统，那么这个插件就是为你准备的。

如果你是正在开发管理插件的开发者，HBLCore 为你提供了一个干净的事件钩子，无需自行实现 API，即可在每次加入时获取封禁状态。

快速开始

1. 激活

运行 /hblcore auth 并点击魔法链接。你的服务器即完成注册。

示例 2. 授予通知权限（可选）

向任何工作人员角色授予 HBLCore.notify 权限。每当有玩家加入时，他们将在游戏内收到通知，显示其 HBL 状态。

3. 大功告成

HBLCore 在后台静默运行。不应用封禁，不写入本地文件。拥有通知权限的工作人员可以随时了解情况。

HBLCore 不会做的事情

明确这一点很重要：

  • 它不会踢出或断开任何玩家
  • 它不会写入 bans.json、whitelist.json 或任何服务器文件
  • 它不会在本地管理警告、封禁或管理历史记录
  • 它不会覆盖或替换任何原版服务器命令

HBLCore 纯粹是一个信息层。你如何利用这些信息由你或消费其事件的插件决定。

游戏内通知

当配置中设置 notify: true 时，具有 HBLCore.notify 权限的工作人员将在每位玩家加入时收到通知弹窗：

状态 通知
清白 绿色 - "[HBLCore] 玩家名 - 清白"
已封禁 红色 - "[HBLCore] 玩家名 - 已被封禁 - {原因}"
待定封禁 橙色 - "[HBLCore] 玩家名 - 待定封禁 - {原因}"
已列入白名单 绿色 - "[HBLCore] 玩家名 - 已列入白名单"

没有 HBLCore.notify 权限的玩家将不会收到通知。

配置

首次运行时，配置会自动创建于 HBLCore/config.json。

{
  "APIKey": "在此填写你的API密钥",
  "notify": true,
  "BanReports": true
}
字段 类型 默认值 描述
APIKey string "在此填写你的API密钥" 你的 hytalebanlist.org API 密钥。通过 /hblcore auth 设置。
notify boolean true 向拥有 HBLCore.notify 权限的工作人员发送游戏内状态通知。
BanReports boolean true 启用 /hblcore report 命令。

命令

/hblcore auth

将本服务器注册到 hytalebanlist.org。打开一个魔法链接——在浏览器中点击它以完成激活。API 密钥会自动保存。

需要权限：HBLCore.auth

/hblcore report {时间} {用户名}

无需原因即可对一名玩家提交报告。API 会返回一个魔法链接——打开它以添加原因、证据，并通过 Web 界面完成提交。本地不会应用任何操作。

需要权限：HBLCore.report 且配置中设置 BanReports: true。

持续时间示例： 30m 2h 7d 2w 1mo 1y perm

/hblcore report 7d SomePlayer
> 已为 SomePlayer 提交报告。请在此处完成：
> https://hytalebanlist.org/report/...

权限

权限 授予对象 作用
HBLCore.auth 服务器管理员 运行 /hblcore auth
HBLCore.report 提交报告的工作人员 运行 /hblcore report
HBLCore.notify 工作人员 / 管理员 接收游戏内加入状态通知

对于插件开发者——事件钩子

HBLCore 提供了一个静态事件 API，任何插件都可以通过一行代码接入。你将接收每位加入玩家的封禁状态，而无需自行实现 hytalebanlist.org API。

注册监听器

import org.hblcore.HBLCorePlugin;
import org.hblcore.event.HBLStatusEvent;
import org.hblcore.event.HBLStatusEvent.PlayerStatus;
// 在你的插件的 setup() 方法中：
HBLCorePlugin.registerStatusListener(event -> {
    if (event.getStatus() == PlayerStatus.BANNED) {
        // 踢出、记录、警报——由你决定
    }
});

可用的事件数据

event.getUsername()   // String  - 加入玩家的用户名
event.getUuid()       // String  - 加入玩家的 UUID
event.getStatus()     // PlayerStatus - CLEAR | BANNED | LOCAL_BAN | WHITELISTED
event.getReason()     // String  - 封禁原因（若为 CLEAR 或 WHITELISTED 则为 null）
event.getAppealUrl()  // String  - 申诉 URL（若不适用则为 null）
event.getExpiresAt()  // Instant - 封禁到期时间（若为永久或不适用则为 null）

状态值

状态 含义
CLEAR 无封禁记录。玩家是清白的。
BANNED 已被 hytalebanlist.org 确认的活跃封禁。
LOCAL_BAN 封禁存在于 hytalebanlist.org，但正在等待审核（尚未确认）。
WHITELISTED 玩家已在 hytalebanlist.org 列入白名单。

处理所有状态

HBLCorePlugin.registerStatusListener(event -> {
    switch (event.getStatus()) {
        case BANNED -> {
            // 活跃封禁已确认——踢出、记录、限制等操作
            String reason = event.getReason();
            String appeal = event.getAppealUrl();
        }
        case LOCAL_BAN -> {
            // 封禁存在但正在等待审核——尚未确认
        }
        case WHITELISTED -> {
            // 明确列入白名单——清除任何本地限制
        }
        case CLEAR -> {
            // 清白玩家——无需操作
        }
    }
});

声明 HBLCore 为依赖项

在你的插件的 manifest.json 中：

{
  "Dependencies": {
    "HBLCore": "*"
  }
}

给开发者的重要提示

  • HBLCore 从不踢出玩家。 你的监听器将决定采取什么行动。
  • 监听器是异步调用的。 避免在回调函数内执行阻塞操作。
  • 每个监听器的异常都会被捕获。 你的代码崩溃不会影响其他监听器或加入流程。
  • 注册与加载顺序无关。 你可以在插件的 setup() 中随时调用 registerStatusListener。

完整的开发者文档：plugin-event-usage.md

实用链接