** 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)
```yaml
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
```
1. Arrange items in your inventory
2. Run the command
3. Items are automatically saved with materials, names, lore, and enchantments!
Supported Actions
```yaml
[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>
```
1. Opens the menu in edit mode
2. Drag and drop items freely
3. 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
```yaml
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
```yaml
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
```yaml
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`:
```yaml
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)
```yaml
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
1. Edit `config.yml` to set your lobby worlds
2. Use `/ul setspawn` to set spawn location
3. Arrange items and use `/ul setjoinitems`
4. 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:
```java
// 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
```xml
<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! 🚀
Need a server to run UltimateLobby?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting
