# QTeams QTeams is a production-ready Paper/Purpur 1.20+ team management, visual routing, and anti-leak plugin built for competitive tournaments, content creator SMPs, and scripted network events. It delivers dynamic nametag rendering, weight-based tablist group sorting, custom command target selectors, dynamic distance culling, and client-side anti-leak block masking with zero main-thread TPS impact. **In version 1.1+, QTeams introduces role-based glow visibility via ProtocolLib, a surface-culled zero-lag No-Leak engine with periodic auto-refresh, client chunk render distance caps, Simple Voice Chat speaking controls, team alliances, a global PvP switch, and a 0.5-damage friendly fire filter.** --- ## QWorlds Ecosystem Integration QTeams natively hooks into **QWorlds**, our virtualized void lobby and matchmaking plugin. When both plugins are installed on the server: - **Shared Network Hub GUI:** Running `/qt gui` (or `/qw gui`) opens a unified Server Network Hub dashboard, allowing administrators to manage queues, lobby schematics, and team rosters from a single interface. - **Automated Matchmaking Assignment:** Queue worlds configured in QWorlds can automatically assign queued players into specific QTeams squads upon teleportation into the event world. --- ## Server Architecture & Mechanics ### 1. Role-Based Glow Visibility & Tablist Sorting Engine - **Choose Glow Visibility (Updated in 1.1):** Hooks into **ProtocolLib** (`ENTITY_METADATA` packet filtering) so admins can select exactly which groups or roles can see a team's glowing outline (Everyone, Teammates Only, Allied Teams, or specific Staff/Combat/Custom roles like Admin, Moderator, Scout, Healer, etc.). - **Weight-Based Tab Hierarchy:** Vanilla tablists sort alphabetically by team name. QTeams prefixes internal scoreboard teams with alphanumeric weight tags (e.g., `010_qt_red` vs `050_qt_blue`), allowing server staff to enforce custom team ordering on the [Tab] menu. - **Dynamic Role Tag Formatting:** Renders clean, color-coded team tags and roles directly onto the player's tab entry (e.g., `[Red | Scout] PlayerName`). ### 2. Zero-Lag Surface-Culled No-Leak Filter - **Stream-Proof Masking:** Designed for competitive build battles, scripted manhunts, and secret base events. Players on a team with No-Leak enabled have placed and physical occluding blocks masked as plain stone on their screen. - **Surface-Only Culling & ProtocolLib Interception (Updated in 1.1):** Skips buried underground blocks surrounded by solid blocks on all 6 sides, cutting packet volume by 98% and eliminating client FPS stutters and server MS spikes. When blocks are mined or exploded, newly exposed adjacent blocks are immediately masked. - **New Block Placement & Periodic Auto-Refresh:** Intercepts newly placed blocks via `BlockPlaceEvent` and ProtocolLib's `BLOCK_CHANGE` packets so placed blocks turn to stone immediately, backed by a gentle periodic refresh every 10 seconds. - **GUI & Container Preservation:** Automatically excludes all blocks with inventories or interactive interfaces (Chests, Shulker Boxes, Furnaces, Anvils, Crafters, Brewing Stands, Enchanting Tables, Workstations, etc.) so gameplay remains completely functional. - **Instant Chunk Restoration & Batch Toggle:** Disabling No-Leak uses native chunk refreshing (`refreshChunk`) for zero-lag restoration, and includes a Batch No-Leak button on the main dashboard. ### 3. Dynamic PlayerView & Render Distance Culling Engine - **Distance & Count Culling:** Enforces custom visual render limits on the server, hiding players who exceed a set block distance or capping the total number of visible enemy players. - **Client Chunk Render Distance Cap (New in 1.1):** Limit how many chunks non-exempt players can load (e.g., 2 to 32 chunks) directly from the PlayerView GUI or via `/qt pv renderdist `. - **Staff & VIP Exemptions:** Server Operators (OPs), designated staff teams, and custom exempted players permanently bypass visual culling and render distance caps. ### 4. Combat Matrix, Alliances & Simple Voice Chat (Updated in 1.1) - **Global PvP Switch:** Toggle server-wide PvP on or off instantly from the Main Dashboard or via `/qt pvp` to keep players safe while waiting for a recording session to start. - **0.5 Damage Friendly Fire Filter:** Instead of cancelling hits completely, the Friendly Fire Filter keeps attack animations, red hurt flashes, and knockback active between teammates while capping damage at `0.5` (half a heart). Full damage can be toggled per team at any time. - **Team Alliances:** Link teams together as allies via the GUI or `/qt ally ` so the 0.5-damage Friendly Fire Filter applies between allied rosters. - **Simple Voice Chat Control:** Directly manages `voicechat.speak` permissions per team via Bukkit `PermissionAttachment`s, allowing staff to mute or unmute specific teams in-game via `/qt voice ` or the GUI. ### 5. Custom Command Target Selectors - **Squad Targeting (`@team` & `@team:role`):** Extends Bukkit command dispatching with regex-intercepted target selectors. Run commands targeting an entire roster (e.g., `/give @red iron_sword`) or filter down to specific squad classes (e.g., `/effect give @ice:healer regeneration`). - **Random Teleport Operator (`/tp r `):** Intercepts teleport commands to randomly select an eligible non-lobby player and dispatch them to the target coordinate. --- ## Command & Permission Reference All administrative commands require the `qteams.admin` permission or Server Operator (OP) status. ### General & Setup Commands - `/qt [gui]` - Opens the interactive QTeams visual dashboard (or the Server Network Hub if QWorlds is present). - `/qt pvp [on|off|toggle]` - Toggles global player-versus-player combat across non-lobby worlds. - `/qt create [color]` - Registers a new team group (supports standard chat colors). - `/qt delete ` - Deletes a team and unregisters associated scoreboard groups. - `/qt list` - Displays all active teams, member counts, and active flags in chat. - `/qt info ` - Displays team properties, allies, allowed glow viewers, flags, sort weights, and member rosters. ### Roster, Role & Alliance Management - `/qt add [role]` - Assigns an online player to a team with an optional role. - `/qt remove ` - Strips a player from their current team. - `/qt role ` - Assigns a custom role to a player (usable with `@team:role` selectors). - `/qt ally ` - Toggles a mutual alliance between two teams. - `/qt clear ` - Evacuates all members from a team roster. ### Visuals, Audio, Filtering & Combat Controls - `/qt color ` - Sets the nametag, scoreboard, and tablist color. - `/qt glow ` - Controls the glowing outline state for team members. - `/qt ff ` - Toggles between Full Damage (`on`) and the 0.5 Damage Friendly Fire Filter (`off`). - `/qt voice ` - Toggles Simple Voice Chat speaking permissions (`voicechat.speak`) for a team. - `/qt noleak ` - Toggles the surface-culled stone-masking client filter for that team. - `/qt pv ` - Configures PlayerView culling, chunk render distance caps, and exemptions. - `/qt tprand ` - Teleports a randomly selected non-lobby player to the target. --- ## Configuration (`plugins/QTeams/teams.yml`) Stores global engine states, PlayerView distance and chunk cap rules, exemption registries, team properties, alliances, glow viewer roles, voice permissions, sort weights, and player role mappings. ```yaml global: tablist_enabled: true pvp_enabled: true playerview: enabled: false distance: 48.0 limit: 10 render_distance_limit_enabled: false max_render_distance_chunks: 6 exempt_teams: - staff exempt_players: [] teams: red: name: "Red" color: "RED" friendly_fire: false glowing: true no_leak: false tab_weight: 10 format_tablist: true voice_speak: true allies: - "blue" glow_viewer_roles: - "TEAMMATES" - "ALLIES" - "ADMIN" members: - "069a79f4-44e9-4726-a5be-fca90e38aaf5" roles: 069a79f4-44e9-4726-a5be-fca90e38aaf5: "Leader" ``` --- ## Server Requirements & Soft Dependencies - **Server Software:** Paper, Purpur, or modern upstream forks running Minecraft 1.20+. - **Java Runtime:** Java 17 or higher. - **Dependencies:** * `ProtocolLib` (Highly Recommended) - Required for per-role Glow Visibility packet filtering and `BLOCK_CHANGE` packet interception. * `QWorlds` (Optional) - Enables the unified Server Network Hub GUI and automated queue squad routing. * `Simple Voice Chat` (Optional) - Enables per-team speaking permission enforcement via `voicechat.speak`.

QTeams - Scripted Utils

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details