Configuration
plugins/AstralEssentials/ ships three configuration files covered on this page: config.yml (the anvil, /xpbottle, /condense, disabled vanilla recipes, command control, and the trash bin — plus world/gameplay toggles), cooldowns.yml (per-command cooldown durations), and containers.yml (custom titles for vanilla containers). messages.yml is documented separately on Messages. The rest of config.yml — mob/trading controls, entity limits, spawner limits, spawn protection, portals, beehive regeneration, enchantment caps, and Ender dragon drops — is covered on World & Server Management.
All three files are loaded through Configurate: a camelCase Java field maps to a kebab-case YAML key (e.g. disableLocatorBar → disable-locator-bar). Every file is re-read by /essentials reload (essentials.command) — see Reloading below and Commands § Admin.
config.yml
World & gameplay settings
Key | Type | Default | Description |
|---|---|---|---|
| boolean |
| Read on every |
| boolean |
| When |
Anvil
Key | Type | Default |
|---|---|---|
| int |
|
| int |
|
xp-bottle
The icon /xpbottle (essentials.xpbottle) gives out, defined as an ItemStackWrapper:
Field | Type | Description |
|---|---|---|
| ComponentWrapper | Item display name (MiniMessage, supports placeholders). |
| ComponentWrapperList | Item lore, one entry per line. |
ExpBottleCommand renders the item once per bottle against a placeholder container carrying %amount% (the number of bottles being created in this call) and %exp% (the experience stored in each bottle). The shipped lore's %amount% xp. line therefore prints the bottle count, not the XP amount — use %exp% if the lore is meant to state how much experience the bottle actually holds.
condensable-items
A Map<String, CondensableItem> driving /condense (essentials.condense) and /condense all (essentials.condense.all). Each entry converts ratio-in of input into ratio-out of output; the map key itself is cosmetic (matching is done on input/output Materials), so it can be renamed freely as long as it stays unique.
Key | Input | Output | Ratio (in:out) |
|---|---|---|---|
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 9:1 |
|
|
| 4:1 |
|
|
| 9:1 |
/condense (no argument) only condenses the item held in the main hand; /condense all scans the entire inventory, condensing as many full sets as it can find for every recipe, then delivers the results through MailboxService#giveOrAdd — added directly to the inventory where there's room, with any leftovers queued to the player's AstralMailbox mailbox.
disabled-crafts
A Set<Material>. On onEnable, for each listed material AstralEssentials looks up every registered recipe whose result matches it (Bukkit.getRecipesFor, server-wide — not scoped to AstralEssentials' own recipes) and calls Bukkit.removeRecipe — the recipe is gone for the rest of the server's uptime. This runs once at startup only; it is not re-applied by /essentials reload. CraftListener also cancels any CraftItemEvent whose recipe result type is in disabled-crafts, live, as a safety net for recipes that slip past the startup sweep.
Command control
Three independent lists, all bypassed by the astralessentials.bypass.commandblock permission (skips the preprocess cancel, the tab-complete filter, and the command-send filter alike).
Key | Type | Behavior |
|---|---|---|
|
|
|
|
| Removed from the server's |
|
| Keyed by server group. |
trash-inventory
Backs /trash (alias /poubelle) — no dedicated permission is checked, so any player who can run the command can open it.
Field | Type | Description |
|---|---|---|
| int | Inventory size in slots ( |
| ComponentWrapper | GUI title, rendered with the opening player's placeholder context (MiniMessage + player placeholders — unlike |
On InventoryCloseEvent, any non-empty leftover contents are staged in memory and a confirmation menu (trash-confirmation, wired to the [confirm-trash]/[refund-trash] actions) opens before the items are discarded for good; closing without confirming (or the menu failing to open) refunds them back to the player.
cooldowns.yml
A flat Duration per throttled command, tracked per player via AstralCore's CooldownService under the key astralessentials:<command>, and bypassed entirely by the bare cooldown.bypass permission. A zero or negative duration disables that command's cooldown.
Key | Default | Command |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| (absent — see below) |
|
| (absent — see below) |
|
|
|
|
|
|
|
CooldownConfiguration also declares strip/stripAll Duration fields, consumed by StripWoodCommand, but the shipped cooldowns.yml above defines neither key. See Commands § Cooldowns for what that gap does at runtime (a NullPointerException on every /strip by a non-bypassing player) and for the full per-command cooldown-check breakdown.
containers.yml
Overrides the GUI title of vanilla containers on open (ContainerListener sets it via InventoryOpenEvent#titleOverride), keyed by ContainerType.
| Fires on |
|---|---|
| A single chest. |
| A double chest ( |
| A barrel. |
| The player's ender chest. |
| A storage minecart ( |
Map keys are matched against the ContainerType enum case- and underscore-insensitively (Configurate's EnumLookup), which is why the shipped ENDERCHEST key (no underscore) still resolves to ContainerType.ENDER_CHEST. A container type with no matching entry — or a missing map entirely — keeps its vanilla title.
Each value is a ComponentWrapper rendered with .get() and no placeholder container, so player-context placeholders don't resolve here, only static MiniMessage. ComponentWrapperTypeSerializer parses the string through AstralCore's shared, non-strict MiniMessage instance, whose registered tags are hover, color, keybind, translatable/translatable-fallback, insertion, font, the decoration tags, gradient, rainbow, reset, newline, transition, selector, score, nbt, shadow-color, sprite, sequential-head, and a custom click tag — an unrecognized tag is left as literal text rather than failing config load. The shipped <image:...> and <shift:...> tags are not among those (no image/shift standard tag or custom resolver exists in AstralCore), so their GUI-background-shifting effect depends entirely on a client-side resource pack recognizing them, not on anything this plugin or AstralCore parses.
Reloading
/essentials reload (essentials.command) calls the same loadConfiguration() used at startup: it re-reads messages.yml, config.yml, cooldowns.yml, and containers.yml, reloads recipes and menus, and re-applies unregistered-commands. EssentialsCommand wraps this call in a try/catch — a bad edit only logs the error and replies with a failure message, leaving the previously-loaded configuration active. This differs from onEnable(), which calls loadConfiguration() uncaught: an invalid config.yml at startup (such as the shipped xp-bottle block above, before a material key is added) prevents the plugin from enabling at all.
Effects that only run once, at onEnable, are not repeated on reload: the startup disable-locator-bar gamerule pass over already-loaded worlds, and disabled-crafts' vanilla recipe removal.
See also
World & Server Management — the rest of
config.yml: mob/trading controls, entity limits, spawner limits, spawn protection, portals, beehive regeneration, enchantment caps, and Ender dragon drops.Commands — the full command and permission reference, including cooldown behavior per command.
Messages —
messages.yml, reloaded alongside these three files.