# Getting Started

This page walks you through installing Whisperstone and trying it for the first time.

## Requirements

- Hytale server 0.7.x (version 1.0.3 is built against 0.7.0)
- Java 25

:::note[Voice for farcalls]
Farcalls use the server's own voice chat. If the server has no voice module, or voice is switched off, Whisperstone runs without calls: the Farcall rune, the call buttons and the **Accept farcalls** switch are hidden. Everything else works.
:::

## Installation

1. Place `KyuubiSoftWhisperstone-1.0.3.jar` in your server's `mods/` folder.
2. Start or restart the server.

On the first start Whisperstone creates its data folder `mods/kyuubisoft_whisperstone/` with:

| File | What it is |
|------|------------|
| `config.json` | Limits, times, sounds and the first-join stone. See [Configuration](./configuration). |
| `runes.json` | The runes of other mods on the start screen. See [Configuration](./configuration#runes-file). |
| `localization/` | One language file for each of the 9 languages |
| `whisperstone.db` | The SQLite database with companions, messages, notices, shared positions and settings |

The language choice is shared with the other KyuubiSoft mods in the folder `mods/kslang/`.

Among others, you should see these lines in the log:

```
[Whisperstone] Loaded 9 language(s), en-US has 207 keys
[Whisperstone] Setup complete
[Whisperstone] Started
```

If the server has no voice module, you also see `[Whisperstone] No voice module on this server, calls are off`.

When the first player joins, Whisperstone connects to the other KyuubiSoft mods that send notices. For each one it finds, it logs a line such as `[Whisperstone] Listening to Shops`, `Listening to Quests` or `Listening to Achievements`.

## Getting a stone

There are three ways to get a Whisperstone:

- **First join.** Every player gets one stone on their first join while `giveOnFirstJoin` is `true` (the default). A player who already carries a stone gets no second one. If the inventory is full, they get it the next time they join or change worlds.
- **Crafting.** At the Workbench, in its tinkering category (`Workbench_Tinkering`). Crafting takes 3 seconds.
- **Admins.** `/kswhisper give <player>` hands a stone to a player who is online. See [Commands](./commands).

| Ingredient | Amount |
|------------|--------|
| `Ingredient_Crystal_Blue` | 3 |
| `Ingredient_Bar_Copper` | 2 |
| `Ingredient_Fibre` | 4 |

The stone is the item `Whisperstone`: a blue crystal shard of quality Rare that does not stack.

You do not need the item to use the stone: `/kswhisper` opens it as well. To make players carry the stone, set `commandNeedsItem` to `true`. Then `/kswhisper` only works with a Whisperstone in the inventory.

## First steps

### For players

1. **Open the stone.** Hold it and right-click it, or type `/kswhisper`.
2. **Find a companion.** Open the **Companions** rune and choose **Find companions**. Type a name or pick a player from **On the server right now**, then click **Request**.
3. **Accept.** The other player sees `<name> wants to be your companion.` at the edge of the screen. They click **Accept** under **Requests** on the **Find companions** screen. If they open the stone while the hint is still on the screen, it goes there directly.
4. **Write.** Open the **Raven** rune, or the raven button next to your companion. Type into **Whisper something …** and press **Send** or Enter.
5. **Call.** Click **Farcall** at the top of a conversation, or the call button next to your companion. They answer by opening their stone and clicking **Accept**.
6. **Share your position.** In a conversation, click the button with the star symbol left of the text field. Your companion gets the position as a message and as a marker on their world map.

All screens are described in [Player UI](./ui-pages).

### For admins

1. **Grant the admin node** `ks.whisperstone.admin` to yourself or your staff group. See [Permissions](./permissions).
2. **Try it alone.** `/kswhisper demo` adds the test companion **Aldric (Test)**, just for you. He greets you, shares a position about 142 blocks to the northeast, sends a sample Marketplace notice and answers your messages after 2 seconds.
3. **Test a call.** `/kswhisper demo ring` makes Aldric call you. When you accept, you hear your own voice, as a voice test. You can also call him: he answers after 3 seconds.
4. **Adjust the settings** in `config.json` and `runes.json`, then run `/kswhisper reload`. See [Configuration](./configuration).

To remove Aldric again, open **Companions**, click his row and choose **Remove**.

## Languages

Whisperstone comes in 9 languages:

| Code | Language |
|------|----------|
| `en-US` | English |
| `de-DE` | Deutsch |
| `es-ES` | Español |
| `fr-FR` | Français |
| `it-IT` | Italiano |
| `pl-PL` | Polski |
| `pt-BR` | Português (BR) |
| `ru-RU` | Русский |
| `tr-TR` | Türkçe |

The files are in `mods/kyuubisoft_whisperstone/localization/`. You can change texts there and load them with `/kswhisper reload`. When an update brings a newer version of a file, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`, so copy your own changes back from there.

Players choose their language with `/kslang <code>`. `/kslang` alone shows the current language and the codes, and `/kslang auto` follows the game language. The choice applies to all KyuubiSoft mods.

The names of the runes from other mods are not in these files. They are in `runes.json`, one label per language.

## Optional integrations

Whisperstone runs on its own. With other KyuubiSoft mods it does more:

| Mod | What it adds |
|-----|--------------|
| [KyuubiSoft Core](https://wiki.kyuubisoft.com/hytale/core/) | Real player heads in the head of a conversation and on the call screens. The cards at the screen edge hide while the world map is open. On showcase servers, the showcase key opens the stone and hands it out once. |
| [VoiceHub](https://wiki.kyuubisoft.com/hytale/voicehub/) | The **Voice Channels** rune. During a call only your companion hears you, even inside a VoiceHub channel. A VoiceHub voice ban also keeps you silent in calls. |
| [Player Shops](https://wiki.kyuubisoft.com/hytale/player-shops/) | The **Marketplace** rune and a notice for the shop owner on every sale or purchase |
| [Quests](https://wiki.kyuubisoft.com/hytale/quest-system/) | The **Quests** rune and a notice for every finished quest |
| [Achievements](https://wiki.kyuubisoft.com/hytale/achievement-system/) | The **Achievements** rune and a notice for every unlocked achievement |
| [Guilds](https://wiki.kyuubisoft.com/hytale/guilds/) | Guild invitations reach offline players as notices |
| [Bank](https://wiki.kyuubisoft.com/hytale/bank/), [Info Hub](https://wiki.kyuubisoft.com/hytale/info-hub/), [Pets](https://wiki.kyuubisoft.com/hytale/pets/), [Season Pass](https://wiki.kyuubisoft.com/hytale/season-pass/), [Graveyard](https://wiki.kyuubisoft.com/hytale/graveyard/) | Their runes |

A missing mod causes no error. Its rune is simply not there.