Le JSON en 5 minutes

Presque tous les fichiers d'add-on sont écrits en JSON. C'est une façon simple d'écrire des données sous forme de texte, avec seulement une poignée de règles. Apprends-les une fois et tu pourras lire n'importe quel fichier d'add-on.

Un premier coup d'œil

Voici un petit fichier JSON qui décrit un animal de compagnie :

{
  "name": "Biscuit",
  "age": 3,
  "is_friendly": true,
  "favorite_foods": ["bone", "cookie"],
  "owner": {
    "name": "Alex",
    "level": 12
  }
}

Lis-le à voix haute : « Biscuit a 3 ans, est gentil, aime les os et les cookies, et appartient à Alex qui est niveau 12. » Le JSON, ce n'est que ça : des noms et des valeurs.

Les briques de base

Objets

Un objet est entouré d'accolades { }. Il contient des paires clé et valeur :

• La clé est toujours du texte entre guillemets doubles, comme "name".
• Deux-points : séparent la clé de sa valeur.
• Une virgule , sépare une paire de la suivante.

Chaque fichier d'add-on commence par un objet, donc le premier caractère est toujours { et le dernier toujours }.

Tableaux

Un tableau est une liste entourée de crochets [ ]. Les éléments sont séparés par des virgules. L'ordre compte.

{
  "version": [1, 0, 0],
  "tags": ["sword", "weapon"],
  "rows": [
    { "item": "minecraft:stick" },
    { "item": "minecraft:diamond" }
  ]
}

Un tableau peut contenir des nombres, du texte, des objets, ou même d'autres tableaux.

Valeurs

Il n'existe que quelques sortes de valeurs :

Fais attention aux types. 64 et "64" se ressemblent, mais le premier est un nombre et le second du texte. Si Minecraft attend un nombre et que tu lui donnes du texte, le réglage est ignoré ou le fichier ne se charge pas.

L'imbrication : la forme des fichiers d'add-on

Des objets peuvent se trouver dans d'autres objets. Les fichiers d'add-on s'en servent beaucoup pour regrouper les choses. Voici un vrai fichier d'objet :

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "demo:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:max_stack_size": 16,
      "minecraft:icon": {
        "textures": {
          "default": "ruby"
        }
      }
    }
  }
}

Suis le chemin de l'extérieur vers l'intérieur : le fichier a un objet "minecraft:item", qui a une "description" et des "components". Dans components, "minecraft:max_stack_size" vaut le nombre 16. Quand ce wiki dit « règle minecraft:max_stack_size dans components », c'est de cet endroit qu'il parle.

Astuce : indente chaque niveau de deux espaces. Le jeu n'en a pas besoin, mais ça rend la forme facile à voir.

Identifiants et espaces de noms

Tout ce que tu ajoutes a besoin d'un identifiant : un nom unique en deux parties séparées par deux-points.

demo:ruby

• La partie avant les deux-points est l'espace de noms (namespace). C'est un peu ta signature.
• La partie après est le nom de la chose.

Le contenu de Minecraft utilise l'espace de noms minecraft, comme dans minecraft:diamond. N'utilise jamais minecraft pour ton propre contenu. Choisis quelque chose de court et d'unique, comme tes initiales ou le nom de ton projet : sam:ruby, dragons:fire_egg.

Les règles qui te protègent :

1. Utilise seulement des lettres minuscules, des chiffres et des tirets bas.
2. Pas d'espaces. Écris ruby_sword, pas ruby sword.
3. Utilise le même espace de noms dans tout ton add-on.
4. Une fois que des joueurs ont ton objet dans leurs mondes, ne le renomme plus, sinon ces objets disparaîtront.

Les noms de composants comme minecraft:icon utilisent aussi l'espace de noms minecraft, parce qu'ils sont intégrés au jeu. Tu peux tous les retrouver dans la référence des composants d'objet.

format_version

La plupart des fichiers commencent par une "format_version". Elle indique à Minecraft quelle version de la structure de fichier tu as écrite, pour que le jeu sache comment la lire. Note que c'est du texte entre guillemets, comme "1.26.30", dans les fichiers d'objet, de bloc et d'entité, mais un simple nombre 2 dans manifest.json.

Dans le doute, copie la version de format d'un exemple qui fonctionne sur ce wiki, et garde la même pour tous les fichiers d'un même type.

Les erreurs courantes

Ces cinq erreurs causent la plupart des packs cassés.

1. Les virgules finales

Une virgule après le dernier élément est interdite.

{
  "nutrition": 4,
  "saturation_modifier": 0.6,
}

Retire la virgule après 0.6 et ça marche.

2. Les virgules manquantes

Le problème inverse : oublier une virgule entre deux paires.

{
  "nutrition": 4
  "saturation_modifier": 0.6
}

Ajoute une virgule après 4.

3. Guillemets manquants ou incorrects

Les clés et le texte ont besoin de guillemets doubles, au début comme à la fin.

{
  name: 'Ruby'
}

La version corrigée est { "name": "Ruby" }.

4. Des crochets qui ne correspondent pas

Chaque { a besoin d'un } et chaque [ d'un ], dans le bon ordre. VS Code met en évidence le crochet correspondant quand tu cliques à côté d'un crochet, ce qui rend la vérification facile.

5. Les commentaires

Le JSON standard n'a pas de commentaires. Tu verras peut-être des lignes de commentaire // dans certains fichiers d'exemple de Mojang, et le jeu les ignore à beaucoup d'endroits, mais d'autres outils et validateurs les rejetteront. Le plus sûr, c'est de ne pas mettre de commentaires dans ton JSON.

Les autres types de fichiers

Tout n'est pas en JSON. Tu croiseras aussi :

• Les fichiers .lang : de simples lignes key=value pour les noms, comme item.demo:ruby.name=Ruby.
• Les fichiers .mcfunction : une commande par ligne. Voir Fonctions.
• Les fichiers .js : du JavaScript pour les scripts.
• Les fichiers .png : les textures.

Se passer du JSON

Si tous ces crochets te paraissent beaucoup, tu n'es pas le seul. Dans GodCraft, tu ne tapes jamais de JSON : tu remplis des formulaires avec des curseurs, des interrupteurs et des sélecteurs, et l'appli écrit des fichiers valides à chaque fois. C'est un moyen rapide de créer quelque chose qui marche, et tu peux toujours revenir ici pour comprendre ce que l'appli a écrit pour toi.

Maintenant que tu sais lire le JSON, essaie Ton premier objet personnalisé, ou découvre comment mettre ton pack dans le jeu avec Exporter et jouer.