📥 安装与依赖

环境要求

安装步骤

1. 将 AdventureQuests.jar 放入 plugins/
2. 重启服务器，生成默认配置
3. 在 quests/ 目录中创建任务配置文件
4. 执行 /aq reload 重载

文件结构

plugins/AdventureQuests/
├── config.yml          # 主配置
├── messages.yml        # 消息配置
├── quests/             # 任务配置目录
│   ├── main/           # 主线任务
│   ├── side/           # 支线任务
│   ├── daily/          # 每日任务
│   ├── weekly/         # 每周任务
│   └── event/          # 活动任务
└── data/               # 玩家数据

📋 任务类型

五大任务类型

任务生命周期

1. 可接取 — 满足前置条件，显示在 GUI 的"可接取"分类
2. 进行中 — 玩家已接取，显示在侧边栏追踪
3. 已完成 — 所有目标完成，自动发放奖励
4. 已过期 — 每日/每周任务到期自动重置

并发控制

# config.yml
max-concurrent-quests: 5  # 同时进行的最大任务数

🎯 目标类型

基础目标

剧情专用目标 v1.2+

📖 剧情系统

概览

剧情系统允许为任务配置丰富的故事体验，包括 NPC 沉浸式对话、阶段命令、通知提示、ActionBar 持续提示、NPC 发光引导等。

阶段 (Stage) 结构

每个任务由多个阶段组成，每个阶段包含一组目标和可选的命令/通知：

stages:
  stage1:
    start-commands:                    # 进入阶段时执行的命令
      - "playsound minecraft:... {player}"
      - "aq npcteam 29 aq_green {player}"
    start-notify:                      # 进入阶段时的通知
      type: TITLE
      title: "&6第一阶段"
      subtitle: "&e去和引导员对话"
    complete-notify:                   # 完成阶段时的通知
      type: BOSSBAR
      text: "&a阶段完成！"
      color: GREEN
      duration: 5
    complete-commands:                 # 完成阶段时执行的命令
      - "aq npcteam 29 aq_blue {player}"
    action-bar: "&e>>> 去和引导员对话 <<<"  # 持续显示的ActionBar
    objectives:
      obj1:
        type: TALK_TO_NPC
        npc-id: "29"
        amount: 1
        display: "&f与 {npc-name} &f对话"  # 支持 {npc-name} 占位符

NPC 发光引导

任务系统会自动管理 NPC 的发光颜色：

• 绿色发光 — 当前阶段需要与该 NPC 交互 (尚未完成)
• 蓝色发光 — 该 NPC 的目标已完成，或任务进行中但当前阶段不需要 NPC

使用 aq npcteam <npcId> <team> <player> 命令手动控制 NPC 发光颜色。

进行中对话 v1.9.3+

当任务进行中玩家再次点击 NPC 时，可以显示提醒对话：

stage2:
  in-progress-dialogue:
    npc-id: "29"
    npc-name: "&a&l引导员"
    lines:
      - "&7你还没有完成任务哦！"
      - "&7快去收集物资吧！"

💬 NPC 对话系统 v1.8+

概览

沉浸式 NPC 对话系统，支持失明/缓慢效果、NPC 发光、粒子效果、可点击的接受/拒绝按钮、距离自动退出等。

对话配置

objectives:
  obj1:
    type: TALK_TO_NPC
    npc-id: "29"                  # Citizens NPC 数字 ID
    amount: 1
    display: "&f与 {npc-name} &f对话"   # 侧边栏显示, {npc-name} 自动替换
    dialogue:
      npc-name: "&a&l引导员"       # NPC 名称 (带颜色代码)
      lines:                       # 对话内容 (逐行显示)
        - "&7欢迎来到冒险世界！"
        - "&7我是你的引导员。"
        - "&7接下来让我教你一些基础知识。"
      accept-text: "&a[接受]"      # 接受按钮文字
      reject-text: "&c[拒绝]"      # 拒绝按钮文字
      exit-distance: 5.0           # 超过此距离自动退出对话
      blindness: true              # 对话时给予失明效果
      slowness: true               # 对话时给予缓慢效果
      effect-duration: 200         # 效果持续时间 (tick)
      npc-glow: true               # NPC 是否发光
      npc-particle: "HAPPY_VILLAGER"  # NPC 头顶粒子效果

{npc-name} 占位符 v1.9.2.4+

在目标的 display 字段中使用 {npc-name} 占位符，系统会自动替换为对话配置中的 npc-name 值：

display: "&f与 {npc-name} &f对话"
# 如果 dialogue.npc-name 是 "&a&l引导员"
# 侧边栏显示: "与 引导员 对话" (带颜色)

解析优先级：目标自身的 dialogue → 同阶段其他目标的 dialogue → 阶段的 in-progress-dialogue

侧边栏颜色代码 FIXED v1.9.2.4

目标 display 字段中的颜色代码 (如 &f &b &a&l) 现在会正确显示在侧边栏中。

操作方式

⚡ 自动触发系统 v1.6+

触发类型

配置示例

# 首次加入触发
trigger:
  type: FIRST_JOIN
  delay: 40              # 延迟 40 tick (2秒) 后触发

# 完成前置任务后触发 (任务链)
trigger:
  type: QUEST_COMPLETE
  quest-id: "newbie_welcome"
  delay: 200             # 延迟 200 tick (10秒) 后触发

# 拥有权限时触发
trigger:
  type: PERMISSION
  permission: "group.vip"
  delay: 40

任务链

通过 QUEST_COMPLETE 类型可以创建任务链，玩家完成前一个任务后自动触发下一个：

# 任务1: newbie_welcome (首次加入自动触发)
# 任务2: newbie_survival (完成任务1后自动触发)
# 任务3: newbie_dominion (完成任务2后自动触发)

🔀 条件系统

概览

条件系统用于控制任务的接取、显示和自动触发。支持多条件 AND/OR 组合。

条件类型

条件格式 (conditions 列表)

conditions:
  - "permission:vip.quest"        # 拥有权限
  - "!permission:banned.quest"    # 没有权限 (反向)
  - "level:10"                    # 等级 >= 10
  - "quest_completed:quest_01"    # 已完成任务
  - "npc_favor:29:5"              # NPC 29 好感度 >= 5
  - "quest_points:100"            # 任务积分 >= 100
  - "item_amount:DIAMOND:5"       # 背包钻石 >= 5
  - "server:survival"             # 当前在 survival 服

🖥️ GUI 界面

任务面板

玩家执行 /quests 打开任务面板 GUI，分类浏览：

• 可接取 — 满足条件但未接取的任务
• 进行中 — 当前正在进行的任务及进度
• 已完成 — 历史完成记录

GUI 配置

# config.yml
gui:
  enabled: true
  title: "&6&l任务面板"
  rows: 6
  fill-item: BLACK_STAINED_GLASS_PANE

操作

📊 侧边栏追踪

功能

使用 Scoreboard 在屏幕右侧实时显示当前追踪的任务名称和目标进度。主线任务优先显示。

显示格式

✦ 任务追踪
                              
§c§l[主线] §6新手教程
§8▪ §7与 §a§l引导员 §7对话 §f0/1
§8▪ §7收集煤炭 §f0/10
§a✔ §a砍伐原木 §f10/10
§8---
§7/quests sidebar §8切换

颜色代码支持 v1.9.2.4+

目标 display 中的颜色代码 (&f &b &a&l) 现在正确渲染在侧边栏中。之前版本会错误地去除所有颜色。

{npc-name} 占位符

使用 {npc-name} 占位符自动从对话配置获取 NPC 名称，避免手动重复输入：

display: "&f与 {npc-name} &f对话"
# 自动替换为 dialogue.npc-name 的值

配置

# config.yml
sidebar:
  enabled: true
  update-ticks: 20        # 更新频率 (tick)

命令

🔔 通知系统

通知类型

通知触发时机

配置示例

# 任务级通知
accept-notify:                     # 接取任务时的通知
  type: TITLE
  title: "&6新任务！"
  subtitle: "&e{quest}"
  fade-in: 10
  stay: 60
  fade-out: 20

accept-notify: false               # 禁用接取通知 (静默接取)

finished-notify:                   # 任务完成通知
  type: BOSSBAR
  text: "&a&l任务完成！"
  color: GREEN
  style: SOLID
  duration: 5

finished-notify: false             # 禁用完成通知

# 阶段级通知
stages:
  stage1:
    start-notify:                  # 进入阶段时
      type: TITLE
      title: "&e第一阶段"
      subtitle: "&7去和引导员对话"
    start-notify: false            # 禁用该阶段的开始通知
    complete-notify:               # 完成阶段时
      type: BOSSBAR
      text: "&a阶段完成！"
      color: GREEN
      duration: 5
    complete-notify: false         # 禁用该阶段的完成通知

禁用通知 v1.9.2.3+

将通知配置设为 false 可完全禁用该通知，适合自动触发的主线任务链 (避免弹出烦人的接取提示)：

accept-notify: false    # 静默接取, 不弹出任何提示
finished-notify: false  # 静默完成

默认通知

如果任务没有配置 accept-notify，默认使用 messages.yml 中的 quest-accepted 消息。

🌐 跨服同步 v1.4+

概览

通过 BungeeCord/Velocity Plugin Messaging Channel 实现多服务器间的任务数据实时同步。需要 MySQL 数据库作为共享存储。

同步协议

配置

# config.yml
database:
  type: mysql              # 必须使用 mysql (跨服共享数据)
  mysql:
    host: localhost
    port: 3306
    database: adventurequests
    username: root
    password: "your_password"
    table-prefix: "aq_"

cross-server:
  enabled: true            # 启用跨服同步
  server-name: "lobby"     # 当前服务器名称 (每个服不同!)

跨服目标指定

可以指定目标必须在哪个子服完成：

objectives:
  obj1:
    type: COLLECT_ITEM
    target: COAL
    amount: 10
    require-server: "resource"  # 只在资源服检测该目标

玩家切服流程 v1.9.2.4

1. 玩家在服务器 A 完成操作 → 写入数据库 + 广播消息
2. 服务器 B 收到消息 → 清除缓存 + 刷新侧边栏
3. 玩家切到服务器 B → 加入时再次刷新缓存 (延迟 3s + 5s 双重保险)
4. COLLECT_ITEM 有 5 秒保护期，防止 HuskSync 未同步背包时覆盖进度

🧭 路径引导

功能

为 REACH_LOCATION 和 TALK_TO_NPC 类型的目标提供粒子路径引导，帮助玩家找到目标位置。

配置

# 任务目标中配置
objectives:
  obj1:
    type: REACH_LOCATION
    target: "world,100,64,200,5"
    amount: 1
    guide:
      enabled: true
      world: "world"
      x: 100
      y: 64
      z: 200
      radius: 5
      arrival-notify:
        type: TITLE
        title: "&a到达目的地！"
      arrival-sound: "entity.player.levelup"

❤️ NPC 好感度系统 v2.0+

概览

NPC 好感度系统为每个玩家追踪其对每个 NPC 的好感度值。好感度会在对话接受和任务完成时自动增长，也可通过管理员命令手动管理。好感度可用作任务接取条件，实现解锁更高级任务的机制。

自动给予

好感度和积分会在以下时机自动给予（可在 config.yml 中配置或关闭）：

设为 false 或 0 可关闭对应的自动给予。

config.yml 配置

npc-favor:
  dialogue-favor: 1       # 对话同意后给予好感度 (0或false关闭)
  dialogue-points: 5      # 对话同意后给予积分
  complete-favor: 1       # 任务完成后给予好感度
  complete-points: 5      # 任务完成后给予积分

管理员命令

任务条件

可以在任务或目标的 conditions 中使用好感度和积分作为前置条件：

conditions:
  - "npc_favor:29:5"      # 对NPC 29的好感度 >= 5
  - "quest_points:100"    # 任务积分 >= 100

PlaceholderAPI 变量

数据存储

• 文件存储 — 保存在 playerdata.yml 的 npc-favor 节
• 数据库存储 — 保存在 aq_npc_favor 表 (uuid, npc_id, favor)

⚙️ config.yml 主配置

核心设置

# config.yml
max-concurrent-quests: 5     # 同时进行的最大任务数
broadcast:
  enabled: true
  types: [MAIN]

gui:
  enabled: true

sidebar:
  update-ticks: 20

language: zh_CN               # 语言

数据库

database:
  type: sqlite                # sqlite / mysql
  mysql:
    host: localhost
    port: 3306
    database: adventurequests
    username: root
    password: ""
    table-prefix: "aq_"

跨服同步

cross-server:
  enabled: false
  sync-interval: 60           # 同步间隔 (秒)

📝 任务配置文件详解

文件位置

plugins/AdventureQuests/quests/
├── main/     # 主线任务 (type: MAIN, 不可取消)
├── side/     # 支线任务 (type: SIDE, 可取消)
├── daily/    # 每日任务 (type: DAILY, 自动重置)
├── weekly/   # 每周任务 (type: WEEKLY, 自动重置)
└── event/    # 活动任务 (type: EVENT, 管理员控制)

完整配置示例

# quests/main/newbie_welcome.yml
# ==========================================
# 任务基本信息
# ==========================================
id: newbie_welcome
type: MAIN                    # MAIN / SIDE / DAILY / WEEKLY / EVENT
display-name: "&6&l第一章 &e欢迎来到冒险世界"
description:
  - "&7欢迎来到冒险世界！"
  - "&7和引导员对话开始你的冒险之旅。"
icon: BOOK

# ==========================================
# 自动触发 (可选)
# ==========================================
trigger:
  type: FIRST_JOIN            # FIRST_JOIN / LOGIN / PERMISSION / QUEST_COMPLETE
  delay: 40                   # 延迟 tick (20=1秒)
  # quest-id: "前置任务ID"    # QUEST_COMPLETE 类型专用
  # permission: "perm.node"   # PERMISSION 类型专用

# ==========================================
# 通知配置 (可选, 设为 false 禁用)
# ==========================================
accept-notify: false           # 静默接取, 不弹提示
# accept-notify:
#   type: TITLE
#   title: "&6新任务！"
#   subtitle: "&e{quest}"

finished-notify:
  type: TITLE
  title: "&a&l任务完成！"
  subtitle: "&e恭喜完成第一章"

# ==========================================
# 完成奖励
# ==========================================
rewards:
  commands:
    - "eco give {player} 100"
    - "xp add {player} 50"
  messages:
    - "&a&l恭喜完成新手教程！奖励已发放。"

# ==========================================
# 任务阶段
# ==========================================
stages:
  stage1:
    start-commands:
      - "playsound minecraft:block.note_block.pling master {player}"
      - "aq npcteam 29 aq_green {player}"
    start-notify:
      type: TITLE
      title: "&6欢迎！"
      subtitle: "&e前去与引导员对话"
    action-bar: "&e&l>>> &f前往 &a引导员 &f处开始冒险 &e&l<<<"
    objectives:
      obj1:
        type: TALK_TO_NPC
        npc-id: "29"
        amount: 1
        display: "&f与 {npc-name} &f对话"   # {npc-name} 自动替换
        dialogue:
          npc-name: "&a&l引导员"
          lines:
            - "&7欢迎来到冒险世界！"
            - "&7我是你的引导员。"
            - "&7接下来去完成一些基础任务吧！"
          accept-text: "&a[好的，我准备好了]"
          reject-text: "&c[等一下...]"
          exit-distance: 5.0
          blindness: true
          slowness: true
          effect-duration: 200
          npc-glow: true
          npc-particle: "HAPPY_VILLAGER"

  stage2:
    start-notify:
      type: BOSSBAR
      text: "&6&l收集物资！&7按Shift+F打开菜单选择资源服"
      color: YELLOW
      style: SEGMENTED_10
      duration: 30
    complete-commands:
      - "aq npcteam 29 aq_blue {player}"
    in-progress-dialogue:       # 进行中再次点NPC时的提醒对话
      npc-id: "29"
      npc-name: "&a&l引导员"
      lines:
        - "&7你还没收集完物资哦！"
        - "&7按Shift+F去资源服吧！"
    objectives:
      obj1:
        type: COLLECT_ITEM
        target: COAL
        amount: 10
        display: "&f收集煤炭"
        require-server: "resource"  # 仅在资源服检测
      obj2:
        type: COLLECT_ITEM
        target: "*_LOG"             # 通配符: 任意原木
        amount: 10
        display: "&f收集任意原木"

目标字段参考

COLLECT_ITEM 通配符 v1.8+

target 支持通配符，以 * 开头匹配材料名后缀：

target: "*_LOG"       # 任意原木 (OAK_LOG, BIRCH_LOG, ...)
target: "*_PLANKS"    # 任意木板
target: "COAL"        # 精确匹配

⌨️ 命令列表

玩家命令

管理员命令

🔐 权限节点

🔗 PlaceholderAPI 变量

📝 更新日志

v2.0.1 LATEST

• FIX Shift+F 菜单冲突修复 — 仅在玩家有 PLAYER_SWAP_HAND 目标且条件满足时拦截事件，否则放行给 TrMenu 等菜单插件；任务完成后 Shift+F 立即恢复正常
• FIX 跨服进度同步 — advanceStoryObjective 推进后立即广播 broadcastProgressUpdate；玩家下线/跳服时保存所有活跃任务进度并广播 REFRESH
• IMPROVED 默认配置更新 — config.yml 启用数据库+跨服同步；messages.yml / guide.yml 更新为最新自定义版本；newbie.yml 旧任务迁移至 quests.yml

v2.0.0

• NEW NPC 好感度系统 — 每个玩家对每个 NPC 独立追踪好感度值，支持文件/数据库持久化
• NEW 好感度自动给予 — 对话接受/任务完成时自动增加好感度和积分 (config.yml npc-favor 节)
• NEW /aq favor 管理命令 — add/take/set/check 四种操作，含 Tab 补全
• NEW PAPI 好感度变量 — %adventurequests_favor_<npcId>%、favor_total、favor_list
• NEW npc_favor / quest_points 条件 — 任务/目标条件支持好感度和积分检查
• NEW 进度变量扩展 — 进度显示/Title 支持 {0}=当前 {1}=目标 {2}=target {3}=任务名
• IMPROVED 货币文案统一 — Vault 经济显示为"银币"，全部 UI/消息/编辑器已同步更新

v1.9.2.4

• FIX Shift+F 兼容修复 — 延迟处理 PLAYER_SWAP_HAND 到下一 tick，避免干扰 TrMenu 等菜单插件
• FIX 跨服侧边栏同步 — giveQuest 时广播 QUEST_START 通知其他服务器；玩家切服时双重延迟刷新缓存 (3s+5s)
• NEW {npc-name} 占位符 — 目标 display 支持 {npc-name}，自动从对话配置获取 NPC 名称
• FIX 侧边栏颜色代码 — display 中的 &f &b &a&l 等颜色代码现在正确显示，不再被错误去除
• IMPROVED 智能截断 — 侧边栏文本按纯文本长度截断，保留颜色代码前缀

v1.9.2.3

• NEW per-quest accept-notify — 每个任务可自定义接取通知，设为 false 可完全禁用
• NEW per-stage start/complete-notify: false — 阶段级通知可单独禁用
• NEW finished-notify: false — 任务完成通知可禁用
• FIX NPC 发光恢复 — 对话退出/拒绝后正确恢复绿色发光；接受后延迟刷新蓝色发光
• NEW NotifyType.NONE — 支持 false 值禁用各级通知

v1.9.2.2

• FIX 跨服缓存刷新 — 玩家加入时立即从数据库刷新缓存，延迟更新侧边栏
• FIX PLAYER_SWAP_HAND ignoreCancelled — 设为 false 确保即使其他插件取消事件，AQ 仍可追踪
• IMPROVED NPC 发光扫描 — 非 NPC 目标阶段时扫描所有阶段的 NPC 并设蓝色发光
• NEW QUEST_COMPLETE 登录检查 — 玩家登录时也检查任务链触发，防止重启丢失

v1.9.1

• NEW COLLECT_ITEM 高水位标记 — 进度只升不降，防止切服时背包为空导致清零
• NEW 跨服保护期 — 玩家加入后 5 秒内不扫描 COLLECT_ITEM，等待 HuskSync 同步背包
• IMPROVED reload 刷新 serverName — CrossServerSync 和 DatabaseStorage 均刷新服务器名

v1.9

• NEW 进度显示管理器 — BOSSBAR/ACTIONBAR/MESSAGE 实时进度提示
• NEW 进度 Title 提示 — 每次进度变化时弹出 Title (支持 {progress} {goal})
• NEW PROGRESS_UPDATE 广播 — 跨服进度实时同步

v1.8

• NEW NPC 沉浸式对话系统 — 失明/缓慢效果、NPC 发光、粒子、距离退出、接受/拒绝按钮
• NEW COLLECT_ITEM 通配符 — 支持 *_LOG、*_PLANKS 等通配符匹配
• NEW 进行中 NPC 对话 — in-progress-dialogue 配置
• IMPROVED FIRST_JOIN 触发改进 — 不再依赖 hasPlayedBefore()，支持已有玩家

v1.7

• NEW 路径引导系统 — 粒子路径引导玩家前往目标位置
• NEW 每日/每周追踪器 — DailyWeeklyTracker 自动管理重置
• IMPROVED 侧边栏性能 — 优化更新频率和渲染逻辑

v1.6

• NEW NPC ID 匹配 — 支持 Citizens NPC 数字 ID 精确匹配
• NEW 自动触发系统 — FIRST_JOIN / LOGIN / PERMISSION / QUEST_COMPLETE 四种触发方式
• NEW 通知系统重构 — 支持 TITLE/MESSAGE/BOSSBAR 三种类型

v1.4

• NEW 跨服数据同步 — MySQL + Plugin Messaging Channel
• NEW require-server — 目标跨服指定

v1.2

• NEW 剧情专用目标 — 19 种新目标类型 (跳跃/潜行/交换手/聊天/命令/死亡/...)
• NEW 阶段条件/命令 — start-commands / complete-commands / conditions

v1.0

• NEW 初始版本 — 主线/支线/每日/每周任务、GUI、侧边栏、基础目标类型