# Getting Started

# Getting Started

This guide walks you through installing VoiceHub on your Hytale server and configuring it for first use.

## Requirements

- Hytale Server 0.7.x (Update 7; version 1.2.4 is built against 0.7.0)
- Java 25+

:::info Voice routing
If the server's voice module is not available, VoiceHub runs in **channel-management-only mode**: channel creation, joining and the UI work, but voice routing is disabled.
:::

## Installation

1. Download the latest `KyuubiSoftVoiceHub.jar` from the releases page.
2. Place the JAR in your server's `mods/` directory.
3. Start (or restart) the server.

On first launch VoiceHub will:
- Extract the default `config.json` to its data folder
- Extract localization files for all 9 supported languages
- Create the SQLite database (`voicehub.db`)
- Create the default channels defined in the config (Proximity and Global by default)
- Install the VoiceRouter hook (if the VoiceModule is available)

You should see log messages like:

```
[VoiceHub] KyuubiSoft VoiceHub v1.0.0 loaded
[VoiceHub] Config loaded (2 default channel(s))
[VoiceHub] Loaded 0 persistent channel(s)
[VoiceHub] Voice routing enabled — VoiceRouter hook active
[VoiceHub] Started — 2 channel(s) active
```

## First Steps

### For Players

1. **Open the channel browser** -- type `/ksvoice open` (or `/vc open`, or `/voicehub open`).
2. **You start in the Proximity channel** -- nearby players can hear you automatically.
3. **Create a channel** -- switch to the **Create** tab, give it a name, choose a type, and click Create.
4. **Invite friends** -- use `/ksvoice invite <player>` or share the channel ID so they can `/ksvoice join <id>`.
5. **Text chat** -- type `!vc <message>` to send text only to your channel members.

### For Admins

1. **Grant yourself admin permission** -- add `kyuubisoft.voicehub.admin` to your player or group.
2. **Open the admin panel** -- type `/ksvoice admin panel`.
3. **Adjust proximity settings** -- change the hearing range and full-volume distance in the admin panel, or via commands:
   ```
   /ksvoice proximity range 100
   /ksvoice proximity volume 24
   ```
4. **Create a persistent admin channel** with a join permission:
   ```
   /ksvoice admin create StaffChat GROUP --perm myserver.staff.voice
   ```

## Configuration Overview

The configuration file is located at `<data-folder>/config.json`. Key settings:

| Setting | Default | What it does |
|---------|---------|-------------|
| `proximity.maxHearingDistance` | `64.0` | How far away players can hear each other (blocks) |
| `proximity.fullVolumeDistance` | `16.0` | Distance at which volume begins to fade |
| `channels.maxChannelsPerPlayer` | `3` | Max channels a single player can own |
| `channels.maxChannelsTotal` | `50` | Server-wide channel limit |
| `channels.allowPlayerCreatedChannels` | `true` | Whether players can create their own channels |
| `channels.allowGlobalChannels` | `false` | Whether GLOBAL type channels are allowed |
| `channels.autoDeleteEmptyAfterMinutes` | `30` | Auto-cleanup timer for empty channels |

See the full [Configuration Reference](./configuration.md) for all options.

## Default Channels

VoiceHub ships with two default channels defined in `config.json`:

| Channel | Type | Description |
|---------|------|-------------|
| **Proximity** | `PROXIMITY` | Distance-based voice -- players nearby can hear you |
| **Global** | `GLOBAL` | Server-wide voice channel |

Default channels are created on server start and cannot be deleted by players. Players are automatically placed in the first default channel (Proximity) when they connect.

You can add, remove, or modify default channels in the `defaultChannels` array of `config.json`:

```json
"defaultChannels": [
  {
    "name": "Proximity",
    "description": "Players nearby can hear you",
    "type": "PROXIMITY"
  },
  {
    "name": "Global",
    "description": "Server-wide voice channel",
    "type": "GLOBAL"
  }
]
```

## Localization

VoiceHub supports 9 languages out of the box:

| Code | Language |
|------|----------|
| `en-US` | English |
| `de-DE` | Deutsch |
| `fr-FR` | Francais |
| `es-ES` | Espanol |
| `pt-BR` | Portugues (BR) |
| `ru-RU` | Russian |
| `pl-PL` | Polski |
| `tr-TR` | Turkish |
| `it-IT` | Italiano |

Language files are stored in `<data-folder>/localization/`. Players can change their language with `/kslang <code>` or `/kslang` to open the language selection UI.

## Optional Integrations

VoiceHub is fully standalone but can integrate with other KyuubiSoft mods when present:

| Integration | What it provides |
|-------------|-----------------|
| **KyuubiSoft Core** | Player avatars (HyVatar) in the member list, I18n context for per-player localization, Showcase NPC opener |

These integrations are detected at runtime via reflection and are silently skipped if Core is not installed.