Синтаксис JSON

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

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

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

Вот пример, как может выглядеть файл JSON

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

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

Основные элементы JSON-файла

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

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

Ключ — это название параметра. Например : "MaxPlayers".
Значение — это то, на что вы хотите его установить. Например : 16.
Запись пары идёт через двоеточие :, а конец пары обычно отмечается запятой, если за ним следует другая пара.

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

В настройке сервера или плагинов, ключ в JSON не меняется, он должен оставаться неизменным и чаще всего имеет какое-то более длинное и точное описание данной настройки, наша задача менять только значение

WARNING

Если во время настройки вы поменяете ключ внутри JSON, например конфигурации плагина, то это приведет к ошибке загрузки плагина или полному сбросу конфигурации до заводских настроек

Объекты

Объекты в JSON — это блоки, заключённые в фигурные скобки { ... }.
Внутри них находятся пары ключ: значение
Обычно, это используется для группировки какой-то определенной функции, чтобы настройка была более читаемая, каждую настройку группируют, помечая что и за что отвечает

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

Здесь ServerConfig — это объект, внутри которого есть параметры Host и Port.

Какие типы данных обычно встречаются

Ниже опишем типы данных, которые вы встретите во время настройки, понимать по значению, к какому типы данных оно относится - это очень важно для правильной настройки и исключения ошибок

Числа (целые и десятичные). Пишутся без кавычек, например:

"MaxPlayers": 16

или

"SpawnX": 100.5

WARNING

Если изначально вы видите целое число, как в MaxPlayers - это значит, что вы не можете сделать его десятичным
Если бы оно поддерживало десятичные числа, оно выглядело бы так : 16.0, учтите это, это очень распространенная ошибка

Строки (текст). Пишутся в кавычках, например:

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

Это обычный текст, он может содержать любые значения и вы можете вписать туда любую информацию

Логические значения (true или false). Без кавычек, например:

"IsServerOpen": true
"IsUseAdminMenu": false

Обычно, true - означает "да", если это не описано иначе в пункте конфигурации.
false - соответственно "нет"
Но в некоторых случаях это может немного отличаться в зависимости от контекста настройки плагина или файла настроек, например :

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

В данном случае разработчик принял решение на использования этого логического значения, как выбор определенной функции работы плагина

Списки

Массив (или список) в JSON — это блок в квадратных скобках [ ... ], где элементы разделяются запятыми. Например:

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

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

Словари

Данный тип схож с типом под пунктом 4, но имеет немного иные условия.

{
  "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, они всегда должны быть уникальны

Конечно, вы можете повстречать более сложные реализации данных решений, бывают даже словарь в словаре, но в рамках данного урока мы разбираем базовые объекты

Правила редактирования JSON-файла

Каждая пара ключ: значение должна идти в кавычках для ключа.
Пример:

"SomeKey": 123

SomeKey — ключ (в кавычках). 123 — значение (число, без кавычек).

WARNING

В случае если для значения используется текст (строка), то они тоже указываются в кавычка

После двоеточия : пишется значение, а затем запятая , если это не последний элемент в блоке.
Например:

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

Если вы забыли запятую или поставили её не там, файл перестанет быть корректным.

Внимательно расставляйте фигурные { } и квадратные [ ] скобки.
Фигурные скобки { } описывают объекты.
Квадратные скобки [ ] описывают списки.
Каждая открывающая скобка должна иметь соответствующую закрывающую.

INFO

Используйте текстовый редактор с подсветкой.
Большинство редакторов покажут, если вы случайно удалили скобку или пропустили запятую. Для этого мы используем SublimeText

Храните резервную копию перед изменениями, чтобы в случае ошибки было куда вернуться

Пример простого конфиг-файла

Допустим, у вас есть плагин с некоторыми настройками.
Файл config.json может выглядеть так:

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

Что здесь есть:

1. ServerName - строка
2. IsServerOpen - логическое значение
3. MaxPlayers - число
4. WelcomeMessage - строка
5. MapRotation - список из трех строк
6. AdminContacts - объект из двух отдельных строк

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

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

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

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

Типичные ошибки при редактировании

В этом пункте разберем ошибки на примерах, ошибочный вариант будет подсвечен красным

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

"Name: "Test" // Пропущена "
"Name": "Test"

Неверный тип данных

"MaxPlayers: "10" // Для числа указаны кавычки, это неверно, они используются только для строк
"MaxPlayers": 10

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

{
  "Key1": "Value1" // <== Тут должна быть запятая
  "Key2": "Value2"
}

INFO

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

Рекомендации при работе

1. Используйте редактор, который подсвечивает ошибки.
   Например, SublimeText выделит неправильные места красным и покажет подсказки.
2. Всегда делайте резервные копии.
   Если вы не уверены в своих изменениях, сохраните старую версию файла под другим именем.
3. Проверяйте файлы после правок.
   Если плагин, который использует этот конфигурационный файл, не запускается или выдаёт ошибку, скорее всего, дело в неправильном формате JSON.
4. Следите за типами данных.
   Если параметр должен быть числом, не ставьте его в кавычки.
   Если это текст, наоборот, заключайте в кавычки.

Заключение

JSON — это простой формат для хранения настроек.
Чтобы успешно им пользоваться, достаточно:

1. Знать, что данные записываются как пары ключ: значение, разделённые запятыми.
2. Строго соблюдать синтаксис: кавычки для строк, правильные фигурные и квадратные скобки, запятые между элементами.
3. Использовать редактор с подсветкой и делать резервные копии, чтобы избежать и быстро устранять ошибки.

INFO

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

Теперь вы смело можете переходить к пунктам :

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

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