Skip to content

Overview

uxmEssentials keeps its settings in HOCON files (.conf), not YAML. If you have configured other plugins with config.yml, the ideas are the same — keys, values, lists — but the syntax is a little friendlier and the layout is split by module rather than piled into one giant file.

This page explains how the config system is organised, where each file lives, and how to edit and reload it safely.

Why HOCON, not YAML

Everything player-facing and every tunable resolves through typed configuration loaded with Configurate. That gives us a few practical wins over YAML:

  • Indentation doesn't matter. Structure comes from { } braces, not from counting spaces. A stray space can't silently reparent a key.
  • Comments survive. Lines starting with # are part of the file, so the shipped defaults document themselves right next to each key.
  • Values are typed. A number is a number and a duration is a duration — the plugin validates them on load and tells you exactly which key is wrong instead of failing cryptically.

HOCON syntax rules

HOCON is forgiving about whitespace and indentation but strict about structure:

  • Blocks open and close with braces: storage { … }. Every { needs a }.
  • Comments start with # and run to the end of the line.
  • String values are usually quoted: backend = "sqlite". Numbers and true/false are not: port = 3306, enabled = true.
  • Lists use square brackets: disabled-worlds = ["arena", "spawn"].
  • Keys are kebab-case (read-pool-size, default-locale) — never camelCase.

If a file won't load after an edit, you almost always have a missing } or a stray quote. The server log names the file and line.

Where everything lives

On first run uxmEssentials extracts its default configuration into plugins/uxmEssentials/. The tree looks like this:

plugins/uxmEssentials/
├── config.conf                     # globals only — storage, locale, network, links…
├── modules/
│   ├── teleport/
│   │   ├── config.conf             # enabled + teleport tunables
│   │   ├── rtp.conf                # /rtp safe-search (a lifted-out big block)
│   │   └── gui/
│   │       └── teleport-settings.conf
│   ├── economy/
│   │   ├── config.conf
│   │   ├── currencies.conf         # per-currency definitions
│   │   └── gui/ …
│   ├── communication/
│   │   ├── config.conf
│   │   ├── join-quit.conf
│   │   ├── announcer.conf
│   │   ├── info-pages.conf
│   │   ├── advancements.conf
│   │   └── gui/ …
│   └── … one folder per module (homes, warps, kits, moderation, …)
├── messages/
│   ├── messages_en.conf            # player-facing text (English)
│   └── messages_tr.conf            # player-facing text (Turkish)
├── commands/
│   └── commands.conf               # rename / realias / disable any command
├── menus/
│   └── example.conf                # your own custom GUIs
└── data/
    └── uxmessentials.db            # the SQLite database (default backend)

The shape is the whole design: global settings live in one small file, and each feature module owns its own folder. You never wade through unrelated settings to tune one feature.

There is no modules.conf file

A common misconception — carried over from older notes — is that a central modules.conf switchboard turns modules on and off. It does not exist. It is not shipped and never created. Each module is enabled or disabled by the enabled key at the top of its own modules/<module>/config.conf. See Per-Module Config.

The sub-files inside a module folder

Most modules need only their config.conf. A few large features lift a big block out into a sibling file so the main file stays readable:

  • modules/teleport/rtp.conf — the /rtp safe-search tuning.
  • modules/economy/currencies.conf — every currency definition.
  • modules/communication/{join-quit,announcer,info-pages,advancements}.conf — the four communication feature blocks.

The gui/ sub-folder holds one file per management GUI panel — the in-game editors you reach through /uxmess gui. You rarely edit these by hand; they are styled the same way as custom menus.

First-run extraction and edits

  • Files are written once, from the bundled defaults, and never overwritten. Your edits survive restarts and plugin upgrades.
  • Delete a single key and it falls back to its built-in default on next load.
  • Delete a whole file and it is regenerated from defaults.
  • commands/commands.conf is generated from the live command list on first run and then left untouched.

How to edit and reload

  1. Open the relevant .conf file in a plain-text editor (VS Code, Notepad++, nano).
  2. Make your change, keeping braces and quotes balanced.
  3. Save the file.
  4. Apply it in-game:
/uxmess reload <module>     # reload just one module (fast, targeted)
/uxmess reload              # reload every module

Reloading a module re-reads only its subtree, stops and restarts that one module off-thread, and re-publishes its commands. Configuration is swapped atomically, so players in-flight are never left half-configured. Reloading never deletes stored data — disabling a module leaves its database rows intact.

When in doubt, reload one module

/uxmess reload economy is safer and faster than a full reload. If a file has a syntax error, only that module refuses to reload and the log tells you where.

Which page covers what

Config concern File Page
Storage / database, default locale, cross-server, server links, update check, map markers config.conf config.conf (Globals)
Enabling/disabling a module and its tunables modules/<m>/config.conf (+ sub-files) Per-Module Config
Renaming, re-aliasing or disabling a command commands/commands.conf Renaming Commands
Player-facing text and languages messages/messages_<lang>.conf Messages & Languages
Colours, glyphs and tone of chat/GUI text catalogs + menus/*.conf UI Style
Custom GUIs menus/*.conf Custom Menu Engine

Next Steps