# QWorlds > **Paper / Purpur 1.21.11** · **Java 21** · **Native Dialog UI (`io.papermc.paper.dialog`)** > Virtualized Void Lobby Grid, Matchmaking Queues, and Live Scripted Event Orchestration. **QWorlds** is a production-ready lobby management, matchmaking queue, and scripted event control plugin built for competitive tournaments, content creator SMPs, and large-scale recording sessions. It eliminates multi-proxy lobby overhead by consolidating personal player hubs into a single virtualized void grid world (`qwlobby_hub`), while equipping operators with a complete suite of live event orchestration tools. > [!IMPORTANT] > **What's New in Version 3.0:** > QWorlds 3.0 introduces **Mojang's Native Dialog UI**, **Per-Player `@box` Selection Wands** with client-sided particle outlines, a **Freeze Wand**, a **Percentage Team Splitter (`/qw split`)**, **Operator Warps**, **World Chat & Whisper (`/msg`) Muting**, **Proximity Chat**, **Fractional Target Selectors (`@team[50%]`, `@box[1/2]`)**, and a 4th Ancient Lobby Relic (**`FlightCharge`**). --- ## 🔗 QTeams & QKits Ecosystem Integration QWorlds 3.0 forms the core of the **QWorlds + QTeams + QKits** event stack: | Feature | Ecosystem Behavior | | :--- | :--- | | **Cross-Plugin Dialog Bar** | Jump directly between `/qw`, `/qt`, and `/qk` from the Native Dialog top navigation bar. | | **Automated Queue Squads** | Configure open world queues (`/qw open [limit] [@team]`) to automatically assign admitted players to a target **QTeams** squad upon arrival. | | **Percentage Team Splitter** | Split players from `@box`, `lobby`, `@a`, or an existing `@team` into multiple **QTeams** by exact percentages/weights (e.g., `royal:50 corrupt:30 chicken:20`) and optionally warp each player to their team's spawn. | | **Universal & Fractional Selectors** | Use `@box`, `@`, and fractional modifiers (`@box[50%]`, `@red[1/2]`, `@a[25%]`, `@box[r]`) across `/tp`, `/give`, `/effect`, `/gamemode`, `/qk give`, and `/qw`. | --- ## ⚙️ Server Architecture & Core Mechanics ### 1. Native Paper 1.21.11 Dialog UI & 6-Tab Controller - **Zero-Chest Native Dialogs:** Built on Paper 1.21.11's `DialogType.multiAction` API with custom small-caps typography, compact `280px` layouts, `12x12` icons, interactive checkboxes (`☑` / `☐`), and text inputs. - **6-Tab Top Navigation Bar:** Instant 1-click switching across all administrative modules: * `🌍 Worlds` — Manage recording worlds, queue quotas, auto-teams, and per-world death modes. * `⚡ Warps & Split` — Manage Operator Warps, `@box` wands, and the Percentage Team Splitter. * `❄ Freeze & Chat` — Control the Freeze Wand, World Chat/Whisper Muting, Team Isolation, and Proximity Chat. * `🏹 Relics` — Configure and distribute the 4 Lobby Relics and pedestals. * `🏗 Pool` — Monitor and pre-generate virtualized void lobby slots. * `👥 Players` — Inspect online players, teleport to personal lobby slots, or manage Lobby Bans. ### 2. Event Control Suite: Per-Player `@box` Wand, Team Splitter & Warps - **Per-Player `@box` Area Selector Wand (`/qw boxwand`):** Gives operators an enchanted Breeze Rod where **Left-Click Block** sets `Pos 1` and **Right-Click Block** sets `Pos 2`. Every operator has an independent `@box` selection rendered with **client-sided cyan dust particle outlines** (and **gold dust outlines** for the Lobby Template Wand) visible only to that operator. - **Universal & Fractional Selector Engine:** Hooks into Paper's `AsyncPlayerSendCommandsEvent` and `AsyncPlayerSendSuggestionsEvent` so `/tp`, `/give`, `/effect`, `/clear`, `/gamemode`, and `/qk` suggest **online player names alongside `@a`, `@p`, `@r`, `@s`, `@box`, `@`, and warps** in one unified list—and continue prompting subsequent arguments after `@box` or `@team`. - **Percentage Team Splitter (`/qw split`):** Randomly shuffles a source group (`@box`, `lobby`, `@a`, or `@`) and distributes players across target teams using largest-remainder math so 100% of players are assigned cleanly. Automatically creates missing teams in **QTeams** and teleports each player to their team's matching warp if configured. - **Operator Warps (`/qw setwarp`, `/qw warp`, `/qw delwarp`):** Save named event warps and teleport yourself, a single player, `@box`, or any `@team` (including fractional selectors) via the GUI, `/qw warp [target]`, or `/tp `. ### 3. Player Freeze Engine, Freeze Wand & World Chat/Whisper Filters - **Freeze Wand (`/qw freezewand`) & `/qw freeze`:** Gives operators a custom Blue Ice wand. **Hit or Right-Click** a player to toggle their freeze state, or **Shift + Right-Click Air** to freeze everyone inside your `@box`. Frozen players have movement, jumping, combat, block breaking/placing, item dropping, inventory clicks, and commands locked while seeing a live `❄ YOU ARE FROZEN BY AN OPERATOR ❄` actionbar alert. - **World Chat Mute & Whisper (`/msg`) Blocking:** Mute text chat per world in the `❄ Freeze & Chat` tab. When a world's chat or messages are muted (or while a player is in the Void Lobby), private whispers (`/msg`, `/tell`, `/w`, `/whisper`, `/r`, `/reply`, `/teammsg`) are automatically blocked for non-OP players. - **Team-Only Isolation, Allowed Chat Teams & Proximity Chat:** Restrict global chat so only specific `@teams` can speak, isolate chat so players only hear teammates, or enable **Proximity Chat** (`15m`, `30m`, `50m`, `100m` radius) with toggleable **OP Chat Spy**. ### 4. Virtualized Void Grid (`qwlobby_hub`) & Collision-Safe Void Rescue - **Grid Chunk Allocation:** Partitions `qwlobby_hub` into a 10-column grid with 256-block offsets at `Y=64`, enforcing isolated 5-chunk view and simulation distances so players in personal lobbies cannot see each other on the tablist, hear each other's chat, or load outside entities. - **Staggered Pre-Gen Pooling (`/qw pregen`):** Pre-generates and caches lobby slots asynchronously with chunk tickets and a live OP progress bar. - **Cubic Bezier Void Rescue Arc:** Falling past `Y=44` launches a smooth cubic Bezier flight curve that sweeps horizontally past the template's bounding box and climbs 26 blocks above the highest roof block before landing at the slot's spawn point. ### 5. Four Ancient Lobby Relics (`relics.yml`) & Bat Minigame | Relic ID | Default Name | Mechanics & Highlights | | :--- | :--- | :--- | | `bow` | **Bow of ParrotX2** | Infinite explosive lobby bow with zero block/entity damage, bat minigame hit registration, and an anti-dupe locked quiver charge in slot 17. | | `trident` | **Treasure Trident** | Loyalty V trident with instant void-recall checks, chunk ticketing during long throws, and cosmetic lightning strikes on impact. | | `cannon` | **Orbital Strike Cannon** | Custom fishing rod (3s cooldown) that calls down 3 concentric rings of falling primed TNT (`6`, `10`, and `14` entities + center strike) with zero block damage. | | `flightcharge` | **FlightCharge** *(New)* | Infinite Wind Charge relic. Looking straight down (`pitch >= 70°`) while mid-air and right-clicking triggers a **Mid-Air Chain Boost** with gust particles and wind burst audio. | - **Artifact Completion Cinematic:** Collecting both the Trident and Cannon triggers a slot-wide perimeter lightning sequence, goat horn audio cue, and toast banner. - **Line-of-Sight Bat Minigame:** Spawns 6 raytraced bats per active lobby slot clamped below eye level (`Y+0.2` to `Y+1.55`). Reaching a 10-hit combo streak sequentially detonates all bats in the slot. ### 6. Directional Info Holograms (`info_signs.yml`) & Custom NPCs (`custom_npcs.yml`) - **Sign-Free Holograms & Web Links:** Physical signs placed inside the lobby template act as coordinate and rotation anchors. When a lobby slot is pasted, the physical sign blocks are cleared (`Material.AIR`) and replaced with yaw-aligned `TextDisplay` holograms (`Billboard.FIXED`) paired with invisible `Interaction` hitboxes. Looking at a hologram reveals its text, and right-clicking it sends a clickable `open_url` link in chat. - **Reflection-Based FancyNpcs Integration:** Spawns queue NPCs (`/qw spawnnpc`) and custom profile NPCs (`/qw spawnplayer`) via reflection with zero hard compile dependencies. ### 7. 5-Mode Player Death Routing & Automatic Team Stripping Configure globally or per recording world how player deaths are handled during events: | Mode ID | GUI Label | Behavior on Player Death | | :--- | :--- | :--- | | `NOTHING` | **Do Nothing** | Player respawns normally inside the recording world and keeps their team. | | `LOBBY` | **Send to Lobby** | Strips the player's QTeams squad, revokes world admission, and sends them to their personal void lobby. | | `LOBBY_WITH_LEAVE` | **Lobby + Leave Msg** | Broadcasts a 100% yellow ` left the game` message to the world, strips their team, and sends them to their lobby. | | `KICK` | **Kick from Server** | Strips the player's team and kicks the eliminated player from the server. | | `BAN` | **Lobby-Ban on Death** | Strips the player's team, applies a permanent Lobby Ban, and locks them inside their personal void lobby. | --- ## 💻 Command & Permission Reference ### Player Commands | Command | Description | | :--- | :--- | | `/qw lobby` | Returns the player to their assigned personal void lobby slot. | | `/qw join ` | Enters the matchmaking queue for an open recording world. | | `/qw leave` | Leaves the current world queue. | ### Operator Commands (`OP`) | Command | Description | | :--- | :--- | | `/qw [gui]` | Opens the Native QWorlds Dialog Control Panel. | | `/qw boxwand` | Gives the operator their personal `Pos 1` / `Pos 2` `@box` Selection Wand. | | `/qw freezewand` | Gives the operator the `Freeze Wand` (Click player or `Shift+Click` for `@box`). | | `/qw freeze ` | Freezes or unfreezes target players, `@teams`, or `@box`. | | `/qw setwarp ` | Saves an Operator Warp at your current location and orientation. | | `/qw warp [target]` | Warps yourself or a target (`player`, `@team`, `@box`, `@a[50%]`) to a warp. | | `/qw delwarp ` | Deletes a saved Operator Warp. | | `/qw split ... [warp]` | Splits `@box`, `lobby`, `@a`, or `@team` into QTeams by percentage. | | `/qw chat` | Opens the Freeze, World Chat Mute, Team Isolation & Proximity Chat Dialog. | | `/qw open [limit] [@team]` | Opens a world queue with optional player quota and auto-team assignment. | | `/qw recording ` | Locks a world into Recording Mode, preventing new queue joins. | | `/qw close ` | Closes the world session, strips non-OP teams, and evacuates players to lobbies. | | `/qw tp [target]` | Teleports yourself or a target group into a recording world. | | `/qw addworld [env]` | Creates or imports a target world (`normal`, `nether`, `the_end`). | | `/qw setspawn ` | Sets the arrival spawn coordinates for the world you are standing in. | | `/qw wand` / `/qw savetemplate` | Gives the Lobby Template Wand or saves the selected lobby structure. | | `/qw setlobby` | Updates the template spawn offset relative to your lobby or wand box. | | `/qw setpedestal ` | Converts the targeted Item Frame into an interactive Relic Pedestal. | | `/qw ` | Toggles a Lobby Relic in your own inventory. | | `/qw giverelic ` | Forces a relic into the inventory of a player, `all`, or `@box`. | | `/qw removerelic ` | Revokes a relic unlock and removes the item from the target. | | `/qw spawnnpc [skin]` | Spawns a queue NPC linked to a recording world. | | `/qw setskin ` | Updates the skin username for a world's queue NPC. | | `/qw spawnplayer ` / `/qw removenpc` | Spawns a custom NPC from `custom_npcs.yml` or removes nearby NPCs. | | `/qw pregen [amount]` | Pre-generates additional personal lobby slots in `qwlobby_hub`. | | `/qw lobbylist` / `/qw lobbytp ` | Opens the Player Directory Dialog or teleports into a player's lobby slot. | | `/qw sendlobby ` | Forces a player or group back to their personal void lobby. | | `/qw lobbyban ` | Locks a player in their personal lobby (`10m`, `2h`, `1d`, `perm`). | | `/qw unlobbyban ` | Lifts an active Lobby Ban from a player. | | `/qw reload` | Reloads all YAML configs, relic names, warps, holograms, and pooled slots. | --- ## 📁 Configuration Files (`plugins/QWorlds/`) ### 1. `config.yml` Stores main engine settings, global and per-world 5-mode death routing, pre-generation pool sizes, cached lobby template data (blocks, signs, item frames, pedestals, and NPC offsets), Operator Warps, per-player `@box` selections, world chat/proximity chat rules, player relic unlocks, and active lobby bans. ```yaml global_death_mode: "LOBBY" pool: target_size: 10 built_slots: 10 chat: muted_worlds: - "event_arena" allowed_teams: [] team_only_isolation: false proximity_enabled: false proximity_radius: 30.0 op_spy: true warps: arena_red: world: "world" x: 120.5 y: 72.0 z: -45.5 yaw: 90.0 pitch: 0.0 worlds: world: state: "CLOSED" open_limit: -1 auto_team: "NONE" death_mode: "LOBBY_WITH_LEAVE" npc_skin: "Notch" ``` ### 2. `relics.yml` Customizes the display names, hex color gradients (`gradient_start` and `gradient_end`), and locked quiver arrow titles for all four ancient lobby relics. Changes apply live via `/qw reload`. ```yaml relics: bow: name: "Bow of ParrotX2" gradient_start: "#FBBF24" gradient_end: "#EF4444" quiver_name: "ParrotX2 Quiver Charge (Locked)" trident: name: "Treasure" gradient_start: "#FFFFFF" gradient_end: "#38BDF8" cannon: name: "Orbital Strike Cannon" gradient_start: "#F43F5E" gradient_end: "#FBBF24" flightcharge: name: "FlightCharge" gradient_start: "#38BDF8" gradient_end: "#E0F2FE" ``` ### 3. `info_signs.yml` Controls floating directional `TextDisplay` holograms, MiniMessage text formatting, and clickable web links (`open_url`). Link a sign inside your lobby template by **Shift + Right-Clicking** it with the Lobby Template Wand (`/qw wand`) and typing the sign ID (e.g., `welcome`). ```yaml signs: welcome: link: "[https://example.com](https://example.com)" lines: - "SERVER NETWORK" - "Scripted Events and Tournaments" - "" - "Click to open our Website" ``` ### 4. `custom_npcs.yml` Declares custom player NPC profiles with MiniMessage nametags and skin usernames that operators can spawn anywhere using `/qw spawnplayer `. ```yaml npcs: host: name: "Event Host" skin: "Steve" moderator: name: "Staff Coordinator" skin: "MHF_Question" ``` --- ## 📦 Server Requirements & Soft Dependencies | Requirement / Dependency | Version / Status | Purpose | | :--- | :--- | :--- | | **Paper / Purpur** | `1.21.11` *(Required)* | Provides the Native Dialog API and modern entity/chunk APIs. | | **Java Runtime** | `Java 21` *(Required)* | Required for compiling and running Paper 1.21.11 plugins. | | **QTeams** | `2.0.0+` *(Recommended)* | Enables live `@team` selectors, percentage team splitting, and cross-plugin navigation. | | **QKits** | `1.0.0+` *(Recommended)* | Enables `@box` and `@team` kit distribution and Void Lobby claim protection. | | **FancyNpcs** | *Optional* | Renders custom player-model NPCs and skins via reflection. | | **Multiverse-Core** | *VERY IMPORTANT* | Supports external world imports and custom environment flags. |

QWorlds - Scripted Utils

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details

GUI