📥 安装教程

1. 将 AdventureChest-1.2.0.jar 放入 plugins/
2. 启动服务器，自动生成默认配置
3. 编辑配置后 /ac reload 热重载
4. 用 LuckPerms 为玩家/组分配权限

依赖说明

🚀 快速上手

管理员快速配置

# 给 VIP 组基础权限
lp group vip permission set adventurechest.use true
lp group vip permission set adventurechest.tp true
lp group vip permission set adventurechest.fetch true

# 给管理员完整权限
lp group admin permission set adventurechest.admin true

# 开启死亡惩罚 (config.yml)
death-penalty:
  enabled: true
  item-chance: 0.5
  item-percent: 0.2

玩家使用方式

1. 死亡后物品自动保存到死亡箱（实体显示在死亡位置）
2. 右键点击死亡箱实体 → 自动拾取所有物品
3. /acgui — 打开死亡箱管理界面
4. /actp 1 — 传送到第 1 个死亡箱
5. /acfetch 1 — 将第 1 个箱子传送到身边

⌨️ 命令列表

管理命令 /ac

玩家命令

管理员扩展

🔑 权限节点

基础权限

高级权限 (需手动授予)

特殊权限

🖥️ GUI 界面 v1.2.0 重制

箱子列表 GUI (/acgui)

显示玩家所有死亡箱图标：位置、剩余时间、物品数量、保护状态。虚空箱子显示 ⚠ 箱子在虚空中! 警告。

箱子详情 GUI v1.2.0

27 格 GUI，灰色玻璃板背景，3 个功能按钮 + 地图信息物品：

虚空箱子处理 v1.2.0

• 传送禁用 — 显示屏障物品，提示无法传送
• 远程赎回可用 — 花费金币直接放入背包
• 丢弃可用 — 放弃所有物品

物品预览 GUI

只读展示箱子内的所有物品（背包、盔甲、副手、经验）。

👁️ 实体显示系统 v1.1.0

ArmorStand 模式（默认）

不可见 ArmorStand 头戴箱子材质。无重力、无碰撞、装备锁定，自动向下偏移 1 格。

MythicMobs 模式

配置 mm-mob-type 为有效 MM 怪物类型。生成失败自动回退到 ArmorStand。

全息文字变量

配置示例

# 使用 MythicMobs
mm-mob-type: "DeathChestMob"
mm-entity-scale: 1.0

# 使用默认 ArmorStand
mm-mob-type: ""

💀 死亡惩罚系统 v1.1.0

工作流程

1. 玩家死亡 → 检查是否启用惩罚
2. 检查 adventurechest.penalty.bypass 权限
3. 按 item-chance 概率触发物品惩罚
4. 按 xp-chance 概率触发经验惩罚
5. 剩余物品和经验存入死亡箱

配置

death-penalty:
  enabled: true
  item-chance: 0.5        # 50% 概率
  item-percent: 0.2       # 丢失 20% 物品
  xp-chance: 1.0
  xp-percent: 0.5
  bypass-permission: "adventurechest.penalty.bypass"

🛡️ 新手保护期 v1.1.0

• 首次进服自动授予 — Player.hasPlayedBefore() == false
• 持久化 — 存储到 protections.yml，重启不丢失
• 永久保护 — 权限 adventurechest.protection.permanent
• 跳过保护 — 权限 adventurechest.protection.bypass
• 管理员命令 — /acprotection add|remove|info

配置

newbie-protection:
  enabled: true
  duration: 3600    # 1小时, 0 = 永久

🔗 物品绑定系统 v1.1.0

绑定标记格式

&c绑定 @        → 红色绑定 (拾取后绑定, 不可GUI解绑)
&a绑定 @        → 绿色绑定 (拾取后绑定, 可花费解绑)
&c绑定 @Steve   → 已绑定到 Steve

绑定行为

• 自动绑定 — 未绑定物品被玩家拾取时自动绑定
• 防丢弃 — 绑定物品无法 Q 键丢弃
• 防交易 — 非主人无法从容器获取
• GUI 解绑 — /acbind 打开解绑 GUI，花费金币/经验/物品解绑
• 免绑权限 — adventurechest.binding.bypass

EcoEnchants 兼容 v1.1.0

检查物品 Lore 中是否包含 Soulbound 关键字。匹配物品保留在玩家身上，不放入死亡箱。

ecoenchants-compat: true
ecoenchants-keep-lore: "Soulbound"

💰 经济系统

Vault 经济

需安装 Vault + 经济插件（如 EssentialsX），直接使用服务器经济余额。

自定义物品货币

custom-currency:
  enabled: true
  material: GOLD_NUGGET
  name: "&6灵魂碎片"
  lore:
    - "&7用于操作死亡箱的特殊货币"
  custom-model-data: 0

价格格式

插件兼容 v1.2.0

• AdventureManage — 反射调用过滤绑定物品，无编译依赖
• Multiverse-Core — GUI 世界名自动显示别名

⚙️ config.yml

基础设置

PvP 设置

实体显示

传送设置

经济设置

音效

💬 messages.yml

所有消息支持 & 颜色代码、&#ff0000 Hex 颜色和 PlaceholderAPI 变量。

常见占位符

{player} {x} {y} {z} {world} {duration} {id} {price} {count} {xp}

v1.2.0 新增消息键

👥 groups.yml

为不同权限组设置不同的箱子参数。

vip:
  permission: "group.vip"
  priority: 10
  chest-duration: 1200
  max-chests: 10
  price-tp: 0
  price-fetch: 0

mvp:
  permission: "group.mvp"
  priority: 20
  chest-duration: 0       # 永不过期
  max-chests: 20

📋 binding.yml

按 Lore 颜色代码定义绑定行为和解绑费用。

color-rules:
  red:
    color-code: "&c"
    description: "永久绑定"
    can-unbind-gui: false

  green:
    color-code: "&a"
    description: "可解绑"
    can-unbind-gui: true
    unbind-cost-money: 5000
    unbind-cost-xp: 10
    unbind-cost-item: "DIAMOND"
    unbind-cost-item-amount: 3

🏷️ PlaceholderAPI 变量

前缀: %achest_

🔧 开发者 API

AdventureChestPlugin plugin = AdventureChestPlugin.getInstance();

// 获取玩家死亡箱列表
List<DeathChest> chests = plugin.getChestManager().getChestsOf(playerUUID);

// 检查新手保护
boolean isProtected = plugin.getProtectionManager().isProtected(player);

// 检查物品是否绑定
boolean isBound = plugin.getBindingManager().isBound(itemStack);

// 通过实体 UUID 获取死亡箱
DeathChest chest = plugin.getChestManager().getChestByEntity(entityUUID);

核心类

❓ 常见问题

Q: 死亡后没有生成箱子？

检查：① 玩家有 adventurechest.use 权限 ② 世界不在 disabled-worlds 中 ③ 不在 WorldGuard 禁用区域 ④ 新手保护未生效 ⑤ spawn-chance 为 1.0

Q: 箱子实体看不到？

检查：① ArmorStand 是否被隐藏 ② MythicMobs ID 是否正确 ③ 服务端是否支持 Equipment API

Q: 物品绑定不生效？

确认：① binding.enabled: true ② binding.yml 已配置 ③ Lore 含 "绑定 @" 格式 ④ 颜色代码匹配

Q: 新手保护和死亡惩罚冲突？

新手保护优先级最高。保护期内不掉落、不触发惩罚、不生成死亡箱。

Q: 箱子在虚空中怎么办？

v1.2.0 自动禁用传送，可远程赎回或丢弃。

Q: VIP 免费传送？

在 groups.yml 中设置 price-tp: 0 和 price-fetch: 0。

📝 更新日志

v1.2.0 最新

• NEW GUI 重制 — 详情 GUI 3 按钮：传送+5s 保护、远程赎回、丢弃
• NEW 5 秒无敌保护 — 传送后自动伤害免疫
• NEW 远程赎回 — 无需前往，直接将物品放入背包
• NEW 虚空检测 — 自动禁用传送，允许赎回/丢弃
• NEW Multiverse-Core — GUI 世界别名显示
• NEW AdventureManage — 自动过滤绑定物品
• FIX 修复 GUI 切换 session 被误删导致物品可被拿取

v1.1.0

• NEW 实体显示系统 — ArmorStand/MythicMobs 不占方块
• NEW 死亡惩罚 — 概率物品/经验丢失
• NEW 新手保护期 — 首次进服定时保护
• NEW 物品绑定 — Lore 标记绑定，GUI 解绑
• NEW EcoEnchants 兼容 — Soulbound 物品保留
• FIX GUI 按钮防盗（Shift-Click/拖拽/数字键）

v1.0.0

• NEW 初始发布 — 死亡箱、全息文字、GUI、传送/Fetch
• NEW Vault 经济 + 自定义货币 + 权限组 + WorldGuard