FAQ & Troubleshooting

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:

Mode	Behavior
BLACKLIST	All items can be lost (default rate), except items in the list
WHITELIST	No items lost, except items explicitly in the list
NONE	No 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
• Check excludedWorlds: if the death world (or a wildcard matching it) is in the list, no gravestone spawns there by design. See Configuration → World Exclusion

Console spams Integrity check failed: ... World thread is not accepting tasks

Fixed as of 2026-04-23. The tickIntegrity scheduler used to submit a restore-task to every world holding a gravestone every 5 seconds — when a world was in the middle of unloading (dimension switch, world close, server shutdown), the world thread rejected the task and the outer catch logged a WARNING stack trace. Every tick. Multiple worlds = console flooded.

All world.execute(...) calls now go through an internal safeWorldExecute helper that catches IllegalStateException/IllegalThreadStateException at submission time, logs at FINE, and continues with the next gravestone. If you’re on an older build, update; if you see this on the latest build please open an issue.

If you want the integrity check to skip certain worlds entirely (e.g. read-only showcase worlds where you don’t care about block restore), add them to excludedWorlds — see the configuration page.

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