CustomDeathMessages

Advanced, context-aware death message and effect management for Minecraft servers.

CustomDeathMessages replaces standard server death notifications with a highly customizable, condition-based messaging engine. It provides server administrators with granular control over death messages, audio cues, particle effects, and visual overlays, ensuring that every player death aligns with the server's unique atmosphere and gameplay loop.

---

Table of Contents

1. Core Capabilities
2. Requirements
3. Commands & Permissions
4. Placeholder Reference
5. Configuration Architecture
6. Upgrade Guide (v1.4)
7. Frequently Asked Questions

---

Core Capabilities

Context-Aware Messaging Engine

• Conditional Logic: Define complex message triggers using AND/OR operators and mathematical/string evaluations (e.g., >, <, contains, equals).
• Granular Routing: Assign specific messages based on permission groups (VIP, Admin, Default), specific worlds, or individual death causes.
• Message Cooldowns: Built-in logic prevents the same randomized message from displaying consecutively to the same player.

Advanced Broadcast System

Take absolute control over who experiences death effects. Every effect (Messages, Sounds, Particles, Titles, Action Bars) can be routed independently using four distinct modes:

• GLOBAL: Broadcast to all online players across the entire server.
• WORLD: Restrict the effect to players in the same world as the victim.
• RADIUS: Limit the effect to players within a configurable block radius.
• VICTIM_ONLY: Ensure the effect is only seen/heard by the player who died.

Visual and Audio Effects

• Custom Audio: Assign global or group-specific death sounds with adjustable volume and pitch.
• Particle Systems: Trigger custom particle explosions or ambient effects upon death.
• Screen Overlays: Utilize Titles, Subtitles, and Action Bars for immediate visual feedback.
• Darken Screen Effect: Simulate a fading/darkening screen effect using localized ambient particles.
• Epic Deaths: Configure a percentage-based chance for "Epic" deaths, triggering unique messages, overridden audio/visuals, and environmental effects like lightning strikes.

Economy and Administration

• Vault Integration: Charge players a configurable fee for displaying custom death messages, with exemption lists for staff or VIP groups.
• Atomic Reloading: The /cdm reload command validates the entire configuration in memory before applying it. If validation fails, the plugin safely aborts the reload, preventing server crashes or broken states.
• Comprehensive Testing Suite: Preview and calibrate messages, sounds, and broadcast radii in real-time without requiring actual player deaths.

---

Requirements

• Server Software: Spigot, Paper, or compatible fork.
• Minecraft Version: 26.3
• Java Environment: Java 17 or higher.
• Soft Dependencies (Optional):
  • PlaceholderAPI: For expanding messages with external plugin placeholders.
  • Vault: For economy integration and per-message costing.
  • EssentialsX: For automatic nickname resolution in death messages.

---

Commands & Permissions

All primary commands are routed through the unified /cdm namespace for a streamlined administrative experience.

Command	Description	Permission
/cdm test <cause> [killer] [source]	Simulates a death event to preview messages and effects.	cdm.test
/cdm broadcast <type> <mode> [args]	Manually triggers and tests broadcast effects (sound, particle, message).	cdm.broadcast
/cdm config validate	Runs a deep structural validation of config.yml and messages.yml.	cdm.reload
/cdm reload	Safely reloads all configuration files with atomic validation.	cdm.reload
/cdm help [command]	Displays comprehensive, context-aware documentation.	cdm.use

Permission Nodes

Permission Node	Description	Default
cdm.use	Base access to the /cdm command router and help menus.	true
cdm.test	Allows usage of the testing and simulation suite.	op
cdm.broadcast	Allows manual triggering of broadcast effects.	op
cdm.reload	Grants access to reload and validation commands.	op
cdm.bypass	Exempts the player from triggering death messages or effects.	false
cdm.message.vip	Assigns the player to the "vip" message and effect group.	false
cdm.message.admin	Assigns the player to the "admin" message and effect group.	false

---

Placeholder Reference

The plugin natively resolves deep contextual data regarding the death event. These can be used in messages.yml and are fully compatible with PlaceholderAPI expansions.

Placeholder	Description
{victim}	The display name (or nickname) of the player who died.
{killer_name}	The entity responsible for the kill (e.g., the Player who shot the arrow, or the Creeper).
{killer_source}	The direct source of the damage (e.g., "Arrow", "Fireball", "Lava").
{killer_displayname}	The killer's formatted display name, including external prefixes/suffixes.
{cause}	The technical Bukkit damage cause (e.g., FALL, ENTITY_ATTACK, VOID).
{world}	The name of the world where the death occurred.
{biome}	The formatted name of the biome (e.g., "Deep Dark", "Nether Wastes").
{x}, {y}, {z}	The exact block coordinates of the death location.
{distance}	The distance in blocks between the victim and the killer (formatted to one decimal).
{victim_weapon}	The display name of the item held in the victim's main hand.
{victim_effects}	A comma-separated list of active potion effects on the victim.
{time}	The current server time, formatted via config.yml.
{cost}	The economic cost deducted for the message (if Vault is enabled).

---

Configuration Architecture

The plugin separates routing logic from text and visual definitions to ensure clean maintainability:

1. config.yml: Governs global server behavior. This includes broadcast routing modes, economy settings, global particle/sound definitions, visual effect toggles, and validation rules.
2. messages.yml: Contains all text-based data. This includes conditional messages, group-specific definitions, epic death pools, and all system/command feedback messages. Server owners can fully translate or customize every string the plugin outputs without touching the codebase.

---

Upgrade Guide (v1.4)

Version 1.4 represents a major stability and architecture milestone.

• Platform Update: The plugin now targets Minecraft 26.3 and requires Java 17.
• Complete Language Externalization: All hardcoded system messages, command errors, and help menus have been moved to messages.yml. You can now fully translate the plugin's administrative interface.
• Killer Resolution Overhaul: The logic for determining {killer_name} and {killer_source} has been completely rewritten to accurately distinguish between environmental deaths, projectile shooters, and direct melee attackers, fixing edge cases where victims were incorrectly listed as their own killers.
• Thread Safety: Asynchronous event handling has been corrected to ensure all world and entity data is processed strictly on the main server thread, eliminating concurrency errors on high-population servers.

Note: Your existing config.yml and messages.yml structures are fully backward compatible. The plugin will automatically generate any missing system-message keys upon startup.

---

Frequently Asked Questions

How does the plugin differentiate between {killer_name} and {killer_source}? The tracking engine analyzes the damage event chain. If a player is killed by an arrow shot by a Skeleton, {killer_name} will resolve to "Skeleton" (the responsible entity), while {killer_source} will resolve to "Arrow" (the direct object that dealt the damage).

What happens if my configuration contains syntax errors during a reload? The atomic reload system intercepts the process. If ConfigValidator detects structural errors, invalid placeholders, or missing required nodes, the reload is aborted. The plugin will continue running safely on the previous, stable configuration, and output a detailed diagnostic report to the administrator.

Can I restrict specific visual effects to only the dying player? Yes. Using the effects-broadcast section in config.yml, you can set title-mode: VICTIM_ONLY and actionbar-mode: VICTIM_ONLY, while keeping sound-mode: WORLD to ensure nearby players hear the death sound without having their screens obstructed by UI elements.

Does this plugin support external economy plugins? Yes. If Vault is installed and an economy provider is present, you can enable cost-per-death-message. You can also define exempt-groups-from-cost to ensure staff or specific VIP tiers are not charged for their death messages.