📥 安装与目录

环境要求

依赖插件

安装步骤

1. 放入 AdventureTask-1.1.0.jar
2. 重启服务器
3. 编辑配置文件
4. /ataskadmin reload

目录结构

plugins/AdventureTask/
├── config.yml          # 核心配置
├── gui.yml             # GUI 自定义
├── messages.yml        # 消息文本
├── tasks.yml           # 任务池模板
├── Translations/
│   ├── items_CN.yml    # 660+ 物品中文
│   └── entities_CN.yml # 100+ 实体中文
└── data/
    └── adventuretask.db

📋 每日任务

每天 00:00 (北京时间) 自动重置，从任务池按权重随机抽取。

• 默认每人每天 5 个任务
• VIP 权限增加额外 +1~+5 槽位
• 支持有序多步骤（需按顺序完成）
• 冻结/延迟的任务在重置时保留

任务池配置 (tasks.yml)

tasks:
  mine_stone:
    name: "§f采集石头"
    description: "§7在世界中挖掘64个石头"
    icon: STONE
    weight: 20              # 越大越容易被抽到
    activity-reward: 10     # 完成获得活跃度
    objectives:
      - type: BREAK_BLOCK
        target: STONE
        amount: 64
    rewards:
      - type: MONEY
        amount: 100
      - type: TASK_COIN
        amount: 5

🎯 目标类型 (51 种)

8 大类，所有类型用于 tasks.yml 的 objectives[].type。

基础资源类 (12)

战斗类 (8)

生活/动物类 (7)

工作台类 (6)

移动/探索类 (7)

数值/状态类 (3) + 交互类 (4) + 通用 (1)

🎁 奖励与活跃度

奖励类型 (7 种)

活跃度系统

完成任务累积活跃度，每周自动重置。达门槛领取阶梯奖励。

• 每任务默认 +10 活跃度（tasks.yml 可自定义）
• 每周上限约 700 (10 任务 × 10 点 × 7 天)
• 阶梯奖励在 config.yml → activity-rewards 配置

🃏 4 种任务卡

卡片配置 v1.1.0

cards:
  reset:
    material: PAPER
    custom-model-data: 0
    name: "§e任务重置卡"
    lore:
      - "§7类型: §eRESET"
      - "§7替换当前任务为新的随机任务"
  exempt:
    material: PAPER
    name: "§b任务豁免卡"
  freeze:
    material: PAPER
    name: "§9任务冷却卡"
  delay:
    material: PAPER
    name: "§d任务延迟卡"

匹配逻辑：material + ChatColor.stripColor(displayName) 同时匹配。

卡片选择 GUI

在任务中心右键进行中任务打开 27 格选择界面：

• 卡片数量以堆叠数显示 (1~127)
• 最后一行：[点击对任务 "xxx" 使用此卡]
• 无库存卡显示灰色玻璃板

发放命令

/ataskadmin givecard <玩家> <RESET|EXEMPT|FREEZE|DELAY> [数量]
# 背包满时自动掉落

🖥️ GUI 系统

任务中心 GUI

54 格界面，/atask 打开：

行0: # # # # # # # # #
行1: # a # 1 2 3 4 5 #      a=每日任务 Tab
行2: # b # 6 7 8 9 A #      b=主线任务 Tab
行3: # c # B C D E F #      c=支线任务 Tab
行4: # d # G H I J K #      d=任务奖励中心 Tab
行5: ← # # @ $ # # # →      @=信息 $=商城

• 4 个 Tab：每日 / 主线 / 支线 / 奖励中心
• 20 个任务槽 (4×5)
• 底部：信息、商城入口、翻页

GUI 100% 自定义

音效反馈

# 格式: 音效名:音量:音调
click-sound: "UI_BUTTON_CLICK:1.0:1.0"
right-click-sound: "BLOCK_NOTE_BLOCK_PLING:1.0:2.0"
click-sound: false    # 关闭

通知系统 v1.1.0

4 种通知事件，每种支持 message / title / sound 三选：

分页系统

• 下一页 (slot 53)：有更多内容时显示
• 上一页 (slot 45)：第 2 页起显示

CraftEngine 支持

material: "ce:myplugin:task_icon"

🛒 任务币商城

完成任务获得任务币，在商城兑换物品。

• 商品在 config.yml → shop 配置
• 4 种限购：每日 / 每周 / 总限购 / 全服限购
• 购买后执行命令（支持 {player}）
• 独立 54 格 GUI，28 个商品槽

⌨️ 命令与权限

玩家命令

管理命令

权限节点

⚙️ 配置文件

config.yml

daily-task-count: 5
timezone: "Asia/Shanghai"
progress-display: "BOSSBAR"
reset-card-daily-limit: 5
delay-card-hours: 12
activity-reset: "WEEKLY"

database:
  type: sqlite    # sqlite / mysql

通知配置 v1.1.0

notifications:
  daily-assigned:
    message: "{prefix}§a今日任务已刷新! 共 §e{count} §a个任务!"
    title: "§6§l每日任务|§e共 {count} 个任务|10|40|10"
    sound: "ENTITY_PLAYER_LEVELUP:0.6:1.5"
  progress-complete:
    message: "{prefix}§a{task_name} §7已完成!"
    title: "§6§l任务完成!|§e{task_name}|10|40|10"
    sound: "ENTITY_PLAYER_LEVELUP:0.8:1.2"

gui.yml v1.1.0

包含：task-center / task-status-* / card-select / shop / activity-reward

card-select:
  card-reset:
    material: SUNFLOWER
    name: "§e任务重置卡"
    lore:
      - "§7当前持有: §e{count} 张"
      - "§a[点击对任务 \"{task_name}\" 使用此卡]"
    click-sound: "BLOCK_NOTE_BLOCK_PLING:1.0:1.5"

messages.yml

支持 & 颜色码、&#RRGGBB Hex、{prefix} {player} {task_name} 等。

内置变量

PlaceholderAPI

🔗 插件集成

AdventureQuests 集成

安装后任务中心自动显示：

• 主线任务 Tab — 进行中的主线列表
• 支线任务 Tab — 进行中的支线列表
• 信息预览物品中显示主线/支线进度

中文命名系统 v1.1.0

• 内置 660+ 物品/方块中文翻译 (items_CN.yml)
• 内置 100+ 实体中文翻译 (entities_CN.yml)
• 优先使用 jar 内置资源，外部文件可覆盖
• 进度全中文化：如 "击杀 僵尸 0/15"

数据存储

自动保存间隔 5 分钟（异步）。存储：任务分配/进度/状态、活跃度、任务币、购买记录。

⚡ 性能优化

三级缓存架构

TaskManager → L1 本地内存 → L2 Redis → L3 MySQL
                ↓ dirty
          异步批量刷盘 + Redis Pub/Sub 跨服失效

• 读：缓存优先，miss 时加载并缓存
• 写：标记脏数据入队，定时批量刷盘
• TTL：离线数据自动淘汰
• 关服：同步刷盘零丢失

分批重置

批次1: 玩家1~10 → 处理 → 等待2tick
批次2: 玩家11~20 → 处理 → 等待2tick
...
# 200人: 从~500ms阻塞 → 分散~2秒, 单次<25ms

世界校验 (WorldValidator)

1. 全局白名单 — 空列表=不限制
2. 世界组 — 同组视为等价
3. 任务级 — objectives[].world 精确限制

限流器 (RateLimiter)

完整配置参考

optimization:
  cache:
    ttl-seconds: 300
    flush-interval-seconds: 30
    batch-size: 20
  reset-batch-size: 10
  reset-batch-delay-ticks: 2
  world-validation:
    enabled: false
    whitelist: []
    groups: {}
  rate-limit:
    objective-cooldown-ms: 50
    gui-open-cooldown-ms: 500

🌐 Redis 跨服部署

前提

• Velocity 代理群组
• Redis 实例
• 所有子服连同一个 MySQL（SQLite 不支持跨服）

数据流

配置

database:
  type: mysql
  mysql:
    host: 127.0.0.1
    port: 3306
    database: adventure_task
    username: root
    password: "your_password"

redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: ""
  database: 0
  pool-size: 8
  ttl-seconds: 600

Pub/Sub

• 频道：adventuretask:invalidate
• 消息：玩家 UUID
• 断线：自动 5 秒重连

降级策略

部署步骤

1. 安装 Redis
2. 配置 MySQL，所有子服同库
3. 每个子服放入 jar，配 database.type: mysql + redis.enabled: true
4. 重启检查日志
5. /ataskadmin stats 验证

未来路线

• 分布式锁 (Redis + Lua)
• 任务预生成
• 活跃度增量更新
• 智能缓存 TTL

📝 更新日志

v1.1.0 最新

• NEW 中文命名系统 — 660+ 物品 + 100+ 实体翻译，进度全中文化
• NEW 卡牌可配置化 — 材质/模型/名称/描述可自定义
• NEW GUI PAPI 支持 — name/lore 支持 PlaceholderAPI
• NEW 通知系统 — 4 事件 × message/title/sound 三选
• NEW 内置变量 — {coins}/{task_name}/{progress}/{activity} 等

v1.1

• NEW 目标大扩展 — 20→51 种，新增 26 种 (战斗/生活/工作台/移动/数值/交互)
• NEW MythicMobs 软依赖 (KILL_MYTHICMOBS)
• FIX WALK_DISTANCE 每 5 格推送 / HARVEST_CROP 成熟检测 / JUMP 使用 Statistic

v1.0.1

• NEW 分页系统优化 + GUI 100% 自定义 + 任务卡 GUI
• FIX ConcurrentModificationException / Shift+Click 数量 / GUI 关闭误清理
• NEW 性能优化四件套：缓存层 + 分批重置 + 世界校验 + 限流器
• NEW Redis 跨服部署