Settings & fields
Categories, field kinds, conditions and expanding sections.
The settings.categories tree is what users see when they configure an instance. Categories group
fields; fields map to environment variables on the container.
Categories
{
"id": "world",
"label": "World",
"description": "World generation and gameplay",
"children": [/* fields or nested categories */]
}Categories nest: children accepts both fields and further categories, so you can build
sections and subsections.
Fields
Every field connects a UI control to an environment variable:
{
"key": "MAX_PLAYERS",
"label": "Max players",
"description": "How many players can join at once.",
"kind": "NUMBER",
"defaultValue": 20,
"min": 1,
"max": 200
}Prop
Type
Field kinds
| Kind | Renders as |
|---|---|
TEXT / STRING | Single-line text input. |
TEXTAREA | Multi-line text. |
NUMBER | Numeric input with optional min/max/step/unit. |
SLIDER | Range slider. |
MEM | Memory picker (e.g. for JVM heap / container memory). |
BOOLEAN | Toggle. |
SELECT | Dropdown over options. |
COMBOBOX | Searchable dropdown over options. |
LIST | Editable list of values. |
PASSWORD | Masked input. |
DATE / DATETIME / TIMEZONE | Date, date-time and timezone pickers. |
READ_ONLY | Displayed but not editable. |
Conditions
enable gates a field on another value. A condition is one of:
{ "equals": "PAPER" }
{ "notEquals": false }
{ "in": ["FABRIC", "QUILT"] }Expanding sections
expand reveals additional fields or whole categories when a value matches. Use it to keep the
form small until a choice makes more options relevant:
{
"key": "TYPE",
"label": "Server type",
"description": "Which server software to run.",
"kind": "SELECT",
"options": [
{ "value": "VANILLA", "label": "Vanilla" },
{
"value": "FORGE",
"label": "Forge",
"expand": {
"children": [
{
"key": "FORGE_VERSION",
"label": "Forge version",
"description": "Leave empty for the recommended build.",
"kind": "TEXT"
}
]
}
}
]
}Expansion can also hang off the field itself with a when condition:
"expand": {
"when": { "equals": true },
"children": [ /* shown only when the toggle is on */ ]
}The official Minecraft template combines these heavily: selecting a mod platform expands its version fields, enabling the whitelist expands the player list, and so on. It's the best worked example of a large, humane settings form.