** 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