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
Section titled “How changes apply”- Edit the files and run
/kswhisper reload. Running calls and hints keep going. presenceTickMillisis read once when the server starts. A change to it needs a restart.- A key that is missing from
config.jsongets its default and is written back into the file, so new options appear after an update. - If
config.jsoncannot be read, Whisperstone uses the defaults and leaves the file alone until you fix it. The log saysconfig.json is broken, using defaults until it is fixed. - Values below the minimum in the tables are raised to the minimum.
config.json
Section titled “config.json”Default file
Section titled “Default file”{ "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
Section titled “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
Section titled “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
Section titled “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, such as guild invitations, are not affected by them.
Shared positions
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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:
{ "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
Section titled “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. 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>.
These symbols ship with the stone:
bote, brett, erfolg, fern, gef, grab, karte, markt, rolle, saison, schatz, stein, tier
How runes are laid out
Section titled “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
Section titled “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
Section titled “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
Section titled “Adding your own rune”Add an entry to the runes list and run /kswhisper reload:
{ "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; a rune from the API with the same id replaces the one in the file.
Language files
Section titled “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.
Database
Section titled “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.