# Configuration

**Version:** 1.0.0

Heirlooms is configured in `mods/kyuubisoft_heirlooms/config.json`. The file is created with the defaults on the first start. On every start and reload the mod writes it back, so options added by a newer version show up and values out of range are corrected in the file.

Heirlooms has no economy. It never pays coins or items. The only options that change gameplay values are boons and banes, and they are **off by default**.

---

## How changes apply

You have two ways to change the settings:

- **In the game:** the [admin window](./ui-pages#the-admin-window) (`/ksheirloom admin`) changes most options. Switches act at once; numbers apply after **Save** in their section. Each change is written to `config.json` right away.
- **In the file:** edit `config.json` and run `/ksheirloom reload`. Some options are only in the file; the tables below say which.

No option needs a restart.

:::note[Tooltips update with the next change]
The tooltip is stored on each item. After you change the rules, an item shows the new state the next time its story changes, for example at its next count or when it changes owner.
:::

---

## Default configuration

```json
{
  "configVersion": 1,
  "kinds": {
    "melee": true,
    "bows": true,
    "tools": true,
    "shields": true,
    "armor": false
  },
  "fame": {
    "proven": 50,
    "famous": 300,
    "legendary": 1000
  },
  "messages": {
    "toasts": true,
    "legendaryChat": true,
    "tooltipHint": true,
    "share": true,
    "shareCooldownSeconds": 60,
    "shareRadius": 32
  },
  "counting": {
    "pvp": false,
    "ignorePlacedBlocks": true,
    "ignoreSpawned": true,
    "ignoreNpcsAndPets": true,
    "farmBrake": true,
    "farmRadius": 8,
    "farmWindowSeconds": 120,
    "farmFreeKills": 20,
    "farmKeepEvery": 4
  },
  "boons": {
    "enabled": false,
    "banLevels": [
      { "kills": 100, "percent": 3 },
      { "kills": 500, "percent": 6 },
      { "kills": 2000, "percent": 10 }
    ],
    "gifts": {},
    "damageCapPercent": 10,
    "maxBans": 2,
    "nightHunterPercent": 5,
    "giantslayerPercent": 5,
    "statusChancePercent": 5,
    "statusCooldownSeconds": 8,
    "statusOfferMin": 50,
    "bindingKills": 25
  },
  "cosmetics": {
    "killSparks": true,
    "milestoneSound": true,
    "groundGlow": true
  },
  "titles": {
    "builtin": {},
    "custom": []
  },
  "creatures": {
    "families": [
      { "id": "trork", "match": ["trork"] },
      { "id": "goblin", "match": ["goblin"] },
      { "id": "skeleton", "match": ["skeleton"] },
      { "id": "zombie", "match": ["zombie"] },
      { "id": "wolf", "match": ["wolf"] },
      { "id": "spider", "match": ["spider"] },
      { "id": "scorpion", "match": ["scorpion"] },
      { "id": "scarak", "match": ["scarak"] },
      { "id": "slime", "match": ["slime"] }
    ],
    "poison": ["spider", "snapdragon", "snake_", "scorpion", "scarak_seeker"],
    "fire": ["burnt", "magma", "ember", "flame", "fire", "firesteel", "incandescent", "shellfish_lava"],
    "frost": ["frost", "_ice", "yeti", "bear_polar", "owl_snow", "leopard_snow"],
    "bosses": ["goblin_duke", "goblin_ogre", "dragon_fire", "dragon_frost", "golem_guardian_void",
               "scarak_broodmother", "trork_chieftain", "shadow_knight", "zombie_aberrant_big"],
    "bossMinHealth": 0,
    "ignored": ["tamed_", "temple_", "edible_", "quest_master", "ks_pet_", "ks_mount_", "ks_npc_", "ks_path_"]
  }
}
```

The mod writes the file with one entry per line; the short form above is the same content. A key that is missing in your file gets its default.

---

## Kinds

Which items get a story. Only items that never stack and wear down can carry one; shields need no durability.

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `melee` | `true` | Rules | Melee weapons (swords, axes, maces, spears) count the creatures they slay |
| `bows` | `true` | Rules | Bows and crossbows count the creatures their arrows slay |
| `tools` | `true` | Rules | Pickaxes count ores, hatchets count tree trunks |
| `shields` | `true` | Rules | Shields count the creature hits they block |
| `armor` | `false` | Rules | Armor counts the creature hits it takes |

Switching a kind off stops new counts on such items. Stories they already carry stay on them.

---

## Fame

How many counts each fame level needs.

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `proven` | `50` | Rules | Proven: the name shines green and the item joins the hall of fame |
| `famous` | `300` | Rules | Famous: the name shines blue |
| `legendary` | `1000` | Rules | Legendary: the name shines gold, and a chat line tells everyone |

- With boons switched on, every level also opens one boon slot on weapons and bows.
- Each level must be higher than the one before. In the file, a value that is too low is raised to one above the level before. In the admin window the values range from 1 to 1,000,000.
- Fame never goes down. If you raise the levels, items keep the fame they reached. If you lower them, items climb at their next count.

---

## Messages

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `toasts` | `true` | Rules, **Notice at milestones** | Cards at the top centre of the screen for milestones, fame levels, titles, banes, boons, new owners and breaks. Only the owner sees them |
| `legendaryChat` | `true` | Rules, **Chat line on legendary** | One chat line for every player online when an heirloom becomes legendary |
| `tooltipHint` | `true` | Rules, **Hint line in the tooltip** | The line "Full story: /ksheirloom" at the end of the tooltip |
| `share` | `true` | Rules, **Allow showing in chat** | The **Show in chat** button in the story window |
| `shareCooldownSeconds` | `60` | Rules | Seconds before a player can show an heirloom again, 0 to 3600 |
| `shareRadius` | `32` | file only | Players within this many blocks in the same world see the line, 4 to 256 |

---

## Counting

These rules apply to every count, not only to boons. See [FAQ](./faq#what-counts-as-a-kill) for how they work together.

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `pvp` | `false` | Rules, **Wins over players** | Players slain with an heirloom are stored on their own counter. They never raise the count, the fame or the hall of fame |
| `ignorePlacedBlocks` | `true` | Rules, **Ignore placed blocks** | Ore and trunk blocks a player placed do not count for tools |
| `ignoreSpawned` | `true` | Rules, **Ignore spawn eggs and commands** | Only creatures the world spawned count, not those from spawn eggs, commands or other mods |
| `ignoreNpcsAndPets` | `true` | Rules, **Ignore villagers and companions** | Creatures whose role id contains a pattern of `creatures.ignored` do not count |
| `farmBrake` | `true` | Rules, **Farm brake** | Many kills at the same spot count less |
| `farmRadius` | `8` | file only | Blocks around a kill that count as "the same spot", 1 to 64 |
| `farmWindowSeconds` | `120` | file only | How far back the brake looks, 10 to 3600 seconds |
| `farmFreeKills` | `20` | file only | Earlier kills at the same spot before the brake starts, 1 to 1000 |
| `farmKeepEvery` | `4` | file only | With the brake on, only every n-th kill counts, 1 to 100 |

**The farm brake in numbers:** when a player already has 20 counts within 8 blocks in the last 120 seconds, only every 4th further kill counts. For ores and trunks the allowance is three times as high (60), because one tree has several trunks and one vein several ores. Each player has their own history; it is cleared when they leave.

`pvp` counts only on an item that already carries a story, and only where players can hurt each other. Version 1.0.0 stores this counter on the item but does not show it in any window.

---

## Boons and banes

:::caution[Admin option, off by default]
Boons and banes change combat values: extra damage against creatures, status effects, regeneration and durability. They are off until an admin switches them on. They never work against players.
:::

The windows and the file call banes "bans"; the tooltip and the cards say "Bane". Both mean the same.

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `enabled` | `false` | Boons, **Boons and bans** | Main switch for boons and banes |
| `banLevels` | 100 / 3 %, 500 / 6 %, 2000 / 10 % | Boons, **Bans** | Kills of one creature group (`kills`) and the extra damage against that group (`percent`) for each bane level |
| `gifts` | `{}` | Boons, one switch per boon | Boon id to `true`/`false`. A boon that is not listed is on |
| `damageCapPercent` | `10` | Boons, **Damage cap** | Most extra damage of all boons and banes together, 0 to 100 % |
| `maxBans` | `2` | Boons, **Bans at once** | How many banes work at once; the strongest count, 0 to 5 |
| `nightHunterPercent` | `5` | file only | Extra damage of Night Hunter at night, 0 to 100 % |
| `giantslayerPercent` | `5` | file only | Extra damage of Giantslayer against bosses, 0 to 100 % |
| `statusChancePercent` | `5` | Boons, **Status: chance** | Chance per hit of Viper's Kiss, Ember and Frostbite, 0 to 100 % |
| `statusCooldownSeconds` | `8` | Boons, **Status: cooldown** | Seconds before the same creature can get a status effect again, 0 to 600 |
| `statusOfferMin` | `50` | file only | Creatures of an element an item must slay before Viper's Kiss, Ember or Frostbite is offered, 1 to 100,000 |
| `bindingKills` | `25` | Boons, **Binding** | Creatures a new owner must slay before the boons wake up for them, 0 to 100,000. `0` means the boons obey every hand at once |

**Bane levels in the file:** up to 5 levels. Entries with `kills` of 0 or less are dropped, the rest are sorted by `kills`, and `percent` is kept between 0 and 100. An empty list brings back the defaults. The admin window edits the values of the existing levels; to add or remove a level, edit the file.

**Boon ids for `gifts`:**

| Id | Boon | Effect |
|----|------|--------|
| `night_hunter` | Night Hunter | +5 % damage at night (`nightHunterPercent`) |
| `giantslayer` | Giantslayer | +5 % damage against bosses (`giantslayerPercent`) |
| `tough` | Tough | 6 s of regeneration after a kill |
| `bloodrush` | Bloodrush | 4 s of faster stamina after a kill |
| `well_kept` | Well-Kept | Every kill restores 1 durability (not on a broken item) |
| `viper` | Viper's Kiss | 5 % chance to poison the creature for 8 s |
| `ember` | Ember | 5 % chance to set the creature on fire for 3 s |
| `frostbite` | Frostbite | 5 % chance to slow the creature for 3 s |

A boon that is switched off is no longer offered and stops working on items that already chose it. Their **Boons** tab marks it "Switched off on this server.", and their tooltip drops the line. Example that switches off Viper's Kiss:

```json
"gifts": { "viper": false }
```

How boons are offered and chosen is described in the [FAQ](./faq#boons-and-banes).

---

## Cosmetics

These change no values and are on by default.

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `killSparks` | `true` | Boons, **Sparks on a kill** | A short burst of small sparks where a creature falls, gone in under a second, only for the killer, once the item is Proven |
| `milestoneSound` | `true` | Boons, **Sound at milestones** | A chime for the owner at milestones, new fame levels, titles, banes and awakened boons |
| `groundGlow` | `true` | Boons, **Glow on the ground** | A legendary heirloom lying on the ground glows gold, so its owner finds it again after death. The admin window marks it as still being tested |

---

## Titles

| Option | Default | Admin window | Meaning |
|--------|---------|--------------|---------|
| `builtin` | `{}` | Titles, **Switch off** / **Switch on** | Built-in title id to `true`/`false`. A title that is not listed is on |
| `custom` | `[]` | Titles, **New title** | The server's own titles |

**Built-in titles:**

| Id | English name | Condition | Items |
|----|--------------|-----------|-------|
| `wolfsbane` | Wolfsbane | Slay 25 Wolves | weapons and bows |
| `trork_terror` | Trork Terror | Slay 50 Trorks | weapons and bows |
| `chieftain_slayer` | Chieftain Slayer | Defeat a boss | weapons and bows |
| `goblin_plague` | Goblin Plague | Slay 50 Goblins | weapons and bows |
| `spider_death` | Spiderdeath | Slay 50 Spiders | weapons and bows |
| `unbreakable` | The Unbreakable | Repaired 10 times | all kinds |
| `veteran` | Veteran | 100 days old | all kinds |
| `ancestral` | Ancestral | Passed through 3 hands | all kinds |
| `tireless` | The Tireless | Slay 1000 creatures | weapons and bows |
| `ore_finder` | Ore Finder | Mine 1000 ores | pickaxes |
| `woodcutter` | Timberfeller | Fell 1000 trees | hatchets |
| `steadfast` | The Steadfast | Block or take 500 hits | shields and armor |

A switched-off title can no longer be earned or put on, and it disappears from the **Titles** tab. Items that already wear it keep it.

**A title of your own:**

```json
"custom": [
  {
    "id": "custom_1",
    "names": { "en-US": "Black Wolf Hunter", "de-DE": "Schwarzwolfjäger" },
    "condition": "ROLE",
    "target": "Wolf_Black",
    "count": 100,
    "enabled": true
  }
]
```

| Field | Meaning |
|-------|---------|
| `id` | Unique id. Use letters, digits and underscores. The admin window names new titles `custom_1`, `custom_2` and so on |
| `names` | Language code to name. A missing or empty name falls back to `en-US`, then to the id |
| `condition` | What is counted, see below. An unknown value counts as `TOTAL` |
| `target` | Creature or group id for `ROLE`, `FAMILY` and `BOSS`, empty otherwise |
| `count` | How many are needed, at least 1 (the admin window allows 1 to 100,000) |
| `enabled` | `false` switches the title off |

| Condition | Counts | Admin window name | Items |
|-----------|--------|-------------------|-------|
| `ROLE` | Kills of one creature, for example `Wolf_Black` | Kind | weapons and bows |
| `FAMILY` | Kills of one group from `creatures.families`, for example `wolf` | Group | weapons and bows |
| `BOSS` | Bosses defeated; with a `target` only that boss | Boss | weapons and bows |
| `TOTAL` | The item's own count (creatures, ores, trees or hits) | Total | all kinds |
| `REPAIRS` | Repairs | Repairs | all kinds |
| `AGE_DAYS` | Days since the story began | Age | all kinds |
| `OWNERS` | Owners in total | Owners | all kinds |

The tooltip and the chat lines show a server title by its English (`en-US`) name. The story window shows it in each player's own language.

Better switch a title off than delete it: whoever wears a switched-off title keeps it.

---

## Creatures

How creatures are sorted into groups, elements and bosses. All lists hold patterns: a pattern matches every creature whose role id contains it, ignoring upper and lower case. These options are only in the file.

| Option | Meaning |
|--------|---------|
| `families` | Creature groups for banes and group titles. Each entry has an `id` and `match` patterns; the first matching entry wins. A creature that matches no entry forms a group of its own |
| `poison` | Poisonous creatures. They count towards Viper's Kiss |
| `fire` | Fire creatures. They count towards Ember |
| `frost` | Frost creatures. They count towards Frostbite |
| `bosses` | Creatures that count as bosses. The game has no boss marker of its own |
| `bossMinHealth` | Creatures with at least this much maximum health count as bosses too. `0` switches this off |
| `ignored` | Creatures that never count while `counting.ignoreNpcsAndPets` is on. The defaults cover tamed animals, temple and quest creatures, and the pets, mounts and NPCs of KyuubiSoft mods |

The default boss list names the Goblin Duke, the Goblin Ogre, both dragons, the Void Guardian, the Scarak Broodmother, the Trork Chieftain, the Shadow Knight and the big Aberrant Zombie. Add the role ids of creatures from other content packs to teach the mod about them.

The nine default groups have translated names in all languages. A group you add has no translated name.

---

## If the file is broken

If `config.json` cannot be read (for example after a missing comma), the log shows `[Heirlooms] config.json is broken, using defaults until it is fixed`. The unreadable file is copied to `config.json.broken` and left as it is, and the mod runs with the defaults. Fix the file and run `/ksheirloom reload`.

If you change a setting in the admin window while the file is broken, the file is written new from the values in use. Your broken version then only survives as `config.json.broken`.

---

## Other files

| File | Content |
|------|---------|
| `hall.json` | The hall of fame (up to 300 heirlooms), the counters and the latest 30 events of the admin overview |
| `localization/<language>.json` | Window, chat and card texts, see [Getting Started](./getting-started#6-languages) |
| `placed/<world>.bin` | Ore and trunk blocks players placed, up to 200,000 per world. When a world is full, the oldest marks are forgotten first |

`hall.json` and `placed/` are saved every 60 seconds and when the server stops. Stories are not in any file; each one is stored on its item.