📥 安装

环境要求

安装步骤

1. 将 AdventurePrize-4.3.0.jar 放入 plugins/
2. 重启服务器，首次启动自动生成默认配置
3. 编辑 plugins/AdventurePrize/ 下的配置文件
4. 执行 /ap reload 热重载

📁 配置目录结构

plugins/AdventurePrize/
├── config.yml              # 主配置文件
├── messages.yml            # 消息文本（完全可自定义）
├── crates/                 # 抽奖箱配置
│   └── example.yml         # 示例抽奖箱
├── animations/             # 23 个动画模板 YAML
│   ├── classic_scroll.yml
│   ├── csgo_rush.yml
│   ├── ring_scanner.yml
│   ├── single_scanner.yml
│   └── ...
└── data/
    └── adventureprize.db   # SQLite 数据库

⌨️ 命令

🔐 权限节点

🎬 动画模板（25 种）

所有动画模板均为 YAML 配置驱动，可通过 Web 编辑器可视化修改或新建。

滚动/旋转类

扫描类 v4.0

特效/翻转类

新增动画 v4.3

轨迹/路径类

🔍 扫描动画 (OVERLAY_SCAN) v4.0

扫描动画是 v4.0 新增的独立轨迹类型，与传统滚动动画有本质区别：

工作原理

1. 奖品固定显示在 GUI 路径槽位上（不滚动）
2. 一块红色玻璃板（可配置材质）沿路径移动，覆盖在奖品上方
3. 玻璃板减速后停在预计算的中奖位置
4. 停留 2 秒后揭示中奖奖品
5. 中奖位置变为屏障方块（won-material），后续扫描自动跳过

YAML 配置项

🔑 钥匙系统

实体钥匙

可交易的物理钥匙物品，由管理员通过 /ap give 发放。玩家可手持钥匙右击抽奖箱使用。

虚拟钥匙

存储在 SQLite 数据库中，GUI 内一键切换实体/虚拟钥匙，实时显示持有数量。

🎁 奖品配置

配置示例

prizes:
  diamond_sword:
    display-name: "&b钻石剑"
    material: DIAMOND_SWORD
    lore:
      - "&7一把锋利的钻石剑"
      - "&e概率: 5%"
    chance: 5.0              # 概率 0.001 ~ 100
    cannot-miss: false       # 是否为保底物品
    cannot-miss-count: 50    # 保底次数
    give-item: true          # 是否给予物品本身
    amount: 1                # 给予数量
    commands:                # 执行指令
      - "cmd:/broadcast %player% 抽中了钻石剑！"
    sound: ENTITY_PLAYER_LEVELUP
    broadcast: true
    broadcast-type:
      - TITLE
      - BOSSBAR
      - CHAT

奖励类型前缀

🎉 庆祝系统 v4.1 重构

v4.1 取消了通用庆祝逻辑，改为每个动画独立的 CELEBRATE 阶段。每个动画 YAML 末尾均有一个 - type: CELEBRATE 阶段。

可配置项

• 音效 — 可配置庆祝音效
• Title — 自定义标题与副标题，支持 {count} 变量
• 消息 — 发送聊天栏消息
• 烟花 — 可配置数量的随机颜色烟花
• 粒子 — 可配置粒子类型和数量

配置示例

celebration:
  enabled: true
  duration-ticks: 60
  sound:
    custom-sound: ENTITY_PLAYER_LEVELUP
    volume: 1.0
    pitch: 1.0
  title:
    enabled: true
    text: "&6&l恭喜中奖!"
    subtitle: "&e获得 {count} 件奖品"
    fade-in: 10
    stay: 40
    fade-out: 10
  messages:
    - "&a恭喜! 您获得了 {count} 件奖品"
  firework:
    enabled: true
    count: 3
  particle:
    enabled: true
    type: VILLAGER_HAPPY
    count: 50

🛡️ 保底机制

在奖品配置中设置 cannot-miss: true 和 cannot-miss-count: N，当玩家连续 N 次未抽中该奖品时，第 N+1 次必定获得。

工作方式

• 保底计数按玩家+抽奖箱独立记录
• 数据存储于 SQLite 数据库
• 管理员可通过 /ap clear 重置玩家记录
• 可在游戏内编辑器中设置 cannot-miss 和 cannot-miss-count

💬 消息配置 (messages.yml) v4.3

v4.3 将所有插件消息迁移至独立的 messages.yml 文件，支持热加载。

主要特性

• 完全可自定义 — 所有聊天消息、GUI 标题、提示文本均可修改
• 热加载 — /ap reload 即时生效，无需重启
• 向后兼容 — 如果 messages.yml 不存在，自动回退到 config.yml
• 占位符 — 支持 {player}、{crate}、{prize}、{count}、{need}

可配置的 GUI 标题

🖥️ Web 可视化编辑器

编辑器功能

📬 邮件集成

当玩家背包空间不足时，奖品自动通过 AdventureMail 发送到邮箱，30 天内可领取。在 config.yml 中启用邮件集成即可。

⚙️ YAML 全配置化 v4.1 增强

v4.1 进一步消除了硬编码值，所有动画内容均可在 YAML 中配置：

📝 更新日志

v4.4.0

• CONFIG softdepend 更新 — plugin.yml 新增 AdventureManage 为可选依赖，提升跨插件兼容性

v4.3.0

• FIX 修复 OVERLAY_SCAN 动画在扫描前泄露最终奖品位置的严重BUG
• FIX 修复 DISPLAY 阶段奖品图标顺序固定导致可预测的问题
• FIX 修复多抽时重复奖品未显示为屏障方块的BUG
• NEW 新增「刮刮乐 Scratch Card」动画
• NEW 新增「多米诺连锁 Domino Chain」动画
• NEW 所有消息迁移至独立 messages.yml
• NEW GUI 标题全部可配置
• IMPROVED 示例箱子增加至 10 个默认奖品

v4.2.0

• FIX 修复单抽后奖池 GUI 只显示 1 个奖品的严重BUG
• FIX 修复庆祝消息 {player} 占位符未替换
• FIX 修复 ESC/E 跳过动画后音效仍继续播放
• NEW 抽奖选择 GUI 改为 YAML 可配置的 draw-options
• IMPROVED DrawCount 重构为 class，支持任意抽奖次数

v4.1.0

• FIX 修复 ESC/E 跳过动画失效
• NEW 庆祝系统重构 — 每动画独立 CELEBRATE phase
• NEW 扫描动画 reveal-sound 可配置
• IMPROVED 盲盒隐藏物品全从 phase config 读取

v4.0.0

• NEW 新增 OVERLAY_SCAN 扫描动画
• NEW 新增 ring_scanner / single_scanner 模板
• NEW 多连抽自动加速
• IMPROVED 速度曲线全面支持多连抽加速