# AuQuestEngine

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

当前插件版本：`1.0.6`

## 1. 功能概览

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

## 2. 运行环境

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

前置插件：

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

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

## 3. 安装方式

构建插件：

```bash
mvn package
```

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

```text
plugins/AuQuestEngine-1.0-SNAPSHOT.jar
```

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

```text
plugins/AuQuestEngine/Quests/
```

## 4. 配置文件

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

```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`。

示例：

```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. 任务类型

常用任务类型：

```text
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. 玩家命令

查看任务信息：

```text
/aquest info
```

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

```text
/aquest info <玩家名>
```

给玩家发放任务：

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

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

```text
/aquest direc <任务ID>
```

## 8. 管理命令

管理命令需要权限：

```text
admin.use
```

重载配置、语言和任务：

```text
/aquestadmin reload
```

开关调试输出：

```text
/aquestadmin debug
```

清空指定玩家任务数据：

```text
/aquestadmin clear <玩家名>
```

SQLite 数据导出为 YAML：

```text
/aquestadmin outsqlite
```

## 9. PlaceholderAPI 变量

插件标识：

```text
aquest
```

任务名称：

```text
%aquest_quest_<任务ID>_name%
```

任务是否完成：

```text
%aquest_quest_<任务ID>_completed%
```

任务总进度：

```text
%aquest_quest_<任务ID>_progress%
```

指定任务目标进度：

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

示例：

```text
%aquest_quest_quest_1_name%
%aquest_quest_quest_1_progress%
%aquest_task_quest_1_id_1%
```

## 10. API 调用

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

```java
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` 中版本号已递增。