Package valorless.rarespawns.events

Class SoulboundEvent

java.lang.Object
valorless.rarespawns.events.SoulboundEvent
All Implemented Interfaces:
org.bukkit.event.Listener
public class SoulboundEvent extends Object implements org.bukkit.event.Listener
Listener responsible for implementing the "Soulbound" behavior for rare items.

When a player dies and the keepInventory gamerule for that world is disabled, this class intercepts the normal item drop flow and preserves any registered rare items whose ItemData.soulbound flag is true. Those items are temporarily stored in-memory and restored to the player upon respawn. If the player logs out before respawning, the items are safely dropped at the logout location to avoid loss on server restart.

Lifecycle

  • Registered once via init() during plugin enable.
  • State (saved soulbound items) only persists between death and respawn events for online players.

Thread Safety

Bukkit events run on the main server thread; no external synchronization is required. The internal savedItems map is only accessed synchronously on that thread.

Failure / Edge Cases

  • If plugin reloads between death and respawn, saved items are not persisted (intentional; no disk IO).
  • If the player inventory is full on respawn, standard Bukkit behavior places excess items in the world.
  • If keepInventory is enabled, the logic is bypassed entirely.

Usage

Mark an item as soulbound in its ItemData. On player death the item will return automatically on respawn instead of dropping.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SoulboundEvent()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    init()
    Registers this listener with the server's plugin manager.
    void
    onPlayerDeath(org.bukkit.event.entity.PlayerDeathEvent event)
    Captures soulbound rare items on player death so they are not dropped and can be restored on respawn.
    void
    onPlayerJoin(org.bukkit.event.player.PlayerJoinEvent event)
     
    void
    onPlayerRespawn(org.bukkit.event.player.PlayerRespawnEvent event)
     
    static void
    shutdown()
    Saves the current state of savedItems to the cache on plugin shutdown.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SoulboundEvent

      public SoulboundEvent()

  • Method Details

    • init

      public static void init()
      Registers this listener with the server's plugin manager.

    • shutdown

      public static void shutdown()
      Saves the current state of savedItems to the cache on plugin shutdown.

      This method should be called during the plugin's disable phase to persist any soulbound items that have been captured but not yet restored. The data is stored as a JSON string in the cache under the key "soulbound".

    • onPlayerDeath

      public void onPlayerDeath(org.bukkit.event.entity.PlayerDeathEvent event)
      Captures soulbound rare items on player death so they are not dropped and can be restored on respawn. Skips processing when the keepInventory gamerule is true.

      Processing:

      • Iterates through EntityDeathEvent.getDrops() and identifies rare items whose ItemData.soulbound flag is true.
      • Clones and removes those items from the drop list and stores them in savedItems keyed by the player's UUID.
      Parameters:
      event - the player death event

    • onPlayerRespawn

      public void onPlayerRespawn(org.bukkit.event.player.PlayerRespawnEvent event)

    • onPlayerJoin

      public void onPlayerJoin(org.bukkit.event.player.PlayerJoinEvent event)