QuizzerBot 插件Wiki文档

1. 插件概述

1.1 基本介绍

欢迎使用 QuizzerBot！这是一个给服务器增加趣味答题活动的插件。支持Paper/Bukkit/Spigot等服务端核心。当前稳定支持API版本1.21.6及以上（已通过1.21.6-1.21.8版本测试，低于1.21.6尚未测试，但由于低版本不支持对话框API因此可能会出问题）。

本文档会尽量覆盖所有功能进行介绍，并区分新旧版本。当前文档对应版本：1.2.0

1.2 核心功能

QuizzerBot 核心就是“答题”。它提供了两种完全独立的答题模式：

经典聊天答题 (所有版本均可使用)
- 插件会按你设定的时间间隔，在聊天框自动发起全服答题。
- 题目和选项会显示在公屏，玩家通过点击选项或输入指令来抢答。
图形界面答题 (1.2.0+ 新增, 需 MC 1.21.6+)
- 利用 Paper 1.21.6+ 新增的 Dialog API，提供了一个可交互的答题菜单。
- 玩家可以随时使用 /quiz dialog 指令拉起这个菜单，按自己的节奏答题。
- 这个功能使用独立的题库和排行榜，适合用来做“背单词CET4\6”、“MC知识问答”等额外挑战。

1.3 运行机制

插件安装后会自动生成：
- config.yml配置文件
- quizzerBook.db H2格式数据库文件
数据库存储：
- 题目数据（QuizzerBook表）
- 玩家统计数据（PlayerStats表）
- 附加题目数据（extraQuizBook表）
- 玩家附加统计数据（PlayerExtraStats表）

警告：请勿手动删除数据库文件，否则将导致数据丢失

1.4 版本兼容性说明

1.2.0+ 版本 (最新):
- 为了支持“图形界面答题”，此版本必须在 Paper 1.21.6 及更高版本上运行。
- 如果你是 1.21.6+ 的服务器，请使用这个版本。
1.1.x 版本:
- 这些版本不包含“图形界面答题”和“CSV导入导出”功能。
- 它们适用于 1.21 ~ 1.21.5 版本的服务器。
- 如果你不打算升级服务器到 1.21.6，请继续使用 1.1.x 版本的插件。(备注：1.1.x版本可能存在时常无法自动触发答题bug，如有需求可联系作者更新修复)

2. 安装与初始化

2.1 安装步骤

将插件jar文件放入服务器plugins目录
重启服务器
检查启动日志确认加载成功

2.2 成功加载标志

正常启动时会显示如下日志信息（具体内容可能因版本不同略有差异）：

[11:15:17 INFO]: [QuizzerBot] 数据库初始化完成
[11:15:17 INFO]: [QuizzerBot] 配置项:最低玩家限制: 1
[11:15:17 INFO]: [QuizzerBot] 配置项:答题时间: 20
[11:15:17 INFO]: [QuizzerBot] 答题系统已成功启动

插件第一次运行时，会自动在 plugins/QuizzerBot/ 目录下生成 config.yml 配置文件和 quizzerBook.db 数据库文件。1.2.0版本为了读写 .db 数据库，插件会自动从网上下载 H2 数据库驱动，下载速度取决于服务端所在服务器网络情况。

3. 功能详解

3.1 自动答题

3.1.1 触发机制

插件会根据 config.yml 里的 trigger_interval_sec: [最小值, 最大值] 配置，在这个时间范围内随机挑一个秒数，倒计时触发答题。(如果把最小值和最大值设成一样的，就是固定时间触发)。
触发时，会检查当前在线人数是否满足 min_players 的最低要求。

3.1.2 答题过程

条件满足后，题目和选项会发到公屏。
玩家有 answer_reveal_delay_sec 秒的时间来作答（比如配置 60 秒）。
玩家可以通过直接点击聊天框里的选项或使用 /quiz ans <答案> 来提交。

3.1.3 结算与奖励

时间一到，插件停止接收答案并开始结算。
插件会看 player_QuickAnswer_limit (抢答名额) 和 player_reward_limit (奖励名额) 这两个配置。
“抢答成功”: 最先答对的前 player_QuickAnswer_limit 名玩家，会被标记为“抢答成功”。
“获得奖励”: 插件会从“抢答成功”的玩家里，按先后顺序发奖励，最多发 player_reward_limit 份。
特殊情况: 如果抢答名额内的玩家答错了，奖励会顺延给后面答对的玩家 (哪怕他不是抢答玩家)，直到发满 player_reward_limit 份奖励为止。

3.2 图形界面答题 (1.2.0+ 新增)

独立题库: 它使用一个叫 extra_questions 的独立题库，管理指令是 /quiz extra ...。
独立统计: 它的排行榜、玩家数据也是独立计算的。
玩法: 玩家输入 /quiz dialog 打开菜单，就可以自己选择题库（如果你未来做了分类）或开始答题。
应用场景: 非常适合做服主定制的内容，比如英语四六级单词（就像你开发的初衷！）、服务器趣味知识问答等。

3.3 题库管理 (1.2.0+ 新增)

为了方便服主编辑大量题目，1.2.0 版增加了 CSV 导入导出功能。

数据表列表(区分大小写)：QuizzerBook extraQuizBook PlayerStats PlayerExtraStats

导出: /quiz database export <表名>
例如: /quiz database export QuizzerBook (导出自动答题的题库)
例如: /quiz database export PlayerExtraStats (导出附加题库)
导出的 .csv 文件会放在 plugins/QuizzerBot/ 目录下，并与数据表名同名，如“QuizzerBook.csv”

导入: /quiz database import <表名>
导入前需要保证要导入的表格文件名和数据表名一模一样（区分大小写），并放在plugins/QuizzerBot/目录中。
危险操作警告：
导入时，插件会先清空数据库里原有的整张表，然后再把你 .csv 文件里的内容全部写进去！
这意味着任何在游戏里用指令添加的题目都会被覆盖！
操作前建议先备份 quizzerBook.db 文件！

3.4 答题流程概览

触发机制：
- 服务器启动后开始计时
- 在配置的随机时间间隔（默认60-70秒）后检查触发条件
- 满足最低玩家数要求后开始答题活动

题目展示：

[11:31:02 INFO]: [答题Bot] 答题时间到~
===========问题编号: 1================
   工作台需要几个木板合成?
   A: 2         B: 4         C: 5         D: 7
=======================================
[11:31:02 INFO]: 答案在10秒后揭晓，【点击选项】即可答题

作答方式：
- 点击聊天框中的选项
- 使用命令/quiz ans <选项>
抢答机制：
- 前N名回答的玩家标记为抢答（N可在配置中设置）
- 抢答成功后全服公告：
```
[11:32:37 INFO]: [答题Bot] yanhy2000 抢答成功！[1/3]
```

结果公布：

[11:32:41 INFO]: [答题Bot] 答案揭晓: 【B】! 
抢答正确: 1人, 普通回答正确: 0人, 共发放奖励: 1人

4. 配置详解

4.1 配置文件说明

quiz:
  # 配置文件版本，不要动
  conf_version: 1

  # (旧版配置，1.2.0+ 已移除语言文件，默认为 zh_CN)
  # language: zh

  # 触发聊天答题的最低在线玩家数
  min_players: 1

  # 答题触发间隔时间（秒），[最小值, 最大值]
  # 在这个范围内随机一个时间点触发
  trigger_interval_sec: [60, 120]

  # 聊天答题开始后，玩家有多长时间作答（秒）
  answer_reveal_delay_sec: 60

  # 答对后给的奖励指令，%player% 会被替换成玩家名
  reward_commands:
    - 'say %player% 在答题中获胜！'
    - 'give %player% diamond 1'

  # 每人每天最多从聊天答题中获取多少次奖励
  daily_reward_limit: 5

  # 每轮聊天答题，最多发多少份奖励
  player_reward_limit: 3

  # 每轮聊天答题，前多少个回答的玩家算作“抢答”
  # (答错了也算抢答名额)
  player_QuickAnswer_limit: 3

5. 数据库结构

5.1 题目表(QuizzerBook)

字段	类型	说明
id	INTEGER	自增主键
quiz	TEXT	题目内容（必填）
optA-optD	TEXT	选项内容（可空）
answer	TEXT	正确答案(A/B/C/D)
isEnable	BOOLEAN	是否启用（默认TRUE）
showCount	INTEGER	题目出现次数统计

5.2 玩家统计表(PlayerStats)

字段	类型	说明
uuid	TEXT	玩家唯一标识
username	TEXT	玩家名
total_attempts	INTEGER	总答题次数
correct_answers	INTEGER	答对次数
quick_answers	INTEGER	抢答成功次数
daily_rewards	INTEGER	当日获得奖励数
last_played_date	TEXT	最后参与日期(YYYY-MM-DD)

5.3 附加题目表(QuizzerBook)

字段	类型	说明
id	INTEGER	自增主键
type	TEXT	题目类型（必填）
quiz	TEXT	题目内容（必填）
optA-optD	TEXT	选项内容（可空）
answer	TEXT	正确答案(A/B/C/D)
isEnable	BOOLEAN	是否启用（默认TRUE）
showCount	INTEGER	题目出现次数统计

5.4 玩家附加统计表(PlayerStats)

字段	类型	说明
uuid	TEXT	玩家唯一标识
username	TEXT	玩家名
total_attempts	INTEGER	总答题次数
correct_answers	INTEGER	答对次数
last_played_date	TEXT	最后参与日期(YYYY-MM-DD)

6. 命令手册

权限：标有 (管理员) 的指令需要 OP 权限。

6.1 玩家命令

命令	说明
/quiz ans <答案>	提交“聊天答题”的答案 (A/B/C/D)
/quiz me	查看你自己的答题统计 (聊天答题)
/quiz query <玩家>	查看其他玩家的统计 (聊天答题)
/quiz top [类别]	查看聊天答题的排行榜 (类别: total, correct, quick, rewards)
/quiz dialog	(1.2.0+) 打开“图形界面答题”菜单

6.2 管理员命令 (通用)

命令	说明
/quiz reload	(管理员) 重载 config.yml 配置文件
/quiz reset <玩家>	(管理员) 重置指定玩家的所有答题数据 (包括聊天和图形界面)
/quiz help	(管理员) 显示帮助菜单

6.3 管理员命令 (经典聊天答题)

命令	说明
/quiz startnow	(管理员) 立即开始一轮聊天答题
/quiz stop	(管理员) 停止自动答题的调度器
/quiz enable <true/false>	(管理员) 启用或禁用自动答题调度器
/quiz add <问题> <正确答案>	(管理员) 添加一道聊天答题 (答案是A/B/C/D)
/quiz delete	(管理员) 删除指定 ID 的聊天题目
/quiz modify <字段> <新值>	(管理员) 修改聊天题目 (字段如: quiz, optA, answer...)
/quiz toggle <true/false>	(管理员) 启用或禁用一道聊天题目
/quiz list [页码]	(管理员) 列出所有聊天答题的题目
/quiz detail	(管理员) 查看聊天题目的详细信息

6.4 管理员命令 (图形界面答题)

命令	说明
/quiz extra add ...	(管理员) 添加题目到“图形界面”题库 (参数同上)
/quiz extra delete	(管理员) 删除“图形界面”题目
/quiz extra modify ...	(管理员) 修改“图形界面”题目
/quiz extra toggle ...	(管理员) 启用/禁用“图形界面”题目
/quiz extra list	(管理员) 列出所有“图形界面”题目
/quiz extra detail	(管理员) 查看“图形界面”题目详情

6.5 管理员命令 (数据库)

命令	说明
/quiz database export <表名>	(管理员) 导出数据表到 CSV (表名: questions 或 extra_questions)
/quiz database import <表名>	(管理员) (危险操作) 从 CSV 导入数据，覆盖原表

1.1.x 旧版本不包含 extra, database新指令。

7. 常见问题

7.1 答题未触发

检查min_players设置
确认题库中有启用状态的问题
查看日志是否有错误信息

7.2 题目管理

添加题目示例：

/quiz add 低版本中Minecraft中钻石在第几层最多？ 1-5 5-12 12-20 20+ b

可使用"-"作为空选项占位符

8. 注意事项

数据备份: 插件的数据库文件 quizzerBook.db 存着你所有的题目和玩家数据，建议定期备份
问题反馈: 遇到 Bug 或有啥好建议，欢迎联系 yanhy2000@foxmail.com

本Wiki文档随插件版本更新，最新版请以实际发布为准