Skip to content

API

Other mods can send notices to a player’s stone and add their own runes to the start screen. Everything goes through one class:

com.kyuubisoft.whisperstone.api.WhisperstoneAPI

All methods are static and safe to call from any thread.

Whisperstone is optional for your mod, so do not link its classes directly. Either keep every use of WhisperstoneAPI inside a separate holder class that is only loaded when Whisperstone is there, or call it by reflection. KyuubiSoft Guilds, for example, uses reflection and lists Whisperstone under OptionalDependencies in its manifest:

"OptionalDependencies": {
"kyuubisoft:whisperstone": "*"
}
Class<?> api = Class.forName("com.kyuubisoft.whisperstone.api.WhisperstoneAPI");
if ((boolean) api.getMethod("isAvailable").invoke(null)) {
api.getMethod("notify", UUID.class, String.class, String.class, String.class)
.invoke(null, playerUuid, "brett", title, text);
}
MethodReturns
isAvailable()true while Whisperstone is running
notify(UUID player, String runeId, String title, String text)true when the notice was stored
registerRune(String id, Map<String, String> labels, String icon, int page, int order, String command, String requiredPlugin, String permission)true when the rune was added
unregisterRune(String id)nothing

Sends a notice to a player’s stone.

  • If the player is online, the notice appears as a hint at the screen edge, with the soundNotice sound, unless the player switched hints or sounds off. It is also stored and shows up in the Raven under Notices.
  • If the player is offline, the notice waits. On their next login they get a summary such as 2 new notices waited for you.
  • runeId names the rune that speaks, for example markt. Its symbol marks the notice, its tile counts the notice in its number, and a click on the notice opens that rune if the player has it. An empty runeId becomes stein.
  • Title and text are shown as they are, so translate them into the player’s language yourself. They are cleaned like messages: line breaks become spaces, invisible characters are removed, and color codes stay plain text. The title is cut to 64 characters and the text to 200.
  • maxNoticesPerPlayer and noticeRetentionDays from config.json apply.

notify returns false when Whisperstone is not running, when the player has never joined the server since Whisperstone was installed, or when title and text are both empty.

Adds a tile to the start screen, or replaces one with the same id.

ParameterMeaning
id1 to 32 characters: a-z, 0-9, - and _. Not bote, fern, gef, karte or stein.
labelsThe name on the tile, by language code. en-US is the fallback.
iconOne of the symbols listed under Icons. Any other value shows the stone symbol.
page0 or 1
orderPosition on the page, lower numbers first
commandRuns as the player when the tile is used. Let it open a window: the stone stays open until that window replaces it.
requiredPluginFor example kyuubisoft:bank. The tile is hidden while that plugin is not loaded. May be null.
permissionChecked as “allowed unless set to false”. May be null.
  • A rune from the API replaces an entry with the same id in runes.json.
  • Registered runes live as long as the server runs. They are not saved, so register them again after every start.
  • registerRune returns false when Whisperstone is not running or the definition cannot be used. The reason is logged as Refused a rune from the API: <reason>.
  • The same layout rules apply as for runes.json. See How runes are laid out.
WhisperstoneAPI.registerRune("myrune", Map.of("en-US", "My Rune", "de-DE", "Meine Rune"),
"karte", 1, 60, "yourcommand open", "yourgroup:yourmod", "yourmod.user.use");

Removes a rune that was added with registerRune. An entry with the same id in runes.json shows again.

SenderRuneNotice
Player ShopsmarktIron Sword ×1 sold · +120 to the shop owner, or bought with a minus for purchases
QuestsrolleCompleted: <quest name>
AchievementserfolgNew achievement unlocked.
GuildsbrettA guild invitation for a player who is offline, with /ksguild accept

Whisperstone itself listens to Player Shops, Quests and Achievements, so these three need no code on their side. They can be switched off with noticesFromShops, noticesFromQuests and noticesFromAchievements. Guilds calls notify itself.