# Hytale

## <mark style="color:blue;">Overview</mark>

The **Hytale** addon creates a powerful bridge between your Discord server and your Hytale game server. Enable two-way chat relay, account linking with rewards, real-time server status monitoring, automated ban synchronization, and remote console access - all seamlessly integrated with Athena Bot.

***

## <mark style="color:blue;">Table of Contents</mark>

1. **Features**
2. **Installation**
3. **Server Requirements**
4. **Commands**

***

## <mark style="color:blue;">Features</mark>

### <mark style="color:yellow;">Account Linking System</mark>

* <mark style="color:red;">**Link Discord to Hytale:**</mark> Players can link their Discord account to their in-game Hytale account
* <mark style="color:red;">**Automatic Role Assignment:**</mark> Assign verified roles to linked players
* <mark style="color:red;">**Nickname Synchronization:**</mark> Automatically sync Discord nicknames with Hytale usernames
* <mark style="color:red;">**Discord Rewards:**</mark> Give coins or other Discord rewards when players link their accounts
* <mark style="color:red;">**In-Game Rewards:**</mark> Execute commands to give in-game items or bonuses upon linking
* <mark style="color:red;">**Recurring Rewards:**</mark> Configure rewards to be claimable once, daily, weekly, or monthly
* <mark style="color:red;">**Admin Controls:**</mark> Force link/unlink accounts and manage reward claims

***

### <mark style="color:yellow;">Two-Way Chat Relay</mark>

* <mark style="color:red;">**Discord to Hytale:**</mark> Messages sent in Discord appear in-game
* <mark style="color:red;">**Hytale to Discord:**</mark> In-game chat messages appear in Discord
* <mark style="color:red;">**Reply Support:**</mark> Discord users can reply to Hytale messages and vice versa
* <mark style="color:red;">**Attachment Detection:**</mark> Automatically indicates when Discord messages contain attachments
* <mark style="color:red;">**World Context:**</mark> Optionally show which world/zone the player is in

***

### <mark style="color:yellow;">Real-Time Server Status Panel</mark>

* <mark style="color:red;">**Live Server Information:**</mark> Display current server status in a dedicated Discord embed
* <mark style="color:red;">**Player Count:**</mark> Show online players and max capacity
* <mark style="color:red;">**Performance Metrics:**</mark> Display TPS (ticks per second), memory usage, and uptime
* <mark style="color:red;">**Player List:**</mark> Show all currently online players
* <mark style="color:red;">**Custom Branding:**</mark> Add server name, description, and thumbnail
* <mark style="color:red;">**Refresh Button:**</mark> Manual refresh option for instant updates
* <mark style="color:red;">**Custom Buttons:**</mark> Add links to your website, wiki, or store
* <mark style="color:red;">**Auto-Updates:**</mark> Configurable update intervals (30s, 1m, 5m, etc.)

***

### <mark style="color:yellow;">Event Notifications</mark>

* <mark style="color:red;">**Player Join/Leave:**</mark> Notify your Discord when players connect or disconnect
* <mark style="color:red;">**Death Messages:**</mark> Broadcast player deaths and their causes
* <mark style="color:red;">**World Events:**</mark> Announce boss spawns, invasions, and special events
* <mark style="color:red;">**Zone Discovery:**</mark> Celebrate when players discover new zones or biomes
* <mark style="color:red;">**Server Status:**</mark> Alert when the server goes online or offline

***

### <mark style="color:yellow;">Ban Synchronization</mark>

* <mark style="color:red;">**Discord to Hytale:**</mark> Automatically ban linked Hytale accounts when a user is banned on Discord
* <mark style="color:red;">**Hytale to Discord:**</mark> Automatically ban Discord users when their Hytale account is banned
* <mark style="color:red;">**Custom Ban Commands:**</mark> Configure the exact command used to ban players in-game
* <mark style="color:red;">**Bidirectional Sync:**</mark> Keep both platforms moderated consistently

***

### <mark style="color:yellow;">Remote Console Access</mark>

* <mark style="color:red;">**Execute Commands:**</mark> Run server commands directly from Discord
* <mark style="color:red;">**Console Channel:**</mark> Dedicated channel for sending commands via chat
* <mark style="color:red;">**Console Logging:**</mark> Real-time relay of server console logs to Discord
* <mark style="color:red;">**Filtered Logs:**</mark> Choose which log categories to display (info, warnings, errors, etc.)
* <mark style="color:red;">**Permission-Based:**</mark> Restrict console access to authorized staff only

***

## <mark style="color:blue;">Installation</mark>

{% hint style="warning" %}
**This is a premium addon!** You must purchase this addon separately and have a valid license.
{% endhint %}

### <mark style="color:yellow;">Step 1: Install Discord Bot Addon</mark>

1. Download the Hytale addon files from your purchase
2. Extract all files into the `plugins/` folder of your Athena Bot installation
3. Restart your bot to load the addon
4. Configure the addon using the `hytale.json5` file in your `configuration/` folder

### <mark style="color:yellow;">Step 2: Install Hytale Server Plugin</mark>

{% hint style="info" %}
The Hytale addon includes a **server-side plugin** that must be installed on your Hytale server.
{% endhint %}

1. Locate the Hytale server plugin files included with your download
2. Install the plugin in your Hytale server's mod/plugin directory
3. Configure the `config.json` file in your Hytale server's plugin directory

***

## <mark style="color:blue;">Server Requirements</mark>

### <mark style="color:yellow;">Hytale Server Plugin Configuration</mark>

The Hytale server-side plugin requires a `config.json` file with the following structure:

```json
{
    "athena_license_key": "YOUR-LICENSE-KEY-HERE",
    "hytale_server_api": {
        "hytale_server_api_port": 3333,
        "hytale_server_api_ip_whitelist": false,
        "hytale_server_api_ip_list": ["localhost"]
    },
    "athena_web_api": {
        "authentication_key": "YOUR-API-KEY-HERE",
        "athena_web_api_ip": "localhost",
        "athena_web_api_port": 3111
    },
    "features": {
        "chat_relay": true,
        "player_join": true,
        "player_leave": true,
        "console_relay": true
    }
}
```

{% hint style="danger" %}
**IMPORTANT:** The `athena_web_api.authentication_key` must match the **first API key** configured in your Athena Bot's Web API settings.
{% endhint %}

### <mark style="color:yellow;">Configuration Parameters</mark>

**athena\_license\_key**

* Your Athena Bot license key

**hytale\_server\_api\_port**

* The port the Hytale plugin's API will listen on (default: 3333)
* This is **NOT** your Hytale game server port

**hytale\_server\_api\_ip\_whitelist**

* Enable IP whitelisting for security (recommended: `true` for production)

**hytale\_server\_api\_ip\_list**

* List of allowed IPs that can connect to the Hytale plugin API
* Include your Athena Bot server's IP address

**athena\_web\_api.authentication\_key**

* API key for authenticating with Athena Bot
* **Must match the first API key in your Web API configuration**

**athena\_web\_api\_ip** and **athena\_web\_api\_port**

* IP address and port where your Athena Bot's Web API is accessible

***

## <mark style="color:blue;">Commands</mark>

### <mark style="color:yellow;">User Commands</mark>

**/link**

* Link your Discord account to your Hytale account
* **Usage:** `/link code:<6-digit-code>`
* **Example:** `/link code:A1B2C3`
* Get your link code by typing `/link` in-game on the Hytale server

**/unlink**

* Unlink your Discord account from your Hytale account
* **Usage:** `/unlink`
* Removes linked role and resets nickname if configured

***

### <mark style="color:yellow;">Admin Commands</mark>

**/hytaleconsole execute**

* Execute a command on the Hytale server console
* **Usage:** `/hytaleconsole execute command:<command>`
* **Example:** `/hytaleconsole execute command:give PlayerName Weapon_Sword_Iron`
* **Permission:** Requires management-level access

**/linkadmin force-link**

* Manually link a Discord user to a Hytale account
* **Usage:** `/linkadmin force-link user:<@user> hytale_username:<username>`
* Bypasses the normal linking process

**/linkadmin force-unlink**

* Manually unlink a Discord user's Hytale account
* **Usage:** `/linkadmin force-unlink user:<@user>`
* Useful for fixing incorrect links

**/linkadmin reset-user**

* Reset a user's link reward claims
* **Usage:** `/linkadmin reset-user user:<@user>`
* Allows them to claim rewards again

**/linkadmin reset-all**

* Reset all users' link reward claims
* **Usage:** `/linkadmin reset-all`
* Use when changing reward configurations

***

## <mark style="color:blue;">Getting Help</mark>

Need assistance with the Hytale addon?

* Join the Athena Bot support Discord server
* Check the configuration guide for detailed setup instructions
* Contact support for technical issues or questions

***