Configuration
Current config files, important keys, feature toggles, storage, economy, shops, auction house, protection, scoreboard, holograms, and custom commands.
Table of Contents
Jump to a section
Overview
What it is, features, and goals
›
Installation
Install steps + recommended setup
›
Commands
Command list + examples
›
Permissions
Permission nodes and rank setup
›
Configurations
Config options and details
›
Tutorials
Common setups and how-to guides
›
Author & Support
Contact, bugs, feedback, links
›
Try: storage.type, auctionHouse, respawnInvulnerability, worldBorder, scoreboard, playerShops, commands.yml
Tip: search "cooldown", "tpa", "warp", "mute", "custom."
Copy buttons use your clipboard
SQLite by default
Split config files
Storage-backed data
Configuration that maps to the live plugin.
HyEssentialsX keeps feature settings in config files and persistent player/server data in the selected storage backend. Server owners should change config keys, not edit storage data by hand.
Default Storage
SQLite is the default backend. JSON, MySQL/MariaDB, and MongoDB are available for servers that need another storage model.
Config Migration
New defaults are merged into existing config files without overwriting server choices when ConfigManager loads and saves.
Feature Modules
Most major systems can be disabled cleanly: homes, warps, kits, TPA, economy, shops, auction house, stats, scoreboard, holograms, mail, and more.
In-Game Editing
The staff command center Config tab can save common server settings back to the same config files, so panel edits remain persistent.
Core Files and Storage
Where the plugin stores configuration and which backend stores player/server data.
| Key | File | Description | Notes |
|---|---|---|---|
config.json
Copy
|
mods/HyEssentialsX/config.json |
Main plugin config: features, storage, teleport, shops, auction house, world, holograms, and core behavior. | Generated and migrated by ConfigManager. |
economyConfig.json
Copy
|
mods/HyEssentialsX/economyConfig.json |
Economy currency, balances, HUD, rewards, paychecks, and economy integrations. | Economy-specific settings. |
rewardsConfig.json
Copy
|
mods/HyEssentialsX/rewardsConfig.json |
Playtime rewards, rankups, and progression rewards. | Used by playtime/rankup systems. |
chatConfig.json
Copy
|
mods/HyEssentialsX/chatConfig.json |
Chat formatting, group formats, join/leave/death messages, broadcasts, and chat behavior. | LuckPerms/HyperPerms-aware formatting is configured here. |
scoreboardConfig.json
Copy
|
mods/HyEssentialsX/scoreboardConfig.json |
Scoreboard HUD layout, lines, colors, logo, placeholder behavior, and defaults. | Scoreboard can also be edited in-game. |
HideNoPermissionCommands
Copy
|
config.json |
Hide commands from tab completion when the sender lacks the command permission. | Default true. HyEssentialsX refreshes command trees so valid permission changes appear without disabling this. |
CommandTreeRefreshEnabled
Copy
|
config.json |
Refresh client command trees after player permission changes, OP virtual-group changes, LuckPerms user/group/context/sync updates, and HyperPerms user/group/context/reload updates. | Default true. Keeps permission-filtered tab completion current without polling. |
commands.yml
Copy
|
mods/HyEssentialsX/commands.yml |
Custom server info commands such as /discord, /website, /vote, or /store. | Permission pattern: hyessentialsx.custom.<command>. |
warning escalation rules
Copy
|
Selected storage backend |
Persistent warning thresholds, actions, durations, windows, reasons, and command-style case actions. | Edited with /warnrules or the staff command center Configuration tab; warning expiry can be set per warning with /warn expire:<duration> or the staff panel. |
staff command center Configuration tab
Copy
|
config.json / split config files |
In-game editor for warning rules, player warps, economy HUD, playtime/rankups, shops, auction house, RTP, homes, command rule prices/timers, chat toggles, and scoreboard placement. | Open with /hexadmin and use the Config tab. Requires admin permission for global config edits. |
announcement presets
Copy
|
config.json |
Named scheduled/manual announcements with chat, screen title, popup, sound, particle, permission target, placeholder, and command actions. | Edited with /announcement or the staff command center Announcements launch button. |
storage.type
Copy
|
config.json |
Selected storage backend for plugin data. | Supports SQLite by default, JSON, MySQL/MariaDB, and MongoDB. |
storage.host / port / database / username / password
Copy
|
config.json |
Database connection settings for remote storage backends. | Only needed for MySQL/MariaDB or MongoDB-style setups. |
storage.jdbcUrl / params / useSsl
Copy
|
config.json |
Advanced SQL connection controls. | Use when your host requires a custom JDBC URL or SSL settings. |
Feature Toggles
High-level systems that can be enabled or disabled.
| Key | File | Description | Notes |
|---|---|---|---|
homes.enabled
Copy
|
config.json |
Enable homes commands and UI. | /sethome, /home, /homes, /delhome. |
homes.maxHomesPerPlayer
Copy
|
config.json |
Default maximum homes per player. | -1 means unlimited. hyessentialsx.sethome.max.<number> and unlimited permissions can override the default. |
warps.enabled
Copy
|
config.json |
Enable warp commands. | /warp, /warps, /setwarp, /delwarp. |
warps.gui.enabled
Copy
|
config.json |
Enable the warps UI. | |
playerWarps.enabled
Copy
|
config.json |
Enable player-owned public/private warps. | /pwarp, /playerwarp, /playerwarps. |
playerWarps.gui
Copy
|
config.json |
Enable the searchable/sortable player warp browse UI. | When disabled, /pwarp falls back to chat listing. |
kits.enabled
Copy
|
config.json |
Enable kits. | /kit, /kits, kit editor commands. |
kits.gui.enabled
Copy
|
config.json |
Enable kits UI. | |
msg.enabled
Copy
|
config.json |
Enable private messaging. | /msg, /r, ignore, social spy. |
commandSpy.enabled
Copy
|
config.json |
Enable staff command spy. | /commandspy, /cmdspy, and /cspy. |
nicknames.enabled
Copy
|
config.json |
Enable nickname and real-name lookup tools. | /nick and /realname. |
tpa.enabled
Copy
|
config.json |
Enable TPA commands. | /tpa, /tpahere, accept, deny, cancel, ignore. |
tpa.gui.enabled
Copy
|
config.json |
Enable TPA UI pages. | |
rtp.enabled
Copy
|
config.json |
Enable random teleport. | /rtp. |
spawn.enabled
Copy
|
config.json |
Enable spawn commands. | /spawn, /setspawn, /delspawn. |
spawn.routing.selectionMode
Copy
|
config.json |
Choose first, random, or nearest when a route has multiple named spawn targets. | Editable with /spawnroute mode. |
spawn.routing.orders
Copy
|
config.json |
Resolution orders for command, firstJoin, join, respawn, and death routes. | Sources include bed, firstjoin, death, group, world, permission, main, setspawn, and worlddefault. |
spawn.routing.firstJoinSpawn / deathSpawn
Copy
|
config.json |
Named spawn targets for first-join and death route sources. | Create targets first with /setspawn <name>. |
spawn.routing.worlds
Copy
|
config.json |
Map world names to one or more named spawn targets. | Editable with /spawnroute world <world> <spawn1,spawn2|none>. |
spawn.routing.groups
Copy
|
config.json |
Permission-group spawn routes with id, permission, priority, and named spawn targets. | Editable with /spawnroute group. |
rules.enabled
Copy
|
config.json |
Enable rules command. | /rules. |
rules.gui.enabled
Copy
|
config.json |
Enable rules UI. | |
motd.enabled
Copy
|
config.json |
Enable message of the day command. | /motd. |
near.enabled
Copy
|
config.json |
Enable nearby player lookup. | /near. |
broadcast.enabled
Copy
|
config.json |
Enable broadcast and auto-broadcast systems. | /broadcast. |
announcements.enabled / intervalSeconds / random / presets
Copy
|
config.json |
Control the named announcement scheduler and preset list. | Existing autoBroadcast messages migrate into announcement presets when the new section is missing. |
adminChat.enabled
Copy
|
config.json |
Enable admin chat. | /adminchat, /a. |
afk.enabled
Copy
|
config.json |
Enable AFK command/state. | /afk. |
mail.enabled
Copy
|
config.json |
Enable the mail system. | /mail. |
economy.enabled
Copy
|
economyConfig.json |
Enable economy commands, balances, rewards, and market systems that depend on money. | Auction house requires economy. |
adminShops.enabled
Copy
|
config.json |
Enable admin shops. | /adminshop. |
playerShops.enabled
Copy
|
config.json |
Enable player shops. | /shop, /shops. |
auctionHouse.enabled
Copy
|
config.json |
Enable auction house UI, commands, and NPC access. | /auctionhouse, /auction. |
stats.enabled
Copy
|
config.json |
Enable stat tracking, stats UI, and leaderboard UI. | /stats, /leaderboard. |
scoreboard.enabled
Copy
|
scoreboardConfig.json |
Enable scoreboard HUD. | /scoreboard, /sb. |
holograms.enabled
Copy
|
config.json |
Enable holograms and hologram commands. | /hologram, /holo, /hg. |
combatLog.enabled
Copy
|
config.json |
Enable combat log detection. | Can restrict commands during combat. |
Command Rules
Shared cooldown, warmup, price, disabled-command, world blacklist, and rank reduction controls for command tuning. Basic command rule values can also be edited from /hexadmin > Config > Cmd Rules.
| Key | File | Description | Notes |
|---|---|---|---|
commandRules.commands.<command>.enabled
Copy
|
config.json |
Enable or disable a specific command rule target. | Current built-in command-rule targets include home, sethome, delhome, warp, spawn, rtp, back, tpa, tpahere, tpahereall, tphere, top, bottom, thru, jumpto, fly, god, freecam, vanish, heal, repair, afk, near, msg, reply, mail, ignore, pay, balance, baltop, rules, motd, discord, list, playtime, stats, leaderboard, and rankup. |
commandRules.commands.<command>.cooldownSeconds
Copy
|
config.json |
Cooldown before the same player can use the command again. | Legacy per-feature cooldown keys are still read as fallbacks. |
commandRules.commands.<command>.warmupSeconds
Copy
|
config.json |
Delay before a teleport-style command completes. | Movement cancellation is controlled by cancelWarmupOnMove. |
commandRules.commands.<command>.cancelWarmupOnMove
Copy
|
config.json |
Cancel pending warmups when the player moves. | Teleport warmups use the shared movement-cancel system. |
commandRules.commands.<command>.price
Copy
|
config.json |
Economy cost to run the command. | Uses the same money formatting/minor-unit behavior as the rest of HyEssentialsX economy config. |
commandRules.commands.<command>.blacklistedWorlds
Copy
|
config.json |
World names where the command is blocked. | Useful for survival worlds, event worlds, or economy-limited areas. |
commandRules.commands.<command>.reductions
Copy
|
config.json |
Permission-based reductions for cooldown, warmup, and price. | Entries can use cooldownReductionPercent, warmupReductionPercent, priceReductionPercent, or absolute cooldownSeconds, warmupSeconds, and price caps. |
Command Spy, Nicknames, and Flight
Staff visibility, nickname validation, and optional paid/timed flight packages.
| Key | File | Description | Notes |
|---|---|---|---|
commandSpy.ignoredCommands
Copy
|
config.json |
Commands that command spy should not report. | Defaults include authentication, private messaging, mail, and command-spy commands. |
commandSpy.logToActivity
Copy
|
config.json |
Log command-spy observations to the staff activity feed. | Visible through staff activity surfaces. |
nicknames.minLength / maxLength
Copy
|
config.json |
Allowed nickname length range. | Applied before saving a nickname. |
nicknames.preventDuplicates
Copy
|
config.json |
Prevent two players from sharing the same plain-text nickname. | Case-insensitive comparison. |
nicknames.blacklist
Copy
|
config.json |
Blocked nickname values. | Useful for staff titles, impersonation protection, and reserved names. |
fly.timedEnabled
Copy
|
config.json |
Enable timed flight grants and paid flight packages. | Default false. /fly buy and /fly time <minutes>. |
fly.timedRequirePermission
Copy
|
config.json |
Require hyessentialsx.fly.time for timed flight purchases. | Default true. Disable only if every player should be able to buy timed flight when timed flight is enabled. |
fly.costPerMinute
Copy
|
config.json |
Economy cost per minute for paid flight. | Set to 0 for free timed flight packages. |
fly.defaultMinutes
Copy
|
config.json |
Default duration used by /fly buy. | Positive integer minutes. |
fly.expiryWarningSeconds
Copy
|
config.json |
Warning offsets before timed flight expires. | Example values: 300, 60, 10. |
Economy, Rewards, and Progression
Money formatting, rewards, paychecks, rankups, playtime, and integrations.
| Key | File | Description | Notes |
|---|---|---|---|
economy.currencyName / symbol / decimalPlaces
Copy
|
economyConfig.json |
Currency naming and formatting. | Amounts are preserved using the plugin's configured decimal behavior. |
economy.startingBalance
Copy
|
economyConfig.json |
Starting balance for new players. | |
economy.hud.enabled
Copy
|
economyConfig.json |
Show economy HUD where supported. | |
economy.baltop.gui.enabled
Copy
|
economyConfig.json |
Enable baltop UI. | Players can be hidden with hyessentialsx.baltop.exempt. |
economy.paychecks.enabled
Copy
|
economyConfig.json |
Enable scheduled paycheck rewards. | Rank amounts can use hyessentialsx.paycheck.amount.<amount>. |
economy.blockRewards.enabled
Copy
|
economyConfig.json |
Pay players for configured block actions. | Use carefully on survival servers. |
economy.mobRewards.enabled
Copy
|
economyConfig.json |
Pay players for configured mob kills. | |
economy.popupRewards.enabled
Copy
|
economyConfig.json |
Show reward popups. | |
economy.vaultUnlocked.enabled
Copy
|
economyConfig.json |
Expose HyEssentialsX through VaultUnlocked economy support. | For compatible integrations. |
playtime.gui.enabled
Copy
|
rewardsConfig.json |
Enable playtime UI. | /playtime. |
playtime.rewards
Copy
|
rewardsConfig.json |
Configure playtime reward milestones. | |
rankup.enabled
Copy
|
rewardsConfig.json |
Enable rankups. | /rankup. |
rankup.requirements
Copy
|
rewardsConfig.json |
Configure playtime, money, and rank requirements. | Rankups can require money, playtime, or both. |
Shops and Auction House
Admin shops, player shops, linked stock, listing limits, fees, and NPC access.
| Key | File | Description | Notes |
|---|---|---|---|
adminShops.enabled
Copy
|
config.json |
Enable server-owned admin shops. | Supports buy/sell entries, stock, money pools, NPC access, and editor UI. |
playerShops.enabled
Copy
|
config.json |
Enable player-owned shops. | Players can create shops when permitted. |
playerShops.directoryEnabled
Copy
|
config.json |
Enable player shop directory browsing. | /shop and /shops. |
playerShops.maxShopsPerPlayer
Copy
|
config.json |
Default max player shops per player. | Admin bypasses still apply. |
playerShops.creationCost
Copy
|
config.json |
Cost to create a player shop. | Requires economy. |
playerShops.chestLinkRadius
Copy
|
config.json |
Maximum radius for linking a shop to a stock container. | |
playerShops.maxTradeQuantity
Copy
|
config.json |
Maximum buy/sell quantity per trade action. | Bulk buy/sell also respects stock and stack limits. |
playerWarps.autoApprove
Copy
|
config.json |
Automatically approve newly created player warps. | Disable when staff should review warps before public use. |
playerWarps.maxWarpsPerPlayer
Copy
|
config.json |
Default player warp limit per player. | Admins bypass through hyessentialsx.playerwarp.admin. |
playerWarps.createCost
Copy
|
config.json |
Economy cost to create a player warp. | Can be 0 for free creation. |
playerWarps.visitCost
Copy
|
config.json |
Economy cost to visit a player warp. | Can be bypassed with hyessentialsx.playerwarp.bypasscost. |
auctionHouse.enabled
Copy
|
config.json |
Enable auction house commands, UI, and linked NPCs. | Requires economy. |
auctionHouse.maxListingSeconds
Copy
|
config.json |
Default maximum listing duration. | Permission duration nodes can raise this. |
auctionHouse.defaultListingSeconds
Copy
|
config.json |
Default listing duration selected in the UI. | |
auctionHouse.maxListingsPerPlayer
Copy
|
config.json |
Default active listing limit per player. | Permission listing nodes can raise this. |
auctionHouse.listingCost
Copy
|
config.json |
Cost to list an item. | Can be 0 for free listings. |
auctionHouse.npcRole
Copy
|
config.json |
NPC role/metadata used by auction house NPCs. | All auction house NPCs open the same market. |
Protection, World, and Safety
Spawn protection, respawn invulnerability, combat log, and expanding world border.
| Key | File | Description | Notes |
|---|---|---|---|
spawnProtection.enabled
Copy
|
config.json |
Enable spawn protection. | |
spawnProtection.radius
Copy
|
config.json |
Radius protected around spawn. | |
respawnInvulnerability.enabled
Copy
|
config.json |
Temporarily protect players after respawn. | |
respawnInvulnerability.bedSeconds
Copy
|
config.json |
Protection duration after bed respawn. | |
respawnInvulnerability.worldSeconds
Copy
|
config.json |
Protection duration after world/default respawn. | |
respawnInvulnerability.cancelOnAttack
Copy
|
config.json |
Remove respawn invulnerability when the player attacks. | Lets players run away without fighting under protection. |
combatLog.enabled
Copy
|
config.json |
Enable combat log detection. | |
combatLog.durationSeconds
Copy
|
config.json |
How long a player remains combat-tagged. | |
worldBorder.enabled
Copy
|
config.json |
Enable world border enforcement. | /worldborder. |
worldBorder.radius
Copy
|
config.json |
Current/default border radius. | |
worldBorder.centerX / centerZ
Copy
|
config.json |
World border center. | |
worldBorder.expansion.enabled
Copy
|
config.json |
Enable automatic border expansion. | |
worldBorder.expansion.amount
Copy
|
config.json |
How much the border grows each interval. | Example: 100. |
worldBorder.expansion.intervalSeconds
Copy
|
config.json |
Real-time interval between expansions. | 86400 seconds is 24 hours. |
worldBorder.expansion.maxRadius
Copy
|
config.json |
Maximum radius after expansion. |
Chat, Mail, Stats, Scoreboard, and Holograms
Presentation systems, player communication limits, UI data, and placeholders.
| Key | File | Description | Notes |
|---|---|---|---|
chat formatting
Copy
|
chatConfig.json |
HyEssentialsX always owns player chat formatting. | Formats resolve nicknames plus LuckPerms/HyperPerms/local rank tags. |
chat.groups / groupPriorities
Copy
|
chatConfig.json |
Group-specific chat formats and priority selection. | Supports {prefix}, {suffix}, {group}, {player}, {displayname}, {realname}, {faction}, %luckperms_prefix%, %luckperms_suffix%, %luckperms_primary_group%, %hyperperms_prefix%, %hyperperms_suffix%, %hyperperms_primary_group%, and LuckPerms meta placeholders. |
chat.groupPrefixes / groupSuffixes
Copy
|
chatConfig.json |
Local fallback prefix and suffix tags by group. | {prefix} and {suffix} use LuckPerms first, then HyperPerms, then these local values when external values are unavailable or blank. |
joinMessages / leaveMessages / deathMessages
Copy
|
chatConfig.json |
Configure join, leave, and death message behavior. | |
mail.maxInbox / maxSent / maxAgeDays
Copy
|
config.json |
Mail storage and retention limits. | |
mail.maxMessageLength
Copy
|
config.json |
Maximum mail body length. | |
mail.notifyOnJoin
Copy
|
config.json |
Notify players about unread mail on join. | |
stats.trackMovement
Copy
|
config.json |
Track movement/distance stats. | Can be disabled if movement tracking is too noisy for your server. |
scoreboard.defaultHidden
Copy
|
scoreboardConfig.json |
Start scoreboard hidden for new players. | |
scoreboard.logo / lines / colors
Copy
|
scoreboardConfig.json |
Scoreboard visual content and formatting. | Use /scoreboard edit for in-game editing. |
scoreboard.anchor / offset / size
Copy
|
scoreboardConfig.json |
Scoreboard placement and sizing defaults. | |
scoreboard.placeholders
Copy
|
scoreboardConfig.json |
Placeholder behavior for scoreboard lines. | Supports plugin placeholders where available. |
holograms.maxNameLength / maxLineLength / maxLines
Copy
|
config.json |
Hologram content limits. | |
holograms.defaultLineSpacing
Copy
|
config.json |
Default line spacing between hologram lines. | |
holograms.placeholders.enabled
Copy
|
config.json |
Enable placeholder updates in holograms. | |
holograms.placeholders.updateIntervalMs
Copy
|
config.json |
How often hologram placeholders refresh. | |
holograms.visibility
Copy
|
config.json |
Hologram visibility settings. |