** UltimateLobby - Complete Plugin Documentation

📋 Plugin Overview

UltimateLobby is a powerful, all-in-one hub/lobby management plugin designed for PaperMC servers running Minecraft 1.21.1 - 1.21.4. This plugin replaces the need for 30+ separate plugins by combining all essential lobby features into a single, optimized, and fully configurable solution.

🎯 What is UltimateLobby?

UltimateLobby transforms your server's hub/lobby into a professional, feature-rich spawn area. Whether you're running a small community server or a large network with multiple game modes, UltimateLobby provides everything you need to create an engaging first impression for your players.

Why Choose UltimateLobby?

Problem	UltimateLobby Solution
Too many plugins causing conflicts	Single plugin handles everything
High resource usage from multiple plugins	Optimized, lightweight code
Inconsistent configurations	Unified YAML configuration system
No in-game editing capabilities	Full in-game GUI editor for items & menus
Difficult to customize	Every feature is toggleable and configurable
Complex setup process	Works out of the box with sensible defaults

✨ Complete Feature List

🛡️ World Protection System

Protect your lobby world from griefing and unwanted modifications with 30+ configurable protection rules:

Feature	Description
Block Protection	Prevent block breaking and placing
Fall Damage	Disable fall damage completely
Void Protection	Teleport players to spawn when falling into void
Weather Lock	Keep weather always clear
Hunger Disable	Players never lose hunger
Mob Spawning	Prevent hostile/all mob spawning
Fire Spread	Stop fire from spreading
Leaf Decay	Prevent leaves from decaying
PvP Toggle	Enable or disable player combat
Item Drop/Pickup	Control item interactions
Interaction Block	Prevent chest/door/container access
Explosion Protection	Block TNT and creeper damage
Crop Trampling	Protect farmland
Anti-WDL	Detect World Downloader mod users

Key Benefit: Each rule can be individually toggled, and players with bypass permissions can override protection.

🎮 Join Experience

Create memorable first impressions with customizable join actions:

Welcome Message (MOTD)

 Multi-line welcome message with placeholders
- "&6&l★ &eWelcome to &6&lYOUR SERVER&e! &6&l★"
- "&7Online: %server_online% | Rank: %vault_prefix%"

Title Display

Customizable title and subtitle
Configurable fade-in, stay, and fade-out timings
PlaceholderAPI support

Join Sound

Any Minecraft sound effect
Adjustable volume and pitch

Firework Effect

Customizable colors and effects
Multiple firework types (Ball, Star, Burst, etc.)
Trail and flicker options

First-Time Join

Special welcome message for new players
Automatic firework celebration
Execute commands on first join (give items, etc.)

🎒 Lobby Items System

Give players interactive hotbar items with the revolutionary In-Game Editor:

Default Items

Slot	Item	Function
0	Compass	Server Selector
1	Chest	Gadgets Menu
2	Player Head	Profile Menu
4	Dye	Player Hider Toggle
7	Comparator	Settings Menu
8	Book	Server Info

In-Game Item Editor

/ul setjoinitems

Arrange items in your inventory
Run the command
Items are automatically saved with materials, names, lore, and enchantments!

Supported Actions

[menu] server-selector     Open a custom menu
[server] survival          Connect to server (proxy)
[world] lifesteal          Connect to a world 
[command] fly              Player runs command
[console] give %player%    Console runs command
[message] &aHello!         Send message
[sound] UI_BUTTON_CLICK    Play sound
[player-hider]             Toggle visibility
[spawn]                    Teleport to spawn
[url] https://...          Send clickable link

📋 Custom Menu System

Create unlimited custom GUIs with the powerful In-Game Menu Editor:

Create Menus

/ul createmenu <name> <rows>
/ul createmenu shop 6

Edit Menus In-Game

/ul editmenu <name>

Opens the menu in edit mode
Drag and drop items freely
Close to auto-save!

Set Item Actions

/ul setaction <menu> <slot> <action>
/ul setaction shop 0 [server] survival

Menu Features

1-6 row support (9-54 slots)
PlaceholderAPI in names/lore
Open sounds
Permission requirements
Pagination support
Confirmation dialogs

Pre-Built Menus

Server Selector - Connect to game servers
Gadgets Menu - Fun cosmetic effects
Profile Menu - Player statistics
Settings Menu - Toggle preferences
Language Menu - Multi-language support

📊 Scoreboard System

Professional, flicker-free scoreboards with animations:

Features

Flicker-Free Updates - Uses team-based rendering
Animated Titles - Cycle through multiple titles
PlaceholderAPI Support - Display any placeholder
Per-Player Content - Unique data for each player
Toggle Command - Players can hide/show

Example Configuration

scoreboard:
  enabled: true
  update-interval: 20
  title: "&6&lYOUR SERVER"
  lines:
    - "&7&m                    "
    - "&fPlayer: &e%player_name%"
    - "&fRank: &e%vault_prefix%"
    - ""
    - "&fOnline: &a%server_online%"
    - "&7&m                    "

📑 Tablist System

Customizable player list with rank sorting:

Features

Custom Header/Footer - Multi-line support
Rank Sorting - Higher ranks appear first
PlaceholderAPI - Dynamic content
Animated Content - Rotating messages
Prefix/Suffix Display - From Vault

Rank Weight System

rank-weights:
  owner: 100       Appears first
  admin: 90
  moderator: 80
  vip: 50
  default: 10      Appears last

💬 Chat Management System

Complete chat control with moderation tools:

Chat Formatting

format: "%vault_prefix%&f%player_name%%vault_suffix%&7: &f%message%"

Anti-Swear Filter

Configurable word list
Leetspeak detection (a→@, e→3, etc.)
Custom replacement text
Staff notifications
Player warnings

Chat Lock

/ul chatlock [reason]

Instantly lock/unlock chat
Custom lock message
Bypass permission for staff

Slow Mode

/ul slowmode <seconds>

Set cooldown between messages
Bypass for VIP/Staff

Clear Chat

/ul clearchat

Clear chat for all players
Staff can see through clear

Command Blocker
Block commands like /pl, /plugins, /ver:

blocked-commands:
  - "/pl"
  - "/plugins"
  - "/version"
  - "/?"

👻 Vanish System

Full-featured staff vanish mode:

Features

Feature	Description
Complete Invisibility	Hidden from all players
Tablist Hiding	Removed from player list
Silent Join/Quit	Fake leave/join messages
Flight Enable	Auto-enable flight when vanished
Night Vision	See in the dark
No Mob Target	Mobs ignore you
No Pickup	Don't pick up items
No Damage	Invincible while vanished
Action Bar	Constant vanish reminder

Commands

/vanish            Toggle vanish
/vanish on         Enable vanish
/vanish off        Disable vanish
/vanish list       List vanished players
/vanish <player>   Toggle for another player

🏃 Movement System

Fun movement features for lobby:

Double Jump

Activate by pressing space while in air
Configurable power and height
Cooldown system
Particle effects
Custom sounds

Launchpads

Pressure plate + base block detection
Configurable launch power
Custom directions per launchpad
Particle effects on launch

Speed Boost Pads

Walk over special blocks for speed boost
Configurable duration and level

👁️ Player Hider System

Let players control visibility of other players:

Three Visibility States

State	Icon	Description
All Visible	Lime Dye	See all players
All Hidden	Gray Dye	See no players
VIP Only	Yellow Dye	See only VIP players

Features

Cycles through states on click
Remembers preference (optional)
Hotbar item updates dynamically
Particle indicators (optional)

🌐 Proxy/Network Support

Connect your lobby to your network:

BungeeCord/Velocity Support

Send players to other servers
Retrieve server player counts
Server status detection

Server Groups (Load Balancing)

server-groups:
  survival:
    - "survival-1"
    - "survival-2"
   Automatically sends to least populated server

Queue System

Join queue for full servers
Position notifications
Auto-connect when space available

🎪 Gadgets System

Fun cosmetic gadgets for players:

Gadget	Effect	Cooldown
Firework	Launch colorful firework	10s
Jump Boost	Temporary high jump	30s
Smoke Bomb	Cloud of smoke particles	15s
Rainbow Trail	Colorful trail behind you	60s
TNT Jump	Explosion launch	5s
Freeze Ray	Freeze in place with ice effect	20s
Speed Boost	Temporary speed increase	30s
Particle Effects	Various particle auras	40s

Features

Per-gadget cooldowns
Permission-based access
VIP-exclusive gadgets
Visual cooldown indicators

📍 Hologram System

Create floating text displays:

Commands

/ul hologram create <id> <text>
/ul hologram delete <id>
/ul hologram list
/ul hologram addline <id> <text>
/ul hologram setline <id> <line> <text>
/ul hologram tp <id>

Features

Multi-line support
PlaceholderAPI support
Auto-updating content
Persistent storage
Text Display entities (1.19.4+)

Here are the Commands Reference and Permissions Reference sections updated to match your provided plugin.yml.

🔧 Commands Reference

🛠️ Lobby Setup & Admin Commands

Command	Aliases	Description	Permission
`/ultimatelobby`	`/ul`, `/lobbymanager`	Main admin command for sub-features (menus, holograms, reloading).	`ultimatelobby.admin`
`/setlobby`	`/setuplobby`, `/createlobby`	Set the Lobby spawn point and adds world to lobby list.	`ultimatelobby.setlobby`
`/sethub`	`/setuphub`, `/createhub`	Set the Hub spawn point and adds world to lobby list.	`ultimatelobby.setlobby`
`/addlobbyworld`	`/addlobby`	Manually add a world to the lobby worlds list.	`ultimatelobby.admin`
`/removelobbyworld`	`/dellobbyworld`	Remove a world from the lobby worlds list.	`ultimatelobby.admin`
`/listlobbyworlds`	`/lobbyworlds`	List all configured lobby worlds.	`ultimatelobby.admin`

🖥️ Sub-Commands (via /ul)
These function as arguments under the main /ul command.

Sub-Command	Description	Permission
`reload`	Reload all configurations.	`ultimatelobby.reload`
`setjoinitems`	Save current inventory as default join items.	`ultimatelobby.setjoinitems`
`createmenu <name>`	Create a new GUI menu.	`ultimatelobby.menu.admin`
`editmenu <name>`	Open the in-game menu editor.	`ultimatelobby.menu.admin`
`hologram <...>`	Manage holograms (create/delete/edit).	`ultimatelobby.hologram.admin`
`chatlock`	Toggle global chat lock.	`ultimatelobby.chat.admin`
`clearchat`	Clear global chat history.	`ultimatelobby.chat.admin`
`slowmode <sec>`	Set chat cooldown.	`ultimatelobby.chat.admin`

👤 Player Commands

Command	Aliases	Description	Permission
`/fly`	-	Toggle flight mode.	`ultimatelobby.fly`
`/gm <mode>`	`/gamemode`	Change game mode (Survival, Creative, etc.).	`ultimatelobby.gamemode`
`/vanish`	`/v`, `/invisible`	Toggle staff vanish mode.	`ultimatelobby.vanish`
`/spawn`	-	Teleport to the spawn point.	`ultimatelobby.spawn`
`/lobby`	`/hub`, `/l`, `/leave`	Teleport to lobby/hub spawn.	`ultimatelobby.spawn`
`/openmenu`	`/menu`, `/gui`	Open a specific custom menu by name.	`ultimatelobby.menu`

🔐 Permissions Reference

👑 Admin Permissions

Permission	Description
`ultimatelobby.admin`	Wildcard: Full access to all plugin features.
`ultimatelobby.reload`	Allow reloading configuration.
`ultimatelobby.setspawn`	Allow setting spawn points.
`ultimatelobby.setlobby`	Allow using setup commands (`/setlobby`, `/sethub`).
`ultimatelobby.setjoinitems`	Allow saving join items inventory.
`ultimatelobby.protection.bypass`	Bypass all world protection (break/place/interact).
`ultimatelobby.staff.notify`	Receive alerts (anti-swear, updates, warnings).
`ultimatelobby.hologram.admin`	Create and manage holograms.

🎮 Gamemode Permissions

Permission	Description
`ultimatelobby.gamemode`	Base permission for `/gm`.
`ultimatelobby.gamemode.survival`	Allow switching to Survival.
`ultimatelobby.gamemode.creative`	Allow switching to Creative.
`ultimatelobby.gamemode.adventure`	Allow switching to Adventure.
`ultimatelobby.gamemode.spectator`	Allow switching to Spectator.
`ultimatelobby.gamemode.others`	Change other players' gamemodes.

👻 Vanish Permissions

Permission	Description
`ultimatelobby.vanish`	Toggle vanish for self.
`ultimatelobby.vanish.others`	Toggle vanish for others.
`ultimatelobby.vanish.see`	See other vanished players.
`ultimatelobby.vanish.list`	List vanished players via command.
`ultimatelobby.vanish.auto`	Automatically join the server vanished.

💬 Chat Management Permissions

Permission	Description
`ultimatelobby.chat.admin`	Use lock, clear, and slowmode commands.
`ultimatelobby.chat.color`	Use color codes in chat messages.
`ultimatelobby.chat.bypass`	Wildcard: Bypass all chat restrictions.
`ultimatelobby.chat.bypass.lock`	Chat while global chat is locked.
`ultimatelobby.chat.bypass.cooldown`	Ignore slowmode cooldowns.
`ultimatelobby.chat.bypass.swear`	Ignore anti-swear filter.
`ultimatelobby.chat.bypass.spam`	Ignore anti-spam filter.
`ultimatelobby.chat.bypass.clear`	See chat history after it is cleared.
`ultimatelobby.command-blocker.bypass`	Use blocked commands (e.g., `/pl`).

📋 Menu Permissions

Permission	Description
`ultimatelobby.menu.admin`	Create, edit, and delete menus.
`ultimatelobby.menu.*`	Access to open ALL custom menus.
`ultimatelobby.menu.server-selector`	Access to Server Selector.
`ultimatelobby.menu.gadgets`	Access to Gadgets Menu.
`ultimatelobby.menu.settings`	Access to Settings Menu.
`ultimatelobby.menu.profile`	Access to Profile Menu.
`ultimatelobby.openmenu.others`	Force open menus for other players.

🎪 Gadget & Feature Permissions

Permission	Description
`ultimatelobby.fly`	Use flight command.
`ultimatelobby.fly.others`	Toggle flight for others.
`ultimatelobby.spawn.bypass-delay`	Teleport immediately without warmup.
`ultimatelobby.doublejump`	Use double jump in lobby worlds.
`ultimatelobby.vip`	VIP status (used for "VIP Only" player visibility).
`ultimatelobby.gadget.*`	Access to all cosmetic gadgets.
`ultimatelobby.gadget.firework`	Use Firework gadget.
`ultimatelobby.gadget.jumpboost`	Use Jump Boost gadget.
`ultimatelobby.gadget.smokebomb`	Use Smoke Bomb gadget.
`ultimatelobby.gadget.rainbowtrail`	Use Rainbow Trail gadget.
`ultimatelobby.gadget.tntjump`	Use TNT Jump gadget.

📊 PlaceholderAPI Placeholders

UltimateLobby registers 30+ custom placeholders:

Vanish Placeholders

Placeholder	Returns
`%ultimatelobby_vanished%`	true/false
`%ultimatelobby_vanished_status%`	&cVanished / &aVisible
`%ultimatelobby_vanished_count%`	Number of vanished players
`%ultimatelobby_real_online%`	Online count excluding vanished

Player Hider Placeholders

Placeholder	Returns
`%ultimatelobby_hider_state%`	all/none/vip
`%ultimatelobby_hider_status%`	Formatted status text
`%ultimatelobby_visible_players%`	Count of visible players
`%ultimatelobby_hidden_players%`	Count of hidden players

Chat Placeholders

Placeholder	Returns
`%ultimatelobby_chat_locked%`	true/false
`%ultimatelobby_chat_status%`	&cLocked / &aOpen
`%ultimatelobby_slowmode%`	Slowmode seconds

Server Placeholders

Placeholder	Returns
`%ultimatelobby_in_lobby%`	true/false
`%ultimatelobby_network_online%`	Total network players
`%ultimatelobby_server_<name>_online%`	Server player count
`%ultimatelobby_server_<name>_status%`	Online/Offline/Full

Queue Placeholders

Placeholder	Returns
`%ultimatelobby_queue_position%`	Queue position or N/A
`%ultimatelobby_queue_server%`	Queued server or None

Player Placeholders

Placeholder	Returns
`%ultimatelobby_flying%`	true/false
`%ultimatelobby_fly_status%`	&aFlying / &7Walking
`%ultimatelobby_gamemode%`	survival/creative/etc
`%ultimatelobby_scoreboard_visible%`	true/false

📦 Dependencies

Required

PaperMC 1.21.1 - 1.21.11 (or compatible fork)
Java 21

Optional (Soft Dependencies)

Plugin	Purpose
PlaceholderAPI	Placeholder support in all text
Vault	Economy, permissions, chat prefixes
ProtocolLib	Tab-complete blocking, packet features

📁 Configuration Files

File	Purpose
`config.yml`	Main plugin configuration (850+ lines)
`messages.yml`	All customizable messages
`menus.yml`	Custom menu definitions
`items.yml`	Lobby item configurations
`scoreboards.yml`	Scoreboard templates (optional)

🚀 Installation Guide

Step 1: Download
Download UltimateLobby-1.0.0.jar from the releases page.

Step 2: Install
Place the JAR file in your server's plugins folder.

Step 3: Start Server
Start or restart your server. Default configuration files will be generated.

Step 4: Configure

Edit config.yml to set your lobby worlds
Use /ul setspawn to set spawn location
Arrange items and use /ul setjoinitems
Create menus with /ul createmenu

Step 5: Permissions
Set up permissions using your permission plugin (LuckPerms recommended).

🔌 Developer API

Other plugins can hook into UltimateLobby:

// Check if API is available
if (UltimateLobbyAPI.isInitialized()) {
    
    // Vanish API
    boolean vanished = UltimateLobbyAPI.isVanished(player);
    UltimateLobbyAPI.vanish(player);
    UltimateLobbyAPI.unvanish(player);
    
    // Menu API
    UltimateLobbyAPI.openMenu(player, "server-selector");
    UltimateLobbyAPI.createMenu("custom", 3);
    
    // Proxy API
    UltimateLobbyAPI.sendToServer(player, "survival");
    UltimateLobbyAPI.addToQueue(player, "pvp");
    
    // Chat API
    UltimateLobbyAPI.lockChat("Maintenance");
    UltimateLobbyAPI.clearChat();
    
    // Scoreboard API
    UltimateLobbyAPI.createScoreboard(player);
    UltimateLobbyAPI.removeScoreboard(player);
}

Maven Dependency

<dependency>
    <groupId>com.ultimatelobby</groupId>
    <artifactId>UltimateLobby</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

❓ Frequently Asked Questions

Q: Does this work with Spigot?
A: UltimateLobby is designed for PaperMC and uses Paper-specific APIs. Spigot is not supported.

Q: Can I use this on a single-server setup?
A: Yes! Simply disable the proxy features in config.yml. All lobby features work standalone.

Q: How do I create custom menus?
A: Use /ul createmenu <name> <rows> then /ul editmenu <name> to open the in-game editor. Place items and close to save!

Q: Why aren't placeholders working?
A: Make sure PlaceholderAPI is installed. UltimateLobby soft-depends on it for placeholder support.

Q: How do I set up launchpads?
A: Place a pressure plate on top of a redstone block. Players stepping on it will be launched!

Q: Can players bypass protection?
A: Yes, give them ultimatelobby.protection.bypass or switch to Creative mode.

Q: How do I disable a specific feature?
A: Every feature has an enabled: true/false toggle in config.yml. Set it to false to disable.

Q: Does vanish persist after rejoin?
A: By default no, but you can enable vanish.persist-on-rejoin: true in config.yml.

Q: How do I add more blocked words?
A: Edit the chat.anti-swear.words list in config.yml and run /ul reload.

Q: Can I have different items for different ranks?
A: Yes! Enable rank-items in items.yml and configure per-rank item overrides.

📈 Performance

UltimateLobby is optimized for performance:

Async Operations - Scoreboards and tablists update asynchronously
Caching - Configuration values and server info are cached
Conditional Loading - Disabled features don't load at all
Efficient Events - Early returns for non-lobby worlds
Minimal Memory - Clean data structures

Resource Usage

Memory: ~5-15 MB depending on features enabled
CPU: Minimal impact, mostly event-driven
Storage: ~100 KB for configuration files

🛠️ Troubleshooting

Plugin Not Loading

Check console for errors
Verify Java 21 is installed
Ensure PaperMC 1.21.1+

Items Not Given

Check items.enabled: true
Verify world is in lobby-worlds list
Check player has no conflicting plugins

Menus Not Opening

Verify menu exists: /ul listmenus
Check permission: ultimatelobby.menu.<name>
Look for errors in console

Scoreboard Not Showing

Enable: scoreboard.enabled: true
Check world is in lobby worlds
Verify no conflicting scoreboard plugins

Thank you for choosing UltimateLobby! 🚀**

UltimateLobby

📖About UltimateLobby