# Getting Started

**Version:** 1.0.1

## 1. Install the mod

1. Stop the server.
2. Put `KyuubiSoftHeirlooms-1.0.1.jar` into the server's `mods/` folder.
3. Optional: [KyuubiSoft Core](https://wiki.kyuubisoft.com/hytale/core/). Heirlooms works without it.
4. Start the server.

```
mods/
  KyuubiSoftHeirlooms-1.0.1.jar
```

No other mod is needed. The mod brings its own window textures and tooltip texts.

---

## 2. Files after the first start

```
mods/
  kyuubisoft_heirlooms/
    config.json           all settings
    localization/         window and chat texts, one file per language (9 files)
    hall.json             hall of fame, admin counters, latest events
    placed/               ore and trunk blocks players placed, one file per world
  kslang/                 language choice shared by all KyuubiSoft mods
```

- `config.json` and `localization/` are created at the first start.
- `hall.json` and `placed/` appear once there is something to save. The mod saves them every 60 seconds and when the server stops.
- The stories themselves are not in these files. Each story is stored on its item, so it travels with the item into chests and to other players.

---

## 3. Check the start

The mod logs lines like these during the start:

```
[Heirlooms] Loaded 9 language(s), en-US has 572 keys
[Heirlooms] Ready, command /ksheirloom
```

If `config.json` cannot be read (for example after a JSON syntax error), the log says `[Heirlooms] config.json is broken, using defaults until it is fixed`. See [Configuration](./configuration#if-the-file-is-broken).

---

## 4. First test

1. Join the server and take a weapon in your hand. A freshly crafted one already carries a story with your name as its maker.
2. Slay a creature that the world spawned. Creatures from spawn eggs or commands do not count, see [FAQ](./faq#what-counts-as-a-kill).
3. Hover over the weapon. The tooltip now shows its fame, its origin, `1 creature · 0 bosses · 1 owner`, the favourite prey and the first moment.
4. Type `/ksheirloom`. The story window opens on the **Chronicle** tab.

The first time a player's item begins a story, a card "A story begins" appears at the top centre of the screen.

### See every fame level at once (admins)

To check the tooltip and the window without fighting for hours, hold a weapon and type `/ksheirloom test --level=3`. The item gets a made-up Legendary story. Levels 0 to 3 stand for New, Proven, Famous and Legendary. This overwrites a real story on the item, so use a spare item. `/ksheirloom clear` removes the story again.

---

## 5. First admin steps

1. Grant yourself `ks.heirlooms.admin`, see [Permissions](./permissions).
2. Type `/ksheirloom admin`. The **Overview** page shows the counters, the latest events and the current rules.
3. Decide the open questions on the **Rules** and **Boons** pages. Switches apply at once; numbers apply after **Save** in their section.

| Question | Default | Where |
|----------|---------|-------|
| Should armor get a story too? | off | Rules, **Armor** |
| Should wins over players count? | off | Rules, **Wins over players** |
| Should weapons learn boons and banes (extra damage against creatures)? | off | Boons, **Boons and bans** |
| Fame levels | 50, 300, 1000 | Rules, **Fame levels** |
| One chat line for everyone when an item becomes legendary | on | Rules, **Chat line on legendary** |
| Chime, sparkle and ground glow | on | Boons, **Cosmetics** |

Heirlooms is purely cosmetic until you switch on boons and banes. It has no economy and never hands out coins or items.

---

## 6. Languages

All window, chat and card texts come in nine languages. Each player sees the language they chose with `/kslang` (shared by all KyuubiSoft mods). `/kslang` alone shows the current language and the available codes in chat, `/kslang de-DE` sets one, and `/kslang auto` follows the game language again. Texts a language lacks come from English.

The tooltip, and the names of items, creatures, titles and boons, follow the game language of each player. With two different settings, one window can show two languages.

The window texts live in `localization/<language>.json` and can be edited. When a newer version brings newer texts, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`. `/ksheirloom reload` reads the files again.

---

## Next steps

- [Commands](./commands) for the full syntax
- [Configuration](./configuration) for every option
- [UI Pages](./ui-pages) for what players and admins see