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
Section titled “How changes apply”You have two ways to change the settings:
- In the game: the admin window (
/ksheirloom admin) changes most options. Switches act at once; numbers apply after Save in their section. Each change is written toconfig.jsonright away. - In the file: edit
config.jsonand run/ksheirloom reload. Some options are only in the file; the tables below say which.
No option needs a restart.
Default configuration
Section titled “Default configuration”{ "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.
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.
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
Section titled “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
Section titled “Counting”These rules apply to every count, not only to boons. See FAQ 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
Section titled “Boons and banes”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:
"gifts": { "viper": false }How boons are offered and chosen is described in the FAQ.
Cosmetics
Section titled “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
Section titled “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:
"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
Section titled “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
Section titled “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
Section titled “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 |
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.