# Configuration

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

The Hytale addon is configured through the `hytale.json(5)` file located in your bot's `configuration/` folder. This guide will walk you through each section to help you set up seamless Discord-Hytale integration.

{% hint style="info" %}
**Remember:** You must also configure the server-side plugin on your Hytale server. See the main Hytale documentation for server setup requirements.
{% endhint %}

***

## <mark style="color:blue;">Part 1: API Connection</mark>

### <mark style="color:yellow;">Connecting to Your Hytale Server</mark>

The first step is configuring how Athena Bot communicates with your Hytale server.

```json5
hytale_server_api: {
    hytale_server_ip: "localhost",
    hytale_server_api_port: 3333
}
```

***

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

**hytale\_server\_ip** (String)

* The IP address of your Hytale server
* Use `"localhost"` if the bot and server are on the same machine
* Use the server's public IP if they're on different machines
* **Examples:**
  * Same machine: `"localhost"`
  * Different machine: `"192.168.1.100"` or `"play.example.com"`

**hytale\_server\_api\_port** (Number)

* The port the Hytale server plugin's API listens on
* **Must match** the port in your Hytale server's `config.json`
* **Default:** `3333`
* This is **NOT** your Hytale game server port!

{% hint style="warning" %}
**Firewall Configuration:** If your bot and Hytale server are on different machines, ensure the API port is open in your firewall and accessible to the bot.
{% endhint %}

***

## <mark style="color:blue;">Part 2: Account Linking</mark>

### <mark style="color:yellow;">Linked Role Assignment</mark>

Automatically assign a Discord role to players who link their accounts.

```json5
account_linking: {
    linked_role: {
        enabled: false,
        role_id: "1457834856447873355"
    }
}
```

**enabled** (Boolean)

* Set to `true` to enable automatic role assignment
* Set to `false` to disable this feature

**role\_id** (String)

* The Discord role ID to assign to linked players
* Right-click a role in Discord → Copy ID (requires Developer Mode)
* Use this to give linked players special permissions or access

***

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

Automatically update Discord nicknames to include Hytale usernames.

```json5
nickname_sync: {
    enabled: true,
    format: "[%hytale_name%] %discord_name%"
}
```

**enabled** (Boolean)

* Set to `true` to automatically sync nicknames when players link accounts
* Set to `false` to leave nicknames unchanged

**format** (String)

* The template for the synchronized nickname
* **Available Placeholders:**
  * `%hytale_name%` - The player's Hytale username
  * `%discord_name%` - The user's Discord username
  * `%discord_display_name%` - The user's Discord display name
* **Examples:**
  * `"[%hytale_name%] %discord_name%"` → `[Steve123] JohnDoe`
  * `"%hytale_name%"` → `Steve123`
  * `"%hytale_name% | %discord_display_name%"` → `Steve123 | John`
* Maximum length: 32 characters (Discord limit)

***

### <mark style="color:yellow;">Discord Rewards</mark>

Give coins or other Discord-based rewards when players link their accounts.

```json5
discord_rewards: {
    enabled: true,
    recurrence: "once",
    rewards: {
        coins: 1000
    }
}
```

**enabled** (Boolean)

* Set to `true` to give Discord rewards upon linking
* Set to `false` to disable Discord rewards

**recurrence** (String)

* How often players can claim Discord linking rewards
* **Options:**
  * `"once"` - One-time reward, never claimable again
  * `"24h"` - Claimable once every 24 hours
  * `"7d"` - Claimable once every 7 days
  * `"30d"` - Claimable once every 30 days

**rewards.coins** (Number)

* Amount of economy coins to give
* Set to `0` to disable coin rewards
* Requires the Economy addon to be installed
* **Recommended values:**
  * One-time: `500-2000` coins
  * Daily: `100-500` coins
  * Weekly: `1000-3000` coins

{% hint style="info" %}
**Adding More Discord Rewards:** Future updates may include additional reward types like XP, badges, or items. Currently, only coins are supported.
{% endhint %}

***

### <mark style="color:yellow;">In-Game Rewards</mark>

Execute commands on the Hytale server to give items, currency, or other bonuses when players link.

```json5
ingame_rewards: {
    enabled: true,
    recurrence: "once",
    commands: [
        "give %player% Weapon_Axe_Iron_Rusty"
    ]
}
```

**enabled** (Boolean)

* Set to `true` to execute in-game reward commands
* Set to `false` to disable in-game rewards

**recurrence** (String)

* How often players can claim in-game linking rewards
* Same options as Discord rewards: `"once"`, `"24h"`, `"7d"`, `"30d"`

**commands** (Array)

* List of commands to execute on the Hytale server
* Commands run with administrator privileges
* **Available Placeholders:**
  * `%player%` - The player's Hytale username
* **Examples:**
  * `"give %player% Weapon_Sword_Iron"` - Give an iron sword
  * `"give %player% Item_Currency_Gold 100"` - Give 100 gold
  * `"teleport %player% SpawnPoint"` - Teleport to spawn
  * `"addpermission %player% vip"` - Grant VIP permission

You can add multiple commands:

```json5
commands: [
    "give %player% Weapon_Axe_Iron_Rusty",
    "give %player% Item_Currency_Gold 500",
    "give %player% Armor_Chest_Leather"
]
```

***

## <mark style="color:blue;">Part 3: Ban Synchronization</mark>

### <mark style="color:yellow;">Keeping Bans Synchronized</mark>

Automatically synchronize bans between Discord and your Hytale server.

```json5
ban_sync: {
    discord_to_hytale: false,
    hytale_to_discord: false,
    ban_command: "ban %player% %reason%"
}
```

***

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

**discord\_to\_hytale** (Boolean)

* Set to `true` to automatically ban linked Hytale accounts when their Discord account is banned
* Set to `false` to disable this sync direction
* When a user with a linked account is banned on Discord, their Hytale account will be banned automatically

**hytale\_to\_discord** (Boolean)

* Set to `true` to automatically ban Discord accounts when their linked Hytale account is banned
* Set to `false` to disable this sync direction
* When a linked player is banned on Hytale, their Discord account will be banned from the server

**ban\_command** (String)

* The command used to ban players on your Hytale server
* **Available Placeholders:**
  * `%player%` - The player's Hytale username
  * `%reason%` - The ban reason from Discord
* **Examples:**
  * `"ban %player% %reason%"`
  * `"blacklist add %player% %reason%"`
  * `"punishment ban %player% permanent %reason%"`

{% hint style="danger" %}
**Use Ban Sync Carefully:** Enabling bidirectional ban sync can be powerful but may lead to unintended consequences. Consider enabling only one direction, or carefully test with a non-linked account first.
{% endhint %}

***

## <mark style="color:blue;">Part 4: Server Status Panel</mark>

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

Display a live-updating embed in Discord showing your Hytale server's current status.

```json5
server_status_panel: {
    enabled: false,
    update_interval: "1m",
    server_name: "My Hytale Server",
    server_description: "An awesome Hytale server!",
    thumbnail: "",
    show_ip: false,
    ip_address: "play.example.com",
    port: 5520,
    max_players: 100,
    show_tps: true,
    show_memory: true,
    show_uptime: true,
    show_player_list: true,
    show_refresh_button: true,
    buttons: []
}
```

***

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

**enabled** (Boolean)

* Set to `true` to enable the server status panel
* Set to `false` to disable it
* When enabled, a dedicated embed will be posted in your configured channel

**update\_interval** (String)

* How often to automatically refresh the status panel
* **Examples:**
  * `"30s"` - Every 30 seconds (high frequency)
  * `"1m"` - Every 1 minute (recommended)
  * `"5m"` - Every 5 minutes (low frequency)
* Shorter intervals provide more real-time data but use more API calls

**server\_name** (String)

* The display name for your server in the status panel
* Appears as the embed title

**server\_description** (String)

* A brief description of your server
* Appears below the server name

**thumbnail** (String)

* URL to an image to display in the status panel
* Leave empty (`""`) to disable
* Recommended size: 128x128 pixels or larger
* **Example:** `"https://i.imgur.com/yourimage.png"`

***

### <mark style="color:yellow;">Connection Information</mark>

**show\_ip** (Boolean)

* Set to `true` to display the server IP and port
* Set to `false` to hide connection information

**ip\_address** (String)

* The IP address or domain players use to connect
* Only displayed if `show_ip` is `true`
* **Examples:** `"play.example.com"`, `"192.168.1.100"`

**port** (Number)

* The game port players use to connect
* Only displayed if `show_ip` is `true`
* **Default Hytale Port:** `5520`

**max\_players** (Number)

* The maximum number of players your server supports
* Used to display "X/Y players online"

***

### <mark style="color:yellow;">Performance Metrics</mark>

**show\_tps** (Boolean)

* Set to `true` to display TPS (ticks per second)
* TPS indicates server performance (20 TPS = optimal)

**show\_memory** (Boolean)

* Set to `true` to display server memory usage
* Shows used memory and total available memory

**show\_uptime** (Boolean)

* Set to `true` to display how long the server has been running
* Shows days, hours, and minutes since last restart

***

### <mark style="color:yellow;">Player Information</mark>

**show\_player\_list** (Boolean)

* Set to `true` to show a list of all online players
* Set to `false` to only show player count

**show\_refresh\_button** (Boolean)

* Set to `true` to add a refresh button to the status panel
* Players can click the button to manually update the information
* Useful when auto-updates are infrequent

***

### <mark style="color:yellow;">Custom Buttons</mark>

Add custom buttons with links to external resources.

```json5
buttons: [
    { Label: "Website", Emoji: "🌐", URL: "https://example.com" },
    { Label: "Discord", Emoji: "💬", URL: "https://discord.gg/yourinvite" },
    { Label: "Vote", Emoji: "⭐", URL: "https://vote.example.com" }
]
```

Each button requires:

* **Label** (String) - The button text
* **Emoji** (String) - An emoji to display (optional, use `""` to omit)
* **URL** (String) - The link the button opens

You can add up to 5 buttons per status panel.

***

## <mark style="color:blue;">Part 5: Features & Event Notifications</mark>

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

```json5
features: {
    chat_relay: true
}
```

**chat\_relay** (Boolean)

* Set to `true` to enable two-way chat relay between Discord and Hytale
* Discord messages appear in-game, and in-game messages appear in Discord
* Requires a dedicated chat channel to be configured

***

### <mark style="color:yellow;">Player Events</mark>

```json5
player_join_leave: true
```

**player\_join\_leave** (Boolean)

* Set to `true` to send notifications when players join or leave the server
* Displays player names and connection status
* Set to `false` to disable join/leave messages

***

### <mark style="color:yellow;">Server Status Updates</mark>

```json5
server_status_updates: true
```

**server\_status\_updates** (Boolean)

* Set to `true` to send alerts when the server goes online or offline
* Useful for monitoring server crashes or restarts
* Set to `false` to disable status alerts

***

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

```json5
death_messages: true,
world_events: true,
zone_discovery: true
```

**death\_messages** (Boolean)

* Set to `true` to broadcast player deaths and their causes to Discord
* Examples: "Steve123 was slain by a Trork" or "Jane456 fell to their death"

**world\_events** (Boolean)

* Set to `true` to announce major world events
* Examples: Boss spawns, invasions, special encounters
* Helps coordinate community participation

**zone\_discovery** (Boolean)

* Set to `true` to celebrate when players discover new zones or biomes
* Encourages exploration and creates excitement

***

### <mark style="color:yellow;">Chat Enhancements</mark>

```json5
show_world_in_chat: true
```

**show\_world\_in\_chat** (Boolean)

* Set to `true` to include the player's current world/zone in chat messages
* Format: `[Hytale] [Orbis] Steve123: Hello!`
* Set to `false` to only show player names

***

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

```json5
console_channel: true,
console_logging: true
```

**console\_channel** (Boolean)

* Set to `true` to enable a dedicated channel for executing server commands
* Staff can type commands directly in Discord, and they execute on the server
* Requires a console channel to be configured

**console\_logging** (Boolean)

* Set to `true` to relay server console logs to Discord
* Displays real-time server output, warnings, and errors
* Requires a console logging channel to be configured

***

### <mark style="color:yellow;">Console Log Filtering</mark>

Control which types of console messages are relayed to Discord.

```json5
console_relay: {
    server_info: true,
    server_warning: true,
    server_error: true,
    command_log: true,
    player_event: true
}
```

**server\_info** (Boolean)

* General server information messages
* Examples: "Server started", "World loaded"

**server\_warning** (Boolean)

* Warning messages that don't stop the server
* Examples: "Plugin took 5s to load", "High memory usage"

**server\_error** (Boolean)

* Critical error messages
* Examples: "Failed to connect to database", "Plugin crash"

**command\_log** (Boolean)

* Logs of commands executed by players or the console
* Examples: "Steve123 executed: /give @self Item\_Gold"

**player\_event** (Boolean)

* Player-related events beyond join/leave
* Examples: Achievements, level-ups, purchases

{% hint style="info" %}
**Performance Tip:** If console logging is overwhelming your Discord channel, disable less important categories like `server_info` and `player_event`.
{% endhint %}

***

## <mark style="color:blue;">Part 6: Channel Configuration</mark>

### <mark style="color:yellow;">Setting Up Channels</mark>

The Hytale addon requires specific Discord channels to be configured for different features.

Use the `/setup` commands in Discord to assign channels:

* **Hytale Chat & Events** - Where chat relay and event notifications are sent
* **Hytale Console** - Where staff can execute server commands (if enabled)
* **Hytale Console Logs** - Where console output is relayed (if enabled)
* **Hytale Server Status** - Where the live status panel is displayed (if enabled)

{% hint style="warning" %}
**Channel Permissions:** Ensure the bot has permissions to send messages, embeds, and manage messages in all configured channels.
{% endhint %}

***

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

### <mark style="color:yellow;">Minimal Setup (Chat Relay Only)</mark>

```json5
{
    config: {
        hytale_server_api: {
            hytale_server_ip: "localhost",
            hytale_server_api_port: 3333
        },
        account_linking: {
            linked_role: { enabled: false },
            nickname_sync: { enabled: false },
            discord_rewards: { enabled: false },
            ingame_rewards: { enabled: false }
        },
        ban_sync: {
            discord_to_hytale: false,
            hytale_to_discord: false
        },
        server_status_panel: {
            enabled: false
        },
        features: {
            chat_relay: true,
            player_join_leave: true,
            server_status_updates: true,
            death_messages: false,
            world_events: false,
            zone_discovery: false,
            show_world_in_chat: false,
            console_channel: false,
            console_logging: false
        }
    }
}
```

***

### <mark style="color:yellow;">Full-Featured Setup</mark>

```json5
{
    config: {
        hytale_server_api: {
            hytale_server_ip: "play.example.com",
            hytale_server_api_port: 3333
        },
        account_linking: {
            linked_role: {
                enabled: true,
                role_id: "1457834856447873355"
            },
            nickname_sync: {
                enabled: true,
                format: "[%hytale_name%] %discord_name%"
            },
            discord_rewards: {
                enabled: true,
                recurrence: "7d",
                rewards: { coins: 1500 }
            },
            ingame_rewards: {
                enabled: true,
                recurrence: "once",
                commands: [
                    "give %player% Weapon_Sword_Iron",
                    "give %player% Item_Currency_Gold 1000"
                ]
            }
        },
        ban_sync: {
            discord_to_hytale: true,
            hytale_to_discord: false,
            ban_command: "ban %player% %reason%"
        },
        server_status_panel: {
            enabled: true,
            update_interval: "1m",
            server_name: "Orbis Legends",
            server_description: "The premier Hytale survival experience!",
            thumbnail: "https://i.imgur.com/serverlogo.png",
            show_ip: true,
            ip_address: "play.example.com",
            port: 5520,
            max_players: 100,
            show_tps: true,
            show_memory: true,
            show_uptime: true,
            show_player_list: true,
            show_refresh_button: true,
            buttons: [
                { Label: "Website", Emoji: "🌐", URL: "https://example.com" },
                { Label: "Vote", Emoji: "⭐", URL: "https://vote.example.com" }
            ]
        },
        features: {
            chat_relay: true,
            player_join_leave: true,
            server_status_updates: true,
            death_messages: true,
            world_events: true,
            zone_discovery: true,
            show_world_in_chat: true,
            console_channel: true,
            console_logging: true,
            console_relay: {
                server_info: true,
                server_warning: true,
                server_error: true,
                command_log: false,
                player_event: false
            }
        }
    }
}
```

***

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

### <mark style="color:yellow;">Bot Can't Connect to Hytale Server</mark>

* Verify the IP address and port are correct
* Ensure the Hytale server plugin is installed and running
* Check firewall rules allow connections on the API port
* Confirm the API key matches in both config files

### <mark style="color:yellow;">Chat Relay Not Working</mark>

* Ensure `chat_relay` is set to `true`
* Verify the chat channel is configured in Discord
* Check that the Hytale server plugin is receiving messages
* Confirm both `features.chat_relay` is enabled in the server plugin config

### <mark style="color:yellow;">Link Rewards Not Given</mark>

* Verify rewards are `enabled: true`
* For Discord rewards, ensure the Economy addon is installed
* Check that `recurrence` settings aren't blocking repeated claims
* Use `/linkadmin reset-user` to reset a specific user's claims

### <mark style="color:yellow;">Status Panel Not Updating</mark>

* Confirm `enabled: true` in `server_status_panel`
* Verify the status channel is configured
* Check that the Hytale server is online and responding
* Ensure `update_interval` is a valid time format

***

## <mark style="color:blue;">Need More Help?</mark>

If you encounter issues not covered here:

* Review the main Hytale addon documentation
* Join the Athena Bot support Discord server
* Check that both the bot addon and server plugin are up to date
* Contact support with your configuration file and error logs

***