AuQuestEngine

AuQuestEngine 是一个面向 Paper / Spigot 服务端的任务系统插件，用于通过配置文件定义任务、任务目标、接取条件、完成提示和奖励命令。

当前插件版本：1.0.6

1. 功能概览

• 支持每日、每周、每月、长期任务。
• 支持 YAML、SQLite、MySQL 三种玩家任务数据存储方式。
• 支持任务接取条件：玩家等级、前置已完成任务、指定世界。
• 支持多种 Bukkit 事件任务目标，例如破坏方块、放置方块、合成、拾取、击杀、钓鱼、村民交易、打开菜单等。
• 支持 PlaceholderAPI 变量。
• 支持 Citizens、MythicMobs、CustomFishing、CustomCrops 等前置插件的扩展任务监听。
• 支持任务完成后执行控制台奖励命令。

2. 运行环境

Java: 21
服务端: Paper 1.21.11
构建工具: Maven

前置插件：

softdepend:
  - Citizens
  - MythicMobs
  - PlaceholderAPI
  - CustomFishing
  - CustomCrops

这些前置不是全部必装。未安装对应插件时，相关任务监听器不会注册。

3. 安装方式

构建插件：

mvn package

构建完成后，将生成的插件包放入服务端：

plugins/AuQuestEngine-1.0-SNAPSHOT.jar

启动服务端后，插件会生成基础配置文件。任务文件需要放在：

plugins/AuQuestEngine/Quests/

4. 配置文件

config.yml 用于配置存储方式和部分任务类型识别列表。

Storage:
  Type: yaml # yaml / sqlite / mysql
  SQLite:
    File: PlayerData.db
  SaveInterval: 10
  MySQL:
    Host: localhost
    Port: 3306
    Database: quest
    Username: root
    Password: root
    TablePrefix: AuQuest_
    Pool:
      MaximumPoolSize: 10
      MinimumIdle: 2
      ConnectionTimeout: 10000
      IdleTimeout: 600000
      MaxLifetime: 1800000

存储说明：

• yaml：玩家数据保存为单独 YAML 文件，适合小型服务器。
• sqlite：玩家数据保存到本地 SQLite 数据库。
• mysql：玩家数据保存到 MySQL，适合多实例或长期运营环境。

插件包已包含 SQLite JDBC、MySQL Connector/J 和 HikariCP。

5. 任务文件格式

任务文件可以放在 plugins/AuQuestEngine/Quests/ 目录下，文件名不限，后缀必须是 .yml。

示例：

quest_1:
  display_name: "&a[初级] 新手成长之路"
  description:
    - "&7完成基础生存挑战任务"
    - "&7砍伐指定木材，熟悉资源收集"
  type: DAILY
  messages:
    receive:
      - "&a你接受了任务：&f新手成长之路"
    complete:
      - "&a任务完成：&f新手成长之路"
      - "&7奖励已发放，请继续成长。"
  conditions:
    level: 0
    completed_quests: []
    worlds: []
  tasks:
    id_1:
      type: BREAK_BLOCK
      display_name: "砍伐云杉木 * 128"
      amount: 128
      targets:
        - SPRUCE_LOG
        - SPRUCE_WOOD
        - STRIPPED_SPRUCE_LOG
        - STRIPPED_SPRUCE_WOOD
  rewards:
    commands:
      - "dlevel give %player% 12000"
      - "points give %player% 5"
    messages:
      - "&a{name} 任务已完成"

字段说明：

• display_name：任务显示名称。
• description：任务描述。
• type：任务类型，可用 DAILY、WEEKLY、MONTHLY、FIXED。
• messages.receive：接取任务后发送给玩家的消息。
• messages.complete：完成任务后发送给玩家的消息。
• conditions.level：最低等级要求。
• conditions.completed_quests：前置已完成任务 ID 列表。
• conditions.worlds：允许推进任务的世界列表，留空表示不限制。
• tasks：任务目标列表。
• rewards.commands：完成后由控制台执行的命令，使用 %player% 替换玩家名。
• rewards.messages：奖励提示，支持 {name} 替换任务名称。

6. 任务类型

常用任务类型：

BREAK_BLOCK          破坏方块
PLACE_BLOCK          放置方块
CRAFT_ITEM           合成物品
PICKUP_ITEM          拾取物品
FISH_ITEM            钓鱼获得物品
FISH_STAR            钓起鱼的星级
PLACE_BUCKET         倒水、倒岩浆、放置粉雪
FILL_BUCKET          装水、装岩浆、装牛奶
HARVEST_CROP         收获农作物
EXP_GAIN             获取经验
BREED                繁殖动物
COLLECT_ENTITY       剪羊毛、取蘑菇煲
COLLECT_BLOCK        收集蜂蜜
TAME_ENTITY          驯服实体
VILLAGER_TRADE_ITEM  村民交易物品
VILLAGER_TRADE_JOB   村民职业交易
BREW_POTION          酿造药水
BREW_POTION_COUNT    酿造药水次数
USE_ANVIL            使用铁砧
ENCHANT_ITEM         附魔物品
FEED_ANIMAL          喂动物
FEED_PLAYER          玩家食用物品
SMELT_ORE            烧制矿物
SMELT_FOOD           烧制食物
INTERACT_NPC         交互 Citizens NPC
INTERACT_ENTITY      交互实体
INTERACT_ITEM        交互手持物品
SEND_COMMAND         发送命令
SEND_CHAT            发送聊天
OPEN_GUI_TITLE       打开指定标题菜单
OPEN_GUI_TYPE        打开指定类型菜单
KILL_TYPE            击杀原版实体
KILL_MYTHIC          击杀 MythicMobs 实体

预留类型存在于枚举中，但未必已有完整监听实现。配置任务前应确认对应监听器已实现。

7. 玩家命令

查看任务信息：

/aquest info

管理员查看指定在线玩家任务信息：

/aquest info <玩家名>

给玩家发放任务：

/aquest js <任务ID> <玩家名>

OP 玩家直接完成自身任务：

/aquest direc <任务ID>

8. 管理命令

管理命令需要权限：

admin.use

重载配置、语言和任务：

/aquestadmin reload

开关调试输出：

/aquestadmin debug

清空指定玩家任务数据：

/aquestadmin clear <玩家名>

SQLite 数据导出为 YAML：

/aquestadmin outsqlite

9. PlaceholderAPI 变量

插件标识：

aquest

任务名称：

%aquest_quest_<任务ID>_name%

任务是否完成：

%aquest_quest_<任务ID>_completed%

任务总进度：

%aquest_quest_<任务ID>_progress%

指定任务目标进度：

%aquest_task_<任务ID>_<任务目标ID>%

示例：

%aquest_quest_quest_1_name%
%aquest_quest_quest_1_progress%
%aquest_task_quest_1_id_1%

10. API 调用

其他插件可以通过 AuQuestAPI 查询或操作玩家任务。

UUID uuid = player.getUniqueId();

boolean started = AuQuestAPI.startQuest(uuid, "quest_1");
boolean completed = AuQuestAPI.hasCompletedQuest(uuid, "quest_1");
boolean active = AuQuestAPI.hasActiveQuest(uuid, "quest_1");

List<String> activeQuests = AuQuestAPI.getActiveQuests(uuid);
List<String> completedQuests = AuQuestAPI.getCompletedQuests(uuid);

AuQuestAPI.directCompleteQuest(uuid, "quest_1");
AuQuestAPI.abandonQuest(uuid, "quest_1");

常用方法：

• getQuestDisplayName(String questId)
• getQuestDescription(String questId)
• getQuestType(String questId)
• hasCompletedQuest(UUID uuid, String questId)
• hasActiveQuest(UUID uuid, String questId)
• getActiveQuests(UUID uuid)
• getCompletedQuests(UUID uuid)
• startQuest(UUID uuid, String questId)
• abandonQuest(UUID uuid, String questId)
• directCompleteQuest(UUID uuid, String questId)

11. 自动刷新规则

任务刷新按任务类型处理：

• DAILY：每日 00:00 后刷新。
• WEEKLY：每周一 00:00 后刷新。
• MONTHLY：每月 1 日 00:00 后刷新。
• FIXED：长期任务，不参与周期刷新。

刷新时会清理对应类型任务的历史进度，并同步在线玩家缓存。

12. 使用流程

1. 将插件 jar 放入服务端 plugins 目录。
2. 启动服务端生成配置文件。
3. 根据需要选择 yaml、sqlite 或 mysql 存储。
4. 在 plugins/AuQuestEngine/Quests/ 下创建任务配置文件。
5. 执行 /aquestadmin reload 重载任务。
6. 使用 /aquest js <任务ID> <玩家名> 给玩家发放任务。
7. 玩家完成目标后自动累计进度。
8. 任务完成后自动发送完成消息并执行奖励命令。

13. 注意事项

• 修改任务文件后需要执行 /aquestadmin reload。
• 数据库模式切换前应先备份旧数据。
• MySQL 模式需要确认数据库、账号和权限正确。
• CustomFishing、CustomCrops、Citizens、MythicMobs 未安装时，对应任务类型不会生效。
• 任务目标 targets 必须与监听器传入的目标字符串一致，原版方块和物品通常使用 Bukkit 枚举名。
• 任务奖励命令由控制台执行，配置前应确认命令不会被重复领取滥用。
• 发布新版本前应确认 plugin.yml 中版本号已递增。