Getting Started Configuration Commands Troubleshooting

Configuration Guide

Master every aspect of your server selector configuration

📁 Configuration File Location

The config file is automatically created after first startup:

Path 
Velocity/plugins/velocitynexus/config.toml

Edit this file with any text editor (VS Code, Notepad++, nano, etc.)

🔧 Complete Configuration Structure

Menu Section

Configure the GUI appearance and size. Supports beautiful MiniMessage gradients:

TOML 
[menu]
# Modern gradient title with MiniMessage format
title = "<gradient:#667eea:#764ba2:#f093fb>âœĶ SERVER SELECTOR âœĶ</gradient>"

# GUI size: 1-6 rows (each row = 9 slots)
rows = 5
  • title - GUI title using MiniMessage format for gradients & colors
  • rows - Number of rows (1-6). Total slots = rows × 9
MiniMessage Format

Gradients: <gradient:#START:#END>Text</gradient>
Colors: <#667eea> or <red>, <gold>, <green>
Multi-stop: <gradient:#667eea:#764ba2:#f093fb> for smooth transitions

Hex Color Format

Use &x&R&R&G&G&B&B format for hex colors. Example: #667eea becomes &x&6&6&7&e&e&a

Server Definitions

Each server uses the [servers.NAME] format. The NAME MUST match your velocity.toml exactly!

TOML 
[servers.Hub]  # ⚠ïļ MUST match velocity.toml server name!
display-name = "<gradient:#ffecd2:#fcb69f>🏠 HUB</gradient>"
description = [
    "",
    "<gradient:#667eea:#764ba2>  â–ļ Main Network Hub</gradient>",
    "",
    "<gray>  Your journey starts here",
    "<gray>  Connect with the community",
    "",
    "<gradient:#ffecd2:#fcb69f>  ⚡ Always Online</gradient>",
    "<yellow>  ðŸ‘Ĩ Players: <white>%players%",
    "",
    "<gradient:#a8edea:#fed6e3>  ❖ Click to join ❖</gradient>",
    ""
]
icon = "NETHER_STAR"   # Minecraft material name
slot = 22              # Inventory slot (0-53 for 6 rows)
enabled = true         # false = decoration only, not clickable

Understanding Server Names

Critical: Names Must Match Exactly!

The server section name [servers.XXXX] MUST exactly match the server name in your Velocity velocity.toml file. Names are case-sensitive!

velocity.toml ✓ 
[servers]
Hub = "127.0.0.1:25566"
Survival = "127.0.0.1:25567"
config.toml ✓ 
[servers.Hub]  # ✓ Matches!
enabled = true

[servers.Survival]  # ✓ Matches!

Available Placeholders

  • %players% - Current player count on that server
  • %maxplayers% - Maximum player limit

Decorative Items

Create non-clickable decoration items by setting enabled = false:

TOML 
[servers.deco_glass]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 0
enabled = false  # Not clickable - just decoration!

ðŸŽĻ Customization Options

Colors & Gradients

Modern gradients using MiniMessage format in display names and descriptions:

TOML 
# Purple to Pink gradient (elegant premium)
display-name = "âœĶ HUB âœĶ"

# Green to Blue gradient (nature theme)
display-name = "⛏ïļ SURVIVAL"

# Orange to Yellow gradient (sunset/warm theme)
display-name = "☀ïļ CREATIVE"

# Red to Pink gradient (fire/intense theme)
display-name = "⚔ïļ PVP"

# Gold theme (luxury/VIP)
display-name = "👑 VIP SERVER"

Materials & Icons

Choose from any Minecraft material name. Common choices:

Material Best For Example Use
NETHER_STAR Hub servers Main lobby, central hub
GRASS_BLOCK Survival Vanilla survival worlds
DIAMOND_SWORD PvP/Combat Duels, KitPVP, FFA
BOW Minigames SkyWars, BedWars
EMERALD Economy Shops, trading servers
BEACON Special/VIP Premium servers, events
DIAMOND_BLOCK Creative Building, creative mode
ENDER_PEARL Practice Practice, training servers
Material Compatibility

Some materials changed names between versions. Use materials that exist in your Minecraft version. Check Spigot Material Javadocs for your version.

Descriptions & Lore

Multi-line descriptions with MiniMessage gradients and color tags:

TOML 
description = [
    "",
    "  â–ļ Main Network Hub",
    "",
    "  Your journey starts here",
    "  ðŸ‘Ĩ Players: %players%",
    "",
    "  ❖ Click to join ❖",
    ""
]

# MiniMessage color tags:
# , , , , , 
# , , , , , 
# , , , 
# text - Smooth color transitions
# , , , ,

Player Count Placeholder

Use %players% to show live player counts:

  • %players% - Shows current player count on that server
  • Updates in real-time as players join/leave
  • Works anywhere in description lines

Slot Positioning

GUI slots are numbered 0-53 (for a 6-row inventory):

Slot Layout 
# 3-Row GUI (27 slots)
Row 1:  0  1  2  3  4  5  6  7  8
Row 2:  9 10 11 12 13 14 15 16 17
Row 3: 18 19 20 21 22 23 24 25 26

# 5-Row GUI (45 slots)
Row 1:  0  1  2  3  4  5  6  7  8
Row 2:  9 10 11 12 13 14 15 16 17
Row 3: 18 19 20 21 22 23 24 25 26
Row 4: 27 28 29 30 31 32 33 34 35
Row 5: 36 37 38 39 40 41 42 43 44

Popular layouts:

  • Center: Slot 13 (3-row), Slot 22 (5-row)
  • Left-Center-Right: Slots 11, 13, 15 (3-row)
  • Bottom Row Center: Slot 22 (3-row), Slot 40 (5-row)

📋 Ready-to-Use Configurations

Simple 3-Server Hub Setup

Perfect for small networks with hub, survival, and minigames:

TOML 
[menu]
title = "âœĶ SERVER SELECTOR âœĶ"
rows = 3

[servers.hub]  # Must match velocity.toml server name!
display-name = "🏠 HUB"
icon = "NETHER_STAR"
slot = 11
description = [
    "",
    "  â–ļ Main Hub",
    "  Start your adventure here",
    "  ðŸ‘Ĩ Players: %players%",
    ""
]
enabled = true

[servers.survival]  # Must match velocity.toml server name!
display-name = "⛏ïļ SURVIVAL"
icon = "GRASS_BLOCK"
slot = 13
description = [
    "",
    "  â–ļ Vanilla Experience",
    "  Build, explore, survive",
    "  ðŸ‘Ĩ Players: %players%",
    ""
]
enabled = true

[servers.minigames]  # Must match velocity.toml server name!
display-name = "ðŸŽŪ MINIGAMES"
icon = "BOW"
slot = 15
description = [
    "",
    "  â–ļ Fun & Games",
    "  SkyWars, BedWars & more",
    "  ðŸ‘Ĩ Players: %players%",
    ""
]
enabled = true

ðŸŽĻ Premium Design with Decorations

A beautiful, spacious 5-row design with gradient borders and modern MiniMessage formatting:

Production-Ready Configuration

This is the recommended production configuration featuring modern MiniMessage gradients, elegant glass pane borders, and professional spacing. Copy this entire config to get started quickly!

config.toml (Full Premium Example) 
# ═══════════════════════════════════════════════════════════════════════════
#  Velocity Nexus - Premium Server Selector Configuration
#  Modern & Elegant GUI Design
# ═══════════════════════════════════════════════════════════════════════════

[menu]
# Premium gradient title with modern colors
title = "<gradient:#667eea:#764ba2:#f093fb>âœĶ SERVER SELECTOR âœĶ</gradient>"

# 5 rows for a spacious, premium look
rows = 5

# ═══════════════════════════════════════════════════════════════════════════
#  SERVER DEFINITIONS
# ═══════════════════════════════════════════════════════════════════════════
# NOTE: The server name in [servers.XXXX] must match your velocity.toml exactly!
# If your server is named "Hub" in velocity.toml, use [servers.Hub] here

[servers.Hub]
display-name = "<gradient:#ffecd2:#fcb69f>🏠 HUB</gradient>"
description = [
    "",
    "<gradient:#667eea:#764ba2>  â–ļ Main Network Hub</gradient>",
    "",
    "<gray>  Your journey starts here",
    "<gray>  Connect with the community",
    "",
    "<gradient:#ffecd2:#fcb69f>  ⚡ Always Online</gradient>",
    "<yellow>  ðŸ‘Ĩ Players: <white>%players%",
    "",
    "<gradient:#a8edea:#fed6e3>  ❖ Click to join ❖</gradient>",
    ""
]
icon = "NETHER_STAR"
slot = 22
enabled = true

# ═══════════════════════════════════════════════════════════════════════════
#  DECORATIVE ITEMS (Disabled servers used as decoration)
# ═══════════════════════════════════════════════════════════════════════════

[servers.deco_top_left]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 0
enabled = false

[servers.deco_top_center_1]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 1
enabled = false

[servers.deco_top_center_2]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 2
enabled = false

[servers.deco_top_center_3]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 3
enabled = false

[servers.deco_top_title]
display-name = "<gradient:#667eea:#764ba2:#f093fb>âœĶ PREMIUM NETWORK âœĶ</gradient>"
description = [
    "",
    "<gradient:#ffecd2:#fcb69f>  Welcome to our server!</gradient>",
    "",
    "<gray>  Select a server below to begin",
    ""
]
icon = "BEACON"
slot = 4
enabled = false

[servers.deco_top_center_5]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 5
enabled = false

[servers.deco_top_center_6]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 6
enabled = false

[servers.deco_top_right_1]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 7
enabled = false

[servers.deco_top_right]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 8
enabled = false

# Border decorations (left & right edges)
[servers.deco_left_2]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 9
enabled = false

[servers.deco_right_2]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 17
enabled = false

[servers.deco_left_3]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 18
enabled = false

[servers.deco_right_3]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 26
enabled = false

[servers.deco_left_4]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 27
enabled = false

[servers.deco_right_4]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 35
enabled = false

# Bottom row decorations
[servers.deco_bottom_left]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 36
enabled = false

[servers.deco_bottom_2]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 37
enabled = false

[servers.deco_bottom_3]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 38
enabled = false

[servers.deco_bottom_4]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 39
enabled = false

[servers.deco_info]
display-name = "<gradient:#a8edea:#fed6e3>â„đ Information</gradient>"
description = [
    "",
    "<gray>  Version: <white>1.0.0",
    "<gray>  By: <gradient:#667eea:#764ba2>AshiePleb</gradient>",
    ""
]
icon = "BOOK"
slot = 40
enabled = false

[servers.deco_bottom_6]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 41
enabled = false

[servers.deco_bottom_7]
display-name = "<gradient:#f093fb:#667eea>◆</gradient>"
description = [""]
icon = "MAGENTA_STAINED_GLASS_PANE"
slot = 42
enabled = false

[servers.deco_bottom_8]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 43
enabled = false

[servers.deco_bottom_right]
display-name = "<gradient:#667eea:#764ba2>◆</gradient>"
description = [""]
icon = "PURPLE_STAINED_GLASS_PANE"
slot = 44
enabled = false

# ═══════════════════════════════════════════════════════════════════════════
#  SETTINGS
# ═══════════════════════════════════════════════════════════════════════════

[settings]
# Update player count in real-time
update-player-count = true

# Sounds when opening menu and clicking items
sounds-enabled = true

# Replace default /server command
override-server-command = true

# Premium error messages
offline-server-message = "<gradient:#ff6b6b:#ee5a6f>✖ This server is currently offline</gradient>"
no-permission-message = "<gradient:#ff6b6b:#ee5a6f>✖ You don't have permission to access this server</gradient>"
Customizing This Config

To add your servers: Duplicate the [servers.Hub] section, change the section name to match your velocity.toml server name, update the display-name, description, icon, and slot. Remove unused decoration items if you want more server slots!

Large Minigames Network

For networks with 7+ servers (5-row layout):

TOML 
[menu]
title = "ðŸŽŪ MEGA NETWORK ðŸŽŪ"
rows = 5

[servers.hub]
display-name = "🏠 HUB"
icon = "NETHER_STAR"
slot = 22
description = [
    "",
    "  â–ļ Main Network Hub",
    "  ðŸ‘Ĩ Players: %players%",
    ""
]
enabled = true

[servers.skywars]
display-name = "ðŸŠķ SKYWARS"
icon = "FEATHER"
slot = 12
description = [
    "",
    "  â–ļ Fight in the Sky",
    "  ðŸ‘Ĩ Playing: %players%",
    ""
]
enabled = true

[servers.bedwars]
display-name = "🛏ïļ BEDWARS"
icon = "RED_BED"
slot = 14
description = [
    "",
    "  â–ļ Protect Your Bed!",
    "  ðŸ‘Ĩ Playing: %players%",
    ""
]
enabled = true

[servers.survival]
display-name = "⛏ïļ SURVIVAL"
icon = "GRASS_BLOCK"
slot = 21
description = [
    "",
    "  â–ļ Vanilla Experience",
    "  ðŸ‘Ĩ Online: %players%",
    ""
]
enabled = true

[servers.creative]
display-name = "🏗ïļ CREATIVE"
icon = "DIAMOND_BLOCK"
slot = 23
description = [
    "",
    "  â–ļ Build Anything",
    "  ðŸ‘Ĩ Builders: %players%",
    ""
]
enabled = true

[servers.kitpvp]
display-name = "⚔ïļ KITPVP"
icon = "DIAMOND_SWORD"
slot = 30
description = [
    "",
    "  â–ļ Choose Kit & Fight",
    "  ðŸ‘Ĩ Fighting: %players%",
    ""
]
enabled = true

[servers.practice]
display-name = "ðŸŽŊ PRACTICE"
icon = "ENDER_PEARL"
slot = 32
description = [
    "",
    "  â–ļ Improve Your Skills",
    "  ðŸ‘Ĩ Training: %players%",
    ""
]
enabled = true

VIP Server with Permissions

Example with a VIP-only server:

TOML 
[servers.vip]
display-name = "👑 VIP SERVER"
icon = "BEACON"
slot = 13
description = [
    "",
    "  VIP EXCLUSIVE",
    "",
    "  Premium server for VIP members",
    "  ðŸ‘Ĩ VIPs Online: %players%",
    "",
    "  ⚠ïļ Requires VIP rank",
    ""
]
enabled = true

# Set up permission in LuckPerms:
# /lp group vip permission set velocitynexus.server.vip true

⚙ïļ All Settings Reference

Setting Type Description Example
menu.title String GUI title (supports colors) "&aServer Selector"
menu.rows Integer Number of rows (1-6) 3
servers.name String Server name (must match velocity.toml) "hub"
servers.displayName String Display name in GUI (supports colors) "&aHub Server"
servers.material String Minecraft material name "NETHER_STAR"
servers.slot Integer Inventory slot position (0-53) 13
servers.description Array Item lore lines (supports colors & placeholders) ["&7Hub", "&a%players%"]
servers.startColor RGB Object Gradient start color (r, g, b: 0-255) { r = 102, g = 126, b = 234 }
servers.endColor RGB Object Gradient end color (r, g, b: 0-255) { r = 240, g = 147, b = 251 }

🎉 Configuration Complete!

Ready to reload and test your changes?

Commands & Permissions Troubleshooting