348 lines
8.6 KiB
Markdown
348 lines
8.6 KiB
Markdown
# 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` 中版本号已递增。
|