---
# 📚 自定义死亡消息 - 更新文档 (v0.0.7)
> **让每一次死亡都变成一个电影般的时刻…… 或是一场史诗般的灭绝。现在带有内置配置验证。**
`CustomDeathMessages` 是一个为 Minecraft 服务器设计的 Spigot/Paper 插件，**它将乏味的默认死亡消息替换为自定义、动态、色彩鲜艳的消息**，并带有可选的 **音效、粒子爆炸、屏幕标题、操作栏、经济成本，甚至还有一个“变暗屏幕”效果**。管理员可以为每种死亡原因、玩家权限组（例如，VIP、Admin）或特定世界（地狱、末地等）定义唯一的死亡消息。版本 0.0.7 在强大的 v0.0.6 的基础上引入了一个 **革命性的集成配置验证器**——确保您的配置在生效之前没有错误。不再有由于缺少逗号而导致服务器崩溃的情况。
> **⚠️ v0.0.7 重要升级说明**
> 为了确保您获得所有新的配置选项、系统消息和验证器命令，**强烈建议您**：
> 1. **备份**您现有的 `config.yml` 和 `messages.yml` 文件。
> 2. **删除**服务器 `plugins/CustomDeathMessages/` 文件夹中的旧 `config.yml` 和 `messages.yml` 文件。
> 3. 重启或重新加载服务器。插件将自动生成新的、最新的配置文件，其中包含所有新的设置和示例。
> 4. 然后您可以将自定义消息和设置从备份手动添加到新文件中。
---
## 🧩 特性
* **死亡原因消息：** 为 `FALL`、`FIRE`、`ENTITY_ATTACK`、`DROWNING`、`VOID` 以及更多提供独特的死亡消息。
* **基于权限的组：** VIP、管理员或默认玩家可以获得定制的消息和音效。
* **按世界覆盖：** 定义 `world_nether`、`world_the_end` 或任何自定义世界中的特殊消息。
* **视觉效果：**
* 粒子爆炸 (`EXPLOSION`、`FLAME` 等)
* 屏幕标题和副标题 (`&cYOU DIED`)
* 操作栏消息 (`&c{victim} died!`)
* 使用环境粒子（例如，`CLOUD`、`SMOKE`）的“变暗屏幕”效果
* **自定义音效：** 全局或按组的死亡音效，带有可调节的音量和音调。
* **高级占位符：**
* `{victim}` — 死亡的玩家。
* `{killer_name}` — 造成杀戮的 **实体** (例如，射出箭矢的骷髅)。
* `{killer_source}` — 造成伤害的 **直接来源** (例如，“Arrow”、“Lava”、“Fireball”)。
* `{killer_displayname}` — 杀手的显示名称（支持插件，如 EssentialsX 或 LuckPerms 的颜色/昵称）。
* `{cause}` — 技术死亡原因 (例如，`FALL`、`ENTITY_ATTACK`)。
* `{world}` — 世界名称。
* `{biome}` — 生物群系名称（例如，“Plains”、“Nether Wastes”、“Deep Dark”）。
* `{x}`、`{y}`、`{z}` — 死亡坐标。
* `{time}` — 服务器时间（从 `config.yml` 格式化）。
* `{distance}` — 受害者和杀手之间的距离（单位：方块），小数点后一位（例如，“5.2”）。
* `{victim_weapon}` — 受害者主手中武器的名称。
* `{victim_effects}` — 受害者拥有的所有活动药水效果列表.
* **PlaceholderAPI 支持：** 使用外部占位符扩展功能。
* **重生消息：** 用自定义消息欢迎玩家重生。
* **实时重新加载：** 使用 `/cdmreload` 应用配置更改，无需重新启动。 **具有原子重新加载功能：如果新配置失败，它将回滚到旧配置。**
* **测试命令：** 使用 `/cdm test [killer_name] [killer_source]` 预览消息。您可以指定负责实体和直接伤害来源。
* **绕过权限：** 拥有 `cdm.bypass` 权限的玩家不会触发死亡消息（适合工作人员）。
* **消息冷却系统：** 防止相同的随机消息连续显示给玩家。
* **史诗死亡系统：** 死亡成为 **史诗** 的概率是可以配置的，具有独特的死亡消息、音效、粒子、标题和 **闪电击中**。
* **Vault 经济集成：** 向玩家收取展示死亡消息的费用。免除（如管理员）支付除外组。
* **游戏内帮助 (`/cdmhelp`)：** 直接在游戏内可访问的多页、完全可配置的帮助系统。动态生成且基于权限控制。
* **条件消息：** 根据复杂的条件显示不同的消息，使用 `AND`、`OR`、`equals`、`startsWith`、`endsWith`、`>`、`<`、`>=`、`<=`。
* **遗留色彩支持：** 自动删除现代十六进制色彩代码，以兼容 Minecraft 1.16 之前的版本。
* **原子配置重新加载：** `/cdmreload` 命令现在会在应用之前验证整个新配置文件。如果任何部分失败，插件将安全地回滚到以前的状态，防止服务器崩溃。
* **基于权限的帮助系统：** 通过 `config.yml` 中的 `help-permissions` 部分控制不同用户组（例如，`default`、`vip`、`op`）可以访问哪些帮助页面。
* **集成配置验证器 (`/cdm config validate`)** — **v0.0.7 新增！** 在配置生效之前，主动扫描您的 `config.yml` 和 `messages.yml` 文件，查找无效的音效、粒子和条件语法错误。 直接在游戏中获得详细的彩色报告 (✅ 成功、❌ 错误、⚠️ 警告)。
---
## ⚙️ 配置
插件在 `plugins/CustomDeathMessages/` 目录下自动生成两个配置文件：
* `config.yml`：全局设置（音效、粒子、半径、视觉效果、史诗死亡概率、成本、遗留支持以及 `help-permissions`）。
* `messages.yml`：按组和原因组织死亡消息，包括史诗消息、条件消息、帮助系统、经济消息和 **验证器新增加的 `config-validator-*` 系统消息** 部分。
### 📄 config.yml (关键片段 - v0.0.7)
```yaml
## 谁会看到死亡消息？
message-to-victim: true
message-to-world: true
message-to-radius: 0
## 全局死亡音效 (使用现代名称：entity.player.death)
play-sound-on-death: true
death-sound: entity.player.death
sound-volume: 1.0
sound-pitch: 1.0
## 粒子效果
play-particles-on-death: true
death-particle: EXPLOSION
particle-count: 50
## 启用基于权限的消息？
use-permission-based-messages: false
## 按世界覆盖
per-world-messages:
world_nether:
default: "&4{victim} fue consumido por el Nether."
world_the_end:
default: "&5{victim} se desvaneció en el vacío eterno."
## 视觉效果
play-title-on-death: false
death-title: "&cYOU DIED"
death-subtitle: "&7{cause}"
play-actionbar-on-death: false
death-actionbar: "&c{victim} has perished!"
play-darken-screen-effect: false
darken-effect-duration-ticks: 20
darken-effect-particle: CLOUD
## {time} 的时间格式
time-format: "HH:mm:ss"
## 重生消息
respawn-message-enabled: true
respawn-message: "&a¡{player} has returned from the dead!"
# === 新增特性 ===
# 史诗死亡系统
epic-death-chance: 0.05 # 史诗死亡发生的概率 (0.0 到 1.0)
# 成本系统（需要 Vault）
cost-per-death-message: 0.0 # 设置为 0.0 以禁用收费。
exempt-groups-from-cost:
- "admin" # 此组中的玩家不必支付。
# 遗留支持 (适用于 MC < 1.16)
legacy-color-support: false # 设置为 true 以自动删除 <#rrggbb> 代码。
# === 帮助权限 ===
help-permissions:
op: "all"
admin: "all"
vip: [1, 2]
default: [1]
```
### 📄 messages.yml (关键片段 - v0.0.7)
```yaml
# ==============================================================================
# 🎯 自定义死亡消息 - 消息 & 效果配置
# ==============================================================================
# 插件作者：SicklySurgeon | 版本：0.0.7
#
# 📌 集成占位符指南 (首次阅读此内容！)
# -----------------------------------------------------------------------------
# {victim}, {killer_name}, {killer_source}, {cause}, {world}, {biome}, {x}, {y}, {z}, {time}, {distance}, {victim_weapon}, {victim_effects}, {cost}
# 💡 您可以使用其他插件的任何 PlaceholderAPI 占位符。
# ==============================================================================
# ==============================================================================
# 💥 史诗死亡消息 & 效果
# ==============================================================================
epic-messages:
- "&6&l!!! 史诗死亡 !!! &e{victim} &6被 &e{killer_name}&6消灭了！"
- "&4&l!!! 末日 !!! &c{victim} &4消失在 &c{killer_name}&4的手中！"
- "&5&l!!! 最终幻想 !!! &d{victim} &5屈服于 &d{killer_name}&5！"
- "&b&l!!! 狙击手 !!! &3{victim} &b被 &3{killer_name}&b从 &3{distance} &3块外击中了！"
# 史诗死亡视觉/音效效果（覆盖全局设置）
system-messages:
epic-sound: "ENTITY_LIGHTNING_BOLT_THUNDER"
epic-particle: "EXPLOSION_EMITTER"
epic-particle-count: 100
epic-title: "&6&l史诗死亡！"
epic-subtitle: "&e{victim} 以史诗的方式死了！"
# ==============================================================================
# 🧠 条件消息 (智能、情境化的消息)
# ==============================================================================
# 操作符: contains, equals, startsWith, endsWith, >, <, >=, <=
# 使用 AND / OR 组合。
default:
messages:
ENTITY_ATTACK:
- condition: "{distance} > 10"
message: "&c{victim} &4被 &c{killer_name}&4从 &c{distance} &4块外击中！"
- condition: "{victim_effects} contains 'Poison'"
message: "&c{victim} &2被 &c{killer_name}&2毒死了！"
- default: "&c{victim} &4被 &c{killer_name}&4消灭了，使用了 {killer_source}。"
# ==============================================================================
# ⚙️ 系统 & 命令消息
# ==============================================================================
system-messages:
# ... (已存在的系统消息) ...
# === 史诗死亡效果 ===
epic-sound: "ENTITY_LIGHTNING_BOLT_THUNDER"
epic-particle: "EXPLOSION_EMITTER"
# === 经济 ===
economy-cost-message: "&c${cost} &7已从您的帐户中扣除。"
economy-insufficient-funds: "&c您无力支付死亡消息费用(${cost})。"
economy-exempt-message: "&7(免于收费)"
# ✅✅✅ 新增：配置验证器的系统消息 ✅✅✅
config-validator-title: "✅ [CustomDeathMessages] 配置验证："
config-validator-success-all: "✅ 所有配置都是有效的！"
config-validator-summary-prefix: "ℹ️ 当前配置： "
config-validator-error-count: "❌ 发现 {error_count} 个问题。请查看上方的消息。"
# 成功消息
config-validator-sound-found: "✅ 找到了音效 '{sound_name}'。"
config-validator-particle-found: "✅ 找到了粒子 '{particle_name}'。"
# 错误消息
config-validator-sound-not-found: "❌ 找不到音效 '{sound_name}'。将使用默认值。"
config-validator-particle-not-found: "❌ 无效的粒子 '{particle_name}'。将使用默认值。"
# 警告消息 (条件)
config-validator-condition-syntax-warning: "⚠️ 警告：位置 '{location}' 中的条件 '{condition}' 具有语法错误 (无效的操作符 '{operator}')。"
config-validator-condition-placeholder-warning: "⚠️ 警告：位置 '{location}' 中的条件 '{condition}' 中存在格式错误的占位符。"
# 配置摘要
config-validator-summary-message-to-world: "消息到世界。 "
config-validator-summary-message-to-radius: "半径：{radius} 个方块。 "
config-validator-summary-sound-enabled: "声音：已启用。 "
config-validator-summary-sound-disabled: "声音：已禁用。 "
config-validator-summary-particles-enabled: "粒子：已启用。 "
config-validator-summary-particles-disabled: "粒子：已禁用。 "
```
---
## 🎮 命令
| 命令 | 描述 | 权限 |
|---|---|---|
| `/cdmreload` | 重新加载 `config.yml` 和 `messages.yml`。使用原子重新加载：如果配置无效，将安全地回滚到旧配置。 | `cdm.reload` |
| `/cdm test [killer_name] [killer_source]` | 测试死亡消息。 您可以选择指定一个 `[killer_name]` 和一个 `[killer_source]`。 | `cdm.test` |
| `/cdmhelp [page]` | 在游戏中显示全面、多页帮助指南。 页面的生成是动态的，并且基于权限控制。 | `cdm.test` |
| `/cdm config validate` — **新增！** | 扫描您的 `config.yml` 和 `messages.yml` 文件，查找无效的音效、粒子和条件语法，并输出详细的报告。 | `cdm.reload` |
---
## 🔐 权限
| 权限 | 描述 | 默认值 |
|---|---|---|
| `cdm.reload` | 允许重新加载配置 **并使用新的 `/cdm config validate` 命令**。 | `op` |
| `cdm.test` | 允许测试消息以及使用 `/cdmhelp`。 | `op` |
| `cdm.bypass` | 玩家将不会收到死亡消息。 | `false` |
| `cdm.message.vip` | 为玩家分配 "vip" 组。 | `false` |
| `cdm.message.admin` | 为玩家分配 "admin" 组。 | `false` |
| `cdm.admin` | 授予访问更新检查器通知的权限。 | `op` |
> **注意：** 要启用基于权限的消息，请在 `config.yml` 中将 `use-permission-based-messages: true` 设置为 true，然后将 `cdm.message.vip` 或 `cdm.message.admin` 分配给玩家。
---
## 🧪 占位符
这些可以在 `messages.yml` 中的任何消息中使用：
* `{victim}` — 死亡的玩家。
* `{killer_name}` — 造成杀戮的 **实体** (例如，射出箭矢的骷髅)。
* `{killer_source}` — 造成伤害的 **直接来源** (例如，“Arrow”、“Lava”、“Fireball”)。
* `{killer_displayname}` — 杀手的显示名称（支持插件，如 EssentialsX 或 LuckPerms 的颜色/昵称）。
* `{cause}` — 技术死亡原因 (例如，`FALL`、`ENTITY_ATTACK`)。
* `{world}` — 世界名称。
* `{biome}` — 生物群系名称（例如，“Plains”、“Nether Wastes”、“Deep Dark”）。
* `{x}`、`{y}`、`{z}` — 死亡坐标。
* `{time}` — 服务器时间（从 `config.yml` 格式化）。
* `{distance}` — 受害者和杀手之间的距离（单位：方块），格式化为一位小数（例如，“5.2”）。
* `{victim_weapon}` — 受害者主手中武器的名称（用于条件）。
* `{victim_effects}` — 受害者拥有的所有活动药水效果列表（用于条件）。
---
## ❓ 常见问题
**问：如何启用基于权限的消息？**
> 答：在 `config.yml` 中将 `use-permission-based-messages: true` 设置为 true，然后将 `cdm.message.vip` 或 `cdm.message.admin` 分配给玩家。
**问：为什么旧服务器上不起作用（`<#rrggbb>`）的十六进制颜色？**
> 答：将 `legacy-color-support: true` 设置为 `config.yml`。 插件将自动删除十六进制代码以提高兼容性。
**问：如何在不死亡的情况下测试消息？**
> 答：使用 `/cdm test [killer_name] [killer_source]`，例如 `/cdm test ENTITY_ATTACK Skeleton Arrow`。
**问：如果玩家有多个组权限会怎样？**
> 答：优先级顺序：`admin` > `vip` > `default`。 匹配第一个。
**问：如何向玩家收取展示死亡消息的费用？**
> 答：安装 Vault 和经济插件（如 EssentialsX）。 将 `cost-per-death-message` 设置为大于 0.0 的值在 `config.yml` 中。将组添加到 `exempt-groups-from-cost` 以排除他们。
**问：什么是史诗死亡？**
> 答：这是一个罕见的、壮观的死亡事件。 它可以配置概率 (`epic-death-chance`) 并且具有独特的死亡消息、音效、粒子、标题和闪电击中。 在 `messages.yml` 中定义史诗消息和效果。
**问：`{killer_name}` 和 `{killer_source}` 有什么区别？**
> 答：`{killer_name}` 是最终负责杀戮的实体 (例如，骷髅)。 `{killer_source}` 是直接击中玩家的东西 (例如，“Arrow”、“Lava”、“Fireball”)。这允许非常详细的消息。
**问：如何在配置生效之前知道我的配置是否已损坏？** — **新增！**
> 答：运行 `/cdm config validate`! 此命令将扫描文件并提供清晰、彩色报告的任何错误或警告，以便您在它们造成问题之前修复它们。
---
## 🛠️ 依赖项
* **必需：** Spigot 或 Paper **1.17+**。
* **可选 (软依赖)：**
* [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) 以获得扩展的占位符支持。
* [Vault](https://www.spigotmc.org/resources/vault.34315/) 用于经济集成。
## 💡 专业提示
* 使用 `/cdmhelp` 来获取所有您需要的信息，而无需离开游戏。
* 将 `cost-per-death-message: 10.0` 和 `exempt-groups-from-cost: ["admin"]` 设置为公平地将死亡货币化。
* 将 `{time}` 与 `time-format: "h:mm a"` 结合起来，以获得诸如“Bob 在下午 3:45 死亡”之类的消息。
* 将 `epic-death-chance: 0.01` 设置为真正罕见和难忘的事件。
* 结合 `{biome}` 来创建沉浸式的特定世界消息（例如，“被地狱吞噬”）。
* 原子重新加载 (`/cdmreload`) 意味着您可以毫不犹豫地试验配置。
* **v0.0.7 的 #1 专业提示：在编辑配置文件并运行 `/cdmreload` 之前，始终运行 `/cdm config validate`。 这是您获得稳定、无错误服务器的新最佳朋友。**
---
使用 `CustomDeathMessages` v0.0.7，**死亡不再是结束…… 它是一个电影般的事件，一种策略性成本，一种特定于生物群系的故事情节，一种完全记录的体验，现在还是一种保证稳定的体验，这要感谢集成的验证器。** 💀⚡💰🌍✅