# Configuration

**Version:** 2.0.1

The graveyard is configured in `mods/kyuubisoft_graveyard/config/graveyard.json`. The file is created with the built-in defaults on the first start. On every later start, options added by a newer version are written into it; the values you set are kept.

The `__comment_...` entries in the file explain some options and have no effect.

:::caution[Check the log after you edit]
If the file cannot be read (for example after a JSON syntax error), the log shows `Failed to load config: ...` and the plugin runs with built-in values (including the `default` design and the particle presets) until the file is fixed. The unreadable file is kept as it is: nothing is written into it, also not by custom designs, and the log says `Config not saved: ... could not be read and is kept as it is.` Fix the file and run `/ksgraveyard reload`.
:::

---

## Reload or restart

`/ksgraveyard reload` reads `graveyard.json`, the files in `custom-items/` and the language files again. Most options apply at once, with these exceptions:

| Change | Takes effect |
|--------|--------------|
| `protectionTimerSeconds`, `gravestoneLifetimeSeconds` | After reload, for **new** gravestones. Existing gravestones keep the times they got when they were created |
| `itemLoss`, `captureMode` | After reload, for the next deaths |
| `enableParticles` | Restart |
| `database` | Restart |
| Images in `images/` | Restart |
| New or changed custom designs | Two restarts, see [Custom Designs](./custom-designs) |

---

## Gravestones

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `protectionTimerSeconds` | Integer | `300` | Seconds a new gravestone can only be looted by its owner. `0` or less = no protection |
| `gravestoneLifetimeSeconds` | Integer | `-1` | Seconds until a gravestone disappears **with its contents**. `0` or less = never |
| `lifetimeWarningBeforeSeconds` | Integer | `60` | When this many seconds are left, the online owner is warned in chat |
| `maxGravestonesPerPlayer` | Integer | `5` | Gravestones a player can have. When a player with this many gravestones dies, the oldest one is removed with its contents first. `0` or less = no limit |

- Protection and lifetime are counted in real time from the moment of death, also while the server is offline.
- Expired gravestones are removed by a check that runs every 10 seconds; the chunk is loaded for that if needed. The owner gets "Your gravestone at X, Z has expired!" when online.
- The lifetime warning ("Your gravestone at X, Z expires in 42s!") is sent at every 10-second check inside the warning time, so the owner gets it several times.
- When the limit removes the oldest gravestone, the owner gets "Your oldest gravestone was deleted (limit reached)."

---

## Capture and map markers

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `captureMode` | String | `"DROPPED_ONLY"` | What goes into a gravestone. `DROPPED_ONLY` = the items the world's death settings would drop. `ALL_ITEMS` = the whole inventory, in worlds that drop items on death |
| `showWorldMapMarker` | Boolean | `true` | Shows each player their own gravestones on the world map. `false` hides the markers |

- `ALL_ITEMS` changes worlds that drop a share of the items on death: the whole inventory goes into the gravestone there, also armor and weapons that would otherwise stay with the player. Worlds that drop everything put everything in anyway, and worlds that keep the inventory still create no gravestone. Upper and lower case do not matter; any other value counts as `DROPPED_ONLY`.
- In both modes, items that KyuubiSoft Item Control marks as soulbound or drop-protected stay with the player. When Item Control (or another mod) has already chosen the items that drop, exactly those go into the gravestone.
- The Statistics tab shows the mode under "What goes into the gravestone".
- `showWorldMapMarker` applies with `/ksgraveyard reload`.

**Options without effect**

| Option | Default | Note |
|--------|---------|------|
| `showPlayerName` | `true` | There is no name tag above gravestones. The `__comment_name` line in the file says so |
| `spawnAtSafePosition` | `true` | Gravestones are always placed at the death position (moved to the ground or the nearest free spot). The `__comment_safe` line in the file says so |

---

## World exclusion: `excludedWorlds`

| Type | Default |
|------|---------|
| List of strings | `[]` |

No gravestone is created when a player dies in a listed world. The death is left to the game: items drop the normal way.

Entries are case-insensitive and support two wildcards:

- `*` matches any number of characters (also none)
- `?` matches exactly one character

```json
"excludedWorlds": [
  "lobby",
  "pvp_*",
  "dungeon_?_instance"
]
```

| Pattern | Matches | Does not match |
|---------|---------|----------------|
| `lobby` | `lobby`, `Lobby` | `lobby_1`, `main_lobby` |
| `pvp_*` | `pvp_arena`, `pvp_1v1`, `pvp_` | `arena_pvp`, `pv_team` |
| `dungeon_?_instance` | `dungeon_1_instance`, `dungeon_a_instance` | `dungeon_12_instance`, `dungeon__instance` |

Gravestones that already stand in a world you exclude later are not touched: they can still be looted and still expire. Remove them with `/ksgraveyard admin_clear` or `admin_remove` if you want them gone.

---

## Grave window: `classicLootLook`

| Type | Default |
|------|---------|
| Boolean | `false` |

- `false`: the new grave window (owner's head, contents with rarity rings, Loot all / Loot / memorial view), see [UI Pages](./ui-pages#the-grave-window).
- `true`: the old stone gravestone window from version 1.x with the images from `images/`, see [Images](#images-for-the-classic-window).

---

## Designs

A design decides which block a player's next gravestone uses.

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `defaultDesign` | String | `"default"` | Design used when a player's selected design no longer exists. New players always start with the design `default` |
| `gravestoneBlockId` | String | `"Furniture_KS_Gravestone"` | Item shown as icon in the menu when the block of a gravestone's design no longer exists |
| `designs` | Map | one entry, `default` | All designs. The key is the design ID used by `design_give` |

The built-in entry:

```json
"designs": {
  "default": {
    "displayName": "Simple Tombstone",
    "blockId": "Furniture_KS_Gravestone",
    "premium": false,
    "price": 0,
    "currency": "coins"
  }
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `displayName` | String | Name in the menu |
| `blockId` | String | Item ID of the block that is placed as gravestone |
| `premium` | Boolean | `false` = free for every player |
| `price` | Integer | With `premium: true`: price in the shop. `0` = cannot be bought, only admins can unlock it ("Locked") |
| `currency` | String | Only used for the graveyard-only currency (see [Purchases](#purchases-and-teleport)); ignored when prices are paid with the server economy |

- The `default` design is added again on every start if it is missing.
- Designs from `custom-items/` are added to this map automatically and updated from their JSON file on every start. Change them in the JSON file, not here. See [Custom Designs](./custom-designs).
- Only the built-in block `Furniture_KS_Gravestone` and the blocks of custom designs open the grave window with **F**. When a design's block cannot open it (a `blockId` of another mod or a vanilla block, or a custom design before the restart that loads its block), the gravestone gets `Furniture_KS_Gravestone` instead and the log says so. Use [Custom Designs](./custom-designs) for new looks.
- Gravestones placed with such a block by older versions cannot be opened; remove them with `/ksgraveyard admin_remove <id>`.
- Changing a player's design only affects gravestones created afterwards.

---

## Particles

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `enableParticles` | Boolean | `true` | Particles above gravestones, the Particles tab and the commands `particle_give` / `particle_revoke`. Needs a restart |
| `particles` | Map | four presets | All particle presets. The key is the particle ID |

The built-in presets:

| ID | `displayName` | `systemId` | `color` | Price |
|----|---------------|------------|---------|-------|
| `none` | No Particles | none | none | free |
| `golden_glow` | Golden Glow | `Block_Top_Glow` | `#ffd700` | 300 |
| `ghost_smoke` | Ghost Smoke | `Totem_Heal_AoE` | `#44ff88` | 500 |
| `arcane_pulse` | Arcane Pulse | `Drop_Legendary` | `#8844ff` | 750 |

```json
"golden_glow": {
  "displayName": "Golden Glow",
  "systemId": "Block_Top_Glow",
  "color": "#ffd700",
  "scale": 1.0,
  "premium": true,
  "price": 300,
  "currency": "coins"
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `displayName` | String | Name in the menu |
| `systemId` | String | Hytale particle system. Leave it out for "no effect" |
| `color` | String | Colour `#rrggbb` that tints the effect. The menu shows the closest of a few fixed swatch colours |
| `scale` | Number | Size of the effect, `1.0` = normal. Only used when `color` is set |
| `premium`, `price`, `currency` | | Same as for designs |

- The four presets are added again on every start if they are missing. To take one out of sale, set `"premium": true` and `"price": 0`; then only admins can unlock it.
- Particles are spawned every 3 seconds above every gravestone whose owner has chosen particles, in every world with gravestones, for players within 64 blocks. They follow the owner's **current** choice, also for gravestones that already stand.

Some vanilla particle systems that can be used as `systemId`: `Block_Top_Glow`, `Totem_Heal_AoE`, `Drop_Legendary`, `Drop_Epic`, `Drop_Rare`, `Drop_Uncommon`, `Dust_Sparkles_Fine`, `Fire_Charged1`, `Block_Gem_Sparks`.

---

## Purchases and teleport

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `purchaseWithEconomy` | Boolean | `true` | Prices of designs and particles and the teleport cost are paid with the server economy |
| `allowTeleportToGravestone` | Boolean | `false` | Shows a **Teleport** button for the selected gravestone in the menu (same world only) |
| `teleportCost` | Integer | `0` | Price of one teleport. `0` (or less) = free |
| `teleportCurrency` | String | `"coins"` | Only used for the graveyard-only currency |

**How prices are paid**

- `purchaseWithEconomy: true` **and** an economy is installed: prices come off the player's server balance. The economy is VaultUnlocked plus an economy plugin, reached through KyuubiSoft Core's economy bridge when Core is installed and directly otherwise. Prices are shown in the economy's format (for example "400 Gold"), and the menu header shows the balance.
- `purchaseWithEconomy: false`, or no economy: prices are charged in a graveyard-only currency ("500 coins"). The plugin never hands this currency out, so players cannot buy anything; unlock premium designs and particles with `design_give` / `particle_give`, and keep `teleportCost` at `0`.

**Teleport**

- The button teleports the player one block above the selected gravestone.
- It only works in the gravestone's world; for gravestones in other worlds the button reads "Only in this world".
- Before anything is charged, the plugin checks that the gravestone still exists, that the player is in its world and that the player's position is known. Then it charges `teleportCost` and teleports.

---

## Item loss: `itemLoss`

Destroys a share of the items that go into a gravestone. Off by default.

```json
"itemLoss": {
  "enabled": false,
  "mode": "BLACKLIST",
  "defaultLossPercent": 10,
  "items": {
    "Weapon_Sword_Iron": { "lossPercent": 25 },
    "Ingredient_Bar_Gold": { "lossPercent": 0 }
  }
}
```

| Field | Type | Default | Meaning |
|-------|------|---------|---------|
| `enabled` | Boolean | `false` | Switches item loss on |
| `mode` | String | `"BLACKLIST"` | `BLACKLIST`, `WHITELIST` or `NONE` (any other value = `NONE`) |
| `defaultLossPercent` | Integer | `10` | Percentage for items that are not listed (only in `BLACKLIST` mode) |
| `items` | Map | `{}` | Item ID to `{ "lossPercent": N }`. The ID must match exactly |

| Mode | What can be lost |
|------|------------------|
| `BLACKLIST` | Every item: listed items with their own percentage (`0` = never), all others with `defaultLossPercent` |
| `WHITELIST` | Only listed items, with their own percentage |
| `NONE` | Nothing |

- A stack of one item is lost with the given chance. From larger stacks the percentage is taken (rounded, at least one item); `100` removes the whole stack.
- Item loss only applies to items that go into the gravestone. The lost items are gone; the player gets no message. In the statistics, "Items lost" counts every item a death took, the destroyed ones included.
- Changes apply with `/ksgraveyard reload`, from the next death on.

---

## Languages

| Option | Type | Default | Meaning |
|--------|------|---------|---------|
| `defaultLanguage` | String | `"en-US"` | Fallback for texts a player's language does not have, and the language of the console-capable admin commands |

The jar contains 9 languages: en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR. Players see the language they picked with `/kslang` (or in the KS settings window of KyuubiSoft Core) if the server lets players choose, otherwise the server's default player language if one is set, otherwise their client language matched to the closest bundled language (for example `de-AT` uses `de-DE`). The default player language and the "players may choose" switch are set in the Language tab of Core's `/ksadmin` hub (Core 2.8.0 or newer) and apply to every KyuubiSoft mod. A text missing in that language is taken from `defaultLanguage`.

**Changing single texts**

1. Create the folder `mods/kyuubisoft_graveyard/i18n/`.
2. Add a file named after the language, for example `en-US.json`, with only the texts you want to change:

```json
{
  "graveyard.spawned": "Your items wait for you at {x}, {z}.",
  "graveyard.loot2.kicker": "Rest in peace"
}
```

3. Run `/ksgraveyard reload`.

Each key replaces the bundled text of the same key; all other texts stay. Keep the placeholders in braces (`{x}`, `{name}`, ...). The keys are listed in the bundled `i18n/en-US.json` inside the jar.

---

## Database: `database`

```json
"database": {
  "type": "sqlite",
  "sqlitePath": "graveyard.db",
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "database": "hytale",
    "username": "root",
    "password": ""
  }
}
```

| Field | Default | Meaning |
|-------|---------|---------|
| `type` | `"sqlite"` | `"sqlite"` or `"mysql"` |
| `sqlitePath` | `"graveyard.db"` | SQLite file, relative to `mods/kyuubisoft_graveyard/` |
| `mysql.host`, `port`, `database`, `username`, `password` | see above | MySQL connection (also works with MariaDB). The database must exist; the tables `gy_gravestones` and `gy_players` are created automatically |

- Changes need a restart.
- Switching between SQLite and MySQL does not copy existing data.
- If the database cannot be opened at the start, the plugin disables itself until the next restart (see [FAQ](./faq#the-log-says-the-graveyard-is-disabled)).

---

## Images for the classic window

Only used with `classicLootLook: true`. The defaults are copied into `mods/kyuubisoft_graveyard/images/` on the first start:

| File | Size | Used for |
|------|------|----------|
| `gravestone_bg.png` | 350 x 497 | Background of the classic grave window |
| `loot_all_button.png` | 384 x 149 | The "Loot All" button (shown at half size, 192 x 74; the button text is part of the image) |

Replace them with your own PNG files of the same size and restart the server. A deleted file is copied again from the jar on the next start.