Configuration Reference

Complete documentation for every option in the EssentialsC config.yml file. Learn how to customize features, optimize performance, and tailor the plugin to your server's needs.

Important

After modifying config.yml, you must restart your server for changes to take effect. Use /language reload for message-only changes. Always backup your configuration before major updates.

File Structure Overview

The config.yml is organized into logical sections. Each major feature has its own configuration block with related settings grouped together. Understanding this structure makes customization easier.

Global Settings

Database connections, message prefix, and core system settings

Module Configurations

Individual settings for each feature (TPA, economy, warps, etc.)

Module Toggles

Enable or disable entire command groups via the modules section

Database Configuration

EssentialsC uses SQLite databases for data persistence. Each module can have its own database file for optimized performance and organization.

database: Section

Located at the root level, this section defines database connections for each module. Currently, only SQLite is supported.

databases:
  rtp:
    type: sqlite
    file: rtp.db
    pool_size: 5
  kits:
    type: sqlite
    file: kits.db
    pool_size: 5
  playerdata:
    type: sqlite
    file: playerdata.db
    pool_size: 5

type: Database type (currently only sqlite)

file: Database filename, stored in /plugins/EssentialsC/databases/

pool_size: Maximum database connections (5 is optimal for most servers)

Global Message Prefix

message-prefix

Prefix added to all plugin messages. Supports MiniMessage formatting. Leave empty for no prefix.

message-prefix: "<gray>[Essentials] "

TPA System

Configure player-to-player teleport requests with cooldowns, timeouts, and movement restrictions.

tpa: Settings

tpa:
  settings:
    cooldown: 5
    timeout: 60
    warmup: 1
    teleport-delay: 3
    cancel-on-move: true
    block-move-threshold-blocks: true

cooldown: Seconds between TPA requests (prevents spam)

timeout: Seconds before pending request expires

warmup: Pre-teleport countdown time (0 = disabled)

teleport-delay: Seconds to wait after warmup completes

cancel-on-move: Cancel if player moves during warmup

block-move-threshold-blocks: Use block precision for movement detection

tpa: Restrictions

  restrictions:
    cross-world: false
    blocked-worlds:
      - world_nether
      - world_the_end

cross-world: Allow teleport between different worlds

blocked-worlds: Worlds players cannot teleport TO

Nickname System

Control nickname customization with length limits, formatting rules, and cooldowns.

nick: Configuration

nick:
  enabled: true
  min-length: 3
  max-length: 16
  allow-formatting: true
  allow-reset: true
  allow-duplicates: false
  cooldown: 60
  max-changes-per-day: 3
  blocked-words:
    - admin
    - staff
    - moderator
  blacklist-patterns:
    - "[0-9]{4,}"
    - "([a-zA-Z])\\1{4,}"

enabled: Enable/disable nickname feature

min/max-length: Character limits for nicknames

allow-formatting: Allow MiniMessage colors/formatting

allow-duplicates: Allow multiple players to use same nickname

cooldown: Seconds between nickname changes

max-changes-per-day: Daily change limit per player

blocked-words: Forbidden words in nicknames

blacklist-patterns: Regex patterns to block

AFK Detection

Automatically mark players as AFK after inactivity. Includes visual effects, auto-kick, and teleport options.

afk: Core Settings

afk:
  enabled: true
  timeout-seconds: 300
  kick-on-afk: false

timeout-seconds: Seconds of inactivity before marking AFK (300 = 5 minutes)

kick-on-afk: Kick players after timeout (use for idle servers)

afk: Visual Effects

  sounds:
    enabled: true
    sound: BLOCK_NOTE_BLOCK_BELL
  particles:
    enabled: true
    particle: CRIT
  bossbar:
    enabled: false
    text: "<yellow>%player% is AFK"
    color: YELLOW
    style: SEGMENTED_20
  actionbar:
    enabled: true
    text: "<gray>%player% is AFK"

sounds: Play sound when player goes AFK

particles: Show particles around AFK players

bossbar: Display AFK status in boss bar

actionbar: Show AFK notification in action bar

afk: Behavior Modifications

  disable-flight: true
  disable-damage: false
  disable-item-pickup: true
  modify-tablist: true
  tablist:
    prefix: '<gray>[<red>AFK<gray>] <white> '
    suffix: ''

disable-flight: Disable flying while AFK

disable-damage: Make AFK players invincible

modify-tablist: Add AFK prefix to tab list

Economy Management (/eco)

Administrative economy commands for managing player balances. Requires Vault.

eco: Configuration

eco:
  enabled: true
  max-transaction-amount: 1000000.0
  notify-target: true
  log-transactions: true

max-transaction-amount: Safety limit per transaction

notify-target: Send message to player whose balance changed

log-transactions: Log all transactions to console

CoinFlip Gambling

Gambling minigame where players can bet money on a coin flip.

coinflip: Configuration

coinflip:
  enabled: true
  min-bet-amount: 1.0
  max-bet-amount: 10000.0
  log-flips: true
  win-chance: 0.5

min/max-bet-amount: Betting limits

win-chance: Probability of winning (0.0 = never, 1.0 = always)

Warp System

Server-wide teleport points with particles, sounds, and per-world cooldowns.

warp: Settings

warp:
  cooldown: 0
  max-per-player: 10
  particles:
    enabled: true
    type: PORTAL
  notifications:
    title-color: "<gold>"
    subtitle-color: "<yellow>"
  sounds:
    enabled: ENTITY_BAT_TAKEOFF
    disabled: ENTITY_BAT_DEATH

cooldown: Seconds between warp uses (0 = disabled)

max-per-player: Maximum personal warps per player

particles: Visual effects on teleport

sounds: Sound effects when toggling warps

Random Teleport (/rtp)

Teleport players to random locations with per-world radius and cooldown settings.

rtp: Per-World Configuration

rtp:
  world:
    enabled: true
    min_radius: 1000
    max_radius: 5000
    cooldown_seconds: 300
  world_nether:
    enabled: true
    min_radius: 500
    max_radius: 2500
    cooldown_seconds: 600

enabled: Enable RTP for this world

min/max_radius: Distance from spawn for teleport

cooldown_seconds: Seconds between RTP uses

Shop System

GUI-based shop system for buying and selling items. Requires Vault.

shop: Configuration

shop:
  enabled: true
  main:
    title: "<green>Main Shop"
    size: 54
    close-button-slot: 49
  section:
    size: 54
    player-head-slot: 4
  economy:
    currency-symbol: $
    enable-sell: true

size: Inventory slots (must be multiple of 9)

currency-symbol: Currency display symbol

enable-sell: Allow selling items back

Sell GUI (/sellgui)

Quick sell inventory for converting items to currency.

sellgui: Configuration

sellgui:
  enabled: true
  title: "<gold>💰 Sell Items"
  size: 54
  currency-symbol: $

size: Inventory slots (9-54)

currency-symbol: Currency display symbol

Home System

Player-owned teleport locations with per-player limits and world restrictions.

homes: Configuration

homes:
  max-homes: 8
  allow-rename: true
  cooldowns:
    set: 30
    teleport: 5
  restrictions:
    disabled-worlds:
      - "pvp_arena"
      - "minigame_lobby"
    allow-cross-world-teleport: true
  naming:
    max-length: 4
    allow-duplicate-names: false

max-homes: Maximum homes per player

cooldowns: Separate cooldowns for set and teleport

disabled-worlds: Worlds where homes cannot be set

Scoreboard System

Per-player scoreboard with PlaceholderAPI support and multiple layout options.

scoreboard: Core Settings

scoreboard:
  enabled: true
  debug-mode: false
  update-interval: 20
  default-layout: yellow

update-interval: Ticks between updates (20 = 1 second)

default-layout: Default layout for new players

scoreboard: Layout Configuration

Each layout defines its own title, colors, and lines. Lines support PlaceholderAPI placeholders.

layouts:
  yellow:
    title: "<#FFE600>Server Name</#FFE600>"
    lines:
      - "⌚ %server_time_kk:mm% | %server_time_dd/MM%"
      - ""
      - "<#FFE600>%player_name%</#FFE600>"
      - " <#FFE600>|</#FFE600> Balance: $%vault_eco_balance_formatted%"
      - " <#FFE600>|</#FFE600> Kills: %statistic_player_kills%"
      - " <#FFE600>|</#FFE600> Deaths: %statistic_deaths%"
      - " <#FFE600>|</#FFE600> World: %player_world%"
      - ""
      - "<#FFE600>Server</#FFE600>"
      - " <#FFE600>|</#FFE600> Online: %server_online%/%server_max_players%"
      - ""
      - "player.server"
    max-lines: 15

title: Scoreboard title with gradient/color support

lines: Array of lines with PlaceholderAPI placeholders

max-lines: Maximum lines to prevent overflow

PlaceholderAPI Setup

For scoreboard to work properly, install these PlaceholderAPI expansions:

/papi ecloud download Player
/papi ecloud download Statistic
/papi ecloud download Server
/papi ecloud download Vault
/papi reload

Command Modules

Enable or disable entire command groups. This is the main way to control which features are available on your server.

modules: Structure

modules:
  admin:
    enabled: true
    commands:
      module: true
      broadcast: true
      ban: true
      ...
  teleport:
    enabled: true
    commands:
      home: true
      warp: true
      ...
  economy:
    enabled: true
    commands:
      balance: true
      pay: true
      ...
  world:
    enabled: true
    commands:
      weather: true
      day: true
      ...
  player:
    enabled: true
    commands:
      afk: true
      repair: true
      ...
  misc:
    enabled: true
    commands:
      magnet: true
      tree: true
      ...

enabled: Master toggle for entire module

commands: Individual command toggles within module

MiniMessage Formatting Reference

EssentialsC uses MiniMessage for all text formatting. This allows gradient colors, hover events, and advanced text features.

Common Formatting Codes

Colors: <red>, <blue>, <green>, <gold>, <dark_blue>, etc.
Hex Colors: <#RRGGBB> or <color:#RRGGBB>
Gradients: <gradient:#ff0000:#00ff00>Text</gradient>
Bold: <bold>Text</bold>
Italic: <italic>Text</italic>
Underline: <underlined>Text</underlined>
Strikethrough: <strikethrough>Text</strikethrough>
Reset: <reset> or <white>

Full MiniMessage Documentation

For advanced features like hover events, click events, and more complex formatting, visit:

https://docs.advntr.dev/minimessage/format.html

Performance Optimization Tips

Reduce Scoreboard Updates

Increase update-interval from 20 to 40 ticks for less CPU usage

Disable Unused Modules

Set enabled: false for entire modules you don't need

Limit Database Pool Size

Lower pool_size to 3 on small servers (under 20 players)

Reduce Particle Effects

Disable particles in warp, rtp, and afk sections

Troubleshooting Common Issues

Configuration Not Loading

Verify YAML syntax is valid (no tabs, use spaces)
Check for correct indentation (2 spaces per level)
Ensure all quotes and brackets are closed properly
Look for syntax errors in server console on startup

Placeholders Showing Raw Text

Install PlaceholderAPI
Download required expansions with /papi ecloud download [name]
Reload PlaceholderAPI with /papi reload
Check expansion compatibility with your server version

Commands Not Available

Verify module is enabled: true in modules section
Check individual command is true in module's commands list
Ensure player has required permission node
Restart server after enabling disabled modules

Still Need Help?

If you encounter configuration issues not covered in this guide:

Discord Configuration Channel

Get help from experienced users

GitHub Issues

Report bugs or request clarifications

Example Configurations

Pre-made configs for different server types