API Documentation: Server Reward System

🔌 Official Plugin

The VotePlugin is an essential tool for increasing the visibility of your Hytale server by encouraging players to vote. It directly connects your server to the hytale.game API to provide a smooth and automated experience.

Here is a concise presentation of the VotePlugin for your Hytale servers, based on the provided configuration files and screenshots:

VotePlugin: Automate your server rewards

The VotePlugin is an essential tool for increasing the visibility of your Hytale server by encouraging players to vote. It directly connects your server to the hytale.game API to provide a smooth and automated experience.

Key Function

• API Synchronization : The plugin uses a unique secret key to communicate with the voting site and checks for new votes every 120 seconds by default.
• Random Bundle System : You can configure different rarity levels for rewards (e.g., Common at 60%, Rare at 30%, and Legendary at 10%).
• Smart Retrieval : If a player votes while offline or with a full inventory, the plugin puts the reward on hold. The player receives a reminder to use the command /pickupvoteonce space is freed up.
• Global Announcements : Each successful vote is announced in the server chat to reward the player and encourage others to do the same.

📦 Configuration

vote-api.properties: Manages the technical connection (secret key, API URL and verification timeouts).

# Unique server secret key (provided by hytale.game)
secret_key=7BC-086-094

# API Base URL
base_url=https://hytale.game/wp-json/hytale-api/v1

# Automatic polling interval (seconds)
poll_interval_seconds=120

# Anti-spam message cooldown for players (seconds)
notify_cooldown_seconds=600

# Unique server secret key (provided by hytale.game)
secret_key=7BC-086-094

# API Base URL
base_url=https://hytale.game/wp-json/hytale-api/v1

# Automatic polling interval (seconds)
poll_interval_seconds=120

# Anti-spam message cooldown for players (seconds)
notify_cooldown_seconds=600

vote-rewards.jsonThis allows you to define chat messages and the exact contents of bundles (item IDs and quantities). You have access to a complete library of items, ranging from basic resources like milk to rarer combat equipment.

{
"broadcast_prefix": "[Vote] ",
  "broadcast_template": "{username} just voted for the server and received {count} reward(s)!",
  "pending_message_template": "[Vote] Pending vote reward(s), use /pickupvote.",
  "inventory_full_message": "[Vote] You don't have enough space in your inventory to claim {count} vote(s). Free up some space and type /pickupvote again.",
  "pickup_success_message": "[Vote] Reward(s) claimed! (+{count})"
  "lots": [
    {
      "name": "Lot Commun",
      "chance": 60,
      "items": [
        { "id": "*Container_Bucket_State_Filled_Milk", "amount": 8 },
        { "id": "*Container_Bucket_State_Filled_Mosshorn_Milk", "amount": 4 }
      ]
    },
    {
      "name": "Lot Rare",
      "chance": 30,
      "items": [
        { "id": "*Container_Bucket_State_Filled_Water", "amount": 16 },
        { "id": "*Deco_Bucket_State_Filled_Milk", "amount": 2 }
      ]
    },
    {
      "name": "Lot Légendaire",
      "chance": 10,
      "items": [
        { "id": "*Deco_Bucket_State_Filled_Mosshorn_Milk", "amount": 1 },
        { "id": "*Deco_Bucket_State_Filled_Water", "amount": 1 }
      ]
    }
  ]
}

{
"broadcast_prefix": "[Vote] ",
  "broadcast_template": "{username} just voted for the server and received {count} reward(s)!",
  "pending_message_template": "[Vote] Pending vote reward(s), use /pickupvote.",
  "inventory_full_message": "[Vote] You don't have enough space in your inventory to claim {count} vote(s). Free up some space and type /pickupvote again.",
  "pickup_success_message": "[Vote] Reward(s) claimed! (+{count})"
  "lots": [
    {
      "name": "Lot Commun",
      "chance": 60,
      "items": [
        { "id": "*Container_Bucket_State_Filled_Milk", "amount": 8 },
        { "id": "*Container_Bucket_State_Filled_Mosshorn_Milk", "amount": 4 }
      ]
    },
    {
      "name": "Lot Rare",
      "chance": 30,
      "items": [
        { "id": "*Container_Bucket_State_Filled_Water", "amount": 16 },
        { "id": "*Deco_Bucket_State_Filled_Milk", "amount": 2 }
      ]
    },
    {
      "name": "Lot Légendaire",
      "chance": 10,
      "items": [
        { "id": "*Deco_Bucket_State_Filled_Mosshorn_Milk", "amount": 1 },
        { "id": "*Deco_Bucket_State_Filled_Water", "amount": 1 }
      ]
    }
  ]
}

🔑 Your login information

• Base URL: https://hytale.game/wp-json/hytale-api/v1
• Your Secret Key: XXX-XXX-XXX (Available in your management interface)
• Test username: Leviauzah

🛠️ Manual Integration (Developers)

The system operates on a simple cycle: Check then Claim .

Step 1: Check pending votes

As soon as a player connects to your server, query the API to retrieve their unclaimed votes.

• Method : GET
• Example URL: https://hytale.game/wp-json/hytale-api/v1/check?username=Leviauzah&secret_key=XXX-XXX-XXX
• JSON response: The API returns a list of objects containing the vote ID and date.

Step 2: Validate the vote (Claim)

Once the reward has been given in the game, you must validate the vote for it to disappear from the queue.

• Method: POST (or GET)
• Example URL: https://hytale.game/wp-json/hytale-api/v1/claim?vote_id=1&secret_key=XXX-XXX-XXX