proximaclient.json — API для плагинов и модов

Также доступно на: English

Файл proximaclient.json позволяет автору плагина или мода расширить приложение ProximaClient под свой проект без участия нашей команды:

settings — добавляет плагину собственный экран настроек (иконка-шестерёнка на карточке плагина → модалка с полями). Пользователь редактирует конфиг через UI, не открывая .yml/.toml вручную.
content — добавляет в автодополнение серверной консоли ваши команды, предметы, эффекты и т.д. (по мере ввода команды пользователь видит подсказки).

Оба блока опциональны — можно поставлять только настройки, только контент, или оба. Формат версионируется полем schemaVersion (текущая версия — 1). Это developer-facing документ; примеры даны для Minecraft.

Если ещё не знаете, как пользователи ставят плагины — см. Как установить плагины на сервер.

Где лежит файл

Приложение ищет манифест в двух местах, в таком порядке приоритета:

В корне вашего .jar — файл proximaclient.json рядом с plugin.yml / paper-plugin.yml / mods.toml / fabric.mod.json.
На CDN ProximaMP (fallback, если в jar файла нет) — по имени плагина/мода.

MyPlugin.jar
├── proximaclient.json   ← здесь, в корне архива
├── plugin.yml
└── ...классы...

Структура jar-архива с proximaclient.json в корне

CDN-фолбек (на стороне ProximaMP)

Если в jar файла нет, приложение пробует взять манифест с нашего CDN по имени плагина. Туда схемы кладёт команда ProximaMP — например, готовые настройки для популярных плагинов, которые сами не поставляют proximaclient.json. Прямого доступа к CDN у авторов плагинов нет: основной путь для вас — файл в jar.

Кеш на стороне приложения — 5 минут. Нужен CDN-фолбек для вашего плагина (например, нельзя менять jar)? Напишите команде ProximaMP — добавим на нашей стороне.

Приоритет: если файл есть и в jar, и на CDN — берётся версия из jar. CDN используется только когда в jar файла нет.

Верхний уровень файла

{
  "schemaVersion": 1,        // версия формата файла (число, по умолчанию 1)
  "settings": { ... },       // опционально — экран настроек
  "content":  { ... }        // опционально — данные для автодополнения консоли
}

Поле	Тип	Обяз.	Описание
`schemaVersion`	number (целое > 0)	нет	Версия формата. Если не указана — подставляется `1`.
`settings`	object	нет	Схема экрана настроек.
`content`	object	нет	Дельта игровых данных для консоли.

Лишние ключи запрещены. Любой неизвестный ключ на любом уровне → весь файл считается невалидным и игнорируется (строгая валидация).

Блок `settings` — экран настроек

Добавляет плагину иконку-шестерёнку и модалку настроек. Пользователь меняет значения — приложение записывает их в указанный конфиг-файл.

Модалка настроек плагина с вкладками

Поля верхнего уровня `settings`

Поле	Тип	Обяз.	Описание
`categoryId`	string	да	Категория плагина (см. список ниже). Значение вне списка → блок `settings` отбрасывается.
`configPath`	string	да	Путь к редактируемому конфигу относительно папки сервера (например `plugins/MyPlugin/config.yml`). Без переносов строк; ≤ 255 символов.
`description`	`{ru, en}`	да	Краткое описание для шапки модалки.
`fields`	массив	да	Поля формы. До 300 штук.
`groups`	массив	нет	Группировка полей по вкладкам. До 50 штук.

Допустимые categoryId (ровно эти 6 значений):

`categoryId`	Назначение
`administration`	Администрирование, управление
`security`	Безопасность, доступы, пароли
`performance`	Производительность, оптимизация
`gameplay`	Игровой процесс, механики
`communication`	Чат, сообщения, уведомления
`other`	Прочее

Поле формы (`fields[]`)

{
  "key": "max-homes",          // обязателен — идентификатор поля
  "path": "homes.max",         // опц. — путь в конфиге (по умолчанию = key)
  "type": "number",            // обязателен — тип контрола
  "required": false,           // опц. — обязательное ли поле
  "label": { "ru": "Макс. домов", "en": "Max homes" },        // обязателен
  "description": { "ru": "Лимит домов на игрока", "en": "Homes per player" }  // опц.
}

Атрибут	Тип	Обяз.	Описание
`key`	string (1–64)	да	Уникальный идентификатор поля внутри схемы.
`path`	string (1–128)	нет	Путь к значению в конфиге (точечная нотация, например `homes.max`). По умолчанию = `key`.
`type`	string	да	Тип поля — один из 6 (см. ниже).
`required`	boolean	нет	Помечает поле обязательным. По умолчанию `false`.
`label`	`{ru, en}`	да	Подпись поля в UI.
`description`	`{ru, en}`	нет	Поясняющий текст под полем.
`options`	массив	для `enum`	Варианты выбора.
`withGenerator`	boolean	для `password`	Кнопка «сгенерировать пароль».

Типы полей (`type`)

`type`	Контрол в UI	Доп. атрибуты
`string`	Текстовое поле	—
`password`	Поле пароля (скрытый ввод)	`withGenerator: true` → кнопка генерации
`number`	Числовое поле	—
`boolean`	Переключатель (тоггл)	—
`enum`	Выпадающий список	`options` — обязателен, ≥ 1 элемента
`string-array`	Редактор списка строк	—

Опция enum (options[]):

{
  "value": "strict",                                  // что сохранится в конфиг (1–128 симв.)
  "label": { "ru": "Строгий", "en": "Strict" }        // что показать в списке
}

Значения value внутри одного поля должны быть уникальны.

Группы / вкладки (`groups[]`)

Опционально. Разбивает поля на вкладки внутри модалки. Поля, не попавшие ни в одну группу, уходят во вкладку «Общее». Если groups не задан — поля рисуются плоским списком.

{
  "id": "general",                                    // обязателен, уникален (1–64)
  "icon": "settings",                                 // опц. — имя иконки
  "label": { "ru": "Общее", "en": "General" },        // обязателен
  "description": { "ru": "Базовые опции", "en": "Basics" },  // опц.
  "fieldKeys": ["max-homes", "mode"]                  // обязателен — key полей этой вкладки
}

Каждый fieldKeys[i] должен ссылаться на существующий key из fields. До 300 ключей на группу.

Блок `content` — данные для консоли

Добавляет в автодополнение серверной консоли команды и игровые объекты вашего плагина. Это плоская дельта поверх встроенных данных игры: можно добавлять новое и убирать существующее.

Автодополнение консоли с командой плагина

Состав блока `content`

Поле	Тип	Описание
`addedCommands`	массив `CommandTemplate`	Новые команды. До 200.
`removedCommands`	массив string	Имена команд, которые убрать из подсказок. До 200.
`addedItems` / `removedItems`	массив	Реестр предметов.
`addedEffects` / `removedEffects`	массив	Реестр эффектов.
`addedEnchantments` / `removedEnchantments`	массив	Реестр зачарований.
`addedMobs` / `removedMobs`	массив	Реестр мобов/сущностей.
`addedBiomes` / `removedBiomes`	массив	Реестр биомов.
`addedAttributes` / `removedAttributes`	массив	Реестр атрибутов.
`addedSounds` / `removedSounds`	массив	Реестр звуков.
`addedParticles` / `removedParticles`	массив	Реестр частиц.
`addedStructures` / `removedStructures`	массив	Реестр структур.
`addedDimensions` / `removedDimensions`	массив	Реестр измерений.

added* принимают массив объектов GameItem, removed* — массив строк-идентификаторов.

Шаблон команды (`CommandTemplate`)

{
  "name": "sethome",                                   // обязателен — имя команды (без слэша)
  "description": { "ru": "Установить дом", "en": "Set home" },  // опц.
  "usage": { "ru": "<имя>", "en": "<name>" },          // опц. — подсказка свободного хвоста
  "slots": []                                          // обязателен — позиционные аргументы
}

Атрибут	Тип	Обяз.	Описание
`name`	string (1–64)	да	Имя команды без слэша. Допустимы `A–Z a–z 0–9 _ : -`. Подкоманды — через `enum` + `followedBy`, а не пробелом в имени.
`description`	`{ru, en}`	нет	Описание команды в подсказке.
`usage`	`{ru, en}`	нет	Хинт по «свободному хвосту» (координаты, JSON, текст). Показывается, когда слоты кончились, но команда ждёт ввод.
`slots`	массив `CommandSlot`	да	Позиционные аргументы по порядку. До 64. Пустой массив = команда без аргументов.

Слоты (`slots[]`) — поддерживаемые `kind`

Каждый слот описывает один позиционный аргумент. Всего 12 видов (kind):

`kind`	Что подсказывает	Откуда берутся значения
`enum`	Фиксированный список	Инлайн, из самого слота (`values`)
`player`	Имя игрока	Игроки онлайн (+ селекторы `@a @e @p @s @r @n`)
`items`	Предмет	Реестр `addedItems` (+ встроенные)
`effect`	Эффект	Реестр `addedEffects`
`enchantment`	Зачарование	Реестр `addedEnchantments`
`mob`	Моб / сущность	Реестр `addedMobs`
`biome`	Биом	Реестр `addedBiomes`
`attribute`	Атрибут	Реестр `addedAttributes`
`sound`	Звук	Реестр `addedSounds`
`particle`	Частица	Реестр `addedParticles`
`structure`	Структура	Реестр `addedStructures`
`dimension`	Измерение	Реестр `addedDimensions`

Простые слоты записываются как { "kind": "player" }, { "kind": "items" } и т.д. Слот enum — особый (см. ниже).

`enum`-слот, `EnumValue` и подкоманды (`followedBy`)

{
  "kind": "enum",
  "values": [
    { "value": "add",    "followedBy": [ { "kind": "player" } ] },
    { "value": "remove", "followedBy": [ { "kind": "player" } ] },
    { "value": "list" }
  ]
}

Атрибут	Тип	Обяз.	Описание
`value`	string (1–64)	да	Значение, которое отправится на сервер как есть.
`label`	`{ru, en}`	нет	Отображаемое имя варианта.
`description`	`{ru, en}`	нет	Пояснение варианта.
`followedBy`	массив `CommandSlot`	нет	Слоты, добавляемые после этого значения, если выбрано именно оно. Так делаются подкоманды. Рекурсивно. До 64.

Подкоманды через followedBy: команда whitelist — это шаблон с name: "whitelist" и одним enum-слотом [add, remove, on, off, list], где у add/remove есть followedBy: [{ "kind": "player" }], а у on/off/list — нет. До 256 значений в одном enum.

Подкоманды followedBy в действии — whitelist add <игрок>

Игровой объект (`GameItem`)

Элемент любого added*-реестра:

{
  "id": "myplugin:magic_wand",                          // обязателен
  "name": { "ru": "Волшебная палочка", "en": "Magic Wand" }  // обязателен
}

Атрибут	Тип	Обяз.	Описание
`id`	string (1–128)	да	Идентификатор, отправляемый на сервер как есть. Формат: `namespace:path` или просто `path`.
`name`	`{ru, en}`	да	Человекочитаемое имя в подсказке.

Реестр динамически расширяется: добавили предмет через addedItems — он сразу доступен в items-слотах команд.

Ограничения и валидация

Файл — недоверенный ввод, поэтому проверяется строго. При любой ошибке валидации файл (или соответствующий блок) полностью игнорируется — приложение продолжит работать без вашей схемы.

Что приведёт к отклонению:

Лишние/неизвестные ключи на любом уровне.
Превышение лимитов: ≤ 200 команд, ≤ 200 removedCommands, ≤ 2000 элементов на реестр, ≤ 256 значений в enum, ≤ 64 слота, ≤ 300 полей, ≤ 50 групп. Локализованные строки {ru, en} — ≤ 200 символов.
Недопустимое имя команды / id (имена команд — только A–Z a–z 0–9 _ : -).
categoryId вне списка — блок settings отбрасывается.
Размер файла > 512 КБ — не читается из jar.
Битый JSON.

Совет: если схема «не подхватывается», проверьте файл строгим JSON-валидатором, сверьте categoryId со списком и убедитесь, что нет лишних полей.

Полный пример `proximaclient.json`

{
  "schemaVersion": 1,
  "settings": {
    "categoryId": "gameplay",
    "configPath": "plugins/Homes/config.yml",
    "description": { "ru": "Настройки системы домов", "en": "Homes settings" },
    "fields": [
      { "key": "max-homes", "path": "homes.max", "type": "number",
        "label": { "ru": "Макс. домов", "en": "Max homes" } },
      { "key": "cooldown", "path": "homes.cooldown-seconds", "type": "number",
        "label": { "ru": "Кулдаун (сек)", "en": "Cooldown (s)" } },
      { "key": "cross-world", "type": "boolean",
        "label": { "ru": "Телепорт между мирами", "en": "Cross-world teleport" } }
    ]
  },
  "content": {
    "addedCommands": [
      { "name": "home", "slots": [],
        "description": { "ru": "Телепорт домой", "en": "Teleport home" } },
      { "name": "sethome", "slots": [],
        "usage": { "ru": "<имя дома>", "en": "<home name>" } },
      { "name": "delhome", "slots": [],
        "usage": { "ru": "<имя дома>", "en": "<home name>" } }
    ]
  }
}

Вопросы по интеграции

Версия формата — schemaVersion: 1. Вопросы по интеграции — к команде ProximaMP через Telegram. Сам ProximaClient — на странице /client.

← Все статьи

proximaclient.json — API для плагинов и модов

Где лежит файл

CDN-фолбек (на стороне ProximaMP)

Верхний уровень файла

Блок settings — экран настроек

Поля верхнего уровня settings

Поле формы (fields[])

Типы полей (type)

Группы / вкладки (groups[])

Блок content — данные для консоли

Состав блока content

Шаблон команды (CommandTemplate)

Слоты (slots[]) — поддерживаемые kind

enum-слот, EnumValue и подкоманды (followedBy)

Игровой объект (GameItem)