QWorlds - Scripted Utils

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 <world> [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, @<team>, 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, @<team>, 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 @<team>) 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 <name> [target], or /tp <target> <warp>.

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 <Player> 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 <world>	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 <target|all|clear|wand>	Freezes or unfreezes target players, @teams, or @box.
/qw setwarp <name>	Saves an Operator Warp at your current location and orientation.
/qw warp <name> [target]	Warps yourself or a target (player, @team, @box, @a[50%]) to a warp.
/qw delwarp <name>	Deletes a saved Operator Warp.
/qw split <source> <team:%>... [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 <world> [limit] [@team]	Opens a world queue with optional player quota and auto-team assignment.
/qw recording <world>	Locks a world into Recording Mode, preventing new queue joins.
/qw close <world>	Closes the world session, strips non-OP teams, and evacuates players to lobbies.
/qw tp <world> [target]	Teleports yourself or a target group into a recording world.
/qw addworld <name> [env]	Creates or imports a target world (normal, nether, the_end).
/qw setspawn <world>	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 <bow|trident|cannon|flightcharge>	Converts the targeted Item Frame into an interactive Relic Pedestal.
/qw <bow|trident|cannon|flightcharge>	Toggles a Lobby Relic in your own inventory.
/qw giverelic <relic> <target>	Forces a relic into the inventory of a player, all, or @box.
/qw removerelic <relic> <target>	Revokes a relic unlock and removes the item from the target.
/qw spawnnpc <world> [skin]	Spawns a queue NPC linked to a recording world.
/qw setskin <world> <skin>	Updates the skin username for a world's queue NPC.
/qw spawnplayer <id> / /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 <player>	Opens the Player Directory Dialog or teleports into a player's lobby slot.
/qw sendlobby <player|@team|@box>	Forces a player or group back to their personal void lobby.
/qw lobbyban <player> <duration|perm>	Locks a player in their personal lobby (10m, 2h, 1d, perm).
/qw unlobbyban <player>	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.

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.

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).

signs:
  welcome:
    link: "[https://example.com](https://example.com)"
    lines:
      - "<gradient:#EF4444:#F59E0B><bold>SERVER NETWORK</bold></gradient>"
      - "<gray>Scripted Events and Tournaments</gray>"
      - ""
      - "<yellow>Click to open our Website</yellow>"

4. custom_npcs.yml

Declares custom player NPC profiles with MiniMessage nametags and skin usernames that operators can spawn anywhere using /qw spawnplayer <id>.

npcs:
  host:
    name: "<gradient:#FDE047:#F59E0B><bold>Event Host</bold></gradient>"
    skin: "Steve"
  moderator:
    name: "<gradient:#38BDF8:#7DD3FC><bold>Staff Coordinator</bold></gradient>"
    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.