Hytale Hub PluginBetaKonfiguration & Setup

Komplette Anleitung zur Einrichtung des Hytale Hub Plugins. Live-Status, Vote Rewards und In-Game Voting in wenigen Minuten einrichten.

Quick Start

  1. 1Lade das Plugin im Profil-Bereich herunter und lege es in deinen mods/ Ordner.
  2. 2Starte den Server einmal, um die config.json zu generieren.
  3. 3Gehe in dein Profil, wähle deinen Server und klicke auf "Konfigurieren". Kopiere die komplette Beispiel-Config (mit vorausgefülltem Token) und ersetze damit deine config.json.
  4. 4Passe die Rewards und Einstellungen nach deinen Wünschen an.
  5. 5Starte den Server neu, damit die Änderungen übernommen werden.

Vollständige Beispiel-Konfiguration

Hier siehst du eine vollständige config.json mit allen verfügbaren Optionen:

config.json
{
  "token": "dein-api-token-hier",
  "features": {
    "heartbeat": true,
    "votifier": true,
    "voteCommand": true,
    "voteCommandName": "vote",
    "testVoteCommand": true,
    "testVoteCommandName": "testvote",
    "voteReminder": true,
    "reminderIntervalMinutes": 120
  },
  "votifier": {
    "mode": "pull",
    "port": 8192
  },
  "rewards": {
    "items": [
      { "itemId": "Ore_Gold", "quantity": 25 },
      { "itemId": "Ore_Silver", "quantity": 25 },
      { "itemId": "Ore_Silver_Shale", "quantity": 25 },
      { "itemId": "Weapon_Longsword_Flame", "quantity": 1 },
      { "itemId": "Weapon_Gun", "quantity": 1 },
      { "itemId": "Weapon_Arrow_Crude", "quantity": 25 },
      { "itemId": "Weapon_Arrow_Crude", "quantity": 25 },
      { "itemId": "Armor_Mithril_Hands", "quantity": 1 },
      { "itemId": "Armor_Mithril_Chest", "quantity": 1 },
      { "itemId": "Armor_Mithril_Head", "quantity": 1 },
      { "itemId": "Armor_Mithril_Legs", "quantity": 1 }
    ],
    "commands": [
      "camshake debug Battleaxe_Frontflip_Chop 10 --player %player%"
    ],
    "description": "1x Komplette Mithril Rüstung, 1x Waffe + 50 Schuss, 25x Silver Ore, 25x Gold Ore"
  },
  "broadcast": {
    "enabled": true,
    "message": "%player% hat gevotet und erhaelt: %rewards%"
  },
  "messages": {
    "voteSuccess": "",
    "voteReminder": "Du hast heute noch nicht gevotet! /vote",
    "alreadyVoted": "Du hast heute bereits gevotet!"
  },
  "debug": false
}

Konfiguration im Detail

token

API-Token für die Authentifizierung

Der API-Token verbindet dein Plugin mit deinem Hytale Hub Account. Du findest ihn in deinem Profil bei deinem Server unter "Konfigurieren".

Wichtig: Halte deinen Token geheim! Teile ihn nicht öffentlich oder committe ihn in Git Repositories.
Beispiel
"token": "rW-ytVoFcysVbhqPGg3_K0lYWUBTdJOgk9nTTsC3KZU"

features

Aktiviere oder deaktiviere einzelne Plugin-Features

Steuere, welche Features des Plugins aktiv sein sollen:

PropertyTypDefaultBeschreibung
heartbeatbooleantrueSendet Spielerzahlen alle 30s an Hytale Hub (Live-Status)
votifierbooleantrueAktiviert das Votifier-System für Vote Rewards
voteCommandbooleantrueAktiviert den /vote Befehl im Spiel
voteCommandNamestring"vote"Name des Vote-Befehls (ohne /). Spieler nutzen dann /<name>
testVoteCommandbooleantrueAktiviert den Admin-Test-Befehl zum Simulieren von Votes
testVoteCommandNamestring"testvote"Name des Test-Vote-Befehls (ohne /). Erfordert Permission
voteReminderbooleantrueErinnert Spieler automatisch ans Voten
reminderIntervalMinutesnumber120Intervall in Minuten zwischen Vote-Erinnerungen
Beispiel
"features": {
  "heartbeat": true,
  "votifier": true,
  "voteCommand": true,
  "voteCommandName": "vote",
  "testVoteCommand": true,
  "testVoteCommandName": "testvote",
  "voteReminder": true,
  "reminderIntervalMinutes": 120
}

votifier

Votifier-Modus und Port-Einstellungen

Das Plugin unterstützt drei verschiedene Modi für maximale Kompatibilität:

TCP

Klassisches Votifier V2. Für VPS/Homeserver mit Port-Forwarding.

HTTP

HTTP POST via WebServer Plugin. Ideal für Nitrado und ähnliche Hoster.

PullEmpfohlen

Plugin fragt Votes ab. Funktioniert überall, keine Ports nötig.

PropertyTypDefaultBeschreibung
mode"tcp" | "http" | "pull""pull"Votifier-Modus (siehe oben)
portnumber8192Port für TCP-Modus. Kann auch über das Plugin-Dashboard auf der Website eingestellt werden.
Empfehlung: Nutze den pull Modus, wenn du dir nicht sicher bist. Er funktioniert mit jedem Hoster ohne zusätzliche Konfiguration.

rewards

Vote-Belohnungen konfigurieren

Das Plugin bietet zwei Arten von Belohnungen – wähle je nach Anwendungsfall:

Item-RewardsSicher

Items werden im /rewards Container gespeichert.

  • ✓ Kein Verlust bei vollem Inventar
  • ✓ Spieler holt ab, wann er will
  • ✓ Persistent über Neustarts
Command-RewardsSofort

Commands werden direkt ausgeführt (Coins, XP, etc.).

  • ✓ Sofortige Ausführung
  • ✓ Ideal für Währungen/XP
  • ✓ Offline-Spieler bei nächstem Join

In-Game /rewards Container

Vote Rewards Container UI

Spieler öffnen mit /rewards ihr persönliches Belohnungs-Inventar

Item-Rewards konfigurieren

Array von Items mit Hytale Item-ID und Menge. Format: Kategorie_Typ_Variante

Items Beispiel
"items": [
  { "itemId": "Ore_Gold", "quantity": 3 },
  { "itemId": "Ingredient_Bar_Copper", "quantity": 5 },
  { "itemId": "Weapon_Sword_Crude", "quantity": 1 }
]
Item-IDs findest du via /help give im Spiel oder in der Hytale-Dokumentation.

Command-Rewards konfigurieren

Führe Server-Commands aus. %player% wird durch den Spielernamen ersetzt:

Commands Beispiel
"commands": [
  "currency add %player% 100",
  "xp give %player% 500"
]

Beschreibung

Wird im Broadcast angezeigt (Platzhalter %rewards%):

Beschreibung
"description": "3x Gold, 1x Diamant, 100 Coins"

broadcast

Öffentliche Ankündigung an ALLE Spieler

Diese Nachricht wird allen Spielern auf dem Server im Chat angezeigt, wenn jemand votet:

PropertyTypDefaultBeschreibung
enabledbooleantrueBroadcast aktivieren/deaktivieren
messagestring-Öffentliche Nachricht (alle sehen das)

Verfügbare Platzhalter:

  • %player% - Spielername
  • %rewards% - Reward-Beschreibung aus config
Beispiel
"broadcast": {
  "enabled": true,
  "message": "%player% hat gevotet und erhaelt: %rewards%"
}
Unterschied zu messages: Broadcast geht an alle online Spieler. Die Einstellungen unter messages sind dagegen privat und nur für den jeweiligen Spieler sichtbar.

messages

Private Nachrichten an einzelne Spieler

Diese Nachrichten werden nur dem jeweiligen Spieler angezeigt (privat, nicht im öffentlichen Chat):

PropertyTypDefaultBeschreibung
voteSuccessstring-Private Nachricht nach erfolgreichem Vote (nur der Voter sieht das)
voteReminderstring-Private Erinnerung an den Spieler (nur er sieht das)
alreadyVotedstring-Private Nachricht wenn bereits gevotet (nur er sieht das)
Beispiel
"messages": {
  "voteSuccess": "Danke fuers Voten! Du hast deine Belohnung erhalten.",
  "voteReminder": "Hey! Du hast heute noch nicht gevotet. Nutze /vote!",
  "alreadyVoted": "Du hast heute bereits gevotet. Komm morgen wieder!"
}
Tipp: Diese Nachrichten sieht nur der betroffene Spieler selbst. Wenn du möchtest, dass alle Spieler sehen wenn jemand votet, nutze die broadcast Einstellung weiter oben.
Unterstützt Farbcodes wie &a für grün, &c für rot, etc.

debug

Debug-Modus für Fehlersuche

Aktiviere detailliertes Logging für die Fehlersuche:

Debug aktivieren
"debug": true
Hinweis: Debug-Modus erzeugt viele Log-Einträge. Deaktiviere ihn im Produktivbetrieb.

Befehle im Spiel

BefehlBeschreibungPermission
/voteVoten und Belohnungen erhalten
/rewardsItem-Rewards Container öffnen
/testvote <player>Vote simulieren (Admin-Test)hytalehub.command.testvote
/resetrules [player]Regel-Akzeptanz zurücksetzen (alle oder einzelner Spieler)hytalehub.command.resetrules

/vote Flow

  1. Prüft ob Account verknüpft ist
  2. Nicht verknüpft: Zeigt Link zum Verknüpfen
  3. Verknüpft: Direkter Vote + Rewards

/rewards Flow

  1. Öffnet persönliche Rewards-UI
  2. Spieler zieht Items ins Inventar
  3. Nicht abgeholte Items bleiben gespeichert

Serverregeln (First-Join Rules Screen)

Das Serverregeln-Feature zeigt jedem neuen Spieler beim ersten Beitritt ein Popup-Fenster mit den Serverregeln an. Der Spieler muss die Regeln lesen und aktiv akzeptieren, bevor er spielen kann. Nach dem Akzeptieren wird eine zweite Seite mit wichtigen Server-Commands angezeigt. Spieler, die die Regeln bereits akzeptiert haben, sehen das Fenster bei zukünftigen Joins nicht mehr.

Perfekt für neue Server! Stelle sicher, dass alle Spieler deine Regeln kennen und akzeptiert haben.

Ablauf für den Spieler

  1. Spieler joint den Server zum ersten Mal
  2. Ein Fenster mit dem Titel "Serverregeln" erscheint
  3. Oben wird ein Countdown angezeigt (z.B. "Bitte lies die Regeln (5s...)")
  4. Nach Ablauf des Countdowns wird der "Akzeptieren"-Button grün und klickbar
  5. Der Spieler hat drei Optionen:
    • Akzeptieren — Öffnet Commands-Seite → Nach "Verstanden" kann der Spieler spielen
    • Ablehnen — Spieler wird gekickt mit konfigurierbarer Nachricht
    • ESC / Fenster schließen — Wird wie "Ablehnen" behandelt (Kick)
  6. Beim nächsten Join erscheint das Fenster nicht mehr
Serverregeln mit Countdown

Countdown-Phase — Button ist noch ausgegraut

Serverregeln akzeptierbar

Countdown abgelaufen — "Akzeptieren" ist jetzt grün

Wichtige Commands

Commands-Seite nach Akzeptieren

Aktivierung

Das Feature ist standardmäßig deaktiviert. Um es zu aktivieren:

  1. Starte den Server einmal, damit die Datei rules_config.json erstellt wird
  2. Öffne mods/HytaleHub_HytaleHubPlugin/rules_config.json
  3. Setze "enabled": true
  4. Lade das Plugin neu oder starte den Server neu

Konfigurationsdatei

Pfad: mods/HytaleHub_HytaleHubPlugin/rules_config.json

rules_config.json (Standard)
{
  "enabled": false,
  "acceptDelaySeconds": 5,
  "declineKickMessage": "Du musst die Regeln akzeptieren um spielen zu koennen.",
  "resetRulesCommand": true,
  "resetRulesCommandName": "resetrules",
  "rules": [
    "1. Respektiere alle Spieler",
    "2. Kein Cheating oder Exploiting",
    "3. Kein Spam im Chat",
    "4. Keine unangemessenen Bauwerke",
    "5. Folge den Anweisungen der Moderatoren"
  ],
  "commands": [
    {
      "command": "/vote",
      "description": "Vote fuer den Server und erhalte Belohnungen"
    },
    {
      "command": "/rewards",
      "description": "Hole deine ausstehenden Rewards ab"
    },
    {
      "command": "/help",
      "description": "Zeige alle verfuegbaren Commands"
    }
  ]
}
EinstellungTypBeschreibung
enabledbooleanAktiviert oder deaktiviert das gesamte Feature. Standard: false
acceptDelaySecondsnumberWie viele Sekunden der Spieler warten muss, bevor er akzeptieren kann. Minimum: 1. Standard: 5
declineKickMessagestringDie Nachricht, die dem Spieler beim Kick angezeigt wird, wenn er ablehnt oder ESC drückt
resetRulesCommandbooleanAktiviert den /resetrules Admin-Befehl zum Zurücksetzen der Regel-Akzeptanz. Standard: true
resetRulesCommandNamestringName des Reset-Befehls (ohne /). Standard: "resetrules"
rulesarrayDie Serverregeln als Textzeilen. Jede Zeile wird als eigener nummerierter Eintrag angezeigt. Beliebig viele Regeln möglich (scrollbar).
commandsarrayDie Commands, die auf der zweiten Seite angezeigt werden. Jeder Eintrag hat command (z.B. /vote) und description (Erklärungstext).

Beispiel: Eigene Regeln konfigurieren

rules_config.json (Erweitert)
{
  "enabled": true,
  "acceptDelaySeconds": 10,
  "declineKickMessage": "Bitte akzeptiere die Regeln um auf unserem Server spielen zu koennen!",
  "resetRulesCommand": true,
  "resetRulesCommandName": "resetrules",
  "rules": [
    "Sei freundlich und respektvoll zu allen Spielern",
    "Kein Griefing oder Zerstören fremder Bauwerke",
    "Keine Cheats, Hacks oder Exploits",
    "Kein Spam oder Werbung im Chat",
    "Keine beleidigenden oder unangemessenen Inhalte",
    "Handelsabsprachen müssen eingehalten werden",
    "Folge den Anweisungen des Server-Teams",
    "Mehrfach-Accounts sind nicht erlaubt",
    "Bugs müssen gemeldet und dürfen nicht ausgenutzt werden",
    "Das Server-Team behält sich das Recht vor, Regeln jederzeit anzupassen"
  ],
  "commands": [
    {
      "command": "/vote",
      "description": "Vote für unseren Server und erhalte Belohnungen"
    },
    {
      "command": "/rewards",
      "description": "Hole deine Vote-Rewards ab"
    },
    {
      "command": "/help",
      "description": "Zeige alle verfügbaren Befehle an"
    },
    {
      "command": "/spawn",
      "description": "Teleportiere dich zum Spawn"
    },
    {
      "command": "/msg",
      "description": "Sende eine private Nachricht an einen Spieler"
    }
  ]
}
Nummerierung: Die Nummerierung der Regeln wird automatisch im UI erzeugt. Falls die Regeltexte bereits mit einer Nummer beginnen (z.B. "1. Respektiere..."), wird diese automatisch entfernt um doppelte Nummerierung zu vermeiden.
Unabhängig: Die rules_config.json ist unabhängig von der Haupt-Konfiguration (config.json). Änderungen an den Regeln erfordern kein Anpassen der Haupt-Config.

Regeln zurücksetzen

Mit dem /resetrules Befehl können Admins die Regel-Akzeptanz zurücksetzen. Betroffene Spieler müssen die Regeln beim nächsten Join erneut akzeptieren.

Für einen einzelnen Spieler:

Im Spiel
/resetrules <spielername>

Für alle Spieler (z.B. nach Regeländerung):

Im Spiel
/resetrules

Ohne Spielername werden alle Akzeptanzen zurückgesetzt.

Tipp: Wenn du die Regeln in der Config änderst, führe einfach /resetrules aus — alle Spieler werden beim nächsten Join aufgefordert, die neuen Regeln zu akzeptieren.

Befehl umbenennen oder deaktivieren:

In der rules_config.json kannst du den Befehl mit resetRulesCommand: false deaktivieren oder mit resetRulesCommandName umbenennen.

Server-Widget (Embeddable Banner)

Bette ein dynamisches Status-Banner auf deiner Website, in Foren oder auf Discord ein. Das Banner zeigt den Live-Status deines Servers und verlinkt automatisch zu deinem Hytale Hub Profil — mehr Sichtbarkeit für deinen Server, ohne Aufwand.

Was zeigt das Banner?

  • • Server-Name & IP-Adresse
  • • Online/Offline Status (live)
  • • Aktuelle Spielerzahl
  • • Vote-Anzahl & Spielmodi
  • • Direkter Link zu deinem Server

4 Stile verfügbar

  • full — 468×120, für Forum-Signaturen & Websites
  • compact — 300×80, für Sidebars
  • badge — shields.io-Style für READMEs
  • minimal — Inline-Status

So geht's

  1. Gehe zu deinem Profil und wähle deinen Server
  2. Klicke auf "Verwalten" und wechsle zum Widget-Tab
  3. Wähle Stil und Theme, dann kopiere den Embed-Code
  4. Füge den Code auf deiner Website, in Foren oder in Discord ein

Tipp: Premium-Server (Boost) bekommen automatisch einen goldenen Rahmen im Banner — noch ein Grund zu boosten!

Häufige Fragen

Wo finde ich meinen API-Token?

Logge dich auf Hytale Hub ein, gehe zu deinem Profil, wähle deinen Server aus und klicke auf "Konfigurieren". Dort kannst du den Token kopieren.

Votes kommen nicht an - was tun?

1. Prüfe ob der Token korrekt ist.
2. Aktiviere debug: true und schaue in die Server-Logs.
3. Bei TCP-Modus: Ist Port 8192 freigegeben?
4. Wechsle testweise auf pull Modus.

Kann ich mehrere Server mit einem Account verbinden?

Jeder Server auf Hytale Hub hat seinen eigenen API-Token. Du kannst mehrere Server in deinem Profil verwalten und für jeden einen separaten Token generieren.

Wie oft aktualisiert sich der Live-Status?

Das Plugin sendet alle 30 Sekunden einen Heartbeat. Auf der Website wird der Status als "Live" angezeigt, solange der letzte Heartbeat nicht älter als 2 Minuten ist.

Weitere Ressourcen

Bald Open Source auf GitHubServer erstellen GuideAPI Dokumentation