Синтаксис JSON

Эта статья очень важна: в формате JSON хранятся настройки плагинов, их локализация и данные. Если понимать, как устроен JSON, вы сможете правильно настраивать плагины и не ломать их файлы.

Возвращайтесь к этой статье как к шпаргалке, если в следующих статьях что-то не получится.

Что такое JSON и зачем он нужен

JSON (JavaScript Object Notation) - простой текстовый формат для хранения настроек. Файл JSON можно открыть в любом текстовом редакторе и менять значения, не разбираясь в коде плагина.

Мы используем Sublime Text, о котором говорилось в статье подготовка.

Пример файла JSON:

{
  "MaxPlayers": 16,
  "WelcomeMessage": "Добро пожаловать на сервер!"
}

Здесь MaxPlayers - числовой параметр, а WelcomeMessage - текстовый, то есть строка.

Пары «ключ: значение»

JSON хранит данные парами «ключ: значение»:

• ключ - название параметра, например "MaxPlayers";
• значение - то, что вы задаёте параметру, например 16.

Ключ и значение разделяются двоеточием :, а пары между собой - запятой. В примере ниже выделена одна пара:

{
  "MaxPlayers": 16,
  "WelcomeMessage": "Добро пожаловать на сервер!"
}

При настройке плагина ключ менять нельзя, меняется только значение.

WARNING

Если изменить ключ в конфигурации плагина, плагин не найдёт свою настройку. Он может выдать ошибку при загрузке или вернуть настройки по умолчанию.

Объекты

Объект - это блок в фигурных скобках { ... }, внутри которого лежат пары «ключ: значение». Объекты группируют связанные настройки, чтобы конфигурацию было проще читать.

{
  "ServerConfig": {
    "Host": "127.0.0.1",
    "Port": 8080
  }
}

Здесь ServerConfig - объект с параметрами Host и Port.

Типы данных

По значению нужно понимать, к какому типу оно относится. Это главный способ избежать ошибок при настройке.

Числа

Целые и дробные числа пишутся без кавычек:

"MaxPlayers": 16

"SpawnX": 100.5

WARNING

Если в конфигурации стоит целое число, например 16, дробное значение туда писать нельзя. Параметр, который принимает дробные числа, обычно выглядит так: 16.0. Это очень частая ошибка.

Строки

Текст пишется в кавычках и может содержать любые символы:

"WelcomeMessage": "Добро пожаловать! На сервер №1"

Логические значения

true означает «да», false означает «нет». Пишутся без кавычек:

"IsServerOpen": true,
"IsUseAdminMenu": false

Иногда разработчик использует логическое значение как выбор между двумя режимами. Тогда смысл обычно описан прямо в названии ключа:

"Use virtual money (false), use physics money (true)": true

Списки

Список, или массив, - это блок в квадратных скобках [ ... ], элементы которого разделяются запятыми:

{
  "AllowedUsernames": [
    "Alice",
    "Bob",
    "Charlie"
  ]
}

Параметр AllowedUsernames хранит список из трёх имён. Элементов может быть сколько угодно, главное разделять их запятыми. После последнего элемента запятая не ставится: лишняя запятая ломает файл так же, как пропущенная.

Словари

Словарь похож на объект, но ключи в нём задаёте вы сами:

{
  "Settings weapon damage": {
    "multiplegrenadelauncher": 40.0,
    "explosive.timed": 300.0,
    "ammo.rocket.basic": 190.0,
    "ammo.rocket.hv": 140.0,
    "ammo.rocket.fire": 80.0
  }
}

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

WARNING

Ключи в словаре не должны повторяться, иначе плагин выдаст ошибку. Например, нельзя указать multiplegrenadelauncher дважды.

Бывают и более сложные конструкции, например словарь внутри словаря, но они строятся из тех же элементов.

Правила редактирования

1. Ключ всегда пишется в кавычках, например "SomeKey": 123.
2. Строковое значение тоже пишется в кавычках, а числа, true и false - без них.
3. После пары ставится запятая, если за ней в том же блоке есть другая пара.
4. У каждой открывающей скобки { или [ должна быть своя закрывающая: фигурные скобки описывают объекты, квадратные - списки.

{
  "Key1": "Value1",
  "Key2": "Value2"
}

INFO

Используйте редактор с подсветкой синтаксиса: большинство редакторов сразу показывают пропущенную запятую или скобку. Перед изменениями сохраняйте резервную копию файла, чтобы было куда вернуться.

Пример конфигурации

Допустим, у плагина такая конфигурация:

{
  "ServerName": "My Awesome Server",
  "IsServerOpen": true,
  "MaxPlayers": 16,
  "WelcomeMessage": "Добро пожаловать!",
  "MapRotation": [
    "DesertMap",
    "ForestMap",
    "SnowMap"
  ],
  "AdminContacts": {
    "Discord": "admin#1234",
    "Email": "admin@example.com"
  }
}

Ключ	Тип значения
ServerName	строка
IsServerOpen	логическое значение
MaxPlayers	число
WelcomeMessage	строка
MapRotation	список из трёх строк
AdminContacts	объект с двумя строками

Как изменить параметр

Например, нужно увеличить количество игроков до 20 и поменять приветствие. Найдите нужные строки и замените значения. Изменённые строки выделены:

{
  "ServerName": "My Awesome Server",
  "IsServerOpen": true,
  "MaxPlayers": 20,
  "WelcomeMessage": "Привет, игрок!",
  "MapRotation": [
    "DesertMap",
    "ForestMap",
    "SnowMap"
  ],
  "AdminContacts": {
    "Discord": "admin#1234",
    "Email": "admin@example.com"
  }
}

Убедитесь, что ничего не удалили и не потеряли запятую после строки, за которой идут другие параметры.

Типичные ошибки

Пропущенная кавычка

Неправильно, после Name нет закрывающей кавычки:

"Name: "Test"

Правильно:

"Name": "Test"

Число в кавычках

Неправильно, кавычки превращают число в строку:

"MaxPlayers": "10"

Правильно:

"MaxPlayers": 10

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

Неправильно, после первой пары нет запятой:

{
  "Key1": "Value1"
  "Key2": "Value2"
}

Правильно:

{
  "Key1": "Value1",
  "Key2": "Value2"
}

INFO

Если плагин перестал работать после ваших правок, почти всегда виноват синтаксис: запятые, кавычки, скобки или неверный тип данных.

Заключение

Чтобы уверенно работать с JSON, достаточно помнить три правила:

1. Данные записываются парами «ключ: значение», разделёнными запятыми.
2. Строки пишутся в кавычках, числа и логические значения - без них.
3. Скобки должны быть парными, а перед изменениями нужна резервная копия.

Теперь переходите к статьям:

1. Конфигурация
2. Разрешения
3. Локализация
4. Дата файлы