QTeams - Scripted Utils

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 <chunks|off>.
• 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 <team1> <team2> 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 PermissionAttachments, allowing staff to mute or unmute specific teams in-game via /qt voice <team> <on|off> 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 <player>): 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 <name> [color] - Registers a new team group (supports standard chat colors).
• /qt delete <team> - Deletes a team and unregisters associated scoreboard groups.
• /qt list - Displays all active teams, member counts, and active flags in chat.
• /qt info <team> - Displays team properties, allies, allowed glow viewers, flags, sort weights, and member rosters.

Roster, Role & Alliance Management

• /qt add <player> <team> [role] - Assigns an online player to a team with an optional role.
• /qt remove <player> - Strips a player from their current team.
• /qt role <player> <role> - Assigns a custom role to a player (usable with @team:role selectors).
• /qt ally <team1> <team2> - Toggles a mutual alliance between two teams.
• /qt clear <team> - Evacuates all members from a team roster.

Visuals, Audio, Filtering & Combat Controls

• /qt color <team> <color> - Sets the nametag, scoreboard, and tablist color.
• /qt glow <team> <on|off|color> - Controls the glowing outline state for team members.
• /qt ff <team> <on|off> - Toggles between Full Damage (on) and the 0.5 Damage Friendly Fire Filter (off).
• /qt voice <team> <on|off> - Toggles Simple Voice Chat speaking permissions (voicechat.speak) for a team.
• /qt noleak <team> <on|off> - Toggles the surface-culled stone-masking client filter for that team.
• /qt pv <toggle|dist|limit|renderdist|exempt|info> - Configures PlayerView culling, chunk render distance caps, and exemptions.
• /qt tprand <target_player> - 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.

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.