## 📦 SafeChest v0.0.5 — 终极玩家安全及服务器管理系统
> **厌倦了死亡时失去所有东西？** SafeChest 会自动将你的整个物品栏、盔甲和副手物品存储到死亡地点的一个箱子里。轻松找回它——不再需要在掉入熔岩后恼火退出游戏！
>
> **版本 0.0.5 是一个革命性的更新。** 我们添加了专业的管理员工具、音效、动画全息图、PlaceholderAPI 集成、分页显示、实时 GUI 更新，以及修复了关键性能 bug。 这不仅仅是一个死亡箱插件，它还是你玩家和工作人员的**终极安全网和服务器管理套件**。
---
## ✨ 关键特性 — v0.0.5 版
🛡️ **自动保护 & 防破坏**
只有你自己（或管理员）才能打开或破坏你的箱子。 可配置的实体/方块爆炸保护。 **现在破坏你自己的箱子会立即恢复你的物品栏——再也不会因为失误导致物品丢失！**
⏳ **实时多行动画计时器全息图**
悬浮显示你的名字、物品数量和实时倒计时。 **在服务器重启后依然存在。**
✨ **新增：** 全息图现在会在时间耗尽时 **闪烁红色/黄色**（可配置阈值和颜色）。
✨ **新增：** 选项只 **闪烁 `{time}`占位符**，发出微妙而优雅的提醒。
🧭 **`/sctp` — 传送到箱子（索引支持）**
点击一下，你就会回到你的死亡地点。 使用 `/sctp 2` 传送到你列表中的特定箱子。 当找不到安全地点时，可以配置“强制传送”。
🔊 **新增：** 传送时播放可配置的音效。
🧲 **`/scfetch` — 把箱子带到你身边**
非常适合在虚空、熔岩或洞穴中死亡。 箱子（及其全息图）会和你一起移动。
🔊 **新增：** 获取时播放可配置的音效。
👁️ **`/scpreview` — 实时预览内部（自动刷新 & 关闭按钮）**
在不动身的情况下查看箱子内容——安全且只读。 完全可定制的 GUI。
✨ **新增：** GUI 会每 **5 秒从数据库自动刷新** 一次。 如果箱子在你看的时候过期，GUI 会自动关闭。
✨ **新增：** GUI 中有专用的 **屏障关闭按钮** 在槽 44，用于明确关闭。
📋 **`/sclist` — 所有活动箱子（带有分页显示！）**
可点击的你所有箱子的列表。 瞬间传送到任何一个箱子。 按时间排序，按世界过滤，显示 UUID。
✨ **新增：** 结果现在是 **分页显示（每页 5 个）**，带有可点击的 `[上一页]` 和 `[下一页]` 按钮。 使用 `/sclist 3` 跳转到第 3 页。
💰 **Vault 经济支持 (带日志)**
对 `/sctp` 或 `/scfetch` 收费 — 可按组配置。 动作栏反馈支付情况。
📝 **新增：** 所有支付和箱子交互现在会 **记录到服务器控制台**，便于审计和调试。
👥 **基于组别的配置 (带自定义箱子材质!)**
为 `默认`、`VIP`、`管理员` 等定义自定义规则——不同的持续时间、限制、价格，**甚至箱子材质**（例如，VIP 会得到木桶，管理员会得到信标箱）。
> 💡 玩家会被分配到他们 **具有权限的第一组**。
💬 **交互式死亡信息 (带动态成本和时间)**
死亡后，你会收到带有可点击按钮的聊天信息：**[传送]**、**[获取]**、**[预览]**。 **每个按钮都可完全配置。**
✨ **新增：** 按钮的悬停文本现在显示 **动态占位符**，例如 `{cost}` 和 `{time}`。 例如：“成本：50 个金币。 剩余时间：2m 30s。”
💾 **持久化 & 自动恢复**
支持 **SQLite 或 MySQL** 存储。 **服务器启动时会恢复箱子和全息图。**
⚠️ **重要：** 表名已从 `angelchests` 更改为 `safechests` — **更新时需要手动迁移**。
⚙️ **超可配置**
控制 **一切**：粒子类型、动作栏消息、GUI 标题、按钮可见性、世界限制、爆炸保护、**音效、全息图动画，以及更多** — 所有内容都可以在 `config.yml` 中编辑。
🔄 **`/safechestreload`**
在不重启服务器的情况下重新加载配置文件 — 现场管理员必备。 比 `/reload` 更安全。
🎨 **视觉 & 音频反馈**
❤️ 可配置创建时的粒子特效。 ✨ 可配置恢复时的粒子特效。 可选的动作栏消息。
🔊 **新增：**可配置 **音效**，用于创建、恢复、传送和过期。
🌐 **多世界支持**
在特定世界中启用或禁用插件。 过滤 `/sclist` 以仅显示当前世界。
✨ **改进：** 配置现在使用 `behavior.disabled-worlds`（黑名单）逻辑更清晰。
🧠 **PlaceholderAPI 集成**
✨ **全新：** 在 **支持 PlaceholderAPI 的任何插件**（计分板、聊天、菜单等）中使用占位符，例如 `%safechest_time_left%`、`%safechest_item_count%`、`%safechest_location%`。
🛠️ **管理员命令套件 (`/safechestadmin`)**
✨ **全新：** 一套强大的工具，用于服务器工作人员：
* `inspect `：列出玩家的所有活动箱子（点击传送）。
* `delete `：按 UUID 删除特定的箱子。
* `purge`：手动清除数据库中所有过期的箱子。
* `stats`：显示服务器范围内的统计信息（总活动/过期箱子、拥有箱子的玩家等）。
⚠️ **关键 Bug 修复：**
* **🐞 修复：箱子交互/破坏时的死锁** — 点击或破坏箱子时不再出现服务器冻结。 操作现在完全异步。
* **🐞 修复：重启时全息图计时器无效** — 服务器重新启动后，全息图的倒计时会正确开始。
* **🐞 修复：经济错误未记录** — 支付失败现在会记录到服务器控制台，便于调试。
---
## 📘 Wiki: 如何使用 SafeChest v0.0.5
### 🧭 1. 基本用法 (对于玩家)
#### 💀 死亡时
- 一个箱子会出现在你的死亡地点。
- 你的所有物品（物品栏、盔甲、副手）都会存储在里面。
- 你会收到一条 **可配置的** 聊天信息，带有可点击的按钮：
- **[传送]** → `/sctp` — 传送到箱子。 悬停显示成本和剩余时间。
- **[获取]** → `/scfetch` — 把箱子带到你身边。 悬停显示成本和剩余时间。
- **[预览]** → `/scpreview` — 在不动身的情况下查看箱子内容。 悬停显示剩余时间。
#### 📥 恢复你的物品
- **走到箱子旁边并右键点击它** 以恢复你的物品栏。
- 也可以使用 **`/sctp`** 传送到它。
- 也可以使用 **`/scfetch`** 把它带到你身边。
#### 👀 预览你的箱子 (无需移动)
```bash
/scpreview
```
- 打开一个虚拟物品栏，显示你存储的所有物品。
- 完全安全 - 你无法拿走或修改任何东西。
- GUI 会每 **5 秒** 从数据库 **实时更新**。 如果箱子过期，GUI 会自动关闭。
- 点击底行中的 **红色屏障** 手动关闭它。
#### 📋 列出你所有的活动箱子 (分页显示!)
```bash
/sclist
```
- 以每页 5 个的页面显示你所有活动的箱子。
- **可配置：** 按当前世界过滤，按过期时间排序，在悬停时显示 UUID。
- 点击任何条目直接传送到该箱子（如果你有权限）。
- 使用 `/sclist 2` 跳转到第 2 页。
---
### ⚙️ 2. 配置 (对于服务器管理员)
#### 📁 你可以自定义的文件
- `config.yml` — **主设置**：存储、箱子材质、全息图文本、粒子类型、死亡信息按钮、GUI 选项、世界限制、爆炸保护、**音效、全息图动画、日志记录以及更多。**
- `groups.yml` — 定义玩家组（例如，`默认`、`VIP`、`管理员`），带有自定义持续时间、箱子限制、命令价格，**以及箱子材质**。
- `lang.yml` — 翻译或自定义插件中的所有消息，包括 **有关分页、管理员命令和日志记录的新消息**。
#### 🎯 示例: 创建一个 VIP 组
在 `groups.yml` 中：
```yaml
vip:
safechest-duration: 600 # 10 分钟
max-allowed-safechests: 10 # 可以拥有最多 10 个活动箱子
price-teleport: 50.0 # 传送需要 50 个金币
price-fetch: 100.0 # 获取需要 100 个金币
material: "BARREL" # ✅ 新增：VIP 会得到木桶而不是箱子！
```
然后，给予玩家权限：
`safechest.group.vip`
> 💡 玩家会被分配到他们 **具有权限的第一组**。
#### 🖋️ 自定义全息图和死亡信息
在 `config.yml` 中：
```yaml
angelchest:
hologram-text: "&a&l[SafeChest]&r\n&b{player}\n&7{items} items / {time}"
# ✅ 新增部分：全息图动画
hologram-animation:
enabled: true
threshold-seconds: 10 # 当剩余时间少于 10 秒时开始闪烁
color-on: "RED"
color-off: "YELLOW"
blink-only-time-placeholder: true # 仅闪烁 {time} 部分
death-message:
enabled: true
show-buttons: true
show-button-tp: true
show-button-fetch: false # 全局禁用 fetch
show-button-preview: true
```
占位符（用于 `hologram-text`、`lang.yml` 和死亡信息悬停）：
- `{player}` — 玩家的名字。
- `{items}` — 箱子中的物品总数。
- `{time}` — 过期前的剩余时间。
- `{cost}` — 动作的成本（用于死亡信息悬停）。
> ✅ **多行全息图现在完全支持，并在服务器启动时自动恢复。**
#### 🎮 自定义玩家体验
在 `config.yml` 中：
```yaml
messages:
use-action-bar: true # 使用动作栏显示“箱子已创建！”而不是聊天信息
use-particles: true
particle-on-create: "HEART"
particle-on-restore: "END_ROD"
# ✅ 新增部分：音效
sounds:
enabled: true
on-create: "ENTITY_PLAYER_LEVELUP"
on-restore: "ENTITY_ENDERMAN_TELEPORT"
on-teleport: "ENTITY_ENDERMAN_TELEPORT"
on-expire: "ENTITY_ITEM_BREAK"
commands:
preview-gui:
title: "&6我的物品 - SafeChest" # 更改 GUI 标题
info-item-material: "BOOK" # 更改信息物品
force-close-only-with-esc: true # 仅通过 ESC 键关闭预览
aclist:
show-only-current-world: true # 仅显示当前世界的箱子
sort-by-expiration: true # 首先显示即将过期的箱子
show-uuid-in-hover: false # 隐藏 UUID (如果为 true，可用于调试)
```
#### 🛡️ 高级行为控制
在 `config.yml` 中：
```yaml
behavior:
# ✅ 重命名：从 'enabled-worlds' 到 'disabled-worlds'
disabled-worlds: ["world_the_end"] # 在末影世界中禁用插件
protect-from-entity-explosions: true # 防止实体爆炸
protect-from-block-explosions: false # 允许 TNT 摧毁箱子
force-clear-drops-on-death: true # 修复双重掉落 bug
```
---
### 💰 3. 经济设置
SafeChest 集成 **Vault**。 确保你安装了兼容的经济插件（例如，EssentialsX、CMI）。
#### 💵 对命令收费
在 `groups.yml` 或 `config.yml` 中，设置价格：
```yaml
price-teleport: 50.0
price-fetch: 100.0
```
玩家在执行 `/sctp` 或 `/scfetch` 时会自动被收费。
> ✅ 如果未安装 Vault，这些功能将静默禁用——没有错误（`softdepend: [Vault]`）。
---
### 🔄 4. 重新加载配置
作为管理员，你可以在**不重启服务器**的情况下重新加载所有配置：
```bash
/safechestreload
```
**所需权限：** `safechest.reload`
此命令：
- 重新加载 `config.yml`、`groups.yml` 和 `lang.yml`。
- 清除缓存中的过期箱子。
- 重新初始化插件容器。
- **不会破坏活动中的箱子或全息图。**
> 🚫 **警告：** 在服务器活动繁忙时避免使用 `/reload`。 `/safechestreload` 更加安全。
---
### 🛡️ 5. 权限 (重命名!)
| 权限 | 描述 | 默认 |
|------------|-------------|---------|
| `safechest.use` | 允许使用死亡箱系统 | `true` |
| `safechest.protect` | 允许保护你的箱子 | `true` |
| `safechest.protect.ignore` | 允许打开其他玩家保护的 SafeChest | `op` |
| `safechest.tp` | 允许使用 `/sctp` | `true` |
| `safechest.fetch` | 允许使用 `/scfetch` | `true` |
| `safechest.group.` | 将玩家分配到组（例如，`safechest.group.vip`） | — |
| `safechest.reload` | 允许使用 `/safechestreload` | `op` |
| `safechest.admin` | ✅ **新增：** 允许使用 `/safechestadmin` | `op` |
> ✅ 使用 LuckPerms、PermissionsEx 或任何其他权限管理器来分配这些权限。
---
### ❓ 6. 常见问题解答 & 故障排除 — v0.0.5
**Q: 为什么我的物品没有被保存？**
A: 确保你拥有 `safechest.use` 权限。 此外，检查你的世界是否 **未** 列入 `behavior.disabled-worlds` 中。
**Q: 全息图在服务器重启后消失了！**
A: **v0.0.3 和 v0.0.5 中已修复！** 全息图现在会在服务器启动时自动恢复，并且倒计时器也会重启。 如果仍然丢失，请查看服务器日志以获取错误。
**Q: 我得到了“正在初始化...请稍后再试”的提示。**
A: 数据库仍在加载。 等待几秒钟再试。
**Q: 我能将箱子更改为木桶或信标箱吗？**
A: 可以！ 在 `config.yml` 中，全局设置：
```yaml
material: "BARREL"
```
或在 `groups.yml` 中按组设置：
```yaml
vip:
material: "SHULKER_BOX"
```
**Q: 我如何禁用死亡信息按钮？**
A: 在 `config.yml` 中，设置 `death-message.show-buttons: false`，或禁用单个按钮，例如 `show-button-fetch: false`。
**Q: 我的玩家抱怨双重掉落！**
A: 在 `config.yml` 中启用 `behavior.force-clear-drops-on-death: true` 以修复此问题。
**Q: 如何让 `/sctp` 即使没有“安全地点”也能工作？**
A: 在 `config.yml` 中设置 `commands.teleport-unsafe-behavior: "force"`。
**Q: 我如何从 v0.0.4 升级？**
A: **关键：** 在启动服务器之前，你**必须重命名你的数据库表**从 `angelchests` 到 `safechests`。 此外，更新所有权限和命令从 `angelchest` 到 `safechest`。
**Q: 我如何查看服务器统计信息？**
A: 使用新的管理员命令：`/safechestadmin stats`。
**Q: 我如何删除特定的箱子？**
A: 使用 `/safechestadmin delete `。 你可以通过 `/safechestadmin inspect ` 找到 UUID。
---