JSON за 5 минут

Почти каждый файл аддона написан в формате JSON. Это простой способ записывать данные текстом, и правил у него совсем немного. Выучите их один раз, и сможете читать любой файл аддона.

Первое знакомство

Вот маленький JSON-файл, который описывает питомца:

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

Прочитайте вслух: «Бисквиту 3 года, он дружелюбный, любит кости и печенье, а его хозяин - Алекс 12-го уровня». Вот и весь JSON: имена и значения.

Строительные блоки

Объекты

Объект заключается в фигурные скобки { }. В нём хранятся пары «ключ - значение»:

• Ключ - это всегда текст в двойных кавычках, например "name".
• Двоеточие : отделяет ключ от значения.
• Запятая , отделяет одну пару от следующей.

Каждый файл аддона начинается с объекта, поэтому первый символ всегда {, а последний всегда }.

Массивы

Массив - это список в квадратных скобках [ ]. Элементы разделяются запятыми. Порядок важен.

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

В массиве могут лежать числа, текст, объекты и даже другие массивы.

Значения

Видов значений всего несколько:

Следите за типами. 64 и "64" похожи, но первое - число, а второе - текст. Если Minecraft ждёт число, а вы дали текст, настройка будет проигнорирована или файл не загрузится.

Вложенность: как устроены файлы аддонов

Объекты могут лежать внутри объектов. Файлы аддонов часто так группируют настройки. Вот настоящий файл предмета:

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

Пройдите путь снаружи внутрь: в файле есть объект "minecraft:item", в нём есть "description" и "components". Внутри components у "minecraft:max_stack_size" стоит число 16. Когда в этой вики написано «задайте minecraft:max_stack_size в components», имеется в виду именно это место.

Совет: делайте отступ в два пробела на каждый уровень. Игре это не нужно, но так структуру легко увидеть.

Идентификаторы и пространства имён

Всему, что вы добавляете, нужен идентификатор: уникальное имя из двух частей, разделённых двоеточием.

demo:ruby

• Часть до двоеточия - это пространство имён (namespace). Это как ваша подпись.
• Часть после него - имя самой вещи.

Собственный контент Minecraft использует пространство имён minecraft, например minecraft:diamond. Никогда не используйте minecraft для своего контента. Выберите что-то короткое и уникальное, например свои инициалы или название проекта: sam:ruby, dragons:fire_egg.

Правила, которые уберегут от проблем:

1. Используйте только строчные латинские буквы, цифры и подчёркивания.
2. Никаких пробелов. Пишите ruby_sword, а не ruby sword.
3. Используйте одно и то же пространство имён во всём аддоне.
4. Когда ваш предмет уже есть у игроков в мирах, не переименовывайте его, иначе эти предметы исчезнут.

Имена компонентов вроде minecraft:icon тоже используют пространство имён minecraft, потому что они встроены в игру. Все они есть в справочнике компонентов предметов.

format_version

Большинство файлов начинаются с "format_version". Он сообщает Minecraft, в какой версии формата вы написали файл, чтобы игра знала, как его читать. Обратите внимание: в файлах предметов, блоков и сущностей это текст в кавычках, например "1.26.30", а в manifest.json - просто число 2.

Если сомневаетесь, скопируйте версию формата из рабочего примера в этой вики и используйте одну и ту же версию во всех файлах одного типа.

Частые ошибки

Эти пять ошибок ломают большинство пакетов.

1. Лишняя запятая в конце

Запятая после последнего элемента запрещена.

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

Уберите запятую после 0.6, и всё заработает.

2. Пропущенные запятые

Обратная проблема: забыть запятую между двумя парами.

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

Добавьте запятую после 4.

3. Пропущенные или неправильные кавычки

Ключам и тексту нужны двойные кавычки, и в начале, и в конце.

{
  name: 'Ruby'
}

Исправленный вариант: { "name": "Ruby" }.

4. Непарные скобки

Каждой { нужна своя }, а каждой [ - своя ], в правильном порядке. VS Code подсвечивает парную скобку, если щёлкнуть рядом с одной из них, так что это легко проверить.

5. Комментарии

В стандартном JSON нет комментариев. В некоторых примерах файлов от Mojang можно встретить строки с комментариями //, и игра во многих местах их пропускает, но другие инструменты и валидаторы их отвергнут. Надёжнее всего вообще не писать комментарии в JSON.

Другие типы файлов

Не всё написано на JSON. Вам также встретятся:

• Файлы .lang: простые строки key=value для названий, например item.demo:ruby.name=Ruby.
• Файлы .mcfunction: по одной команде на строку. См. Функции.
• Файлы .js: JavaScript для скриптов.
• Файлы .png: текстуры.

Без JSON

Если все эти скобки кажутся слишком сложными, вы не одиноки. В GodCraft вам вообще не нужно печатать JSON: вы заполняете формы с ползунками, переключателями и списками, а приложение каждый раз пишет правильные файлы. Это быстрый способ сделать что-то рабочее, а сюда всегда можно вернуться, чтобы разобраться, что приложение для вас написало.

Теперь, когда вы умеете читать JSON, попробуйте гайд Ваш первый предмет или узнайте, как добавить пакет в игру, в гайде Экспорт и игра.