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/minecraft/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.8.0"
`paused`	boolean	Nein	"true" oder "false"
`game`	string	Nein	"minecraft" oder "hytale"

Antwort-Beispiel

{
  "actions": [
    {
      "id": 501,
      "action": "fake_death",
      "player": "Steve",
      "params": {},
      "viewer": "ChatterName",
      "label": null,
      "show_title": true
    }
  ],
  "display": {
    "live": true,
    "streamer": "ExampleStreamer",
    "platform": "twitch",
    "url": "https://twitch.tv/examplestreamer",
    "viewers": 128
  }
}

cURL

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

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.yml), 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

Prüft den Bearer-Token gegen den registrierten Minecraft-Server, speichert den letzten Kontaktzeitpunkt, die gemeldeten Spieler/Whitelist/Items, verbucht die Ergebnisse bereits gesendeter Aktionen und liefert bis zu 20 wartende Aktionen zurück (als "gesendet" markiert, danach nicht mehr in einer zweiten Antwort enthalten).

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

commands: führt eine Liste erlaubter Server-Befehle aus
drop_hand: wirft den Gegenstand aus der Haupthand weg
drop_hotbar: wirft alle Hotbar-Gegenstände zufällig weg
throw_item: wirft den Gegenstand aus der Hand mit Aufwärtskurve weg
shuffle_inventory: mischt das Inventar durch
hotbar_chaos: wechselt zeitweise zufällig den Hotbar-Slot
pin: fixiert den Spieler an seiner Position
knockback: schlägt den Spieler zurück
invert_controls: invertiert die Steuerung
strip_armor: entfernt die Rüstung
damage_tool: beschädigt das Werkzeug in der Hand
hot_potato: gibt eine "heiße Kartoffel", die nach Ablauf explodiert
jail: teleportiert in einen Glaskäfig
cobweb: platziert Spinnweben um die Füße
ice_floor: ersetzt den Boden durch Packeis
pumpkin_head: setzt einen Kürbis auf den Kopf
sky_launch: katapultiert nach oben
anvil_rain: lässt Ambosse ungefährlich vom Himmel fallen
harmless_tnt: platziert TNT ohne Explosionsschaden
half_health: halbiert die Gesundheit
swap_places: tauscht die Position mit einem anderen Spieler
firework_show: zündet Feuerwerke
set_spawn: setzt den Respawn-Punkt
random_teleport: startet einen zufälligen Höhenfall-Teleport
ground_teleport: beendet einen Höhenfall sicher am Boden
fake_death: simuliert den Tod ohne echten Verlust

POST /api/v1/minecraft/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": "pin",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "seconds": 10
    },
    "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/minecraft/bridge/test-action' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"action":"pin","player":"Steve","params":{"seconds":10}}'

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/minecraft/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": "pin",
    "group": "sabotage",
    "player": "Steve",
    "params": {
        "seconds": 10
    },
    "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/minecraft/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.