📚 Custom Death Messages - Official Documentation (v1.3)

Turn every death into a cinematic moment… or an EPIC apocalypse. Now with a unified command system, simplified permissions, and fine-grained broadcast control for every effect.

CustomDeathMessages is a Spigot/Paper plugin for Minecraft servers that replaces boring, default death messages with custom, dynamic, colorful messages, complete with optional sound effects, particle explosions, screen titles, action bars, economic costs, and even a "darken screen" effect. Version 1.3 is a major feature release that builds on the stable foundation of v1.0 by introducing a powerful new broadcast system, dedicated testing commands, full support for Minecraft 1.21.11, and the complete removal of the in-game editor to prioritize core stability and performance. This release focuses on precision, control, and reliability, giving server administrators unprecedented control over who experiences each death effect.

⚠️ UPGRADE INSTRUCTIONS
Your existing configuration files are fully compatible. However, please note these important changes:

1. Editor Removal: The in-game configuration editor (/cdm editor) has been completely removed from the plugin. All configuration must now be done manually by editing the config.yml and messages.yml files.
2. New Broadcast System: The plugin now offers four modes for controlling who sees death effects. Your old message-to-* settings are respected, but you can now use the new, more powerful effects-broadcast section in config.yml.
3. New Commands: A powerful new /cdm broadcast command suite has been added for testing and triggering effects.
4. Minecraft 1.21.11 Support: The plugin has been updated and tested for the latest Minecraft version.
5. Internal Architecture: The plugin's core has been completely refactored for better reliability and future development. You, as a user, won't see any difference in basic functionality, but it's more stable and maintainable.

---

🧩 Features

• Death Cause Messages: Unique messages for FALL, FIRE, ENTITY_ATTACK, DROWNING, VOID, and more.
• Permission-Based Groups: VIPs, Admins, or default players get tailored messages and sounds.
• Per-World Overrides: Define special messages for world_nether, world_the_end, or any custom world.
• Visual Effects:
  • Particle explosions (EXPLOSION, FLAME, etc.)
  • Screen Titles & Subtitles (&cYOU DIED)
  • Action Bar messages (&c{victim} died!)
  • "Darken Screen" effect using ambient particles (e.g., CLOUD, SMOKE)
• Custom Sounds: Global or per-group death sounds with adjustable volume and pitch.
• Advanced Placeholders:
  • {victim} — Player who died.
  • {killer_name} — The entity RESPONSIBLE for the kill (e.g., the Skeleton who shot the arrow).
  • {killer_source} — The DIRECT source of the damage (e.g., "Arrow", "Lava", "Fireball").
  • {killer_displayname} — Killer's display name (supports colors/nicks from plugins like EssentialsX or LuckPerms).
  • {cause} — Technical death cause (e.g., FALL, ENTITY_ATTACK).
  • {world} — World name.
  • {biome} — Biome name (e.g., "Plains", "Nether Wastes", "Deep Dark").
  • {x}, {y}, {z} — Death coordinates.
  • {time} — Server time (format from config.yml).
  • {distance} — Distance (blocks) between victim and killer, with one decimal (e.g., "5.2").
  • {victim_weapon} — Name of the weapon in the victim's main hand.
  • {victim_effects} — List of active potion effects on the victim.
• PlaceholderAPI Support: Expand functionality with external placeholders.
• Respawn Message: Welcome players back with a custom message on respawn.
• Live Reload: Use /cdm reload to apply config changes without restarting. Features atomic reload: if the new config fails, it reverts to the old one.
• Test Command: Use /cdm test <CAUSE> [killer_name] [killer_source] to preview messages. You can specify both the responsible entity and the direct damage source.
• Bypass Permission: Players with cdm.bypass won't trigger death messages (ideal for staff).
• Message Cooldown System: Prevents the same random message from being shown to a player consecutively.
• Epic Death System: A configurable chance for a death to be EPIC, featuring unique messages, sounds, particles, titles, and a lightning strike.
• Vault Economy Integration: Charge players for displaying death messages. Exempt groups (like admins) from paying.
• In-Game Help (/cdm help): A multi-page, fully configurable help system accessible directly in-game. Dynamically generated and permission-controlled.
• Conditional Messages: Show different messages based on complex conditions using AND, OR, equals, startsWith, endsWith, >, <, >=, <=.
• Legacy Color Support: Automatically strips modern hex color codes for compatibility with servers running Minecraft versions older than 1.16.
• Atomic Configuration Reload: The /cdm reload command now validates the entire new configuration before applying it. If any part fails, the plugin safely reverts to the previous state, preventing server crashes.
• Automatic Update Notifications — The plugin checks for new versions on startup and notifies admins when they join the server with a direct link to download the update.
• Minecraft 1.21.11 Support — NEW in v1.1! Fully compatible and tested with the latest Minecraft version, including all new sounds, particles, and biome names.
• Advanced Broadcast System — NEW in v1.1! Take total control over who experiences each death effect with four broadcast modes:
  • GLOBAL: All online players on the server.
  • WORLD: All players in the same world as the victim.
  • RADIUS: Only players within a configurable distance.
  • VICTIM_ONLY: Only the dying player sees/hears the effect.
• Powerful /cdm broadcast Command Suite — NEW in v1.1! Test and trigger any broadcast effect manually:
  • /cdm broadcast sound <mode> [radius] [sound]
  • /cdm broadcast particle <mode> [radius] [particle]
  • /cdm broadcast message <mode> <message>
  • /cdm broadcast test – Simulates all broadcast modes.
  • /cdm broadcast global <type> – Send an effect to all players instantly.

---

⚙️ Configuration

(Configuration details for config.yml and messages.yml remain as previously described in your last documentation, with the messages.yml file now on version 1.1 and containing the new broadcast-system section.)

---

🎮 Commands

Command	Description	Permission
/cdm	Shows the main menu of available commands	cdm.use
/cdm test <cause> [killer] [source]	Test a death message with optional parameters	cdm.test
/cdm broadcast ...	NEW! Test and trigger broadcast effects manually	cdm.broadcast
/cdm help [command]	Shows comprehensive help documentation in-game	cdm.use
/cdm config validate	Validates configuration files for errors	cdm.reload
/cdm reload	Reloads configuration with atomic reload	cdm.reload

All commands now use the unified /cdm prefix - This provides a consistent, streamlined interface that's easier to remember and use.

---

🔐 Permissions

Permission	Description	Default
cdm.use	Base permission for accessing the main /cdm command	true
cdm.reload	Allows reloading config and using /cdm config validate	op
cdm.test	Allows testing messages	op
cdm.broadcast	NEW! Allows access to the broadcast testing suite	op
cdm.bypass	Player won't receive death messages	false
cdm.message.vip	Assigns player to "vip" group	false
cdm.message.admin	Assigns player to "admin" group	false
cdm.admin	Grants access to update checker notifications	op

---

🧪 Placeholders

The placeholder list remains the same as v1.0, offering deep contextual information for your messages.

---

❓ FAQ

Q: How do I control who sees my death effects now?

A: Use the new effects-broadcast section in config.yml. You can set a default-mode for all effects or override it for specific ones like sound-mode or title-mode.

Q: What's the difference between the old message-to-* and the new broadcast system?

A: The old system only controlled the death message. The new broadcast system gives you fine-grained control over every effect: messages, sounds, particles, titles, and the darken screen.

Q: How can I test the new broadcast modes?

A: Use the new /cdm broadcast test command to see how many players each mode would reach, or use /cdm broadcast sound WORLD to play a sound to your entire world.

Q: Is this plugin compatible with Minecraft 1.21.11?

A: Yes! Version 1.1 has been fully built, tested, and verified to work with Minecraft 1.21.11.

Q: Do I need to reconfigure everything for v1.1?

A: No! Your existing config.yml and messages.yml files will work perfectly. The new broadcast settings have sensible defaults that mimic the old behavior, so your server will function exactly as before. You can then choose to adopt the new features at your own pace.

Q: What happened to the in-game editor?

A: The in-game configuration editor (/cdm editor) has been completely removed in v1.1. All configuration must now be done by manually editing the config.yml and messages.yml files in your server's plugins/CustomDeathMessages/ folder.

The rest of the FAQ from v1.0 remains valid and unchanged.

---

🛠️ Dependencies

• Required: Spigot or Paper 1.17+.
• Built Against: Spigot API 1.21.11.
• Optional (Soft-depend):
  • PlaceholderAPI for extended placeholder support.
  • Vault for economy integration.

💡 Pro Tips

• The #1 Pro Tip for v1.1: Use /cdm broadcast test to perfectly calibrate your RADIUS settings before going live.
• Set your title-mode and actionbar-mode to VICTIM_ONLY for a personal, immersive experience.
• Use GLOBAL mode for sounds and particles on epic deaths to make them a true server-wide event.
• Combine the new broadcast system with the existing conditional messages to create deeply immersive, context-aware death events that feel alive.
• Remember: There is no longer an in-game editor. Embrace the power and precision of direct file editing!