Skip to content

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.


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 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.


{
"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.

OptionDefaultAdmin windowMeaning
meleetrueRulesMelee weapons (swords, axes, maces, spears) count the creatures they slay
bowstrueRulesBows and crossbows count the creatures their arrows slay
toolstrueRulesPickaxes count ores, hatchets count tree trunks
shieldstrueRulesShields count the creature hits they block
armorfalseRulesArmor 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.

OptionDefaultAdmin windowMeaning
proven50RulesProven: the name shines green and the item joins the hall of fame
famous300RulesFamous: the name shines blue
legendary1000RulesLegendary: 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.

OptionDefaultAdmin windowMeaning
toaststrueRules, Notice at milestonesCards at the top centre of the screen for milestones, fame levels, titles, banes, boons, new owners and breaks. Only the owner sees them
legendaryChattrueRules, Chat line on legendaryOne chat line for every player online when an heirloom becomes legendary
tooltipHinttrueRules, Hint line in the tooltipThe line “Full story: /ksheirloom” at the end of the tooltip
sharetrueRules, Allow showing in chatThe Show in chat button in the story window
shareCooldownSeconds60RulesSeconds before a player can show an heirloom again, 0 to 3600
shareRadius32file onlyPlayers within this many blocks in the same world see the line, 4 to 256

These rules apply to every count, not only to boons. See FAQ for how they work together.

OptionDefaultAdmin windowMeaning
pvpfalseRules, Wins over playersPlayers slain with an heirloom are stored on their own counter. They never raise the count, the fame or the hall of fame
ignorePlacedBlockstrueRules, Ignore placed blocksOre and trunk blocks a player placed do not count for tools
ignoreSpawnedtrueRules, Ignore spawn eggs and commandsOnly creatures the world spawned count, not those from spawn eggs, commands or other mods
ignoreNpcsAndPetstrueRules, Ignore villagers and companionsCreatures whose role id contains a pattern of creatures.ignored do not count
farmBraketrueRules, Farm brakeMany kills at the same spot count less
farmRadius8file onlyBlocks around a kill that count as “the same spot”, 1 to 64
farmWindowSeconds120file onlyHow far back the brake looks, 10 to 3600 seconds
farmFreeKills20file onlyEarlier kills at the same spot before the brake starts, 1 to 1000
farmKeepEvery4file onlyWith 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.


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

OptionDefaultAdmin windowMeaning
enabledfalseBoons, Boons and bansMain switch for boons and banes
banLevels100 / 3 %, 500 / 6 %, 2000 / 10 %Boons, BansKills of one creature group (kills) and the extra damage against that group (percent) for each bane level
gifts{}Boons, one switch per boonBoon id to true/false. A boon that is not listed is on
damageCapPercent10Boons, Damage capMost extra damage of all boons and banes together, 0 to 100 %
maxBans2Boons, Bans at onceHow many banes work at once; the strongest count, 0 to 5
nightHunterPercent5file onlyExtra damage of Night Hunter at night, 0 to 100 %
giantslayerPercent5file onlyExtra damage of Giantslayer against bosses, 0 to 100 %
statusChancePercent5Boons, Status: chanceChance per hit of Viper’s Kiss, Ember and Frostbite, 0 to 100 %
statusCooldownSeconds8Boons, Status: cooldownSeconds before the same creature can get a status effect again, 0 to 600
statusOfferMin50file onlyCreatures of an element an item must slay before Viper’s Kiss, Ember or Frostbite is offered, 1 to 100,000
bindingKills25Boons, BindingCreatures 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:

IdBoonEffect
night_hunterNight Hunter+5 % damage at night (nightHunterPercent)
giantslayerGiantslayer+5 % damage against bosses (giantslayerPercent)
toughTough6 s of regeneration after a kill
bloodrushBloodrush4 s of faster stamina after a kill
well_keptWell-KeptEvery kill restores 1 durability (not on a broken item)
viperViper’s Kiss5 % chance to poison the creature for 8 s
emberEmber5 % chance to set the creature on fire for 3 s
frostbiteFrostbite5 % 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.


These change no values and are on by default.

OptionDefaultAdmin windowMeaning
killSparkstrueBoons, Sparks on a killA short burst of small sparks where a creature falls, gone in under a second, only for the killer, once the item is Proven
milestoneSoundtrueBoons, Sound at milestonesA chime for the owner at milestones, new fame levels, titles, banes and awakened boons
groundGlowtrueBoons, Glow on the groundA 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

OptionDefaultAdmin windowMeaning
builtin{}Titles, Switch off / Switch onBuilt-in title id to true/false. A title that is not listed is on
custom[]Titles, New titleThe server’s own titles

Built-in titles:

IdEnglish nameConditionItems
wolfsbaneWolfsbaneSlay 25 Wolvesweapons and bows
trork_terrorTrork TerrorSlay 50 Trorksweapons and bows
chieftain_slayerChieftain SlayerDefeat a bossweapons and bows
goblin_plagueGoblin PlagueSlay 50 Goblinsweapons and bows
spider_deathSpiderdeathSlay 50 Spidersweapons and bows
unbreakableThe UnbreakableRepaired 10 timesall kinds
veteranVeteran100 days oldall kinds
ancestralAncestralPassed through 3 handsall kinds
tirelessThe TirelessSlay 1000 creaturesweapons and bows
ore_finderOre FinderMine 1000 orespickaxes
woodcutterTimberfellerFell 1000 treeshatchets
steadfastThe SteadfastBlock or take 500 hitsshields 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
}
]
FieldMeaning
idUnique id. Use letters, digits and underscores. The admin window names new titles custom_1, custom_2 and so on
namesLanguage code to name. A missing or empty name falls back to en-US, then to the id
conditionWhat is counted, see below. An unknown value counts as TOTAL
targetCreature or group id for ROLE, FAMILY and BOSS, empty otherwise
countHow many are needed, at least 1 (the admin window allows 1 to 100,000)
enabledfalse switches the title off
ConditionCountsAdmin window nameItems
ROLEKills of one creature, for example Wolf_BlackKindweapons and bows
FAMILYKills of one group from creatures.families, for example wolfGroupweapons and bows
BOSSBosses defeated; with a target only that bossBossweapons and bows
TOTALThe item’s own count (creatures, ores, trees or hits)Totalall kinds
REPAIRSRepairsRepairsall kinds
AGE_DAYSDays since the story beganAgeall kinds
OWNERSOwners in totalOwnersall 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.


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.

OptionMeaning
familiesCreature 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
poisonPoisonous creatures. They count towards Viper’s Kiss
fireFire creatures. They count towards Ember
frostFrost creatures. They count towards Frostbite
bossesCreatures that count as bosses. The game has no boss marker of its own
bossMinHealthCreatures with at least this much maximum health count as bosses too. 0 switches this off
ignoredCreatures 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 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.


FileContent
hall.jsonThe hall of fame (up to 300 heirlooms), the counters and the latest 30 events of the admin overview
localization/<language>.jsonWindow, chat and card texts, see Getting Started
placed/<world>.binOre 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.