Skip to content

Configuration

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

FileWhat it holds
config.jsonLimits, times, sounds and the first-join stone
runes.jsonThe runes of other mods on the start screen
localization/<language>.jsonAll texts, one file per language
whisperstone.dbThe SQLite database
  • 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.
{
"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
}
KeyDefaultMinimumWhat it does
maxContacts1001Most 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.
requestsPerMinute101Companion requests a player may send per minute
requestCooldownSeconds600After a declined request, the asker waits this many seconds before asking that player again
KeyDefaultMinimumWhat it does
maxMessageLength2001Longest 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.
messagesPerSecond11Messages a player may send per second. Shared positions count too.
messagesPerMinute201Messages a player may send per minute. Shared positions count too.
messageRetentionDays301Messages older than this are deleted
maxMessagesPerConversation2001Above this, the oldest message of the conversation is deleted
KeyDefaultMinimumWhat it does
noticeRetentionDays71Notices older than this are deleted
maxNoticesPerPlayer501Above this, the player’s oldest notice is deleted
noticesFromShopstrueThe owner of a player shop gets a notice for every sale and purchase
noticesFromQueststruePlayers get a notice for every finished quest
noticesFromAchievementstruePlayers 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.

KeyDefaultMinimumWhat it does
pinMinutes301How long a shared position stays on the companion’s world map and in their Star Map
maxPinsPerPlayer201Shared positions a player can see at once. Above this, the oldest one goes.
KeyDefaultMinimumWhat it does
ringSeconds301How long a call rings before it counts as not answered
ringSoundEverySeconds31How often the ring sound repeats for the player who is being called
callsPerMinute61Calls a player may start per minute
callCooldownSeconds300After a declined call, the caller waits this many seconds before calling that player again
KeyDefaultMinimumWhat it does
toastSeconds81How long each hint card stays at the screen edge
maxQueuedToasts201Hints that can wait per player. When the line is full, the oldest waiting hint is dropped.
soundMessageSFX_Drop_Items_GemsA new message or shared position, and the login summary of new messages
soundNoticeSFX_Drop_Items_GemsA notice from another mod, a companion request, an accepted request, and the end of a call
soundRingSFX_Sleep_NotificationA 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.

KeyDefaultMinimumWhat it does
presenceTickMillis1000200How often, in milliseconds, the stone reads player positions and runs its timers (ringing, hints, shared positions). Needs a restart.
KeyDefaultWhat it does
giveOnFirstJointrueEvery player gets one Whisperstone on their first join. A full inventory gets another try on the next join or world change.
commandNeedsItemfalseWhen true, /kswhisper only opens the stone if the player carries a Whisperstone

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.

idLabel (en-US)pageordercommandrequiredPluginpermission
schatzTreasury050ksbank page 1kyuubisoft:bankks.bank.user.page
rolleQuests060ksquestkyuubisoft:questbookks.quest.user.use
marktMarketplace070ksshop browsekyuubisoft:shopsks.shop.user.browse
brettNotice Board080ksinfokyuubisoft:infohubks.info.user.use
tierPets110kspetkyuubisoft:petsks.pet.user.use
erfolgAchievements120ksachievementskyuubisoft:achievementsks.achievements.user.use
saisonSeason Pass130ksseasonpass openkyuubisoft:seasonpassks.seasonpass.user.use
grabGraveyard140ksgraveyard menukyuubisoft:graveyardks.graveyard.user.use
stimmeVoice Channels150ksvoice openkyuubisoft:voicehubks.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"
}
FieldWhat it does
runesVersionAt the top of the file. Used for updates, see below. A file without it counts as version 1. The bundled file is version 2.
id1 to 32 characters: a-z, 0-9, - and _. Not bote, fern, gef, karte or stein, which belong to the built-in runes.
labelsThe name on the tile, by language code. A missing language falls back to en-US, then to any label, then to the id.
iconThe symbol on the tile, see Icons. Any other value shows the stone symbol.
page0 for the first page, 1 for the second
orderPosition on the page, lower numbers first
commandThe command the tile runs, as the player who clicks it. A leading / is allowed.
requiredPluginOptional. A plugin ID such as kyuubisoft:bank. The rune is hidden while that plugin is not loaded.
permissionOptional. 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

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

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.

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.

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.

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.

whisperstone.db is an SQLite file with these tables:

TableContent
playersName, last seen, and whether the first stone was given
relationsCompanions, open requests and blocks
messagesMessages and shared positions in conversations
read_markersHow far each player has read each conversation
noticesNotices from other mods
pinsShared positions on the world map, with their end time
settingsThe 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.