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.WhisperstoneAPIAll methods are static and safe to call from any thread.
Optional dependency
Section titled “Optional dependency”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);}Methods
Section titled “Methods”| Method | Returns |
|---|---|
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 |
notify
Section titled “notify”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
soundNoticesound, 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. runeIdnames the rune that speaks, for examplemarkt. 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 emptyruneIdbecomesstein.- 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.
maxNoticesPerPlayerandnoticeRetentionDaysfromconfig.jsonapply.
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.
registerRune
Section titled “registerRune”Adds a tile to the start screen, or replaces one with the same id.
| Parameter | Meaning |
|---|---|
id | 1 to 32 characters: a-z, 0-9, - and _. Not bote, fern, gef, karte or stein. |
labels | The name on the tile, by language code. en-US is the fallback. |
icon | One of the symbols listed under Icons. Any other value shows the stone symbol. |
page | 0 or 1 |
order | Position on the page, lower numbers first |
command | Runs as the player when the tile is used. Let it open a window: the stone stays open until that window replaces it. |
requiredPlugin | For example kyuubisoft:bank. The tile is hidden while that plugin is not loaded. May be null. |
permission | Checked as “allowed unless set to false”. May be null. |
- A rune from the API replaces an entry with the same
idinrunes.json. - Registered runes live as long as the server runs. They are not saved, so register them again after every start.
registerRunereturnsfalsewhen Whisperstone is not running or the definition cannot be used. The reason is logged asRefused 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");unregisterRune
Section titled “unregisterRune”Removes a rune that was added with registerRune. An entry with the same id in runes.json shows again.
Who uses it
Section titled “Who uses it”| Sender | Rune | Notice |
|---|---|---|
| Player Shops | markt | Iron Sword ×1 sold · +120 to the shop owner, or bought with a minus for purchases |
| Quests | rolle | Completed: <quest name> |
| Achievements | erfolg | New achievement unlocked. |
| Guilds | brett | A 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.