📂Configuration

Complete guide to configuring the Hytale addon

Getting Started

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.

Remember: You must also configure the server-side plugin on your Hytale server. See the main Hytale documentation for server setup requirements.

Part 1: API Connection

Connecting to Your Hytale Server

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

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

Configuration Parameters

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!

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.

Part 2: Account Linking

Linked Role Assignment

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

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

Nickname Synchronization

Automatically update Discord nicknames to include Hytale usernames.

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)

Discord Rewards

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

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

Adding More Discord Rewards: Future updates may include additional reward types like XP, badges, or items. Currently, only coins are supported.

In-Game Rewards

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

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:

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

Part 3: Ban Synchronization

Keeping Bans Synchronized

Automatically synchronize bans between Discord and your Hytale server.

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

Configuration Parameters

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%"

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.

Part 4: Server Status Panel

Real-Time Server Information

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

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: []
}

Basic Configuration

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"

Connection Information

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"

Performance Metrics

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

Player Information

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

Custom Buttons

Add custom buttons with links to external resources.

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.

Part 5: Features & Event Notifications

Chat Relay

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

Player Events

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

Server Status Updates

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

Game Event Notifications

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

Chat Enhancements

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

Console Access

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

Console Log Filtering

Control which types of console messages are relayed to Discord.

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

Performance Tip: If console logging is overwhelming your Discord channel, disable less important categories like server_info and player_event.

Part 6: Channel Configuration

Setting Up Channels

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)

Channel Permissions: Ensure the bot has permissions to send messages, embeds, and manage messages in all configured channels.

Example Configurations

Minimal Setup (Chat Relay Only)

{
    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
        }
    }
}

Full-Featured Setup

{
    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
            }
        }
    }
}

Troubleshooting

Bot Can't Connect to Hytale Server

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

Chat Relay Not Working

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

Link Rewards Not Given

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

Status Panel Not Updating

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

Need More Help?

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

Last updated 16 minutes ago

hashtagGetting Started

hashtagPart 1: API Connection

hashtagConnecting to Your Hytale Server

hashtagConfiguration Parameters

hashtagPart 2: Account Linking

hashtagLinked Role Assignment

hashtagNickname Synchronization

hashtagDiscord Rewards

hashtagIn-Game Rewards

hashtagPart 3: Ban Synchronization

hashtagKeeping Bans Synchronized

hashtagConfiguration Parameters

hashtagPart 4: Server Status Panel

hashtagReal-Time Server Information

hashtagBasic Configuration

hashtagConnection Information

hashtagPerformance Metrics

hashtagPlayer Information

hashtagCustom Buttons

hashtagPart 5: Features & Event Notifications

hashtagChat Relay

hashtagPlayer Events

hashtagServer Status Updates

hashtagGame Event Notifications

hashtagChat Enhancements

hashtagConsole Access

hashtagConsole Log Filtering

hashtagPart 6: Channel Configuration

hashtagSetting Up Channels

hashtagExample Configurations

hashtagMinimal Setup (Chat Relay Only)

hashtagFull-Featured Setup

hashtagTroubleshooting

hashtagBot Can't Connect to Hytale Server

hashtagChat Relay Not Working

hashtagLink Rewards Not Given

hashtagStatus Panel Not Updating

hashtagNeed More Help?

Getting Started

Part 1: API Connection

Connecting to Your Hytale Server

Configuration Parameters

Part 2: Account Linking

Linked Role Assignment

Nickname Synchronization

Discord Rewards

In-Game Rewards

Part 3: Ban Synchronization

Keeping Bans Synchronized

Configuration Parameters

Part 4: Server Status Panel

Real-Time Server Information

Basic Configuration

Connection Information

Performance Metrics

Player Information

Custom Buttons

Part 5: Features & Event Notifications

Chat Relay

Player Events

Server Status Updates

Game Event Notifications

Chat Enhancements

Console Access

Console Log Filtering

Part 6: Channel Configuration

Setting Up Channels

Example Configurations

Minimal Setup (Chat Relay Only)

Full-Featured Setup

Troubleshooting

Bot Can't Connect to Hytale Server

Chat Relay Not Working

Link Rewards Not Given

Status Panel Not Updating

Need More Help?