Mechanics

What happens on death

On every player death, AlphaGraves captures the full 36-slot inventory, all armor, the offhand item, and total XP — then clears vanilla's own drops and XP loss entirely so nothing hits the ground on its own. From there, exactly one of three systems takes over, in this priority order:

1. PvP Grave — if the kill was a direct melee hit from another player (not a projectile) and pvp-grave.enabled is true.
2. Grave Slot — otherwise, the items go into the player's next available slot (see below).
3. Fallback Grave — if every slot the player has permission for is currently on cooldown.

Items drop naturally instead of going into a grave when a physical grave is needed but not allowed: the world is in no-fallback-worlds, or fallback-grave.enabled is false and every slot is full. The same applies to a PvP kill in a no-fallback-worlds world.

Grave Slots

Each slot is an independent, permission-gated container a player can own, configured entirely in config.yml under grave-slots. Four ship by default:

Claim delay is how long after death a grave stays locked before it can be opened at all. Reuse cooldown is how long after claiming before that same slot can hold a new grave. Every slot can also carry its own claim_cost (none / xp_levels / money) — money costs silently do nothing if Vault isn't installed. Add as many slots as you want beyond the default four; the GUI lists them in the order they're defined.

PvP Grave

A direct melee kill (sword, axe, fist — not a projectile, fire, lava, or fall) bypasses the entire slot system. A physical grave spawns right at the death location instead, regardless of whether the victim had a free slot.

pvp-grave:
  enabled: true
  who_can_open: anyone      # "owner" = only the victim/admins | "anyone" = killer too, after protection
  loot_protection: 5m       # only matters when who_can_open is "anyone"
  grave_expiration: 20m
  expire_action: drop       # "drop" scatters items | "delete" removes them permanently
  notify_victim: true

Projectile kills (arrows, tridents) are not treated as PvP grave triggers — those fall through to the normal slot system like any other death cause.

Fallback Grave

The safety net: when a player dies and every slot they have permission for is still on cooldown, a physical grave spawns at the death location so items are never simply lost to a full queue.

fallback-grave:
  enabled: true
  who_can_open: owner
  grave_expiration: 1h
  expire_action: drop
  claim_cost: {type: none, amount: 0}

world-settings.no-fallback-worlds can disable physical graves (both fallback and PvP) in specific worlds while keeping the normal slot system working — if every slot happens to be full there too, items drop naturally instead of spawning a grave.

Auto-Claim & Reminders

Both are opt-in per player through /graves settings — the plugin never force-claims or force-notifies without the player choosing to.

auto-claim:
  permission: alphagraves.graves.autoclaim
  check_interval_ticks: 100   # how often to scan online players (20 ticks = 1s)
  drop_overflow_items: true   # present in config.yml, but this version does not read it

grave-reminder:
  permission: alphagraves.graves.autoreminder

Claim costs

Every grave slot, PvP grave and fallback grave has a claim_cost block. One code path charges it for all three, so they behave the same way.

claim_cost:
  type: money    # none | xp_levels | money
  amount: 250    # whole number; 0 = free whatever the type

On physical graves the cost is paid once per player per grave, and the record of who has paid survives restarts. A claim never charges anyone for a grave whose items cannot be read, see Safe storage.

Visuals & Holograms

Physical graves (both fallback and PvP) show a floating, optionally spinning/bobbing marker item plus a text hologram above it.

grave-visual:
  display-item: PLAYER_HEAD   # any Material, or "basehead-<base64>" for a custom skull texture
  scale: 1
  animation: true             # takes effect immediately on /agraves reload
  view-range-blocks: 32       # how close a player must be to see the floating item

Both the marker and the hologram are only shown to players inside view-range-blocks, and the spin, bob and text updates pause while nobody is in range. Raise the values if graves need to be visible from further away.

display-item: PLAYER_HEAD shows the victim's own skin on the floating marker. The hologram supports full MiniMessage formatting and an unlimited number of lines — set lines: [] to hide it entirely.

grave-hologram:
  view-range-blocks: 16       # how close a player must be to see the text
  lines:        # normal (fallback) graves
    - ''
    - '&f{player}s <#FF0000>ɢʀᴀᴠᴇ'
    - '&fᴇxᴘɪʀᴇꜱ: <#FF0000>{time_remaining}'
    - '&fᴅᴇᴀᴛʜ ᴄᴀᴜꜱᴇ: <#FF0000>{death_cause}'
  pvp-lines:    # PvP graves — falls back to 'lines' if left empty
    - ''
    - '&f{player}s <#FF0000>ɢʀᴀᴠᴇ'
    - '&fᴋɪʟʟᴇʀ: <#FF0000>{killer}'
    - '&fᴇxᴘɪʀᴇꜱ: <#FF0000>{time_remaining}'

{killer} safely resolves to an empty string on non-PvP graves, so it's fine to leave it in a shared line.

Explosion Protection

On by default — prevents TNT, creepers, and any other explosion from destroying a grave's display entities. Set explosion-protection.enabled: false to allow graves to be blown up like any other entity.

Expiry

A physical grave disappears when its grave_expiration runs out, and expire_action decides what happens to the items: drop scatters them at the grave and delete removes them for good. The owner gets a chat message if they are online. The check runs once a minute.

If the grave's items cannot be decoded when it expires, the plugin does not drop or delete anything. It logs one error and leaves the data on disk for an admin to recover.

Safe storage

• Unreadable graves are never destroyed. If stored items cannot be decoded, a claim returns a "data error" message to the player, nothing is charged and nothing is removed.
• Corrupt player files are kept. A player file that fails to load is renamed to <uuid>.yml.corrupt-<timestamp> and the player starts with a fresh profile. The old file stays in playerdata/.
• Saves are batched. Dirty profiles are written every save-interval-ticks and on shutdown, and changes made while a save is running are not lost.