Spieler

Base: /api/players

Online- und bekannte Spieler, Aktionen und Inventar

Verarbeitung: PlayersHandler

Endpunkte

GET /api/players

Spieler auflisten

Liefert alle Online-Spieler mit Position, Welt, Spielmodus, Leben und Werten sowie die dem Mod bekannten Offline-Spieler.

Antwort-Beispiel

[
  {
    "name": "Steve",
    "uuid": "1234...",
    "world": "default",
    "avatar": "<base64>",
    "x": 10.5,
    "y": 64.0,
    "z": -3.2,
    "gamemode": "Adventure",
    "health": 90,
    "maxHealth": 100,
    "stamina": 80,
    "maxStamina": 100,
    "mana": 0,
    "maxMana": 100,
    "defence": 12,
    "op": false,
    "online": true
  }
]

cURL

curl -X GET 'http://localhost:5550/api/players' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest jeden Online-Spieler auf dem Thread seiner Welt; Offline-Einträge stammen aus known_players.json.

GET /api/players/known

Bekannte Spieler

Schlanke Liste aller Spieler, die schon auf dem Server waren (Name, UUID, zuletzt gesehen).

Antwort-Beispiel

[
  {
    "uuid": "1234...",
    "name": "Steve",
    "online": true,
    "gamemode": "Adventure",
    "world": "default",
    "lastSeen": 1737000000000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/players/known' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest nur den Spieler-Tracker, ohne Weltzugriff. Für Auswahllisten gedacht.

GET /api/players/{name}

Spieler abrufen

Liefert dieselben Detaildaten wie die Liste für einen Online-Spieler.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "name": "Steve",
  "uuid": "1234...",
  "world": "default",
  "x": 10.5,
  "y": 64.0,
  "z": -3.2,
  "gamemode": "Adventure",
  "health": 90,
  "maxHealth": 100,
  "op": false,
  "found": true
}

cURL

curl -X GET 'http://localhost:5550/api/players/Eranio' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Sucht den Spieler in allen geladenen Welten und liest die Daten auf dem Thread dieser Welt.

GET /api/players/{name}/inventory

Inventar abrufen

Liefert Hotbar, Lager, Rüstung, Werkzeugfach, Rucksack und Werkzeuge mit Item-IDs, Mengen und Bildern.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "player": "Steve",
  "hotbar": [
    {
      "id": "hytale:sword_iron",
      "count": 1,
      "slot": 0,
      "durability": 90,
      "maxDurability": 100,
      "icon": "<base64>"
    }
  ],
  "storage": [],
  "armor": [],
  "utility": [],
  "backpack": [],
  "backpackCapacity": 18,
  "uniqueItemUsages": [
    "Upgrade_Backpack_1"
  ]
}

cURL

curl -X GET 'http://localhost:5550/api/players/Eranio/inventory' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Liest alle InventoryComponent-Container auf dem Welt-Thread; Bilder sind base64-kodiert.

POST /api/players/{name}/kick

Spieler kicken

Trennt einen Online-Spieler mit einer Meldung vom Server.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`reason`	string	Nein	Meldung für den Spieler, Standard „Kicked by admin“

Antwort-Beispiel

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/kick' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Please read the rules"}'

Internes Verhalten

Schließt die Verbindung des Spielers direkt.

POST /api/players/{name}/op

OP vergeben

Gibt dem Spieler Operator-Rechte.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/op' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Schreibt OP in permissions.json und nimmt den Spieler in die Gruppe hytale:Admin auf.

POST /api/players/{name}/deop

OP entziehen

Entzieht dem Spieler die Operator-Rechte.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/deop' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Entfernt OP aus permissions.json und der Gruppe hytale:Admin.

POST /api/players/{name}/teleport

Spieler teleportieren

Teleportiert den Spieler zu Koordinaten in seiner aktuellen Welt.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`x`	number	Ja	Ziel X
`y`	number	Ja	Ziel Y
`z`	number	Ja	Ziel Z

Antwort-Beispiel

{
  "success": true,
  "player": "Steve",
  "x": 10.0,
  "y": 64.0,
  "z": -3.0
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/teleport' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"x": 120.5, "y": 80, "z": -45.5}'

Internes Verhalten

Fügt auf dem Welt-Thread eine Teleport-Komponente hinzu und behält die Blickrichtung.

POST /api/players/{name}/give

Item geben

Legt ein Item ins Inventar, zuerst in die Hotbar.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`item`	string	Ja	Item-ID (auch itemId)
`amount`	integer	Nein	Menge 1 bis 999, Standard 1 (auch quantity)

Antwort-Beispiel

{
  "success": true,
  "item": "hytale:sword_iron",
  "amount": 1
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/give' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item": "Weapon_Sword_Iron", "amount": 1}'

Internes Verhalten

Erzeugt auf dem Welt-Thread einen ItemStack; schlägt mit Fehler fehl, wenn das Inventar voll ist.

POST /api/players/{name}/heal

Spieler heilen

Füllt das Leben des Spielers voll auf.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/heal' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Setzt den Lebenswert auf dem Welt-Thread auf das Maximum.

POST /api/players/{name}/gamemode

Spielmodus setzen

Wechselt den Spieler zwischen Abenteuer und Kreativ.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`gamemode`	string	Ja	adventure oder creative

Antwort-Beispiel

{
  "success": true,
  "gamemode": "creative"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/gamemode' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"gamemode": "creative"}'

Internes Verhalten

Ruft Player.setGameMode auf dem Welt-Thread auf.

POST /api/players/{name}/inventory/clear

Inventar leeren

Leert Hotbar, Lager, Rüstung, Werkzeugfach, Rucksack und Werkzeuge.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Antwort-Beispiel

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/clear' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internes Verhalten

Leert alle Container auf dem Welt-Thread.

POST /api/players/{name}/inventory/slot

Platz belegen

Legt ein Item auf einen bestimmten Platz und ersetzt den bisherigen Inhalt.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`item`	string	Ja	Item-ID (auch itemId)
`amount`	integer	Nein	Menge 1 bis 999, Standard 1
`section`	string	Nein	hotbar, storage, armor, utility, backpack oder tools, Standard storage
`slot`	integer	Nein	Platz-Nummer, Standard 0

Antwort-Beispiel

{
  "success": true,
  "item": "hytale:sword_iron",
  "amount": 1
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item": "Food_Bread", "amount": 16, "section": "hotbar", "slot": 2}'

Internes Verhalten

Ruft setItemStackForSlot im gewählten Container auf.

POST /api/players/{name}/inventory/slot/remove

Platz leeren

Entfernt das Item von einem Platz.

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`section`	string	Nein	Container, Standard storage
`slot`	integer	Nein	Platz-Nummer, Standard 0

Antwort-Beispiel

{
  "success": true,
  "section": "storage",
  "slot": 0
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot/remove' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"section": "storage", "slot": 5}'

Internes Verhalten

Ruft removeItemStackFromSlot im gewählten Container auf.

POST /api/players/{name}/inventory/slot/swap

Plätze tauschen

Tauscht zwei Plätze, auch zwischen Containern (zum Beispiel Lager und Hotbar).

Parameter

Name	Typ	Pflicht	Beschreibung
`name`	string	Ja	Spielername

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`fromSection`	string	Nein	Quell-Container, Standard storage
`fromSlot`	integer	Nein	Quell-Platz, Standard 0
`toSection`	string	Nein	Ziel-Container, Standard storage
`toSlot`	integer	Nein	Ziel-Platz, Standard 0

Antwort-Beispiel

{
  "success": true
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot/swap' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"fromSection": "storage", "fromSlot": 3, "toSection": "hotbar", "toSlot": 0}'

Internes Verhalten

Tauscht die ItemStacks auf dem Welt-Thread.