HytaleCharts Voting Plugin

The HytaleCharts plugin for Hytale servers enables automatic vote reward delivery by connecting your server to HytaleCharts.com - the premier Hytale server listing platform.

Overview

HytaleCharts is a server listing platform where players can discover and vote for their favorite Hytale servers. The HytaleCharts plugin integrates with both HytaleCharts.com and Pixlpay to provide:

• Server Status Reporting - Keep your HytaleCharts listing accurate with real-time player counts
• Vote Rewards via Pixlpay - Automatically reward players who vote for your server
• Server Verification - Verify ownership of your server listing

How Vote Rewards Work

Vote rewards use a two-part system:

Player votes on HytaleCharts.com
        |
        v
HytaleCharts records the vote
        |
        v
+-------------------+
| Pixlpay polls     |
| HytaleCharts API  |
| (every 15 min)    |
+--------+----------+
         |
         v
Vote matched to customer via Discord ID
         |
         v
Reward created in Pixlpay dashboard
         |
         v
Customer claims reward in store account
         |
         v
Coupon code generated or Discord role queued

Vote Matching

Votes are matched to store customers using Discord ID. For this to work:

1. Your customer must log in to your Pixlpay store via Discord OAuth
2. The same Discord account must be used when voting on HytaleCharts

Requirements

• Hytale dedicated server (Early Access or later)
• Java 21+
• A server listed on HytaleCharts.com
• A Pixlpay store with the HytaleCharts integration enabled

Installation

Step 1: Download the Plugin

Download HytaleCharts.jar

Or download from your HytaleCharts Dashboard under Plugin Integration.

Step 2: Install the Plugin

Copy HytaleCharts.jar to your server's plugins directory:

plugins/HytaleCharts.jar

Step 3: Start the Server

Start your Hytale server. The plugin will generate a default configuration file at:

plugins/HytaleCharts/config.json

Step 4: Get Your Heartbeat Secret

1. Log in to HytaleCharts.com
2. Go to your Dashboard
3. Click on your server
4. Navigate to Plugin Integration
5. Copy your Heartbeat Secret

Step 5: Configure the Plugin

Edit plugins/HytaleCharts/config.json and add your secret:

{
  "secret": "your_heartbeat_secret_here",
  "debug": false
}

Step 6: Restart the Server

Restart your server to apply the configuration.

Configuration

Edit plugins/HytaleCharts/config.json:

{
  "secret": "your_heartbeat_secret_here",
  "debug": false
}

Configuration Options

Option	Default	Description
secret	"YOUR_SECRET_HERE"	Your heartbeat secret from HytaleCharts dashboard
debug	false	Enable verbose logging for troubleshooting

How It Works

Server Status Reporting

The plugin automatically reports your server status to HytaleCharts every 5 minutes:

• Current player count
• Maximum player slots
• List of online players (usernames, UUIDs, and worlds)
• Plugin version

This keeps your HytaleCharts listing accurate and helps players find active servers.

Player Count Tracking

The plugin uses a reliable dual-tracking system:

1. Event-based tracking - Listens for player connect/disconnect events
2. Universe query - Queries the server for authoritative player count

If the counts drift, the plugin automatically syncs to maintain accuracy.

Setting Up Vote Rewards in Pixlpay

After installing the HytaleCharts plugin on your server, configure vote rewards in your Pixlpay dashboard:

Step 1: Enable HytaleCharts Integration

1. Go to Settings > Integrations > HytaleCharts in your Pixlpay store dashboard
2. Enter your HytaleCharts credentials:
   • Server ID - Your HytaleCharts server ID
   • Server Slug - Your server's URL slug
   • API Token - From your HytaleCharts dashboard
3. Click Test Connection to verify
4. Click Save

Step 2: Create Vote Rewards

1. Click Add Reward
2. Choose a reward type:
   • Discount Coupon - Percentage or fixed amount off
   • Free Product - 100% off a specific product
   • Discord Role - Assign a role when claimed
3. Choose the reward model:
   • Per Vote - Reward given for every vote
   • Milestone - Reward unlocked at specific vote counts (10, 25, 50, 100)
4. Configure reward details and expiration
5. Click Save

For detailed information on configuring vote rewards, see the HytaleCharts Integration Guide.

Commands

All commands require the hytalecharts.admin permission.

Command	Description
/hytalecharts status	Show plugin status and connection info
/hytalecharts reload	Reload the configuration file
/hytalecharts debug	Toggle debug mode on/off

Permissions

Permission	Description
hytalecharts.admin	Access to all /hytalecharts commands

Timing Constants

Constant	Value	Purpose
Heartbeat Interval	5 minutes	Time between status reports to HytaleCharts
HTTP Timeout	10 seconds	Request timeout for API calls

Troubleshooting

Plugin Not Loading

Symptoms:

• Plugin doesn't appear in server console on startup
• No config file generated

Solutions:

1. Ensure Java 21+ is installed
2. Verify the JAR is in the correct plugins/ directory
3. Check server console for error messages

"Server Verification Failed"

Symptoms:

• Console shows "HytaleCharts not configured" warning
• "Invalid secret key" error (HTTP 401)

Solutions:

1. Verify your heartbeat secret is correct
2. Ensure your server is listed on HytaleCharts
3. Check that the secret hasn't expired - regenerate if needed
4. Restart the server after updating config

Heartbeat Rate Limited (HTTP 429)

Symptoms:

• "Heartbeat rate limited" warning in console

Solutions: This is normal after server restarts or rapid reconnections. The plugin will automatically retry at the next interval.

Status Not Updating on HytaleCharts

Symptoms:

• HytaleCharts website shows outdated player count
• Server marked as offline

Solutions:

1. Check console for connection errors
2. Verify your server has internet access
3. Enable debug mode to see detailed API responses
4. Ensure your firewall allows outbound HTTPS connections

Votes Not Matching to Customers

Problem: Votes appear on HytaleCharts but aren't linked to store customers.

Solutions:

1. Ensure customers log in to your store via Discord OAuth
2. Verify the same Discord account is used for both voting and store login
3. Check that the HytaleCharts integration is properly configured in Pixlpay
4. Click "Sync Now" in Pixlpay dashboard to force an immediate sync

Vote Rewards Not Appearing

Problem: Customer voted but doesn't see a reward.

Solutions:

1. Wait for the next Pixlpay poll cycle (up to 15 minutes)
2. Click "Sync Now" in Pixlpay dashboard
3. Verify the customer's Discord account is linked to their store account
4. Check that vote rewards are configured and enabled in Pixlpay

Log Files

Check your Hytale server console or logs directory for HytaleCharts messages:

Log Level	Description
INFO	General information and status updates
WARNING	Warnings and non-critical issues
SEVERE	Critical errors requiring attention

Enable debug: true in config for verbose logging during troubleshooting.

Best Practices

1. Keep the plugin updated - Download the latest version when available
2. Monitor your logs - Check for errors or warnings regularly
3. Use debug mode sparingly - Enable only when troubleshooting to avoid log spam
4. Test the integration - Have a team member vote and verify the reward flow
5. Promote voting - Add vote links to your Discord, website, and in-game messages

Security

• Protect your config file - Keep plugins/HytaleCharts/config.json secure
• Use unique secrets - Each server should have its own heartbeat secret
• Regenerate compromised secrets - If you suspect your secret is exposed, regenerate it in the HytaleCharts dashboard

Related Documentation

• HytaleCharts Integration Guide - Setting up vote rewards in Pixlpay
• Hytale Plugin - Pixlpay delivery plugin for Hytale servers
• Custom Discord Bot - Discord role rewards

Support

• HytaleCharts Documentation
• HytaleCharts Discord
• Pixlpay Troubleshooting Guide
• Pixlpay Discord Support
• Contact Support