📥 安装与目录

环境要求

安装步骤

1. 将 AdventureLottery-1.0.0.jar 放入 plugins/ 目录
2. 按需安装 Vault / PlayerPoints / AdventureMail
3. 启动服务器，自动生成配置文件和示例奖池
4. 编辑配置文件和奖池定义
5. 执行 /al admin reload 热加载

目录结构

plugins/AdventureLottery/
├── config.yml              # 主配置 (数据库/备份/暂存箱/音效)
├── messages.yml            # 全部消息文本
├── exchange.yml            # 兑换商店配置
├── chests.yml              # 方块宝箱数据 (自动生成)
├── pools/
│   ├── demo_standard/      # 标准奖池示例
│   │   ├── pool.yml        # 奖池定义
│   │   └── prizes.yml      # 奖品列表
│   └── demo_scoring/       # 积分奖池示例
│       ├── pool.yml
│       └── prizes.yml
└── data.db                 # SQLite 数据库 (自动生成)

🎯 奖池类型

AdventureLottery 支持两种奖池模式，满足不同玩法需求：

标准奖池 (STANDARD)

经典抽奖模式，玩家消耗 钥匙 或 货币 进行抽奖，每次随机获得一个奖品。

• 支持保底机制 (小保底 / 大保底 / 天花板)
• 支持 1/5/10 连抽
• 支持重复奖品处理 (允许 / 移除 / 转换)
• 支持前置奖品解锁链

积分奖池 (SCORING)

积分收集模式，每次抽奖获得 ♦ 积分，积满后可兑换奖励。

• 无保护抽 — 固定消耗，抽到不同奖品时积分清零
• 保护抽 — 递增消耗，抽到不同奖品仅加 1♦
• ♦ 进度条直观显示 (7 格)
• 积满后可兑换宝箱奖励 (支持左键/右键两种奖励)
• 积分奖池不支持连抽

消耗模式

货币类型

🎬 动画系统

AdventureLottery 提供 5 种抽奖动画效果，每个奖池可独立配置。

动画类型一览

动画阶段

滚动类动画 (WHEEL/MARQUEE/CSGO) 分为 3 个阶段：

1. 慢启动 — 缓慢开始滚动，营造期待感
2. 快速滚动 — 高速滚动，奖品快速切换
3. 减速停止 — 逐渐减速，最终停在目标奖品上

预启动特效

单抽动画开始前会播放暗幕 + 闪烁预启动效果 (约 0.7 秒)，增强仪式感。

连抽加速

连抽模式下动画会自动加速，减少等待时间：

跳过动画

在动画播放中关闭 GUI 可跳过动画。为防止误触，需要 关闭两次 才会真正跳过：

1. 第一次关闭：GUI 重新打开，显示 "再次关闭将跳过动画" 提示
2. 第二次关闭：动画跳过，所有奖品自动通过邮件/暂存箱发放

🛡️ 保底机制

保底系统确保玩家不会无限抽取而不出好东西。AdventureLottery 支持 3 层保底，优先级从高到低：

三层保底

触发优先级

每次抽奖时按 天花板 → 大保底 → 小保底 → 正常随机 顺序判定。高优先级触发后跳过低优先级。

配置示例

pity:
  small-pity: 5            # 每5抽触发小保底
  small-pity-prizes:       # 小保底候选奖品ID列表
    - uncommon_sword
    - uncommon_armor
  big-pity: 25             # 每25抽触发大保底
  big-pity-prizes:
    - epic_weapon
  ceiling: 100             # 累计100抽触发天花板
  ceiling-prizes:
    - legendary_set

📦 暂存箱

暂存箱是奖品的安全中转站。当发放方式设为 STASH 时，奖品先进入暂存箱，玩家随时领取。

功能

• 领取 (左键) — 将奖品发放到背包，执行奖励指令
• 分解 (右键) — 分解奖品获得补偿材料 (需奖品配置 decompose-commands)

容量限制

每个玩家的暂存箱容量可在 config.yml 中设置，默认 54 格：

stash:
  max-size: 54

发放方式

♦ 积分奖池

积分奖池是一种特殊玩法：每次抽奖不直接给奖品，而是收集 ♦ 积分，积满后兑换大奖。

玩法流程

1. 玩家选择 无保护抽 或 保护抽
2. 抽奖结果为一个奖品 — 若与上次相同则 ♦+1，若不同则行为取决于抽法
3. ♦ 进度条 (7 格) 实时显示收集进度
4. 积满后点击对应宝箱兑换奖励

两种抽法

宝箱兑换

积分池最多可配置 7 个等级的宝箱奖励，每个宝箱支持左键/右键两种奖励：

score:
  max: 7
  filled-symbol: "♦"
  empty-symbol: "◇"
  chest-rewards:
    3:
      display-name: "3♦ 铜宝箱"
      material: CHEST
      left-name: "奖励A"
      left-commands:
        - "give %player% iron_ingot 16"
      right-name: "奖励B"
      right-commands:
        - "give %player% gold_ingot 8"

🧱 方块宝箱

管理员可以将世界中的任意方块设置为抽奖入口。玩家左键/右键点击该方块即可打开对应奖池的抽奖界面。

功能特性

• 全息文字 — 方块上方自动生成浮动标题文字
• 粒子特效 — 方块周围持续播放粒子效果，吸引玩家注意
• 背包检查 — 背包空间不足时提示警告，确认后放行
• 数据持久化 — 方块位置自动保存到 chests.yml

管理指令

⚙️ config.yml

主配置文件，管理数据库、备份、暂存箱、音效等全局设置。

数据库配置

database:
  type: sqlite          # sqlite 或 mysql
  mysql:
    host: localhost
    port: 3306
    database: adventurelottery
    username: root
    password: ""
  table-prefix: "al_"
  pool-size: 5

备份设置

backup:
  enabled: true
  interval-hours: 24    # 备份间隔 (小时)
  keep-days: 7          # 备份保留天数

暂存箱设置

stash:
  max-size: 54          # 单个玩家暂存箱容量

抽奖记录

history:
  max-per-player: 100   # 每个玩家最大记录数

音效设置

sounds:
  pull: "minecraft:entity.experience_orb.pickup"
  pity-small: "minecraft:entity.player.levelup"
  pity-big: "minecraft:ui.toast.challenge_complete"
  stash-claim: "minecraft:entity.item.pickup"
  stash-decompose: "minecraft:block.grindstone.use"

📋 奖池配置 (pool.yml)

每个奖池文件夹下的 pool.yml 定义奖池的基本属性。

完整字段说明

标准奖池示例

id: demo_standard
display-name: "&6标准宝箱"
description:
  - "&7经典转盘抽奖"
  - "&7每5抽一次小保底"
type: STANDARD
permission: ""

cost:
  currency-type: KEY
  currency-id: "standard"
  currency-name: "标准钥匙"
  base-amount: 1
  cost-mode: FIXED

pity:
  small-pity: 5
  small-pity-prizes: [uncommon_sword, uncommon_armor]
  big-pity: 25
  big-pity-prizes: [epic_weapon]
  ceiling: 100
  ceiling-prizes: [legendary_set]

duplicate:
  mode: ALLOW         # ALLOW / REMOVE / CONVERT
  convert-to: ""

delivery: STASH

multi-pull:
  enabled: true
  options: [1, 5]

animation:
  type: WHEEL

gui-title: "&6✦ 标准宝箱 ✦"

重复处理模式

🎁 奖品配置 (prizes.yml)

奖品定义文件，每个奖品以唯一 ID 为键，配置展示、权重、奖励等属性。

奖品字段说明

稀有度等级

奖品配置示例

common_stone:
  display-name: "圆石 x32"
  rarity: COMMON
  weight: 40.0
  display-material: COBBLESTONE
  display-lore:
    - "&7一堆普通的圆石"
  reward-commands:
    - "give %player% cobblestone 32"
  decompose-commands:
    - "give %player% cobblestone 8"
  decompose-description: "&7分解获得: 圆石 x8"

epic_weapon:
  display-name: "传说之刃"
  rarity: EPIC
  weight: 1.0
  display-material: NETHERITE_SWORD
  display-lore:
    - "&5传说中的神兵利器"
  reward-commands:
    - "give %player% netherite_sword 1"
  pity-eligible:
    small: false
    big: true
    ceiling: false

播报配置

每个奖品可单独配置播报方式：

epic_weapon:
  broadcast:
    enabled: true
    chat: true
    actionbar: false
    bossbar: true
    bossbar-duration: 5
  sound:
    enabled: true
    sound: "minecraft:ui.toast.challenge_complete"
    volume: 1.0
    pitch: 1.0
  firework:
    enabled: true
    colors: [RED, GOLD]
    type: BALL_LARGE

🔄 兑换商店

兑换商店允许玩家使用货币/物品兑换钥匙或其他道具。通过 /al exchange 打开。

兑换项配置

# exchange.yml
items:
  standard_key_buy:
    display-name: "标准钥匙 x1"
    display-material: TRIPWIRE_HOOK
    custom-model-data: 0
    display-lore:
      - "&7用于标准奖池抽奖"
    cost:
      currency: VAULT      # KEY / ITEM / VAULT / POINTS
      currency-id: ""
      amount: 1000
    reward-commands:
      - "al admin givekey %player% standard 1"

  diamond_to_key:
    display-name: "钻石换钥匙"
    display-material: DIAMOND
    cost:
      currency: ITEM
      currency-id: "DIAMOND"  # 物品材质
      amount: 5
    reward-commands:
      - "al admin givekey %player% standard 1"

💬 消息配置 (messages.yml)

所有插件消息均在 messages.yml 中配置，支持 &颜色码、&#RRGGBB 和占位符。

消息分类

可用占位符

⌨️ 命令列表

统一命令: /adventurelottery (别名: /al, /choujiang)

玩家命令

管理员命令

🔑 权限节点

玩家权限

管理员权限

📊 PlaceholderAPI 变量

需安装 PlaceholderAPI，变量前缀为 %lottery_。

使用示例

# 在计分板/菜单中显示
标准钥匙: %lottery_keys_standard%
抽奖次数: %lottery_pulls_demo_standard%
暂存箱: %lottery_stash_count% 件

🔗 插件联动

可选依赖

联动说明

• 所有依赖均为 软依赖 (softdepend)，未安装时对应功能自动禁用
• 使用 KEY 货币时不需要任何外部插件
• 使用 ITEM 货币时不需要任何外部插件 (直接扣除背包物品)
• 发放方式为 MAIL 但未安装 AdventureMail 时，自动回退到 STASH

📝 更新日志

v1.0.0 首发 — 2026-05-18

• NEW 5 种动画系统 — 转盘 (WHEEL)、跑马灯 (MARQUEE)、CS:GO (CSGO)、翻牌 (CARD_FLIP)、直接展示 (DIRECT)
• NEW 双奖池模式 — 标准奖池 (STANDARD) + 积分奖池 (SCORING)
• NEW 3 层保底机制 — 小保底 / 大保底 / 天花板保底，优先级分级判定
• NEW 连抽系统 — 1/5/10 连抽，动画自动加速 (5 连=3× / 10 连=4×)
• NEW 暂存箱 — 奖品安全暂存，支持左键领取 + 右键分解
• NEW 方块宝箱 — 任意方块绑定奖池，全息文字 + 粒子特效
• NEW 兑换商店 — Vault / Points / 物品兑换钥匙
• NEW 4 种货币 — KEY (虚拟钥匙) / ITEM (物品) / VAULT (银币) / POINTS (点券)
• NEW 3 种消耗模式 — 固定 (FIXED) / 递增 (ESCALATING) / 指数 (EXPONENTIAL)
• NEW 重复处理 — 允许 (ALLOW) / 移除 (REMOVE) / 自动转换 (CONVERT)
• NEW 前置解锁 — 奖品之间 DAG 依赖链
• NEW 积分池♦系统 — 7 格进度条、无保护/保护双抽法、宝箱兑换
• NEW 播报系统 — 聊天 / ActionBar / BossBar / 音效 / 烟花 全维度播报
• NEW 跳过动画 — 双关闭确认机制，奖品邮件安全发放
• NEW 预启动特效 — 暗幕 + 闪烁预启动动画 (0.7 秒仪式感)
• NEW 数据持久化 — SQLite / MySQL 双驱动，HikariCP 连接池，自动备份
• NEW PlaceholderAPI — 5 个 PAPI 变量 (钥匙/次数/保底/积分/暂存箱)
• NEW 消息外置 — 所有文本 messages.yml 可配置
• NEW 统一命令 — /al 玩家 + /al admin 管理
• NEW bStats 统计 — 插件使用数据匿名统计

v1.0.0 BugFix 补丁 — 2026-05-18

• FIX 方块宝箱无法触发抽奖 — 修复了点击方块宝箱后 GUI 按钮无响应的问题
• FIX GUI 开启时轨道空白 — 修复了打开抽奖界面后奖品轨道需等待 0.4 秒才显示的问题
• FIX 5 连抽奖品丢失 — 修复了连抽中途跳过动画时未播放部分的奖品不发放的严重问题
• FIX 连抽动画速度优化 — 5 连抽加速至 3× (原 2×)，10 连抽加速至 4× (原 3×)，结果展示暂停时间按倍率缩短
• FIX 空奖品池防护 — 增加空奖品列表防护，避免配置错误导致崩溃