proximaclient.json: a plugin settings screen in ProximaClient

A proximaclient.json file at the root of the .jar gives your plugin a settings screen in ProximaClient: the plugin's card on the "Plugins" tab gets a "Config editor" icon, and the server owner changes settings in a form. The screen is there for plugins on the Paper, Purpur and Folia cores, and on imported servers also on Pufferfish, Spigot and CraftBukkit. The same file adds console hints for the commands of a plugin or mod.

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

How the app reads the file

• Only from the root of the .jar, in UTF-8 without a BOM, and only if the file is 512 KB or smaller.
• Afresh each time the "Plugins" tab or the editor opens.
• Strictly. An extra key or a missing required one at any level, an unknown type or kind, a character not allowed in a command name or id, a limit exceeded or a JSON error, and the app drops the whole file: the plugin gets neither settings nor hints. Every key is required unless these pages call it optional or mark it "For …". An unknown categoryId, an enum with no options, a repeated group id or value in options, or a group naming a field that doesn't exist removes the whole settings block: the screen, and the category and description on the card. The console hints stay.

Text for people is written as a pair, {"ru": "…", "en": "…"}: both languages are required, each up to 200 characters. The settings and content blocks are optional. schemaVersion is the format version, currently 1; without it, 1 is assumed.

The settings block

Key	What it is
categoryId	The category on the plugin card: administration, security, performance, gameplay, communication or other.
description	The description on the card, in place of the one from plugin.yml.
configPath	The settings file, as a path from the server's plugins folder: Homes/config.yml, not plugins/Homes/config.yml. Formats: .yml, .yaml, .json and .properties.
fields	The form fields, up to 300.
groups	The form's tabs, up to 50. Optional.

A field in fields:

Key	What it is
key	The field's name, different for each field, up to 64 characters.
path	Where the value sits in the settings file, dot-separated: homes.max. Optional: without it, key is used.
type	string, password (hidden input), number, boolean (a toggle), enum (a pick from a list) or string-array (a list of strings).
label	The field's label.
description	A note under the field. Optional.
required	Optional. true: the settings won't save while the field is empty.
options	For enum: 1 to 100 options {"value": "…", "label": {…}} with different values.
withGenerator	For password: true adds a button that fills in a random password.

A group in groups is a tab: id (different for each), label, fieldKeys (the keys of its fields, in order), and an optional description and icon. Fields that aren't in any group go to a last tab, "General", and without groups the form is a single list. icon takes one of the names 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 and Zap; any other name gives the Settings icon.

What happens to the settings file

• If the file doesn't exist yet, the form is empty, and saving creates it along with its folder.
• Saving writes the file anew: its comments are lost, and a .properties file is also sorted by key and loses its lines without =. Other keys that aren't in fields stay.
• An empty field is written as null, an empty string-array as [], and in .properties as an empty value.

Check: the plugin card has the "Config editor" icon, and a value saved in the editor shows up in the settings file on the "Files" tab.