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

## 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:

```json
"OptionalDependencies": {
  "kyuubisoft:whisperstone": "*"
}
```

```java
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

| 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

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.

### 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](./configuration#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 `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](./configuration#how-runes-are-laid-out).

```java
WhisperstoneAPI.registerRune("myrune", Map.of("en-US", "My Rune", "de-DE", "Meine Rune"),
    "karte", 1, 60, "yourcommand open", "yourgroup:yourmod", "yourmod.user.use");
```

### unregisterRune

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

## Who uses it

| Sender | Rune | Notice |
|--------|------|--------|
| [Player Shops](https://wiki.kyuubisoft.com/hytale/player-shops/) | `markt` | `Iron Sword ×1 sold · +120` to the shop owner, or `bought` with a minus for purchases |
| [Quests](https://wiki.kyuubisoft.com/hytale/quest-system/) | `rolle` | `Completed: <quest name>` |
| [Achievements](https://wiki.kyuubisoft.com/hytale/achievement-system/) | `erfolg` | `New achievement unlocked.` |
| [Guilds](https://wiki.kyuubisoft.com/hytale/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.