🎰 AdventurePrize

一、简介

AdventurePrize —— 一款高级 GUI 抽奖箱插件，拥有 25 种精美动画模板

AdventurePrize 允许您轻松创建自定义抽奖箱（真的是无限的可能性）供玩家使用。提供 25 种开箱动画、钥匙双系统、硬保底+软保底概率提升、Web可视化编辑器、稀有度等级系统等功能。让您的服务器抽奖体验焕然一新。

AdventurePrize 支持 Paper / Purpur 1.21.4+ 服务器（Java 21），并且会第一时间支持未来版本。

AdventurePrize

25种动画 > 滚动、扫描、翻转、轨迹等多类型开箱动画
钥匙双系统 > 实体 + 虚拟 + 混合模式三向切换
保底机制 > 硬保底 + 软保底渐进概率提升，保障玩家体验
Web编辑器 > 拖拽式布局设计 + 动画实时预览
稀有度等级 > 自定义概率区间、材质、颜色
邮件集成 > 背包满时自动邮寄奖品
GUI操作 > 内容百分之99自定义
多奖品类型 > 物品、命令、经济、称号等多种奖品
数据存储 > 支持 SQLite 本地存储
高自定义 > 动画模板、抽奖箱配置全部YAML自定义

二、插件前置说明

都是非必须

PlaceholderAPI — PAPI变量支持
AdventureMail — 邮件系统，背包满时自动邮寄奖品

下一篇安装 →

📥 安装

环境要求

项目	要求
服务端	Paper / Purpur 1.21.4+
Java	Java 21+
可选依赖	AdventureMail、PlaceholderAPI

安装步骤

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

上一篇← 插件总览

下一篇动画模板 →

🎬 动画模板（25 种）

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

滚动/旋转类

模板 ID	名称	描述
`classic_scroll`	经典滚动	水平滚动，CSGO 风格开箱
`csgo_rush`	急速滚动	高速滚动逐渐减速
`ring_spin`	环形旋转	奖品环形排列旋转选中
`roulette_wheel`	轮盘旋转	经典轮盘赌风格
`slot_machine`	老虎机	3 列独立滚动

扫描类 v4.0

模板 ID	名称	描述
`ring_scanner`	环形扫描	红色玻璃板沿环形路径扫描
`single_scanner`	单行扫描	红色玻璃板沿单行扫描

特效/翻转类

模板 ID	名称	描述
`card_flip`	卡牌翻转	发牌后翻转揭晓
`shell_game`	贝壳洗牌	贝壳游戏风格
`lucky_grid`	九宫格	3x3 格子轮流高亮
`treasure_map`	宝藏寻猎	宝箱开启揭晓
`chaos_storm`	混沌风暴	随机闪烁后聚焦
`pb_gacha`	扭蛋机	盲盒扭蛋风格
`pubg_crate`	空投箱	PUBG 空投开箱
`scratch_card`	刮刮乐 v4.3	灰色涂层逐个刮开揭示
`domino_chain`	多米诺 v4.3	S形路径链式翻转

轨迹/路径类

模板 ID	名称	描述
`diamond_spiral`	钻石漩涡	菱形轨迹聚焦
`galaxy_spiral`	银河螺旋	螺旋向内旋转
`snake_chase`	蛇形追逐	蛇形路径扫描
`zigzag_path`	之字路径	之字形轨迹滚动
`ping_pong_bounce`	乒乓弹跳	来回弹跳选中
`tornado_vortex`	龙卷风	旋风式旋转聚焦
`wave_tide`	波浪潮汐	波浪式扫描
`waterfall_drop`	瀑布级联	奖品瀑布式下落
`meteor_shower`	流星雨	流星划过选中

上一篇← 安装

下一篇扫描动画 →

🔍 扫描动画 (OVERLAY_SCAN)

工作原理

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

配置项

键	默认值	说明
`trajectory`	—	设为 `OVERLAY_SCAN`
`overlay-material`	`RED_STAINED_GLASS_PANE`	扫描覆盖材质
`scan-laps`	`3`	扫描圈数
`scan-repeatable`	`true`	允许重复扫中同位
`won-material`	`BARRIER`	已中奖槽位替换材质
`won-display-name`	`&c&l已获得`	已中奖槽位显示名
`reveal-sound`	—	揭示音效配置
`speed-curve`	`DECELERATE`	速度曲线

上一篇← 动画模板

下一篇钥匙系统 →

🔑 钥匙系统

实体钥匙

可交易的物理钥匙物品，由管理员通过 /ap give 发放。右键抽奖箱时自动选择。

虚拟钥匙

存储在 SQLite 数据库中，GUI 内一键切换，实时显示持有数量。

混合模式 v4.5

同时拥有两种钥匙时自动进入混合模式：优先消耗实体钥匙，不足部分从虚拟钥匙扣除。支持 实体 → 虚拟 → 混合 三种模式循环切换。

上一篇← 扫描动画

下一篇奖品配置 →

🎁 奖品配置

示例

prizes:
  diamond_sword:
    display-name: "&b钻石剑"
    material: DIAMOND_SWORD
    chance: 5.0
    cannot-miss: false
    cannot-miss-count: 50
    give-item: true
    amount: 1
    commands:
      - "cmd:/broadcast %player% 抽中了钻石剑！"
    sound: ENTITY_PLAYER_LEVELUP
    broadcast: true

奖励类型

前缀	说明	示例
`cmd:`	Console 执行	`cmd:/give %player% diamond 64`
`op:`	OP 身份执行	`op:/gamemode creative %player%`
`player:`	玩家身份执行	`player:/spawn`

上一篇← 钥匙系统

下一篇庆祝系统 →

🎆 庆祝系统

v4.1 取消通用庆祝逻辑，每个动画独立 CELEBRATE 阶段。支持音效、Title、消息、烟花、粒子。

示例配置

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} 件奖品"
  firework:
    enabled: true
    count: 3
  particle:
    enabled: true
    type: VILLAGER_HAPPY
    count: 50

上一篇← 奖品配置

下一篇保底机制 →

🛡️ 保底机制

硬保底

设置 cannot-miss: true 和 cannot-miss-count: N，连续 N 次未抽中时第 N+1 次必定获得。计数按玩家+抽奖箱独立记录。

软保底 v4.4

可配置 softPityStart 和 softPityRatePerDraw，抽奖次数超过阈值后稀有品概率渐进提升。

上一篇← 庆祝系统

下一篇messages.yml →

💬 messages.yml v4.3

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

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

可配置的 GUI 标题

键	默认值	说明
`gui-draw-select-title`	`&d选择抽奖次数 - {crate}`	抽奖选择 GUI
`gui-preview-title`	`&d奖池预览 - {crate}`	奖池预览 GUI
`gui-editor-title`	`&5箱子编辑 - {crate}`	编辑器 GUI

ℹ️ 邮件集成

背包空间不足时，奖品自动通过 AdventureMail 发送到邮箱，30 天内可领取。

上一篇← 保底机制

下一篇Web 编辑器 →

🌐 Web 可视化编辑器

启动

cd web-editor
npx serve -l 3000 .

访问 http://localhost:3000 打开编辑器。

功能

可视化布局 — 拖拽式 GUI 布局设计
动画阶段编辑 — 工作流式阶段序列配置
材质选择器 — 1000+ Minecraft 物品图片预览搜索
实时预览 — 动画效果即时预览
配置管理 — 保存/加载/导入/导出 YAML

上一篇← messages.yml

下一篇稀有度等级 →

💎 稀有度等级

在 config.yml 的 rarity-tiers 段自定义概率区间：

rarity-tiers:
  common:
    min-probability: 80
    max-probability: 101
    material: WHITE_STAINED_GLASS_PANE
    label: "普通"
    color: "&7"
  legendary:
    min-probability: 0
    max-probability: 20
    material: ORANGE_STAINED_GLASS_PANE
    label: "传说"
    color: "&6"

上一篇← Web 编辑器

下一篇PAPI 变量 →

📊 PlaceholderAPI 变量

占位符	说明
`%adventureprize_pity_<箱子ID>%`	当前保底计数
`%adventureprize_keys_<箱子ID>%`	虚拟钥匙余额
`%adventureprize_draws%`	总抽奖次数

上一篇← 稀有度等级

下一篇命令 →

⌨️ 命令

命令	权限	说明
`/ap help`	`adventureprize.use`	显示帮助
`/ap list`	`adventureprize.use`	列出所有抽奖箱
`/ap open <箱子>`	`adventureprize.use`	打开抽奖箱
`/ap preview <箱子>`	`adventureprize.use`	预览奖池
`/ap give <玩家> <箱子> <类型> <数量>`	`adventureprize.admin`	给予钥匙
`/ap take <玩家> <箱子> <类型> <数量>`	`adventureprize.admin`	扣除钥匙
`/ap set <箱子>`	`adventureprize.admin`	设为抽奖箱
`/ap remove`	`adventureprize.admin`	移除抽奖箱
`/ap editor`	`adventureprize.admin`	游戏内编辑器
`/ap reload`	`adventureprize.admin`	重载配置
`/ap history [玩家] [箱子]`	`adventureprize.admin`	抽奖历史
`/ap stats <箱子>`	`adventureprize.admin`	统计数据
`/ap reloadcrate <箱子>`	`adventureprize.admin`	热更新单箱

上一篇← PAPI 变量

下一篇权限 →

🔐 权限

权限	说明	默认
`adventureprize.use`	基础使用	所有玩家
`adventureprize.admin`	管理员权限	OP
`adventureprize.admin.crate`	抽奖箱管理	OP
`adventureprize.admin.key`	钥匙管理	OP
`adventureprize.admin.editor`	编辑器权限	OP
`adventureprize.bypass.cooldown`	绕过冷却	OP
`adventureprize.bypass.key`	无需钥匙	OP

上一篇← 命令

下一篇更新日志 →

📝 更新日志

v4.5.0 最新

FIX 修复 Elimination 淘汰动画奖品显示 BUG
FIX 修复矿洞探索空槽点击问题
NEW 混合钥匙模式 (MIXED)
UPD 钥匙来源三向切换 + GUI 增强

v4.4.0

NEW 稀有度等级自定义 + 揭示音效 + PAPI 集成
NEW /ap history、/ap stats、/ap reloadcrate
NEW 会话超时保护 + 抽奖冷却 + 软保底系统
UPD 数据库写操作全部异步化

v4.3.0

FIX 修复 OVERLAY_SCAN 泄露奖品位置
NEW 刮刮乐 + 多米诺连锁动画
NEW messages.yml 独立消息文件

v4.2.0

FIX 修复单抽后奖池 GUI 显示 BUG
NEW draw-options YAML 可配置连抽

v4.1.0

NEW 庆祝系统重构 + reveal-sound 可配置

v4.0.0

NEW OVERLAY_SCAN 扫描动画 + 多连抽加速

上一篇← 权限