proximaclient.json: экран настроек плагина в ProximaClient

Файл proximaclient.json в корне .jar даёт плагину экран настроек в ProximaClient: на карточке плагина во вкладке «Плагины» появляется значок «Редактор конфига», и владелец сервера меняет настройки в форме. Экран есть у плагинов на ядрах Paper, Purpur и Folia, а у импортированных серверов — ещё на Pufferfish, Spigot и CraftBukkit. Тот же файл добавляет командам плагина или мода подсказки в консоли.

{
  "schemaVersion": 1,
  "settings": {
    "categoryId": "gameplay",
    "description": { "ru": "Дома игроков", "en": "Player homes" },
    "configPath": "Homes/config.yml",
    "fields": [
      { "key": "max-homes", "path": "homes.max", "type": "number",
        "label": { "ru": "Домов на игрока", "en": "Homes per player" } },
      { "key": "mode", "type": "enum",
        "label": { "ru": "Режим", "en": "Mode" },
        "options": [
          { "value": "strict", "label": { "ru": "Строгий", "en": "Strict" } },
          { "value": "free", "label": { "ru": "Свободный", "en": "Free" } }
        ] }
    ],
    "groups": [
      { "id": "limits", "icon": "Sliders",
        "label": { "ru": "Лимиты", "en": "Limits" },
        "fieldKeys": ["max-homes"] }
    ]
  }
}

Как приложение читает файл

• Только из корня .jar, в кодировке UTF-8 без BOM и размером до 512 КБ.
• Заново при каждом открытии вкладки «Плагины» и редактора.
• Строго. Лишний ключ или нет обязательного на любом уровне, неизвестный type или kind, недопустимый знак в имени команды или id, превышенный лимит, ошибка в JSON — и приложение не берёт файл целиком: у плагина нет ни настроек, ни подсказок. Обязателен каждый ключ, который на этих страницах не назван необязательным и не помечен «Для …». Неизвестная categoryId, enum без вариантов, повтор id группы или value в options и ссылка группы на несуществующее поле убирают весь блок settings: экран, категорию и описание на карточке. Подсказки в консоли остаются.

Тексты для людей пишутся парой {"ru": "…", "en": "…"}: оба языка обязательны, каждый до 200 знаков. Блоки settings и content необязательны. schemaVersion — версия формата, сейчас 1; без него считается 1.

Блок settings

Ключ	Что это
categoryId	Категория на карточке плагина: administration, security, performance, gameplay, communication или other.
description	Описание на карточке вместо описания из plugin.yml.
configPath	Файл настроек, путь от папки plugins сервера: Homes/config.yml, а не plugins/Homes/config.yml. Форматы .yml, .yaml, .json и .properties.
fields	Поля формы, до 300.
groups	Вкладки формы, до 50. Необязателен.

Поле в fields:

Ключ	Что это
key	Имя поля, у каждого своё, до 64 знаков.
path	Где значение в файле настроек, через точку: homes.max. Необязателен: без него берётся key.
type	string, password (скрытый ввод), number, boolean (переключатель), enum (выбор из списка) или string-array (список строк).
label	Подпись поля.
description	Пояснение под полем. Необязателен.
required	Необязателен. true: с пустым полем настройки не сохранятся.
options	Для enum: от 1 до 100 вариантов {"value": "…", "label": {…}} с разными value.
withGenerator	Для password: true добавляет кнопку, которая подставляет случайный пароль.

Группа в groups — это вкладка: id (у каждой свой), label, fieldKeys — ключи её полей по порядку — и необязательные description и icon. Поля, которых нет ни в одной группе, попадают на последнюю вкладку «Общее», а без groups форма — один список. Для icon подходят имена Activity, Bell, Bug, Code, Compass, Cpu, Database, FileText, Folder, Globe, HardDrive, Heart, Layers, Lock, Map, MessageSquare, Network, Palette, Server, Settings, Shield, Sliders, Sword, Terminal, Users, Wrench и Zap; другое имя даёт иконку Settings.

Что происходит с файлом настроек

• Если файла ещё нет, форма пустая, а сохранение создаёт его вместе с папкой.
• Сохранение записывает файл заново: комментарии из него пропадают, а .properties ещё и сортируется по ключам и теряет строки без =. Остальные ключи, которых нет в fields, остаются.
• Пустое поле записывается как null, пустой string-array — как [], а в .properties — как пустое значение.

Проверьте: на карточке плагина есть значок «Редактор конфига», а значение, сохранённое в редакторе, появилось в файле настроек на вкладке «Файлы».