Bridge-Endpunkt

Base: /api/v1

Der eine Endpunkt, über den dein Plugin mit dem Panel spricht: sendet den aktuellen Stand und empfängt wartende Aktionen.

Verarbeitung: MinecraftBridgeController

POST /api/v1/hytale/bridge

Status senden & Aktionen abholen

Dasselbe, was dein Plugin bei jedem Abfrage-Intervall tut: meldet Spielerstand, Whitelist und die Ergebnisse zuvor gesendeter Aktionen, und bekommt im Gegenzug bis zu 20 wartende Aktionen sowie den aktuellen Live-Status zurück.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`version`	string	Nein	Plugin-Version, z. B. "1.3.0"
`paused`	boolean	Nein	"true" oder "false"
`game`	string	Nein	"minecraft" oder "hytale"

Antwort-Beispiel

{
  "actions": [
    {
      "group": "sabotage",
      "id": 914,
      "action": "freeze",
      "player": "Steve",
      "params": { "seconds": 10 },
      "viewer": "ChatterName",
      "label": null,
      "show_title": true
    }
  ],
  "display": {
    "live": true,
    "streamer": "ExampleStreamer",
    "platform": "tiktok",
    "url": "https://tiktok.com/@examplestreamer/live",
    "viewers": 342
  }
}

cURL

curl -X POST 'https://your-panel.example/api/v1/hytale/bridge' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"version":"1.4.0","paused":false,"game":"hytale"}'

Wichtig zum Verständnis: Dies ist der Abruf, den das Plugin selbst macht. Um gezielt "Aktion X bei Spieler Y" auszulösen und das Ergebnis zu sehen, nutze "Testaktion senden" und "Teststatus abfragen". Hier meldet das Plugin nur seinen Status, das Panel entscheidet unabhängig davon, welche Aktionen bereits warten (durch Kanalpunkte-Einlösung, TikTok-Geschenk, Automation oder den Test-Knopf im Panel selbst ausgelöst) und liefert sie bei der nächsten Abfrage aus; im Demo-Modus zeigt der Knopf deshalb nur ein Beispiel dafür, wie eine Antwort mit wartender Aktion aussieht (abhängig vom "game"-Feld). Trage bei "Deine Server-URL" die Adresse des Panels ein, mit dem dein Plugin verbunden ist (die gleiche wie in deiner config.json), und bei "Authorization" deinen Token im Format "Bearer dein-token". Dieser Aufruf verhält sich dann genau wie ein normaler Abruf deines Plugins: wartende Aktionen werden als "gesendet" markiert und in dieser Antwort ausgeliefert. Teste live nur, wenn dein Server gerade keine Aktion erwartet, sonst bekommt dein eigentliches Plugin diese Aktion beim nächsten Abruf nicht mehr zu sehen. Hinweis: Dieses Testwerkzeug sendet die Anfrage immer zuerst unverschlüsselt (http) und folgt keiner Weiterleitung, bei einem Panel, das nur verschlüsselte Verbindungen (https) annimmt, siehst du deshalb hier evtl. nur eine Weiterleitungs-Antwort statt der echten Daten. Nutze in dem Fall das curl-Beispiel unten.

Internes Verhalten

Identisch zur Minecraft-Variante (anderer Endpunkt-Pfad: /api/v1/hytale/bridge statt /api/v1/minecraft/bridge, damit in einer Hytale-Installation nirgends "minecraft" auftaucht), zusätzlich enthält jede zurückgegebene Aktion ein "group"-Feld ("sabotage" oder leer), nach dem StreamBridge-Hytale die Titel-Darstellung (rot/grün) einfärbt.

Mögliche Werte für "action" in den zurückgegebenen Aktionen (vollständige Tabelle mit Parametern in der Anleitung "Aktionen-Referenz"):

freeze: friert den Spieler ein
root: verankert den Spieler am Boden
slow: verlangsamt den Spieler
stun: betäubt den Spieler
poison: vergiftet den Spieler
burn: Verbrennungseffekt
stamina_drain: entzieht Ausdauer
mana_drain: entzieht Mana
regeneration: heilt über Zeit
stoneskin: verleiht Schutz
immune: macht vorübergehend immun gegen Effekte
morph: verwandelt in ein Tier
launch: katapultiert nach oben
knockback: schlägt in eine zufällige Richtung
scale_giant: macht riesig
scale_tiny: macht winzig
random_warp: teleportiert zu einem zufälligen Warp
teleport_back: teleportiert zum letzten gespeicherten Ort
random_instance: teleportiert in eine zufällige Instanz
leave_instance: verlässt die aktuelle Instanz
spawn_mob: spawnt Gegner am Spieler
animal_rain: lässt Tiere vom Himmel regnen
night: setzt die Spielzeit auf Mitternacht
day_clear: setzt die Spielzeit auf Mittag, entfernt erzwungenes Wetter
weather: erzwingt ein bestimmtes Wetter
drop_hand: wirft den Gegenstand aus der Hotbar
shuffle_hotbar: mischt die Hotbar durch
half_health: halbiert die Gesundheit
heal: heilt vollständig
stamina_refill: füllt die Ausdauer auf
antidote: entfernt alle Status-Effekte
give_item: gibt ein Item
portal_time_add: erhöht die Portal-Restzeit
portal_time_remove: verringert die Portal-Restzeit
vulnerable: macht verwundbar
electric_shock: Stromschlag, betäubt kurz
fall_immunity: kein Fallschaden
fire_immunity: kein Feuerschaden
dimension_teleport: zufälliger sicherer Ort in derselben Welt bzw. Dimension
world_spawn: zum Startpunkt der aktuellen Welt
teleport_to_player: zu einem anderen Spieler in derselben Welt
swap_places: Platz mit einem anderen Spieler tauschen
portal_timer_pause: Portal-Uhr anhalten, läuft danach weiter
void_hold: Leere-Invasion aufhalten
camera_topdown: Kamera von oben
camera_sidescroller: Seitenansicht, nur 2D-Bewegung
hide_debug: Koordinaten-Anzeige sperren
fake_sound: Schreck-Geräusch nur für den Spieler

POST /api/v1/hytale/bridge/test-action

Testaktion senden

Stellt eine Aktion für den eigenen Server in die Warteschlange, genau so, als hätte ein Zuschauer sie ausgelöst. Das Plugin holt sie beim nächsten Abruf ab und führt sie aus. So lässt sich prüfen, ob die ganze Kette funktioniert: Panel nimmt an, Plugin holt ab, Spiel führt aus, Ergebnis kommt zurück.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`action`	string	Ja	Aktion aus dem Katalog
`player`	string	Ja	Spielername (muss auf deinem Server online sein)
`params`	object	Nein	Parameter als JSON, wird bei Auswahl einer Aktion vorbelegt
`viewer`	string	Nein	Angezeigter Zuschauername, Standard "API-Test"

Antwort-Beispiel

{
    "id": 1234,
    "status": "pending",
    "action": "spawn_mob",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "mob": "yeti",
        "count": 1
    },
    "result": null,
    "created_at": "2026-10-14T09:30:00+02:00",
    "sent_at": null,
    "plugin_seen_at": "2026-10-14T09:30:00+02:00"
}

cURL

curl -X POST 'https://your-panel.example/api/v1/hytale/bridge/test-action' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"action":"spawn_mob","player":"Steve","params":{"mob":"yeti","count":1}}'

Demo-Modus: Wähle eine Aktion (die Parameter werden passend vorbelegt) und einen Spielernamen, die Antwort zeigt, wie der Eintrag aussehen würde, danach kannst du bei "Teststatus abfragen" mit derselben ID das Ergebnis sehen. Eigener Server: Trage oben die Adresse deines Panels und "Bearer dein-token" ein (derselbe Token wie in der Plugin-Konfiguration), der Spieler muss online sein. Die Aktion wird dann wirklich im Spiel ausgeführt. Rufe währenddessen nicht "Status senden & Aktionen abholen" auf, sonst holst du die Aktion statt deines Plugins ab.

Internes Verhalten

Prüft den Token, prüft Aktion und Spielernamen gegen den Aktionskatalog des Panels (nur Aktionen, die das Plugin selbst ausführt), begrenzt die Parameter genauso wie bei echten Auslösungen (Dauer, Anzahl, erlaubte Auswahlwerte) und legt einen Warteschlangen-Eintrag mit Status "pending" an. Höchstens 20 Testaktionen pro Minute.

GET /api/v1/hytale/bridge/test-action/{id}

Teststatus abfragen

Zeigt, was aus einer Testaktion geworden ist: "pending" (wartet), "sent" (vom Plugin abgeholt), "done" (ausgeführt), "failed" (fehlgeschlagen, Grund in "result", zum Beispiel "player_offline" oder "no_space") oder "expired" (nicht rechtzeitig abgeholt).

Parameter

Name	Typ	Pflicht	Beschreibung
`id`	integer	Ja	ID aus "Testaktion senden"

Antwort-Beispiel

{
    "id": 1234,
    "status": "done",
    "action": "spawn_mob",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "mob": "yeti",
        "count": 1
    },
    "result": null,
    "created_at": "2026-10-14T09:30:00+02:00",
    "sent_at": "2026-10-14T09:30:01+02:00",
    "plugin_seen_at": "2026-10-14T09:30:02+02:00"
}

cURL

curl 'https://your-panel.example/api/v1/hytale/bridge/test-action/1234' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Trage bei "id" die ID aus "Testaktion senden" ein. Mit eigenem Server und Token siehst du hier das echte Ergebnis aus dem Spiel, meist schon ein bis zwei Sekunden nach dem Senden.

Internes Verhalten

Liefert nur Einträge des eigenen Servers. Holt das Plugin einen Eintrag nicht innerhalb von 30 Sekunden ab oder meldet kein Ergebnis, wird er auf "expired" gesetzt. "plugin_seen_at" zeigt, wann sich das Plugin zuletzt gemeldet hat.