Caveats

Since this plugin is essentially "reimplementing" the death and respawning code, there will inevitably be some discrepancies between a player going into death spectating vs. a normal player death in Minecraft.

For server owners

Known non-vanilla behaviors of this plugin are documented here, along with a recommendation of how to deal with each: https://github.com/MLG-Fortress/DeathSpectating/issues?q=is%3Aissue+is%3Aopen+label%3A%22Non-vanilla+behavior%22 (Developers are welcome to help resolve/implement these behaviors via PRs or addons!)

You cannot enter death spectating mode when using Essentials' /suicide or /kill

• Essentials performs Player#setHealth(0), which does not fire a damage event that can be canceled. This means the player is actually killed; so the plugin ignores this case.

For developers

Here's the obvious:

Player#isDead() will always return false (except in cases where DeathSpectating does not handle the death).

• Include Player#hasMetadata("DEAD") when checking if a player is death spectating or not (and supposed to be effectively "dead"). You can also use DeathSpectating#isSpectating(Player) if you're hooking into the plugin.

Player#getGameMode() == SPECTATOR in PlayerDeathEvent

• The player's prior gamemode is stored in the DEAD metadata. Use (GameMode)Player#getMetadata("DEAD").get(0).value() to get this value.

• Some reasons why gamemode is set before firing PlayerDeathEvent:

  • Simplicity. If Player#hasMetaData("DEAD"), then we know for sure that they are in a death spectating mode, and as such have the appropriate spectating attributes (unless otherwise changed by another plugin).
  • Immediately setting a player to spectating gamemode ensures they don't accidentally pick up the very items/experience they're supposed to drop.

The player will not teleport while death spectating

• PlayerTeleportEvent is canceled (along with other related events) in MiscListeners when a player is death spectating.
• Also, if the killer is an entity, it will be tracked in a SpectateTask. You can disable this by setting the killer to null. You can get the task object when a DeathSpectatingEvent is fired (which occurs right before the task is scheduled to run).
• If you want to override this, the easiest way is to uncancel the PlayerTeleportEvent (along with a check to see if the player is death spectating, depending on your use case). If you require more functionality than this, open an issue or PR.