JSON en 5 minutos

Casi todos los archivos de un complemento están escritos en JSON. Es una forma sencilla de escribir datos como texto y solo tiene unas pocas reglas. Apréndelas una vez y podrás leer cualquier archivo de un complemento.

Un primer vistazo

Aquí tienes un pequeño archivo JSON que describe una mascota:

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

Léelo en voz alta: "Biscuit tiene 3 años, es simpático, le gustan los huesos y las galletas, y su dueño es Alex, que es de nivel 12". Eso es todo lo que es JSON: nombres y valores.

Las piezas básicas

Objetos

Un objeto va entre llaves { }. Contiene pares de clave y valor:

• La clave siempre es texto entre comillas dobles, como "name".
• Los dos puntos : separan la clave de su valor.
• Una coma , separa un par del siguiente.

Todos los archivos de un complemento empiezan con un objeto, así que el primer carácter siempre es { y el último siempre es }.

Arrays

Un array es una lista entre corchetes [ ]. Los elementos se separan con comas. El orden importa.

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

Un array puede contener números, texto, objetos o incluso otros arrays.

Valores

Solo hay unos pocos tipos de valores:

Fíjate en los tipos. 64 y "64" se parecen, pero el primero es un número y el segundo es texto. Si Minecraft espera un número y le das texto, el ajuste se ignora o el archivo no se carga.

Anidar: la forma de los archivos de un complemento

Los objetos pueden ir dentro de otros objetos. Los archivos de los complementos lo usan mucho para agrupar cosas. Este es un archivo de objeto real:

{
  "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"
        }
      }
    }
  }
}

Sigue el camino de fuera hacia dentro: el archivo tiene un objeto "minecraft:item", que tiene una "description" y unos "components". Dentro de components, "minecraft:max_stack_size" vale el número 16. Cuando esta wiki dice "pon minecraft:max_stack_size en components", se refiere a este sitio.

Consejo: sangra cada nivel con dos espacios. Al juego no le hace falta, pero así se ve la forma con facilidad.

Identificadores y espacios de nombres

Todo lo que añades necesita un identificador: un nombre único hecho de dos partes separadas por dos puntos.

demo:ruby

• La parte de antes de los dos puntos es el espacio de nombres (namespace). Es como tu firma.
• La parte de después es el nombre de la cosa.

El contenido propio de Minecraft usa el espacio de nombres minecraft, como en minecraft:diamond. Nunca uses minecraft para tu propio contenido. Elige algo corto y único, como tus iniciales o el nombre de tu proyecto: sam:ruby, dragons:fire_egg.

Reglas para ir sobre seguro:

1. Usa solo letras minúsculas, números y guiones bajos.
2. Sin espacios. Usa ruby_sword, no ruby sword.
3. Usa el mismo espacio de nombres en todo tu complemento.
4. Cuando los jugadores ya tengan tu objeto en sus mundos, no le cambies el nombre, o esos objetos desaparecerán.

Los nombres de componentes como minecraft:icon también usan el espacio de nombres minecraft, porque vienen integrados en el juego. Puedes consultarlos todos en la referencia de componentes de objeto.

format_version

La mayoría de los archivos empiezan con un "format_version". Le dice a Minecraft qué versión de la estructura del archivo has escrito, para que el juego sepa cómo leerlo. Fíjate en que es texto entre comillas, como "1.26.30", en los archivos de objetos, bloques y entidades, pero un número simple 2 en manifest.json.

Si tienes dudas, copia la versión de formato de un ejemplo que funcione de esta wiki, y mantenla igual en los archivos del mismo tipo.

Errores comunes

Estos cinco errores causan la mayoría de los paquetes rotos.

1. Comas finales

No se permite una coma después del último elemento.

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

Quita la coma después de 0.6 y funcionará.

2. Comas que faltan

El problema contrario: olvidar una coma entre dos pares.

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

Añade una coma después de 4.

3. Comillas que faltan o son incorrectas

Las claves y el texto necesitan comillas dobles, tanto al principio como al final.

{
  name: 'Ruby'
}

La versión corregida es { "name": "Ruby" }.

4. Corchetes y llaves que no cierran

Cada { necesita un } y cada [ necesita un ], en el orden correcto. VS Code resalta la pareja de un corchete cuando haces clic al lado, así que es fácil comprobarlo.

5. Comentarios

El JSON estándar no tiene comentarios. Puede que veas líneas de comentario con // en algunos archivos de ejemplo de Mojang, y el juego las ignora en muchos sitios, pero otras herramientas y validadores las rechazarán. La costumbre más segura es no poner comentarios en tu JSON.

Otros tipos de archivo

No todo es JSON. También te encontrarás con:

• Archivos .lang: líneas simples key=value para los nombres, como item.demo:ruby.name=Ruby.
• Archivos .mcfunction: un comando por línea. Consulta Funciones.
• Archivos .js: JavaScript para los scripts.
• Archivos .png: texturas.

Saltarse el JSON

Si tantos corchetes te parecen demasiado, no eres el único. En GodCraft nunca escribes JSON: rellenas formularios con deslizadores, interruptores y selectores, y la app escribe archivos válidos siempre. Es una forma rápida de crear algo que funcione, y siempre puedes volver aquí para entender lo que la app ha escrito por ti.

Ahora que sabes leer JSON, prueba Tu primer objeto personalizado, o aprende a meter tu paquete en el juego en Exportar y jugar.