Le format NBT (Named Binary Tag) est un système de stockage de données hiérarchisé employé par Minecraft pour conserver des informations dans ses fichiers de sauvegarde. Il repose sur une organisation en balises, chacune étant définie par un identifiant numérique, un nom et un contenu (payload). Ce format existe aussi sous une forme textuelle, le Stringified Named Binary Tag (SNBT), qui permet de lire et modifier ces données sous forme de texte.
Ce qu’il faut retenir :
- Le NBT est un format hiérarchisé utilisé par Minecraft pour stocker les données des entités, blocs et fichiers de sauvegarde.
- Le SNBT est la version textuelle du NBT, principalement utilisée dans les commandes de la Java Edition.
- Chaque tag du NBT possède un identifiant numérique, un nom et un contenu appelé payload.
- Le format SNBT prend en charge différents types de données, comme les entiers, flottants, chaînes, listes, tableaux et compounds.
- La conversion entre NBT et SNBT conserve la structure des données et respecte les types et formats définis.
Sommaire
Le format SNBT
Le SNBT, aussi appelé data tag, reprend la structure du NBT mais sous forme de texte. Il est généralement écrit entre accolades { } sous forme de paires clé:valeur séparées par des virgules. Ces valeurs peuvent elles-mêmes contenir d’autres paires, permettant de décrire une structure arborescente complexe.
Exemple :
{name1:123,name2:"sometext1",name3:{subname1:456,subname2:"sometext2"}}
Les noms de tags peuvent être entourés de guillemets doubles s’ils contiennent des caractères spéciaux.
Types de données du SNBT
| Type | Description | Format SNBT | Exemple |
|---|---|---|---|
| Byte | Entier signé sur 8 bits (–128 à 127). | <nombre>b ou <nombre>B | 34B, -20b |
| Boolean | Pas de type booléen natif ; représenté par un byte (0 ou 1). | true ou false | true |
| Short | Entier signé sur 16 bits (–32 768 à 32 767). | <nombre>s ou <nombre>S | 31415s |
| Int | Entier signé sur 32 bits. | <nombre>, <nombre>i ou <nombre>I | 31415926 |
| Long | Entier signé sur 64 bits. | <nombre>l ou <nombre>L | 31415926l |
| Float | Nombre flottant simple précision (32 bits). | <nombre>f ou <nombre>F | 3.1415926f |
| Double | Nombre flottant double précision (64 bits). | <nombre>, <nombre>d ou <nombre>D | 3.1415926 |
| String | Chaîne de caractères. Peut être entre guillemets simples ou doubles, ou sans guillemets si elle respecte certaines règles. | "texte", 'texte' | "Hello \"World!\"" |
| List | Liste ordonnée de valeurs du même type. | [valeur,valeur,...] | [3.2,64.5,129.5] |
| Compound | Ensemble non ordonné de paires clé/valeur. | {clé:valeur,...} | {X:3,Y:64,Z:129} |
| Byte Array | Tableau d’octets. | [B;1b,2b,3b] | [B;1b,2b,3b] |
| Int Array | Tableau d’entiers 32 bits. | [I;1,2,3] | [I;1,2,3] |
| Long Array | Tableau d’entiers 64 bits. | [L;1l,2l,3l] | [L;1l,2l,3l] |
Formats numériques et suffixes
- Les nombres peuvent être en notation scientifique (
1.2e3), hexadécimale (0xCAFE) ou binaire (0b101). - Les caractères
_peuvent séparer les chiffres pour améliorer la lisibilité (1_000). - Les suffixes indiquent le type (
b,s,l,f,d) et éventuellement le signe (uous).
Séquences d’échappement
Le SNBT prend en charge 13 séquences d’échappement, par exemple :
| Séquence | Caractère |
|---|---|
\n | Saut de ligne |
\t | Tabulation |
\\ | Antislash |
\" | Guillemets doubles |
\u2604 | Caractère Unicode (ex. U+2604) |
Conversion entre NBT et SNBT
- Vers SNBT : un objet NBT est converti en texte lors de l’exécution de
/data get. Les nombres sont suffixés selon leur type, les chaînes sont entre guillemets. - Depuis SNBT : le texte est analysé et converti en NBT en tenant compte des types. Les listes hétérogènes sont normalisées.
Test de tags NBT
Certains contextes (comme /execute if data) permettent de tester si un objet NBT contient certains tags. La comparaison est partielle : la structure peut contenir d’autres tags et tout de même correspondre. Pour les tableaux d’octets, d’entiers ou de longs, l’ordre et la taille sont strictement vérifiés.
Format binaire du NBT
Un fichier NBT est généralement un TAG_Compound compressé en GZip. Chaque tag contient :
- Un identifiant de type.
- La taille de son nom (2 octets, big-endian).
- Son nom (UTF-8).
- Le payload.
Liste des tags NBT
| ID | Tag | Description | Capacité |
|---|---|---|---|
| 0 | TAG_End | Marque la fin d’un compound. | N/A |
| 1 | TAG_Byte | Entier signé 8 bits. | –128 à 127 |
| 2 | TAG_Short | Entier signé 16 bits. | –32 768 à 32 767 |
| 3 | TAG_Int | Entier signé 32 bits. | –2 147 483 648 à 2 147 483 647 |
| 4 | TAG_Long | Entier signé 64 bits. | ±9,22 × 10¹⁸ |
| 5 | TAG_Float | Flottant 32 bits. | ~±3,4 × 10³⁸ |
| 6 | TAG_Double | Flottant 64 bits. | ~±1,79 × 10³⁰⁸ |
| 7 | TAG_Byte_Array | Tableau d’octets. | 2 147 483 647 max |
| 8 | TAG_String | Chaîne UTF-8. | 65 535 octets |
| 9 | TAG_List | Liste de tags du même type. | 2 147 483 639 max |
| 10 | TAG_Compound | Ensemble de tags nommés. | Limité par la mémoire |
| 11 | TAG_Int_Array | Tableau d’entiers 32 bits. | 2 147 483 647 max |
| 12 | TAG_Long_Array | Tableau d’entiers 64 bits. | 2 147 483 647 max |
Fichiers utilisant le NBT
level.dat<nom>.dat(joueurs, villages, raids…)servers.dat(serveurs multijoueurs)hotbar.nbt(barres d’outils rapides)- Données de chunks, structures générées ou sauvegardées, scoreboards…
Différences avec JSON
- NBT gère plusieurs types numériques, pas de
nullni de booléen natif. - Les tableaux NBT doivent être homogènes.
- Les clés peuvent être non citées en SNBT, mais doivent l’être en JSON.
Historique
Le format NBT remonte à la phase Indev de Minecraft, avec initialement les tags 0 à 10. Il a été spécifié par Notch et est toujours utilisé, bien que des optimisations aient été ajoutées au fil des versions.
