# Configuration

All files are in the data folder `mods/kyuubisoft_whisperstone/`:

| File | What it holds |
|------|---------------|
| `config.json` | Limits, times, sounds and the first-join stone |
| `runes.json` | The runes of other mods on the start screen |
| `localization/<language>.json` | All texts, one file per language |
| `whisperstone.db` | The SQLite database |

## How changes apply

- Edit the files and run `/kswhisper reload`. Running calls and hints keep going.
- `presenceTickMillis` is read once when the server starts. A change to it needs a restart.
- A key that is missing from `config.json` gets its default and is written back into the file, so new options appear after an update.
- If `config.json` cannot be read, Whisperstone uses the defaults and leaves the file alone until you fix it. The log says `config.json is broken, using defaults until it is fixed`.
- Values below the minimum in the tables are raised to the minimum.

## config.json

### Default file

```json
{
  "maxContacts": 100,
  "requestsPerMinute": 10,
  "requestCooldownSeconds": 60,
  "maxMessageLength": 200,
  "messagesPerSecond": 1,
  "messagesPerMinute": 20,
  "messageRetentionDays": 30,
  "maxMessagesPerConversation": 200,
  "noticeRetentionDays": 7,
  "maxNoticesPerPlayer": 50,
  "noticesFromShops": true,
  "noticesFromQuests": true,
  "noticesFromAchievements": true,
  "pinMinutes": 30,
  "maxPinsPerPlayer": 20,
  "ringSeconds": 30,
  "ringSoundEverySeconds": 3,
  "callsPerMinute": 6,
  "callCooldownSeconds": 30,
  "toastSeconds": 8,
  "maxQueuedToasts": 20,
  "soundMessage": "SFX_Drop_Items_Gems",
  "soundNotice": "SFX_Drop_Items_Gems",
  "soundRing": "SFX_Sleep_Notification",
  "presenceTickMillis": 1000,
  "giveOnFirstJoin": true,
  "commandNeedsItem": false
}
```

### Companions

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `maxContacts` | `100` | 1 | Most companions a player can have. A player with a full list cannot send requests, and no request can be accepted while either list is full. |
| `requestsPerMinute` | `10` | 1 | Companion requests a player may send per minute |
| `requestCooldownSeconds` | `60` | 0 | After a declined request, the asker waits this many seconds before asking that player again |

### Messages

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `maxMessageLength` | `200` | 1 | Longest message in characters. An accented letter or an emoji counts as one. The text field in the window takes at most 200 characters, so a higher value has no effect. |
| `messagesPerSecond` | `1` | 1 | Messages a player may send per second. Shared positions count too. |
| `messagesPerMinute` | `20` | 1 | Messages a player may send per minute. Shared positions count too. |
| `messageRetentionDays` | `30` | 1 | Messages older than this are deleted |
| `maxMessagesPerConversation` | `200` | 1 | Above this, the oldest message of the conversation is deleted |

### Notices from other mods

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `noticeRetentionDays` | `7` | 1 | Notices older than this are deleted |
| `maxNoticesPerPlayer` | `50` | 1 | Above this, the player's oldest notice is deleted |
| `noticesFromShops` | `true` | | The owner of a player shop gets a notice for every sale and purchase |
| `noticesFromQuests` | `true` | | Players get a notice for every finished quest |
| `noticesFromAchievements` | `true` | | Players get a notice for every unlocked achievement |

The three switches only matter while the mod in question is installed. Notices that other mods send through the [API](./api), such as guild invitations, are not affected by them.

### Shared positions

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `pinMinutes` | `30` | 1 | How long a shared position stays on the companion's world map and in their Star Map |
| `maxPinsPerPlayer` | `20` | 1 | Shared positions a player can see at once. Above this, the oldest one goes. |

### Farcalls

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `ringSeconds` | `30` | 1 | How long a call rings before it counts as not answered |
| `ringSoundEverySeconds` | `3` | 1 | How often the ring sound repeats for the player who is being called |
| `callsPerMinute` | `6` | 1 | Calls a player may start per minute |
| `callCooldownSeconds` | `30` | 0 | After a declined call, the caller waits this many seconds before calling that player again |

### Hints and sounds

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `toastSeconds` | `8` | 1 | How long each hint card stays at the screen edge |
| `maxQueuedToasts` | `20` | 1 | Hints that can wait per player. When the line is full, the oldest waiting hint is dropped. |
| `soundMessage` | `SFX_Drop_Items_Gems` | | A new message or shared position, and the login summary of new messages |
| `soundNotice` | `SFX_Drop_Items_Gems` | | A notice from another mod, a companion request, an accepted request, and the end of a call |
| `soundRing` | `SFX_Sleep_Notification` | | A ringing call, for the player who is being called |

Sounds are Hytale sound event IDs. Leave a value empty for no sound. Players can switch sounds off for themselves with **Sounds** or **Silence** in the stone's settings.

### Background

| Key | Default | Minimum | What it does |
|-----|---------|---------|--------------|
| `presenceTickMillis` | `1000` | 200 | How often, in milliseconds, the stone reads player positions and runs its timers (ringing, hints, shared positions). Needs a restart. |

### Item and command

| Key | Default | What it does |
|-----|---------|--------------|
| `giveOnFirstJoin` | `true` | Every player gets one Whisperstone on their first join. A full inventory gets another try on the next join or world change. |
| `commandNeedsItem` | `false` | When `true`, `/kswhisper` only opens the stone if the player carries a Whisperstone |

## Runes file

`runes.json` lists the runes that open other mods. The built-in runes (Raven, Farcall, Companions, Star Map, Stone) are not in it and cannot be changed.

### Default runes

| `id` | Label (en-US) | `page` | `order` | `command` | `requiredPlugin` | `permission` |
|------|---------------|--------|---------|-----------|------------------|--------------|
| `schatz` | Treasury | 0 | 50 | `ksbank page 1` | `kyuubisoft:bank` | `ks.bank.user.page` |
| `rolle` | Quests | 0 | 60 | `ksquest` | `kyuubisoft:questbook` | `ks.quest.user.use` |
| `markt` | Marketplace | 0 | 70 | `ksshop browse` | `kyuubisoft:shops` | `ks.shop.user.browse` |
| `brett` | Notice Board | 0 | 80 | `ksinfo` | `kyuubisoft:infohub` | `ks.info.user.use` |
| `tier` | Pets | 1 | 10 | `kspet` | `kyuubisoft:pets` | `ks.pet.user.use` |
| `erfolg` | Achievements | 1 | 20 | `ksachievements` | `kyuubisoft:achievements` | `ks.achievements.user.use` |
| `saison` | Season Pass | 1 | 30 | `ksseasonpass open` | `kyuubisoft:seasonpass` | `ks.seasonpass.user.use` |
| `grab` | Graveyard | 1 | 40 | `ksgraveyard menu` | `kyuubisoft:graveyard` | `ks.graveyard.user.use` |
| `stimme` | Voice Channels | 1 | 50 | `ksvoice open` | `kyuubisoft:voicehub` | `ks.voicehub.user.use` |

Each entry looks like this in the file:

```json
{
  "id": "schatz",
  "labels": {"en-US": "Treasury", "de-DE": "Schatzkammer", "es-ES": "Tesoro", "fr-FR": "Trésor", "it-IT": "Tesoro", "pl-PL": "Skarbiec", "pt-BR": "Tesouro", "ru-RU": "Сокровищница", "tr-TR": "Hazine"},
  "icon": "schatz",
  "page": 0,
  "order": 50,
  "command": "ksbank page 1",
  "requiredPlugin": "kyuubisoft:bank",
  "permission": "ks.bank.user.page"
}
```

### Fields

| Field | What it does |
|-------|--------------|
| `runesVersion` | At the top of the file. Used for updates, see below. A file without it counts as version 1. The bundled file is version 2. |
| `id` | 1 to 32 characters: `a`-`z`, `0`-`9`, `-` and `_`. Not `bote`, `fern`, `gef`, `karte` or `stein`, which belong to the built-in runes. |
| `labels` | The name on the tile, by language code. A missing language falls back to `en-US`, then to any label, then to the `id`. |
| `icon` | The symbol on the tile, see [Icons](#icons). Any other value shows the stone symbol. |
| `page` | `0` for the first page, `1` for the second |
| `order` | Position on the page, lower numbers first |
| `command` | The command the tile runs, as the player who clicks it. A leading `/` is allowed. |
| `requiredPlugin` | Optional. A plugin ID such as `kyuubisoft:bank`. The rune is hidden while that plugin is not loaded. |
| `permission` | Optional. The rune is hidden for players who have this node set to `false`. Players without any setting see it. |

An entry with a bad `id`, a reserved `id` or no `command` is skipped. The log names it: `Ignored rune in runes.json (<id>): <reason>`.

### Icons

These symbols ship with the stone:

`bote`, `brett`, `erfolg`, `fern`, `gef`, `grab`, `karte`, `markt`, `rolle`, `saison`, `schatz`, `stein`, `tier`

### How runes are laid out

- The built-in runes sit on the first page with the orders 10 (Raven), 20 (Farcall), 30 (Companions) and 40 (Star Map). Stone is always the last tile of the first page.
- Each page holds 9 tiles. Runes that do not fit on the first page move to the front of the second page.
- Runes that do not fit on the second page are left out. The log says `No room for rune <id>, two pages hold 18 tiles`.
- A rune is hidden for a player when its mod is not loaded or the player's permission for it is denied. Farcall is hidden while voice is not available.
- A number on a tile counts what is unread: messages and notices on Raven, open requests on Companions, and the unread notices of that mod on a mod's rune.

### Running a rune

The tile runs its command as the player. The window of the other mod replaces the stone. If the command does not exist on the server, the player sees `This rune cannot be opened right now.` and the log says which command is missing. When the other mod refuses the command, for example for a missing permission, the stone gives no message of its own.

### Updates

When a new Whisperstone version brings new runes, they are added to your file once:

- Only runes that came after the version of your file are added, and only if your file has no rune with that `id`. A rune you removed earlier stays removed.
- Your file is saved first as `runes.json.backup`. Everything you changed stays as it is.
- Version 1.0.3 adds the Voice Channels rune to files from older versions.

If `runes.json` cannot be read, the stone uses the bundled runes and leaves your file alone. The log says `runes.json is broken, using the bundled runes`.

### Adding your own rune

Add an entry to the `runes` list and run `/kswhisper reload`:

```json
{
  "id": "myrune",
  "labels": {"en-US": "My Rune", "de-DE": "Meine Rune"},
  "icon": "karte",
  "page": 1,
  "order": 60,
  "command": "yourcommand open",
  "requiredPlugin": "",
  "permission": ""
}
```

Replace `yourcommand open` with a command that exists on your server. Best is a command that opens a window. Other mods can add runes from their code through the [API](./api#registerrune); a rune from the API with the same `id` replaces the one in the file.

## Language files

The texts are in `localization/<language>.json`, for example `en-US.json`. You can change them and load them with `/kswhisper reload`. When an update brings newer texts, your file is replaced and the old one is kept as `<language>.json.backup-v<old version>`. See [Getting Started](./getting-started#languages).

## Database

`whisperstone.db` is an SQLite file with these tables:

| Table | Content |
|-------|---------|
| `players` | Name, last seen, and whether the first stone was given |
| `relations` | Companions, open requests and blocks |
| `messages` | Messages and shared positions in conversations |
| `read_markers` | How far each player has read each conversation |
| `notices` | Notices from other mods |
| `pins` | Shared positions on the world map, with their end time |
| `settings` | The five switches of each player |

About once an hour, messages and notices older than their retention time and expired positions are deleted. Running calls and the hints on the screen are not stored.