JSON

JSON (JavaScript Object Notation) ist ein Format zur Beschreibung von Daten. JSON-Dateien sind auch Teil von Ressourcenpaketen und Datenpaketen und gehören somit zur Plugin API, d.h. zu den Dateien, mit denen man das Spiel ändern kann, ohne das Programm modifizieren zu müssen (z.B. Texturen, Sounds etc.).

Dateien, die ein JSON-Format enthalten, sind meist vom Dateityp ".json", aber jeder andere Dateityp ist auch möglich, z.B. ".mcmeta" für Minecraft Metadaten, denn JSON-Dateien sind lesbare Textdateien, die mit jedem Texteditor geöffnet werden können.

Striktes JSON und NBT-JSON

In Minecraft wird JSON z.B. bei JSON-Texten und zur Beschreibung von Standard-Ressourcen und Standard-Weltdaten verwendet und hier striktes JSON genannt. Es gibt in Minecraft nämlich auch eine JSON-ähnliche Variante, die bei der Eingabe von NBT-Daten verwendet wird. Diese ist weniger strikt, man kann beispielsweise die doppelten Anführungsstriche bei Namen und anderen Ein-Wort-Texten weglassen. Ein Fremdprogramm zur Analyse von JSON-Daten würde solche Daten ablehnen, aber Minecraft kann natürlich seine eigenen Daten problemlos lesen.

Das NBT-Format (Named Binary Tag) ist das Format, in dem die Spielstand-Speicherung stattfindet. Alle Blöcke und die Positionen und Eigenschaften aller Wesen und Objekte werden im NBT-Format in Dateien gespeichert. Diese Dateien sind nicht mit einem Texteditor lesbar, man benötigt dafür einen speziellen NBT-Editor.

Das NBT-Format hat eine Baumstruktur, d.h. ein bestimmtes Datenelement kann Unterelemente haben, die wiederum Unterelemente haben können usw. Weil mit JSON solche Baumstrukturen dargestellt werden können, ist JSON hervorragend geeignet, um NBT-Daten darzustellen oder um NBT-Daten als Teil eines Befehls einzugeben.

Elemente von JSON

Ein Text wird immer mit doppelten Anführungszeichen markiert. In NBT-JSON können die Anführungszeichen auch weggelassen werden, wenn ein Text nur aus einem einzigen Wort besteht oder es können einfache Anführungszeichen verwendet werden.

Einige spezielle Zeichen in einem Text müssen mit einem vorangestellten Backslash (Rückwärtsschrägstrich) gekennzeichnet werden, z.B \" für ein Anführungszeichen innerhalb eines Textes oder \n für einen Zeilenumbruch. Wenn Texte geschachtelte JSON-Elemente mit Texten enthalten, müssen je nach Schachtelungstiefe weitere Backslashes verwendet werden (siehe Escaping).

"Beispielwort"
"Beispiel für einen Text mit mehreren Worten"
"Dieser \"Text\" enthält einen\nZeilenumbruch"
'Beispiel für NBT-JSON'

Eine Zahl wird von JSON automatisch erkannt. In NBT-JSON kann ein Zusatzbuchstabe den Datentyp angeben:

• b = Byte
• s = Short
• nichts = Int
• l = Long
• f = Float
• d = Double

Oft kann man diese Kennzeichnung weglassen, aber bei manchen NBT-Daten muss sie unbedingt angegeben werden, damit der Wert eine Auswirkung hat. Der Datentyp kann für jeden NBT-Parameter durch das NBT-Symbol abgelesen werden, z.B. steht für Byte. Das Überfahren des Symbols mit der Maus zeigt den Datentyp zusätzlich an.

123
0b
0.5f

Eine Eigenschaft besteht aus einem Namen und einem Wert, die durch einen Doppelpunkt getrennt sind. Der Name ist immer ein Text, der Wert kann auch ein Text sein oder eine Zahl. Bei striktem JSON muss auch der Name in doppelten Anführungszeichen stehen.

NameA:123
NameB:Kurzfreitext
NameXXX:"Ein Freitext mit mehreren Worten"
"Name":"Striktes JSON"

Ein Objekt kann beliebig viele Eigenschaften und Unterobjekte haben. Die Reihenfolge ist dabei unerheblich. Das Objekt hat einen Namen mit Doppelpunkt, gefolgt von einer geschweiften Klammer. Dann folgen durch Komma getrennt die Eigenschaften und Unterobjekte. Achtung: nach dem letzten Element folgt kein Komma. Zum Schluss endet das Objekt wieder mit einer geschweiften Klammer:

Objektname:
{
  NameZZZ:25.0f,
  NameABC:Wert
}

Bei einer Liste ist im Gegensatz zum Objekt die Reihenfolge der Aufzählungselemente bedeutsam. Listen werden mit eckigen Klammern markiert:

Listenname:
[
  Element1, 
  Element2,
  Element3
]

Kommentare sind in JSON nicht vorgesehen. Weil das Spiel aber unbekannte Eigenschaften ignoriert, kann man eine Eigenschaft z.B. "__comment" nennen und dort einen Freitext schreiben. Dies ist bei NBT-JSON und striktem JSON an vielen Stellen beliebig oft möglich und wird auch von den Spielentwicklern so gemacht:

Objektname:
{
  __comment:"Das ist ein Kommentar in NBT_JSON",
  Name1:Wert1,
  "__comment":"Ein Kommentar in striktem JSON",
  "Name2":"Wert2"
}

Eine Baumstruktur wird in JSON gebildet, indem ein Objekt Unterobjekte enthält:

{
  Name1:Wert1,
  Name2:Wert2,
  Unterobjekt:
  {
    Name3:Wert3,
    Name4:Wert4,
    UnterunterobjektA:
    {
      Name5:Wert5
    },
    UnterunterobjektB:
    {
      Name6:Wert6
    }
  }
}

Beispiele

Die Struktur für die Definitionsdatei eines Ressourcenpaketes sieht auszugsweise so aus:

• Die namenlose Haupteigenschaft.
  • pack: Alle allgemeinen Daten für das Ressourcenpaket.
    • description: Die Beschreibung des Ressourcenpaketes (...)
    • pack_format: Das Format des Ressourcenpaketes (...)

und wird so in eine Mcmeta-Datei geschrieben:

{
  pack:
  {
    description:"eine Beschreibung",
    pack_format:1
  }
}

Die NBT-Daten für reitende Wesen sehen in den Objektdaten und Kreaturdaten auszugsweise so aus:

• Alle Objekt- bzw. Kreaturdaten
  • Type: 0 = Pferd, 1 = Esel, 2 = Maultier, 3 = Zombiepferd, 4 = Skelettpferd
  • Tame: 1 oder 0 (true/false) - zahm ja/nein
  • Passengers: Liste mit Objekten, die dieses Objekt als Passagier hat
    • Ein Passagier
      • id: Objekt-ID
      • Invulnerable: 1 oder 0 (true/false) - unverwundbar ja/nein

und werden so beim Befehl /summon verwendet:

/summon skeleton_horse ~ ~ ~
{
  Tame:1,
  Passengers:
  [
    {
      id: skeleton,
      Invulnerable:1
    },
    {
      id: zombie,
      Invulnerable:1
    }
  ]
} 

Der Befehl /tellraw erwartet striktes JSON, hier ein Beispiel:

/tellraw @p 
[
  {"text":"Fettgrün ", "color":"green", "bold":true},
  {"text":"und kursiv ", "italic":true}
]

Siehe auch die Beispiele zur Baumstruktur unter Befehl#NBT-Daten.