Skip to main content

FAQ & Troubleshooting

General​

How does the gravestone system work?​

When a player dies, their items are stored in a gravestone block at the death location instead of dropping on the ground. The player can return to the gravestone, press F to open the loot UI, and click "Loot All" to recover their items.

What happens if I die again before recovering my items?​

A new gravestone is created for each death. You can have up to maxGravestonesPerPlayer active gravestones (default: 5). When this limit is exceeded, the oldest gravestone is automatically deleted.

Can other players loot my gravestone?​

During the protection period (protectionTimerSeconds, default: 300 seconds / 5 minutes), only the owner can loot the gravestone. After the protection expires, anyone can loot it.

Do gravestones despawn?​

By default, no — gravestoneLifetimeSeconds is set to -1 (never). If you set a positive value, gravestones will despawn after that many seconds. A warning is sent to the owner lifetimeWarningBeforeSeconds before expiry.

Economy & Purchases​

How do premium designs and particles work?​

Premium designs and particles can be purchased with in-game currency if VaultUnlocked is installed. Without VaultUnlocked, premium items can only be unlocked via admin commands (design_give, particle_give).

Which economy plugins are supported?​

The plugin checks for economy providers in this order:

  1. KyuubiSoft Core — uses Core's ExternalEconomyBridge (supports VaultUnlocked + EliteEssentials)
  2. VaultUnlocked direct — connects via the vault2 API
  3. Disabled — no economy, admin commands only

Can I charge for teleporting to gravestones?​

Yes — set allowTeleportToGravestone: true and configure teleportCost and teleportCurrency in the config. Set teleportCost to 0 for free teleports.

Designs & Particles​

How do I add custom gravestone designs?​

See Custom Designs. Create a JSON file in custom-items/, set the Parent to any vanilla furniture item, restart twice, and the design appears automatically.

Why does adding a custom design require two restarts?​

The first restart generates a designs JAR file from the JSON templates. The second restart loads the generated JAR with the new items.

Can I change the loot UI background?​

Yes — replace images/gravestone_bg.png with your own 350×497 PNG image. Restart the server.

Item Loss​

How does item loss work?​

When enabled, a configurable percentage of items are destroyed on death before being stored in the gravestone:

ModeBehavior
BLACKLISTAll items can be lost (default rate), except items in the list
WHITELISTNo items lost, except items explicitly in the list
NONENo item loss

Per-item loss percentages can be configured:

"itemLoss": {
  "enabled": true,
  "mode": "BLACKLIST",
  "defaultLossPercent": 10,
  "items": {
    "Key_Dungeon": { "lossPercent": 0 }
  }
}

Troubleshooting​

Gravestone doesn't spawn on death​

  • Check that the plugin is loaded: look for [Graveyard] Setup complete in server logs
  • Verify captureMode is set (DROPPED_ONLY or ALL_ITEMS)
  • Check if the death location is valid (not in a void or unloaded chunk)
  • The gravestone uses smart placement — it avoids existing blocks and skips trees/leaves

Loot UI doesn't open when pressing F​

  • Ensure the gravestone block has IsUsable: true
  • Check that the CollectGravestoneInteraction listener is registered
  • Verify the gravestone hasn't expired or been removed by an admin

Custom designs don't appear​

  • Verify the JSON file is in custom-items/ (not in a subdirectory)
  • Check that the Parent field is a valid vanilla furniture item ID
  • Restart the server twice (generate JAR → load JAR)
  • Check server logs for errors during design generation

WorldMap marker not showing​

  • Ensure showWorldMapMarker is true in config
  • Markers are only visible to the gravestone owner
  • The marker provider requires the WorldMap API — check for integration errors in logs

Economy purchases not working​

  • Verify VaultUnlocked is installed and has an active economy provider
  • Check server logs at startup for: [Graveyard] Economy via...
  • Ensure the currency field in design/particle configs matches your economy provider

Database errors​

  • For SQLite: ensure the graveyard.db file has write permissions
  • For MySQL: verify connection settings in database.mysql
  • Check server logs for SQL exceptions