添加README.md

README.md

@@ -0,0 +1,347 @@
+# 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` 中版本号已递增。