UltimateLobby

** 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 | |---------|-------------| | Anti-WDL | Prevent block breaking and placing | | Anti-WDL | Disable fall damage completely | | Anti-WDL | Teleport players to spawn when falling into void | | Anti-WDL | Keep weather always clear | | Anti-WDL | Players never lose hunger | | Anti-WDL | Prevent hostile/all mob spawning | | Anti-WDL | Stop fire from spreading | | Anti-WDL | Prevent leaves from decaying | | Anti-WDL | Enable or disable player combat | | Anti-WDL | Control item interactions | | Anti-WDL | Prevent chest/door/container access | | Anti-WDL | Block TNT and creeper damage | | Anti-WDL | 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 - Language Menu - Connect to game servers - Language Menu - Fun cosmetic effects - Language Menu - Player statistics - Language Menu - Toggle preferences - Language Menu - Multi-language support

---

📊 Scoreboard System

Professional, flicker-free scoreboards with animations:

Features - Toggle Command - Uses team-based rendering - Toggle Command - Cycle through multiple titles - Toggle Command - Display any placeholder - Toggle Command - 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 - Prefix/Suffix Display - Multi-line support - Prefix/Suffix Display - Higher ranks appear first - Prefix/Suffix Display - Dynamic content - Prefix/Suffix Display - 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 | |---------|-------------| | Action Bar | Hidden from all players | | Action Bar | Removed from player list | | Action Bar | Fake leave/join messages | | Action Bar | Auto-enable flight when vanished | | Action Bar | See in the dark | | Action Bar | Mobs ignore you | | Action Bar | Don't pick up items | | Action Bar | 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 | |-------|------|-------------| | VIP Only | Lime Dye | See all players | | VIP Only | 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 | |--------|--------|----------| | Particle Effects | Launch colorful firework | 10s | | Particle Effects | Temporary high jump | 30s | | Particle Effects | Cloud of smoke particles | 15s | | Particle Effects | Colorful trail behind you | 60s | | Particle Effects | Explosion launch | 5s | | Particle Effects | Freeze in place with ice effect | 20s | | Particle Effects | 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 Permissions 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 Hub 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 - Java 21 (or compatible fork) - Java 21

Optional (Soft Dependencies) | Plugin | Purpose | |--------|---------| | ProtocolLib | Placeholder support in all text | | ProtocolLib | 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:

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

Resource Usage - Storage: ~5-15 MB depending on features enabled - Storage: 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! 🚀**