Kbbstoper

安装与配置

KBBSToper 的安装、宣传帖顶帖检测、奖励体系、数据库与代理配置的完整说明。

KBBSToper

检测**苦力怕论坛（klpbbs.com）**服务器宣传帖的顶帖记录，玩家绑定论坛账号后顶帖即可在游戏里领取奖励。

环境要求

项目	要求
服务端	Paper 及其衍生
版本	1.21+
硬依赖	无
软依赖	PlaceholderAPI（提供占位符，可选）
内置库	Jsoup 1.17.2、bStats（由服务端自动下载）
网络	需要能访问 klpbbs.com（不通可配代理）

Jsoup 与 bStats 写在 plugin.yml 的 libraries 里，由服务端在启动时自动下载。首次启动需要联网，否则插件会因缺库无法加载。

安装

放入插件

把 jar 放进 plugins/，启动一次生成配置。

找到宣传帖 ID

打开你在苦力怕论坛的服务器宣传帖，地址形如 https://klpbbs.com/thread-1034574-1-1.html，中间那串数字 1034574 就是帖子 ID。

填进配置

bbs:
  url: '1034574'    # 换成你自己的帖子 ID

重启服务器

控制台出现 插件已启用! 即成功。

插件目录结构：

plugins/KBBSToper/
├── config.yml      # 主配置：数据库、帖子、奖励、代理
├── lang.yml        # 全部提示文案
├── gui.yml         # 箱子 GUI 布局
└── bbstoper.db     # SQLite 数据库（用 MySQL 时不生成）

命令与权限

主命令 kbbstoper，别名 /bt 与 /poster。下表用 /bt 举例。

玩家指令（`bbstoper.user`，默认所有人）

命令	作用	权限
`/bt`	打开箱子 GUI	无需权限
`/bt help`	显示帮助	无需权限
`/bt binding <论坛ID>`	绑定论坛账号	`bbstoper.binding`
`/bt reward`	领取顶帖奖励	`bbstoper.reward`

管理指令（`bbstoper.admin`，默认 OP）

命令	作用	权限
`/bt testreward [模式]`	测试奖励，模式：`normal` `incentive` `offday`	`bbstoper.testreward`
`/bt list [页码]`	列出顶帖记录	`bbstoper.list`
`/bt top [页码]`	按顶帖次数排名玩家	`bbstoper.top`
`/bt check bbsid <论坛ID>`	查这个论坛 ID 被谁绑定了	`bbstoper.check`
`/bt check player <玩家名>`	查这个玩家绑定的论坛 ID	`bbstoper.check`
`/bt delete player <玩家名>`	删除该玩家的全部数据	`bbstoper.delete`
`/bt reload`	重载配置	`bbstoper.reload`
—	绕过查询冷却	`bbstoper.bypassquerycooldown`

两个伞节点（bbstoper.user / bbstoper.admin）通过 plugin.yml 的 children 建立父子关系，给伞节点即拥有其下全部子权限。

/bt binding 要填的是论坛用户名（ID），不是 uid 数字。填错会导致永远匹配不到顶帖记录，而且换绑有 changeidcooldown（默认 30 天）冷却。建议在服内公告里把这点写清楚。

config.yml 配置详解

基础

version: 3.7.4

# DEBUG 模式
debug: false

website: "klpbbs.com"

字段	说明
`version`	配置文件版本标记，不要手动改
`debug`	开启后输出详细日志，排查抓取问题时用
`website`	论坛域名。插件用它拼接抓取地址与帖子链接

数据库

database:
    # 表名前缀, 在 sqlite 和 mysql 都有效
    prefix: 'bt_'
    # 定时自动断开并重新连接数据库，单位秒，0 = 关闭
    timingreconnect: 0
    # 可选 mysql 或 sqlite
    type: 'sqlite'
    mysql:
        ip: 'localhost'
        port: '3306'
        database: 'databasename'
        user: 'username'
        password: 'password'
        ssl: false
    sqlite:
        folder: '%PLUGIN_FOLDER%'
        database: 'bbstoper.db'

字段	说明
`prefix`	表名前缀，两种数据库都生效。留空写 `''`
`timingreconnect`	定时重连间隔（秒）。长连接变慢时可以试着开，如 `3600`
`type`	`sqlite`（默认，单服够用）或 `mysql`（多服共享数据时用）
`sqlite.folder`	`%PLUGIN_FOLDER%` 表示插件目录

单服直接用默认的 SQLite 就行。只有在多个子服需要共享绑定与顶帖数据时才需要 MySQL——这时把所有子服的 database 一节配成同一个库、同一个 prefix 即可。

帖子与冷却

bbs:
    # 服务器宣传贴的帖子 id
    url: '1034574'
    # 顶帖列表/玩家排名每页的大小
    pagesize: 10
    # 玩家多久能更换一次绑定的 id, 单位天
    changeidcooldown: 30
    # 玩家多久能使用一次奖励指令以及查询指令, 单位秒
    querycooldown: 30
    # 如果一个玩家没有顶贴是否在加入时发送提示消息
    joinmessage: true

字段	默认	说明
`url`	`1034574`	必须改成你自己的帖子 ID
`pagesize`	`10`	`/bt list` 与 `/bt top` 每页条数
`changeidcooldown`	`30`	换绑冷却，单位天
`querycooldown`	`30`	查询/领奖冷却，单位秒。可用 `bbstoper.bypassquerycooldown` 绕过
`joinmessage`	`true`	未顶帖的玩家进服时提示（文案在 `lang.yml` 的 `info`）

代理

proxy:
    enable: false
    ip: '127.0.0.1'
    port: 10809

服务器无法直连 klpbbs.com 时开启。插件用 Jsoup 走这个 HTTP 代理抓取页面。

GUI 行为

gui:
    # 玩家排名的显示数量
    topplayers: 5
    # 显示 GUI 中的头颅皮肤
    displayheadskin: true
    # 是否启用按键后输入绑定 ID
    usechatgetid: true
    # 取消绑定的关键词
    cancelkeywords:
    - 'cancel'
    - '取消'

字段	说明
`topplayers`	GUI 里排行榜显示几名
`displayheadskin`	显示头颅皮肤。获取皮肤可能造成主线程卡顿，卡就关掉
`usechatgetid`	点绑定按钮后监听聊天获取论坛 ID。被聊天插件干扰时关掉它，改用 `/bt binding`
`cancelkeywords`	监听聊天期间输入这些词可取消绑定

usechatgetid 依赖玩家聊天事件。若服务器装了会修改或取消聊天事件的插件（聊天频道、敏感词过滤、VentureChat 等），插件可能拿不到正确输入，表现为「点了绑定按钮然后输入没反应」。这时把它设为 false，让玩家用 /bt binding <论坛ID> 命令绑定。

奖励体系

三类奖励，可叠加也可独立：

reward:
    # 自动奖励间隔，单位秒，0 = 关闭
    auto: 30
    # 顶贴后领取奖励的有效期, 单位天
    period: 10
    # 同一玩家距上次顶贴多少分钟后再次顶贴才算有效, 0 = 一直有效
    interval: 10
    # 一天能领取几次顶帖奖励
    times: 1
    # 奖励命令, %PLAYER% = 领奖玩家
    commands:
    - 'experience add %PLAYER% 1000'
    - 'eco give %PLAYER% 20'

字段	默认	说明
`auto`	`30`	每隔多少秒自动抓取宣传帖，检测到顶帖就自动给在线玩家发奖。0 = 只能手动 `/bt reward`
`period`	`10`	顶帖后多少天内有效，过期不能领
`interval`	`10`	同一玩家两次有效顶帖的最小间隔（分钟），防刷
`times`	`1`	每天最多领几次
`commands`	—	奖励命令，`%PLAYER%` 替换为玩家名，以控制台身份执行

auto 每次都要抓取一次论坛页面，是网络 IO 密集操作。官方注释建议设为 30 左右，不要设成 1 ~ 5 这种极小值——既给论坛造成压力，也可能触发对方的频率限制导致抓取失败。完全关掉（0）则玩家必须手动 /bt reward。

激励奖励

无人顶帖一段时间后，第一个来顶帖的玩家获得额外奖励：

    incentivereward:
        enable: false
        # 是否为额外奖励(是否还会给与普通的奖励)
        extra: true
        # 距上一次有人顶贴多久之后给激励奖励, 单位分钟
        period: 30
        commands:
        - 'effect give %PLAYER% haste 2'

休息日奖励

指定日期顶帖有额外奖励：

    offdayreward:
        enable: false
        extra: true
        # 星期几 或 MM-dd 格式的具体日期
        offdays:
        - 'SATURDAY'
        - 'SUNDAY'
        - '10-01'
        - '05-01'
        commands:
        - 'effect give %PLAYER% speed 2'

offdays 支持两种写法：

星期：SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY
具体日期：MM-dd，如 10-01 表示每年 10 月 1 日

extra 的含义

extra 决定这份奖励是「额外」还是「替代」：

`extra`	行为
`true`	普通奖励 + 这份奖励都发
`false`	只发这份奖励，不发普通奖励

当休息日奖励与激励奖励的 extra 都为 false，且两个条件同时满足时，只有休息日奖励会被发放。 这是插件的既定优先级。想让两份都发就把 extra 设为 true。

用 /bt testreward normal|incentive|offday 可以在不真的顶帖的情况下测试三类奖励命令是否可用。

PlaceholderAPI 占位符

需要服务器安装 PlaceholderAPI。

占位符	返回
`%bbstoper_bbsid%`	当前玩家绑定的论坛用户名，未绑定返回 `lang.yml` 的 `gui.notbound`
`%bbstoper_posttimes%`	当前玩家的顶帖次数
`%bbstoper_pageid%`	宣传帖 ID
`%bbstoper_pageurl%`	宣传帖完整链接
`%bbstoper_lastpost%`	上次被顶帖的时间；从没人顶过返回 `----`；帖子不可视返回提示文本
`%bbstoper_extrarewards%`	当前可获得的额外奖励描述，没有则返回 `lang.yml` 的 `none`
`%bbstoper_top_<序号>%`	排行第 N 名的顶帖信息，如 `%bbstoper_top_1%`

%bbstoper_lastpost% 与 %bbstoper_extrarewards% 在解析时会发起一次网页抓取。放在计分板、TAB 列表这类高频刷新的位置会造成大量网络请求甚至卡顿。这两个占位符建议只用在 GUI lore 或聊天消息里。

gui.yml：箱子界面

gui:
  title: '%PREFIX%'
  rows: 3
  border:
    fill: 'WHITE_STAINED_GLASS_PANE'
    slots:
      - 0;1;2;3;4;5;6;7;8
      - 9;17
      - 18;26
  items:
    bind:
      slot: 12
      type: 'PLAYER_HEAD'
      displayName: '&a绑定绑定'
      lore:
        - '&7点击绑定您的论坛ID'
      action: 'binding'
      # 已绑定后的替换内容
      bound-type: 'PLAYER_HEAD'
      bound-displayName: '&a已绑定：%player_name%'
      bound-lore:
        - '&7绑定账号：%bbstoper_bbsid%'
        - '&7顶贴次数：%bbstoper_posttimes%'
        - '&7上次顶贴：%bbstoper_lastpost%'
      bound-action: 'binding'

字段	说明
`title`	界面标题，`%PREFIX%` 取 `lang.yml` 的 `prefix`
`rows`	行数
`border.fill`	边框材质
`border.slots`	边框槽位，分号分隔
`items.<名字>.slot`	图标位置
`items.<名字>.type`	材质
`items.<名字>.displayName` / `lore`	显示内容，`&` 颜色码，支持 PAPI 占位符
`items.<名字>.action`	点击行为，见下表
`bound-*`	玩家已绑定时替换用的内容

可用的 action：

action	行为
`binding`	开始绑定流程
`reward`	领取奖励
`top`	打开顶帖排行
`open`	发送宣传帖链接（文案在 `lang.yml` 的 `clickposticon`）

默认 gui.yml 的第 33 ~ 34 行用了全角引号 '，不是标准 YAML 引号。

        - ‘’
        - ‘&e点击重新绑定’

这两行会被当成字面量文本处理——第一行显示为 ‘’ 两个字符（而不是预期的空行），第二行会带着全角引号一起显示。虽然 YAML 解析不报错，但显示效果不对。建议改成：

        - ''
        - '&e点击重新绑定'

lang.yml：全部文案

所有玩家可见文字都在 lang.yml，用 & 颜色码。常用占位符：

占位符	出现在	含义
`%PREFIX%`	各处	插件前缀
`%COOLDOWN%`	`querycooldown` `oncooldown`	剩余冷却
`%PAGE%` / `%TOTALPAGE%`	列表分页	当前页 / 总页数
`%PLAYER%`	`broadcast` `idowner`	玩家名
`%TIME%`	`reward` `intervaltooshort`	顶帖时间
`%EXTRA%`	`extrareward` `extrainfo`	额外奖励描述
`%REWARDTIMES%`	`overtime`	每日可领次数
`%INTERVAL%`	`intervaltooshort`	顶帖间隔要求
`%KEYWORD%`	`enter`	取消绑定的关键词列表
`%ID%` / `%UUID%`	`check` 系列	论坛 ID / 玩家 UUID

failedresolveweb 这条提示在宣传帖被移入审核区时会反复出现。想禁用它就留空：

failedresolveweb: ''

排错

控制台报「获取网页时错误」

网络问题。按顺序查：

服务器能不能访问 klpbbs.com（curl -I https://klpbbs.com）
需要代理的话是否配了 proxy.enable: true
auto 是否设得过小导致被论坛限流

控制台报「处理网页信息失败，宣传帖目前可能不可视或被删除」

bbs.url 填错，或帖子被移入审核区 / 已删除。确认帖子在浏览器里能正常打开。

玩家顶帖了但领不到奖励

按顺序查：

/bt check player <玩家名> 确认绑定的论坛 ID 正确（填 uid 数字是最常见错误）
顶帖时间是否超过 reward.period（默认 10 天）
今天是否已领满 reward.times 次
距上次顶帖是否不足 reward.interval 分钟
开 debug: true 看抓取到的顶帖列表里有没有他的论坛 ID

点绑定按钮后输入没反应

聊天事件被其他插件修改或取消。把 gui.usechatgetid 设为 false，改用 /bt binding <论坛ID>。

打开 GUI 时卡顿

头颅皮肤获取造成的。设 gui.displayheadskin: false。

插件加载失败，报缺少 jsoup / bstats

plugin.yml 的 libraries 需要服务端首次启动时联网下载。确认服务器能访问 Maven Central，或手动把这两个库放进服务端的 libraries 目录。

从 BBSToper 迁移后所有绑定都没了

两者数据库结构不通用，这是预期行为。需要玩家重新执行 /bt binding。

编辑此页面或提交问题报告

更新日志

Snow-EnchantSP 各版本的变更记录。

更新日志

KBBSToper 各版本的变更记录，以及与上游 BBSToper 的差异。