原创 - 娱乐 - 经济 - 游戏模式 - [1.20-1.21] TreasureCoffer 轻量抽奖插件, 宝箱设置, 钥匙/点券/金币/单抽/连抽/ 保底

版权类型: 原创

插件中文名称: TreasureCoffer

插件英文名称: TreasureCoffer

原帖地址: #

支持的核心（服务端）

Spigot

适配版本（Java）

1.20

TreasureCoffer - 您的终极宝箱抽奖解决方案

还在为服务器缺乏趣味性和激励机制发愁吗？TreasureCoffer 是一款专为 Bukkit/Spigot 1.20.1 服务器打造的强大宝箱抽奖插件，它不仅提供了完善的抽奖系统，还融入了实体宝箱、玩家个人宝箱等创新玩法，让您的服务器焕发全新活力！

快速上手指南
按照以下步骤，轻松配置并启用您的第一个宝箱：

创建宝箱：执行命令 /tc create 我的第一个宝箱
添加普通奖励：手持您想作为奖励的物品，执行 /tc add 我的第一个宝箱 50 (50代表50%的概率，可自定义)
添加保底奖励：手持您想作为保底奖励的物品，执行 /tc addlucky 我的第一个宝箱 100 (保底池物品概率通常设为100，确保获得)
设置消费方式：例如，设置为消耗100金币：/tc money 我的第一个宝箱 100 VAULT (或使用 POINTS 对应点券)
设置保底次数：例如，抽10次必出保底：/tc setmax 我的第一个宝箱 10
设置宝箱外观 (可选)：手持一个箱子方块，执行 /tc setbox 我的第一个宝箱
放置实体宝箱 (可选)：找到一个合适的位置，执行 /tc spawnbox 我的第一个宝箱

完成以上步骤后，玩家即可通过点击您放置的实体宝箱方块，或使用命令 /tc lottery 我的第一个宝箱来打开抽奖界面进行抽奖了！

主要特性一览

多宝箱系统：轻松创建和管理多个不同主题的宝箱，每个宝箱均可独立配置奖池、价格与外观。
保底机制：设定抽奖次数上限，当玩家达到指定次数后，必定获得预设的保底大奖，增加玩家参与积极性。
多种消费方式：支持服务器主流经济系统，包括 Vault (金币)、PlayerPoints (点券)，以及独特的钥匙物品消耗。
实体宝箱方块：允许在游戏世界中放置可供玩家直接交互的宝箱方块，增强沉浸感。
直观GUI界面：精美的图形用户界面，清晰展示奖池内物品、抽奖按钮及相关信息。
单抽与连抽：提供便捷的单次抽取和多次连续抽取选项，满足不同玩家的抽奖习惯。
自定义消息：插件内所有提示、公告等消息均可在配置文件中进行个性化修改，完美融入服务器风格。
权限控制：细致入微的权限节点设计，精确控制玩家及管理员对各项功能的使用权限。

核心功能一览

强大的抽奖机制：支持普通奖池、保底奖池，单抽与N连抽，满足不同玩家需求。
高度自定义GUI：抽奖界面、按钮、边框、物品展示均可自定义，完美融入您的服务器风格。
实体宝箱方块：在世界中放置可交互的宝箱，支持自定义外观、发光、旋转等特效。
玩家个人宝箱：玩家可创建自己的宝箱，设置抽奖费用，与其他玩家互动，赚取收益。
多种货币支持：支持金币 (Vault)、点券 (PlayerPoints) 及特定钥匙物品作为抽奖消耗。
完整物品序列化：完美保留物品所有NBT数据，MOD物品、特殊附魔道具也能轻松放入奖池。
命令奖励系统：可将服务器指令作为奖励，支持 %player% 变量。
详细的玩家数据：记录玩家抽奖次数，自动触发保底。
多语言消息系统：内置中英文消息配置，可自由定制提示信息。
权限精细控制：完善的权限节点，轻松管理玩家和管理员操作。
PlaceholderAPI 支持：提供占位符，方便与其他插件联动显示数据。

核心功能详解

1. GUI自定义与抽奖体验

界面布局随心控：抽奖按钮、翻页按钮的位置都可以在 `config.yml` 中自由设定，打造独一无二的抽奖界面。
动态抽奖按钮：自定义按钮的材质、名称、Lore，清晰展示当前抽奖次数、保底进度、所需货币或钥匙。
智能抽奖模式：左键单击进行单次抽取，右键单击进行N连抽（默认9连，可在宝箱配置中单独设置），插件还会根据玩家背包剩余空间自动调整N连抽的次数，非常贴心！
分页奖励展示：奖品太多也不怕！GUI支持分页显示，一目了然。
NBT完美兼容：无论是原版附魔书，还是带有复杂NBT标签的MOD物品、RPG插件物品，都能完美存入奖池并被玩家抽中。

2. 抽奖箱配置 (Crate Configuration)

多样化开启条件：每个宝箱都可以独立设置消耗金币、点券或特定钥匙。钥匙识别支持完整NBT数据或物品名称，杜绝仿制。
双奖池设计：
- 普通奖池：配置常规奖励及其获取概率。支持添加物品和服务器指令（指令支持 `%player%` 变量，空格请用下划线 `_` 替代）。
- 保底奖池：设置保底触发次数。当玩家抽奖达到指定次数后，必定从保底奖池中抽取奖励。同样支持概率设置。
保底信息透明：可设置是否允许玩家查看保底奖池内容及当前保底进度。
灵活的连抽设置：每个宝箱都可以单独定义N连抽的默认次数。

3. 实体宝箱方块系统 (Physical Crate Blocks)

沉浸式抽奖：管理员可以在游戏世界中的任意位置放置实体宝箱方块。
外观大师：手持任何方块或物品，即可将其设置为宝箱的外观，创造出千奇百怪的宝箱造型！
动态特效：支持设置宝箱方块的旋转、缩放、位置偏移，甚至可以使其发光并自定义发光颜色！
便捷交互：玩家左键点击宝箱方块打开抽奖界面，右键点击查看保底奖励（如果允许）。管理员Shift+右键可快速移除宝箱方块。
数据持久：所有宝箱方块位置和状态都会保存，重启服务器后可通过指令一键恢复。

4. 玩家宝箱系统 (Player Crate System)

人人都是宝箱主：玩家可以创建属于自己的个人宝箱（可根据权限限制创建数量）。
自定义奖池：玩家可以将自己的物品（同样支持NBT）放入个人宝箱作为奖励，并设置各项物品的概率。
设定抽奖费用：宝箱主人可以为自己的宝箱设置金币或点券的抽奖费用。
互动抽奖赚收益：其他玩家可以支付费用抽取这些个人宝箱，费用会自动转给宝箱主人，即使主人离线也能收到！
隐私控制：宝箱主人可以设置是否允许其他玩家查看自己宝箱内的具体奖品内容（即使不给看，也能抽）。
安全删除：删除个人宝箱时，之前放入的物品会自动返还给宝箱主人。

5. 消息与提醒 (Messages & Notifications)

全方位提示：抽奖成功、触发保底、背包空间不足（单抽/连抽）、自动调整连抽次数等均有对应提示。
全服中奖广播：可配置是否广播普通抽奖和保底抽奖的中奖信息，以及是否在控制台显示。
多语言支持：内置 `messages.yml` (中文) 和 `messages_en.yml` (英文)，您可以轻松编辑所有提示信息，支持颜色代码。

宝箱系统 (Crate System)
TreasureCoffer 的核心在于其灵活的宝箱创建与管理机制。您可以：

创建无限数量的宝箱，例如“新手宝箱”、“活动宝箱”、“神器宝箱”等。
为每个宝箱独立配置：
- 普通奖池 (Normal Rewards) 和保底奖池 (Lucky Rewards)。
- 消费方式 (金币、点券或特定钥匙)。
- 保底触发次数 (Max Pulls for Lucky Reward)。
- 支持的连抽次数选项。
- 实体宝箱方块的外观材质。

奖励系统 (Reward System)
插件提供了强大且细致的奖励配置选项：

普通奖池：玩家每次抽奖时，将根据您为每个物品设定的概率，随机抽取该奖池中的奖励。
保底奖池：当玩家在特定宝箱的抽奖次数累计达到预设值时，下一次（或该次）必定获得保底奖池中的指定奖励。
奖励概率：每个加入奖池的物品都可以设置独立的获取概率，精确控制稀有度。
完整物品序列化：支持完美保存物品的各项NBT数据，包括附魔、Lore、自定义名称、自定义模型数据 (CustomModelData) 等，确保奖励原汁原味。

消费系统 (Currency System)
每个宝箱都可以定义其抽奖所需的消费类型和金额：

金币 (Vault)：通过与 Vault 插件联动，扣除玩家的游戏币。
点券 (PlayerPoints)：通过与 PlayerPoints 插件联动，扣除玩家的点券。
钥匙 (Keys)：要求玩家背包中拥有特定配置的钥匙物品才能进行抽奖。钥匙本身可以作为其他活动的奖励或通过商店购买。

GUI 界面 (Graphical User Interface)
提供用户友好的图形界面，提升玩家体验：

抽奖主界面：动态展示当前宝箱的部分奖品（可配置显示数量），设有清晰的单抽和连抽按钮。
奖励预览：玩家可以方便地查看宝箱内普通奖池和保底奖池中的所有可能物品及其概率（可配置是否显示概率）。
便捷操作：通常左键点击为单次抽奖，右键点击（或特定按钮）为多次连续抽奖。
保底进度显示：在界面上清晰展示玩家当前的抽奖次数以及距离触发保底还需的次数。

实体宝箱方块 (Physical Crates)
让抽奖更具仪式感和互动性：

世界放置：管理员可以在游戏世界中的任意位置放置实体宝箱方块。
自定义外观：可以使用任何原版方块或自定义物品模型作为宝箱方块的视觉外观。
交互方式：
- 通常左键点击实体宝箱方块会打开对应的抽奖GUI界面。
- 通常右键点击实体宝箱方块可以快速查看该宝箱的保底奖励信息。
发光效果：支持为宝箱方块设置是否发光，并可以自定义发光的颜色（通常依赖客户端特性或辅助插件）。
精细调整：可对宝箱方块的显示位置进行微调，如位置偏移、旋转角度和缩放比例，以适应不同场景。

数据存储与安全

数据存储
插件数据采用易于管理和备份的 YAML 文件格式进行存储：

宝箱配置文件 (Crate Configurations)：储存于 `plugins/TreasureCoffer/crates/` 目录下，每个宝箱一个独立的 `.yml` 文件。
玩家数据文件 (Player Data)：储存于 `plugins/TreasureCoffer/players/` 目录下，记录玩家各宝箱的抽奖次数等信息。

安全机制
为保障服务器稳定和公平，插件内置了多项安全措施：

防止玩家从GUI界面中非法拖拽或拿取展示的奖品。
严格的权限控制，防止未授权玩家破坏已放置的实体宝箱方块。
点击冷却系统，有效防止玩家因快速重复点击抽奖按钮而可能引发的问题。
抽奖前进行背包空间检查，若空间不足则提示玩家，避免奖励物品因无法拾取而丢失。

指令大全 (Commands)

YAML：

# 管理员指令
/tc create <宝箱名>            # 创建一个指定名称的官方宝箱
/tc add <宝箱名> [概率]        # 将手持物品添加到指定宝箱的普通奖池
/tc addlucky <宝箱名> [概率]   # 将手持物品添加到指定宝箱的保底奖池
/tc addcmd <宝箱名> <命令> [概率] # 添加命令奖励到宝箱的普通奖池 (%player%变量, 下划线替代空格)
/tc open <宝箱名>             # 查看指定宝箱的普通奖品 (管理员右键删除)
/tc openlucky <宝箱名>        # 查看指定宝箱的保底奖品 (管理员右键删除)
/tc set <玩家名> <宝箱名> <次数> # 设置玩家对特定宝箱的抽奖次数 (用于保底)
/tc reload                    # 重载插件配置和宝箱数据
/tc money <宝箱名> <价格> <类型> # 设置宝箱的消费货币类型(金币/点券)和价格
/tc keyset <宝箱名> <true/false> # 开启或关闭宝箱的钥匙消耗
/tc keyadd <宝箱名>           # 将手持物品设置为宝箱的钥匙
/tc setmax <宝箱名> <次数>      # 设置宝箱的保底次数上限
/tc setbox <宝箱名>           # 设置宝箱方块的外观 (手持物品)
/tc spawnbox <宝箱名>         # 在当前位置生成宝箱方块
/tc setglow <宝箱名> <true/false> # 设置宝箱方块是否发光
/tc setglowcolor <宝箱名> <颜色> # 设置宝箱方块发光颜色 (如 RED, BLUE, 0xFF00FF)
/tc restoreboxes              # 恢复所有已记录的宝箱方块

# 玩家宝箱相关指令 (部分需要特定权限)
/tc createplayer <宝箱名>      # 创建个人宝箱
/tc addplayer <宝箱名> <概率>  # 添加手持物品到自己的个人宝箱
/tc delplayer <宝箱名>         # 删除自己的个人宝箱并返还物品
/tc setplayermoney <宝箱名> <金额> # 设置个人宝箱的金币费用
/tc setplayerpoints <宝箱名> <点券> # 设置个人宝箱的点券费用
/tc setviewplayer <宝箱名> <true/false> # 设置个人宝箱是否允许其他玩家查看内容

# 通用抽奖指令
/tc lottery <宝箱名>          # 打开指定官方宝箱的抽奖界面
/tc openplayer <玩家名> <宝箱名> # 打开其他玩家的个人宝箱进行抽奖
/tc viewplayer <玩家名> <宝箱名> # 查看其他玩家的个人宝箱内容 (若允许)

权限节点 (Permission Nodes)

YAML：

# 管理员权限
treasurecoffer.admin.*             # 允许使用所有管理指令 (OP默认拥有)
treasurecoffer.admin.create        # 允许创建宝箱
treasurecoffer.admin.add           # 允许向宝箱添加普通奖励
treasurecoffer.admin.addlucky      # 允许向宝箱添加保底奖励
treasurecoffer.admin.addcmd        # 允许添加命令奖励
treasurecoffer.admin.open          # 允许查看宝箱普通奖励 (及删除)
treasurecoffer.admin.openlucky     # 允许查看宝箱保底奖励 (及删除)
treasurecoffer.admin.set           # 允许设置玩家对宝箱的抽奖次数
treasurecoffer.admin.reload        # 允许重载插件
treasurecoffer.admin.money         # 允许设置宝箱的消费货币类型和价格
treasurecoffer.admin.keyset        # 允许设置宝箱的钥匙使用状态
treasurecoffer.admin.keyadd        # 允许添加钥匙物品到宝箱
treasurecoffer.admin.setmax        # 允许设置宝箱的保底次数上限
treasurecoffer.admin.setbox        # 允许设置宝箱实体的外观
treasurecoffer.admin.spawnbox      # 允许生成宝箱方块
treasurecoffer.admin.removebox     # 允许破坏宝箱方块 (Shift+右键)
treasurecoffer.admin.restoreboxes  # 允许恢复所有宝箱
treasurecoffer.admin.viewall       # 允许查看所有玩家的宝箱，即使设置为不可见

# 玩家权限
treasurecoffer.lottery             # 允许打开官方宝箱抽奖界面 (基础权限)

# 玩家个人宝箱权限
treasurecoffer.player.create.<数量> # 允许玩家创建指定数量的个人宝箱 (例如 .player.create.1, .player.create.3)
treasurecoffer.player.create       # (如果不想用数量限制，可以给这个基础权限，配合config里的默认数量)
treasurecoffer.player.add          # 允许玩家向自己的宝箱添加物品 (配合 createplayer 使用)
treasurecoffer.player.delete       # 允许玩家删除自己的宝箱 (配合 createplayer 使用)
treasurecoffer.player.setprice     # 允许玩家设置个人宝箱的费用 (配合 createplayer 使用)
treasurecoffer.player.setview      # 允许玩家设置个人宝箱的查看权限 (配合 createplayer 使用)
treasurecoffer.player.openother    # 允许打开其他玩家的宝箱进行抽奖
treasurecoffer.player.viewother    # 允许查看其他玩家的宝箱内容 (如果对方设置为可查看)

(注意: 权限节点 `treasurecoffer.player.create.<数量>` 这种写法是示例，具体插件内可能是 `treasurecoffer.player.create.1`, `treasurecoffer.player.create.3` 等，或者通过配置限制数量并给一个总的 `treasurecoffer.player.create` 权限。请以插件实际生成的为准或查阅其文档确认。此处根据README中的 `treasurecoffer.player.create.1` 等推断。)

技术规格 & 依赖

服务器版本： Bukkit / Spigot / Paper 1.20.1 (宝箱方块使用ItemDisplay实体，需要此版本支持)
Java 版本： Java 17
核心依赖 (需自行安装)：
- Vault API： 用于金币作为抽奖货币 (几乎是服务器必备经济前置)
- PlayerPoints API： 用于点券作为抽奖货币 (如果需要点券抽奖功能)
可选依赖 (增强功能)：
- PlaceholderAPI：用于在其他插件 (如计分板、聊天) 中显示TreasureCoffer的相关信息。
  - `%treasurecoffer_count_<宝箱名>%` - 显示玩家对指定宝箱的当前抽奖次数
  - `%treasurecoffer_max_<宝箱名>%` - 显示指定宝箱设定的保底次数上限