# FAQ

**Version:** 1.0.0

## General

### Which items can become heirlooms?

Melee weapons, bows and crossbows, pickaxes, hatchets and shields, and armor if an admin switches it on. Only items that never stack and wear down can carry a story, because two stories cannot merge into one stack. Shields are the exception: they need no durability.

### When does the story begin?

- A **crafted** item begins its story right away, with the crafter as its maker and first owner and the crafting day as its start.
- Any **other** item begins with its first count: the first creature it slays, the first ore or trunk, the first blocked or taken hit. Its origin then says "found".

The first time a player's item begins a story, a card "A story begins" appears.

### Where is the story stored?

On the item itself, under 1 KB per item. That is why the story travels with the item through drops, chests and trades, and why there is no story database. Only the hall of fame, the admin counters and the placed blocks are kept in files, see [Configuration](./configuration#other-files).

### Do items from other content packs work?

The mod reads the item's own data (weapon family, tool, armor), so items that are built like the game's own weapons, tools, shields and armor work too. For their creatures, admins can add groups and bosses in the [creature lists](./configuration#creatures).

---

## What counts

### What counts as a kill?

A kill counts for an heirloom when all of this is true:

- **A player dealt the killing blow.** For a melee weapon it must be a direct hit, with the weapon in the player's hand (hotbar or tool belt) when the creature dies. For a bow or crossbow it must be an arrow fired from it; the kill goes to the bow it came from, also after the player switched to another slot, as long as the bow stays in its slot.
- **The creature was close.** A direct kill more than 8 blocks away from the player is not credited.
- **The creature counts as prey.** Only creatures the world spawned count, not those from spawn eggs, commands or other mods. Tamed animals, temple and quest creatures, and the pets, mounts and NPCs of KyuubiSoft mods never count. Both rules can be switched off.
- **The farm brake lets it through,** see [below](#how-does-the-mod-stop-farming).

Damage over time (poison, burning), falls and other damage from the world do not count. An item that can carry a story but has none yet begins its story with its first counted kill.

### What do tools, shields and armor count?

| Item | Counts |
|------|--------|
| Pickaxe | Every ore block it breaks while in your hand |
| Hatchet | Every tree trunk block it breaks while in your hand. One tree has several trunks; the windows call them "trees" |
| Shield | Every creature hit it blocks while it sits in your off-hand slot |
| Armor (off by default) | Every creature hit that hurts you; each worn armor piece counts it |

Shields and armor count only blows of creatures: no players, no falls, no damage over time. They count at most one hit per 1.5 seconds per player.

### Why did my kill not count?

- Something else dealt the killing blow: poison, fire, a fall, another player.
- You hit it with a melee weapon from more than 8 blocks away.
- The creature came from a spawn egg, a command or another mod, or it is a pet, a mount, an NPC or a tamed animal.
- The farm brake was active.
- The kind of item is switched off on the **Rules** page of the admin window.
- The item cannot carry a story: it stacks or never wears down.
- You held another item in your hand when the creature died.

### How does the mod stop farming?

| Rule | Default | Option |
|------|---------|--------|
| Only creatures the world spawned count | on | `counting.ignoreSpawned` |
| Pets, NPCs, tamed animals and similar creatures never count | on | `counting.ignoreNpcsAndPets`, `creatures.ignored` |
| Ore and trunk blocks a player placed do not count, also after a restart | on | `counting.ignorePlacedBlocks` |
| Farm brake: after 20 counts within 8 blocks in 120 seconds, only every 4th further kill counts (60 counts for ores and trunks) | on | `counting.farmBrake`, `farmRadius`, `farmWindowSeconds`, `farmFreeKills`, `farmKeepEvery` |
| A direct kill farther than 8 blocks away is not credited | always | – |
| Shields and armor count at most one hit per 1.5 seconds | always | – |

If an item was farmed anyway, an admin can take it out of the hall of fame on the **Item** page of the admin window. Its story stays.

### Do kills of my combat pet count?

With [Companions](https://wiki.kyuubisoft.com/hytale/pets/), combat pets credit the damage they deal to their owner. Heirlooms treats such a kill like a direct hit by the owner: it counts for the melee weapon in the owner's hand, but only when the creature dies within 8 blocks of the owner. Kills farther away are not credited. Bows never get pet kills.

### Do wins over players count?

Only if an admin switches on **Wins over players** (`counting.pvp`, off by default). Then a player slain with an heirloom that already has a story is added to a separate counter on the item. It never raises the count, the fame or the hall of fame, and version 1.0.0 does not show this counter in any window yet. Killing yourself never counts.

---

## Fame, titles and the hall of fame

### Can fame go down?

No. An item keeps the highest fame it reached. If an admin raises the fame levels, items keep their fame; if the levels are lowered, items climb at their next count.

### How do I get a title?

Titles are earned by themselves when the item meets their condition, for example 25 wolves or 100 days. You then get a card "Title earned". No title is put on by itself: open `/ksheirloom`, go to **Titles**, pick the card and click **Wear**. An item wears one title at a time, and **Take off** removes it. Age titles such as Veteran count real days since the story began; they are checked when the story changes or when you open the window.

### When does an heirloom enter the hall of fame?

When it reaches **Proven** (50 counts by default). Its entry follows the item: count, fame, title and current owner. Each list shows up to 30 heirlooms; the server keeps up to 300 and drops the weakest when it is full. Deleted stories leave the hall, and admins can hide single items.

### What counts as a repair?

A repair counts when a broken heirloom is repaired. The break and the repair both go into the chronicle, and the repair counts towards The Unbreakable and the Well-Kept boon. Repairing an item that was worn down but not broken does not count.

---

## Owners and binding

### How does an heirloom change owners?

As soon as an heirloom lands in another player's inventory, by pickup, from a chest or in a trade, that player becomes its next owner. The new owner gets a card "An heirloom", and the chronicle says "Passed to" with the name. Every owner is counted; the latest five keep their names and their share of the count.

### What is the binding?

It only matters when boons are switched on. When an heirloom reaches a new owner, its boons and banes sleep until 25 creatures have fallen to it in the new hands (`boons.bindingKills`). While they sleep they have no effect, and the tooltip dims them. Story, fame and titles keep counting. When the binding is done, the owner gets a card "Boons awakened".

A crafted item and the first owner of a found item never wait. With `bindingKills` set to `0` the boons obey every hand at once.

### What happens when I get my old weapon back?

A former owner who gets an heirloom back is not counted as a new owner, and the boons obey them again at once.

---

## Boons and banes

### Why does my weapon have no boons?

- Boons and banes are **off by default**. An admin switches them on with **Boons and bans** on the **Boons** page of the admin window. Until then the **Boons** tab says "Boons are off on this server".
- Only weapons and bows learn boons. Tools, shields and armor gather fame and titles only.
- A slot opens with each fame level. A New item has no slot yet.

The story keeps everything boons need while they are off. When an admin switches them on, earned banes apply at once, and an open slot offers its choice the next time the story changes or the owner opens `/ksheirloom`.

### How are boons offered?

There is one slot per fame level: Proven, Famous and Legendary. When a slot opens, the item offers up to three boons that fit its story, and the owner picks one in the **Boons** tab. Only one choice is open at a time; the next slot waits.

| Boon | Offered more for |
|------|------------------|
| Night Hunter | A high share of creatures slain at night |
| Giantslayer | Bosses defeated |
| Tough | Wins with less than a quarter of health left |
| Bloodrush | Five creatures slain within ten seconds |
| Well-Kept | Repairs and breaks |
| Viper's Kiss, Ember, Frostbite | Only after 50 poisonous, fire or frost creatures; then they rank high |

Boons the item already has and boons an admin switched off are not offered. **Later** keeps the choice open on the item. Effects are listed on [Configuration](./configuration#boons-and-banes).

### How do banes work?

Banes grow by themselves from kills of one creature group: at 100, 500 and 2000 kills the item deals +3, +6 or +10 % damage against that group. Groups such as Trorks, Goblins or Wolves come from the config; a creature in no group forms a group of its own. At most two banes work at once, the strongest ones.

### How much extra damage is possible?

Banes, Night Hunter and Giantslayer add up, but together they give at most +10 % (`boons.damageCapPercent`). The bonus counts for hits of the melee weapon in hand and for arrows of that bow. Viper's Kiss, Ember and Frostbite have a 5 % chance per hit, and the same creature gets a status effect at most once every 8 seconds.

### Do boons work against players?

No. Extra damage and status effects only hit creatures, and Tough and Bloodrush only start after a creature kill.

### Can I change a chosen boon?

No. "The choice stays with the item and travels with it. Only an admin can reset it." An admin uses **Reset boons** on the **Item** page; the owner then chooses again. Banes stay, they belong to the creatures.

### Is it "ban" or "bane"?

The same thing. The windows and the config say "ban", the tooltip and the cards say "Bane".

---

## Other KyuubiSoft mods

Heirlooms needs no other mod. These connections exist in 1.0.0:

| Mod | What it adds |
|-----|--------------|
| [KyuubiSoft Core](https://wiki.kyuubisoft.com/hytale/core/) | The moment cards take a row of Core's shared card lane, so they do not cover the cards of other KyuubiSoft mods. The server's default language and whether players may choose their own, set in Core, apply to Heirlooms too |
| [Companions](https://wiki.kyuubisoft.com/hytale/pets/) | Kills of combat pets right next to their owner count for the owner's melee weapon. Pets and mounts themselves do not count as prey |
| All KyuubiSoft mods | One shared language choice with `/kslang` |

Version 1.0.0 has no tile in Core's `/ksadmin` hub. Open the admin window with `/ksheirloom admin`.

---

## Troubleshooting

### The tooltip still shows old values

The tooltip is stored on the item. After a change to the rules, for example new fame levels or the hint line switched off, an item shows the new state the next time its story changes: at its next count, a new owner, a break or a repair.

### My config changes have no effect

- Changes by hand need `/ksheirloom reload`.
- If the file has an error, the log says `[Heirlooms] config.json is broken, using defaults until it is fixed`. Fix the file and reload, see [Configuration](./configuration#if-the-file-is-broken).

### A window shows two languages

Window texts follow `/kslang`, while the names of items, creatures, titles and boons follow the game language. Set both to the same language, or use `/kslang auto` to follow the game.

### The story window does not show my shield

The window shows the item in your hand. A shield in the off-hand slot is not in your hand; hover over it to read its story in the tooltip.

### The hall of fame is empty

Items join once they are **Proven** (50 counts by default). Items an admin hid are not listed.