QTeams

QTeams is a production-ready Paper/Purpur 1.21.11 team management, combat routing, and packet-level visual filtering plugin built for competitive tournaments, content creator SMPs, and large-scale scripted events. In Version 2.0, QTeams replaces legacy chest menus and ProtocolLib hooks with Mojang's Native Dialog UI (io.papermc.paper.dialog) and a Netty-level PacketEvents 2.7+ engine, delivering zero-lag block masking, real-time per-team tablist count buffers, 6-channel display/color spoofing, a 3-mode combat matrix, a Lobby Kick/Ban Stick, and customizable death sounds.

---

QWorlds & QKits Ecosystem Integration

QTeams 2.0 natively bridges with QWorlds (virtualized void lobbies & event control) and QKits (lossless kit distribution):

• Cross-Plugin Navigation Bar: Jump directly between /qt, /qw, and /qk from the Native Dialog top bar.
• Lobby Team Admission: Admit individual @teams or all teamed players waiting in the QWorlds Void Lobby directly into the active recording world via /qt admit <@team|all>.
• Unified @team & @box Target Selectors: Use @<team>, @box (per-player Pos1/Pos2 selection wand), and fractional selectors (@red[50%], @box[1/2]) across /tp, /give, /effect, /gamemode, /qk give, and /qw.

---

Server Architecture & Core Mechanics

1. Native Dialog UI & Small-Caps Typography (New in 2.0)

• Zero-Chest Native Dialogs: Built on Paper 1.21.11's DialogType.multiAction interface with custom small-caps typography (sc(...)), compact 280px layouts, 12x12 icons, interactive checkboxes (☑/☐), text inputs, and number sliders.
• 6-Tab Top Navigation Bar: Instant 1-click switching between ★ Teams, ⚔ PvP & God, 👁 PlayerView, 🌍 Worlds & Messages, 🔊 Death Sound, and ⚡ Kick/Ban Stick.
• Live Team Duplication & Renaming: Duplicate any team's full configuration (/qt duplicate <@team>, auto-incrementing @red -> @red1) or rename teams live (/qt rename <@team> <new_name>) with automatic ally, rival, and scoreboard migration.

2. PacketEvents Tablist Buffers & Stealth Glow/Color Spoofing (Updated in 2.0)

• Per-Team Online Tablist Buffers: Injects real-time PacketEvents PLAYER_INFO_UPDATE header rows (00_qb_<team>) sorted immediately above each team's roster (%03d_%s_0 above %03d_%s_1), displaying ✦ @TeamName (X online) based strictly on that specific team's online player count.
• Viewer-Specific Glow Filtering: Intercepts ENTITY_METADATA packets on the Netty thread to dynamically toggle the 0x40 glowing flag per viewer (No One, Everyone, Teammates, Allies, Server OPs, or specific @teams).
• 6-Channel Display Matrix & Stealth Overhead Color: Independently toggle [Team] prefixes and team colors across 6 channels: Nametag, Tablist, Chat, Killfeed, Join/Leave, and Commands (plus Color Chat Text and Nametag Visibility). Enabling Stealth Overhead Color spoofs TEAMS packets so only permitted glow viewers see a team's overhead color/tag while rivals see plain white names.

3. Netty Zero-Lag No-Leak Filter (Updated in 2.0)

• Packet-Level Chunk & Block Masking: Intercepts outgoing CHUNK_DATA, BLOCK_CHANGE, and MULTI_BLOCK_CHANGE packets in PacketEvents to mask solid underground/base blocks as plain stone while preserving stair/slab/button/pressure-plate block states.
• Functional Block Exclusions: Automatically preserves ores, chests, shulker boxes, barrels, furnaces, anvils, crafters, beds, doors, glass, leaves, ladders, water/lava, and workstations.
• Staggered Radius Refresh & Mining Exposure: Toggling No-Leak refreshes loaded chunks smoothly without main-thread spikes, and breaking blocks immediately masks newly exposed adjacent faces.

4. 3-Mode Combat Matrix, PvP Exemptions & Immortality (Updated in 2.0)

• 3-Mode Relationship Matrix: Configure combat rules independently for Teammates, Allied Teams, and Specific Rival Teams using three modes:
  • NO_PVP — Cancels combat damage completely.
  • REDUCED — Allows hits and knockback while scaling damage by a configurable multiplier (10%, 25%, 50%, 75%).
  • NORMAL — Full vanilla PvP damage.
• 4-Tier PvP Exemptions (Per-Team & Per-Player):
  • DEFAULT — Follows standard Global & Team PvP rules.
  • GOD_ATTACKER — Can attack anyone (bypassing NO_PVP), but cannot be damaged by players.
  • FORCE_PVP — Can attack and be attacked by anyone, overriding NO_PVP.
  • PACIFIST — Cannot deal or receive any PvP damage.
• Immortality (God Mode): Toggleable per team or per player (/qt immortal <@team|player>), clamping fatal damage so the player never drops below 0.5 hearts (1.0 HP).

5. Lobby Kick Stick (1s) & Timed Ban Stick (New in 2.0)

• Custom Admin Wand (/qt kickstick): Hit or Right-Click any player to kick them back to the Lobby (1s default) or apply a timed Lobby Ban (30s, 1m, 5m, 10m, 30m, 1h, Perm).
• Quick Controls: Shift + Right-Click Air cycles ban duration; Shift + Left-Click Air opens the Stick Settings & Active Bans Dialog.

6. Customizable Death Sound & World Message/Whisper Routing (New in 2.0)

• Death Sound Engine (/qt deathsound): Play custom sounds on player deaths with 8 built-in presets (wither, thunder, bell, totem, warden, anvil, goat_horn, dragon), custom sound IDs, volume/pitch sliders (0.1–2.0), and audience routing (Same World, All Worlds, Killer & Victim Only, OPs Only).
• Full-Yellow Join/Leave/World Messages & Whisper Muting: Broadcasts clean, 100% yellow joined/left the game and joined/left the world messages. Muting messages for a world in /qt joinleave also blocks /msg, /tell, /w, /whisper, /r, and /teammsg for non-OPs in that world.

7. Enhanced /tp Command & 2-Way PlayerView Culling

• Built-In /tp & /teleport Router: Provides instant multi-argument tab-completion for online players, @a, @p, @r, @s, @box, @<team>, r (random non-OP player), QWorlds warps, and relative ~ coordinates.
• 2-Way PlayerView Exemptions: Separate Target Exempt (always visible to others) and Viewer Exempt (sees all players regardless of distance/count caps) toggles for both teams and individual players.

---

Command & Permission Reference

All administrative commands require qteams.admin or Server Operator (OP) status.

Core & Team Management

• /qt [gui] — Opens the Native QTeams Dialog Dashboard.
• /qt create <name> [color] — Creates a new team with one of the 16 Minecraft colors.
• /qt rename <@team> <new_name> — Renames an existing team and migrates all references.
• /qt duplicate <@team> — Clones a team's settings into an auto-numbered copy (e.g., @red1).
• /qt delete <@team> — Deletes a team and unregisters its scoreboard entries.
• /qt add <player> <@team> / /qt remove <player> — Adds or removes a player from a team.
• /qt clear <@team> — Clears all members from a team.
• /qt list / /qt info <@team> — Lists active teams or inspects a team's full configuration.

Combat, Visuals, Audio & World Tools

• /qt pvp [on|off|toggle] — Toggles Global PvP across recording worlds.
• /qt pvp <@team> <teammates|allies|@rival> <NO_PVP|REDUCED|NORMAL> — Configures the 3-mode combat matrix.
• /qt pvp exempt <@team|player> [DEFAULT|GOD_ATTACKER|FORCE_PVP|PACIFIST] — Sets PvP exemptions.
• /qt immortal <@team|player> — Toggles God Mode immortality.
• /qt ally <@team1> <@team2> — Toggles a mutual alliance between two teams.
• /qt display <@team> [all|prefixes|colors|nametag|tablist|chat|killfeed|joinleave|commands|spoofcolor] — Configures the 6-channel display matrix.
• /qt glow <@team> <on|off|color> / /qt color <@team> <color> — Updates team glow and color.
• /qt noleak <@team> <on|off> / /qt voice <@team> <on|off> — Toggles No-Leak masking or Simple Voice Chat speaking.
• /qt deathsound [gui|on|off|test|sound_key] [volume] [pitch] [audience] — Configures the death sound engine.
• /qt kickstick [gui|give|time|unban|@team|player] [duration] — Manages the Lobby Kick/Ban Stick.
• /qt admit <all|@team|gui> [world] — Admits teamed players from the Lobby into a recording world.
• /qt joinleave / /qt gamemode <ops|recording|lobby|@team> [mode] — Configures world messages and auto-join gamemodes.
• /qt pv <gui|toggle|dist|limit|renderdist|exempt|info> — Configures PlayerView culling and chunk caps.
• /tp <target|@team|@box|r|x y z> [destination|warp|x y z] — Enhanced teleport command with full multi-argument tab-completion.

---

Server Requirements & Dependencies

• Server Software: Paper or Purpur 1.21.11.
• Java Runtime: Java 21.
• Dependencies:
  • packetevents-spigot (2.7.0+) — Required for Netty No-Leak block masking, per-viewer Glow/Stealth Color spoofing, and Tablist Team Buffers.
  • QWorlds (Optional) — Enables @box area selectors, warps, and Lobby admission.
  • QKits (Optional) — Enables @team and @box kit distribution.
  • Simple Voice Chat (Optional) — Enables per-team voicechat.speak muting.