VZone Plugins/VGraves/Grave System

VGRAVES

Grave System

This page explains the full runtime lifecycle of a grave: death checks, save rules, reclaim paths, pricing, expiration, limits, and cleanup.

Death Save Flow

  1. The plugin first checks exclusions such as grave-permissions, keep-inventory logic, optional WorldGuard rules, and exception item filters.
  2. The inventory is snapshotted into typed saved-item entries from storage, armor, offhand, and XP.
  3. A grave is created with id, timestamps, world, coordinates, items, XP, and reclaim price.
  4. If the player is already at the configured maximum amount of saves, the oldest grave is removed first.

Claim Modes

Ticket reclaim

  • Checks grave existence, expiration, ticket usage limit, and ticket balance.
  • If restore fails, the ticket and usage changes are rolled back.

Currency reclaim

  • Checks price availability, reclaim limit, balance, withdraw command, optional balance verification, restore, and grave removal.
  • If restore fails after withdrawal, the plugin attempts a refund with the configured give command.
Delayed balance verification callbacks are flushed on reload and disable so a half-finished money flow cannot remain stuck during plugin lifecycle changes.

Pricing Rules

  • Fixed pricing uses pricing.fix.values and is checked first.
  • Calculated pricing uses base_price, per_item, scale_multiplier, and max_price.
  • If both are enabled, calculated pricing becomes a fallback only when no fixed value exists for the current claim number.
  • If only fixed pricing is enabled and no matching claim number exists, currency reclaim is unavailable for that grave.

Usage Limits and Expiration

  • maximum_buy_usage and maximum_ticket_usage track reclaim limits. -1 means unlimited.
  • Every grave stores an expiration timestamp.
  • Expired graves are processed on startup, repeating cleanup, and grave load.
  • DELETE removes the grave, while DROP releases main items, armor, offhand, and XP at the original death location.

Storage Backends

LOCAL   - plugins/VGraves/players/<uuid>.json
MYSQL   - relational SQL tables through HikariCP
MARIADB - relational SQL tables through HikariCP
H2      - embedded SQL database through HikariCP

The plugin also supports savePlayerData, saveAll, and cleanupExpired operations through the public API for integration scenarios.

PreviousCommandsNextGUIs Overview