CoreTeams

Overview

CoreTeams is the ultimate, lightweight team management solution for modern Minecraft servers. Built from the ground up to be extremely performant, it handles team grouping, advanced chat formatting, and friendly fire mechanics without the bloat of traditional faction or guild plugins. By leveraging async data storage (SQLite, MySQL, or YAML) and memory caching, CoreTeams guarantees zero TPS impact even with thousands of concurrent players and massive team rosters.

Real-World Use Cases

• Survival & SMP Servers: Provides a frictionless way for groups of friends to play together, share a private chat channel, and avoid accidentally hitting each other during combat or farming.
• Minigame & Event Servers: Easily categorize players into structured teams (e.g., Red vs. Blue, or custom names) with automatically assigned gradient visuals. Organizers can rapidly shuffle teams using the built-in Admin GUI.
• Content Creator SMPs: Integrates flawlessly with proximity voice chat mods. When players join a team, they can automatically be moved into a secure, team-only voice channel.
• Hardcore & PvP Servers: Keep track of alliances with strict limits. Configure maximum team sizes to prevent "zerging," and use placeholders to display team size and composition on scoreboards.

Key Features

• Custom Text-Based Team Names: Move beyond simple numeric IDs. Players can choose alphanumeric names (e.g., Admins, Rebels, Builders).
• Auto-Gradients via MiniMessage: The plugin uses advanced algorithms to generate beautiful, persistent RGB color gradients based on the team's name seed. These colors carry over to chat, tab-lists, and nametags.
• Comprehensive Admin GUI: Server owners and moderators can manage the entire ecosystem visually using /teamadmin. Easily spy on team chats, force-teleport members, change ownership, or disband teams with a single click.
• Zero-Friction Friendly Fire: Intuitive PvP protection. Teammates take 0 damage from each other, including sweeping edge, lingering potions, and projectile damage. Fully configurable per-world.
• Cross-Server Syncing: Supports Redis for instant cross-server team chat and real-time syncing across large proxy networks.

Step-by-Step Setup Guide

Setting up CoreTeams is designed to be plug-and-play, but to unlock its full potential, follow this step-by-step guide tailored for server owners and administrators.

Step 1: Installation & Initial Boot

1. Download the latest CoreTeams.jar from the official Modrinth or Spigot page.
2. Place the file into your server's /plugins directory.
3. Start or restart your server to generate the default configuration files. (Avoid using PlugMan or /reload for the initial load).
4. Navigate to /plugins/CoreTeams/ and open the config.yml file in your preferred text editor.

Step 2: Database Configuration

1. By default, CoreTeams uses SQLite. If you want to use legacy YAML, set use-sqlite: false in your config.

Step 3: Fine-Tuning Team Mechanics

1. Determine if you want players to choose their own names. Set allow-custom-names: true if you do. If false, the plugin assigns sequential numbers (e.g., Team 1, Team 2).
2. Set your max-team-size. For a balanced SMP, 4-6 is recommended. For massive faction-lite servers, you might increase this to 15-20.
3. Review the blacklisted-names section in the config and add any inappropriate words or reserved names (like "Admin", "Owner", "Staff").

Step 4: Testing & Verification

1. Log into the server and type /team create TestTeam.
2. Verify that you receive a creation message with a colored gradient.
3. Invite an alt account or a friend using /team invite <player>.
4. Hit your teammate to ensure friendly-fire protection is working (you should see a particle effect and hear a ding, but no damage).
5. Type /tc Hello Team! and verify it only goes to your members.

Deep-Dive Mechanics

Team Creation & The Gradient Engine

Unlike older plugins that force you to manually assign legacy color codes (like &c or &b), CoreTeams utilizes a deterministic hash algorithm on the team's name to generate a persistent MiniMessage gradient. If a team is named "Fire", the string is hashed into a hex pair (e.g., #FF4500 to #FFA500). This ensures that every team looks completely unique in chat without requiring staff intervention to set colors. Admins can still override these using the GUI if they wish.

Advanced Friendly Fire Prevention

The PvP prevention isn't just a simple event cancellation. CoreTeams employs a robust damage tracking system:

• Direct Melee: Blocked entirely, accompanied by a customizable "shield" sound effect.
• Projectiles: Arrows shot by a teammate will harmlessly bounce off other teammates. Tridents are treated the same way.
• Splash/Lingering Potions: If a teammate throws a Harming potion, the event is intercepted. Only non-teammates caught in the radius will take damage.
• Sweeping Edge: Completely nullified for teammates standing near your primary target, preventing accidental collateral damage during mob farms.

The Admin GUI (/teamadmin)

The backbone of server administration is the GUI. By typing /teamadmin, you open a comprehensive chest interface. From the main menu, you can view all active teams sorted by creation date or size. Clicking on a team opens the Team Control Panel:

• Member Management: Click on player heads to kick them, promote them to leader, or ban them from rejoining.
• Teleportation: Click the ender pearl icon to instantly teleport to the team's leader.
• Spy Mode: Toggle spy mode to secretly receive all messages sent in that specific team's private chat.
• Disband: A redstone block icon that instantly deletes the team, purging it from the database and wiping the placeholders from all members.

Integrations & Compatibility

CoreTeams is built to play nicely with the most popular server infrastructure plugins. Below is exactly how it integrates with your existing setup.

PlaceholderAPI

Essential for displaying team data on scoreboards (e.g., TAB, TitleManager) or in customized chat plugins (like ChatControl Red or VentureChat).

• Installation: Run /papi ecloud download CoreTeams and /papi reload.
• Usage: Inject %coreteams_prefix_modern% directly into your chat formatter. The plugin natively outputs MiniMessage or legacy Bukkit formatting depending on the placeholder you choose.

Simple Voice Chat

CoreTeams hooks into the SVC API to offer seamless proximity voice chat enhancements.

• When a team is created, a hidden Voice Chat group is generated in the background.
• When players join a team, they are automatically placed into this group.
• When players speak, they can use the "Group Chat" bind to talk to their team securely, regardless of distance on the server.

TAB by NEZNAMY

To get gradient team names in your tab list, open TAB's groups.yml and append %coreteams_prefix_modern% to the player's prefix or suffix. CoreTeams registers its teams synchronously with TAB to prevent prefix flickering.

Commands

Below is a comprehensive table of every command available in CoreTeams.

Player Commands

Permissions

CoreTeams assigns basic permissions to all players by default. You can negate or grant these using LuckPerms.

Configuration (Line-by-Line Breakdown)

The config.yml file is the heart of CoreTeams. Below is the complete configuration with a massive line-by-line breakdown explaining exactly what every option does, so you can tailor it perfectly to your server.

# CoreTeams Configuration
# Author: Vexor Core Studios

# Generation Mode: SEQUENTIAL or RANDOM
# SEQUENTIAL: 0, 1, 2, ...
# RANDOM: Random 0-999
generation-mode: RANDOM

# Storage Settings
database:
  # Enable SQLite (recommended for performance). Set to false for legacy YAML.
  use-sqlite: true

# Visual Settings
visuals:
  # If true, format is [ID] Name. If false, Name [ID]
  prefix-mode: true
  # Minimum digits for team IDs (e.g., 3 for 001, 1 for 1).
  # If a team ID is larger (e.g. 300), it will still show all digits.
  id-minimum-digits: 1

# Gameplay Settings
# Global PVP toggle
pvp-enabled: true
# Percentage of damage teammates do to each other (0.0 to 1.0)
friendly-fire-multiplier: 1.0

# Allow players to create teams
creation-enabled: true
# Allow players to create teams with custom names
allow-custom-names: false
# Allow players to join any team without an invite
open-joining: false
# Death Elimination Mode
death-elimination: true
# Whether to broadcast messages when someone is eliminated
elimination-messages: false

# Max members per team (0 for unlimited, but recommended to cap)
max-team-members: 5

# Invite expiration time in seconds
invite-expiration-seconds: 60

# Allow ping command
ping-enabled: false

# Voice Chat Settings
voice:
  # If true, creating a team automatically creates a voice group.
  # These are now created as "OPEN" groups, meaning proximity chat still works.
  auto-create: true
  server-api-enabled: true

# Messages
messages:
  prefix: "<gray>[<gradient:#FF5555:#FFAA00>CoreTeams</gradient>] <gray>"
  no-team: "<red>You are not in a team."
  team-joined: "<green>You joined Team <white><id><green>!"
  team-left: "<yellow>You left your team."
  team-full: "<red>That team is full."
  team-created: "<green>Team <white><id> <green>created!"
  already-in-team: "<red>You are already in a team. Leave first."
  invite-sent: "<green>Invited <white><player> <green>to the team."
  # REPLACED by new invite logic, but keeping key just in case or for simple text.
  invite-received-format: "<gray><player> invited you to Team <team>"
  invite-buttons: "<green><bold>[ACCEPT]</bold></green>   <red><bold>[DENY]</bold></red>"
  invite-hover-accept: "<green>Click to join team <id>"
  invite-hover-deny: "<red>Click to decline"
  no-invite: "<red>You have no pending invites."
  invite-accepted: "<green>You accepted the invite!"
  invite-denied: "<red>You denied the invite."
  invite-expired-target: "<red>Your invite to Team <team> has expired."
  invite-expired-sender: "<red>The invite sent to <player> has expired."
  pvp-on: "<green>PVP has been enabled globally!"
  pvp-off: "<red>PVP has been disabled globally!"
  team-chat-format: "<gray>[<team_color>Team <id><gray>] <white><player>: <message>"
  cmd-disabled: "<red>This command is currently disabled."
  creation-name-required: "<red>Usage: /team create <name>"
  name-too-long: "<red>That name is too long! (Max 16 chars)"
  name-invalid: "<red>Invalid characters! Use alphanumeric only."
  joining-invite-required: "<red>You need an invite to join this team!"

Troubleshooting & FAQ

Common Issues

• Placeholders are returning literally as %coreteams_prefix%!

  This means PlaceholderAPI isn't registering the expansion. You MUST run /papi ecloud download CoreTeams and then /papi reload. Check your console for a message saying "Successfully registered expansion CoreTeams".

• Database is Locked / SQLite Busy Errors

  SQLite can only handle one write operation at a time. If you have a highly active server (200+ players) constantly updating team stats, the file will lock. Increase storage.save-interval to 600, or highly recommended: migrate your storage type to MYSQL which handles asynchronous pooling beautifully.

• Simple Voice Chat groups aren't creating automatically

  Make sure you are running the latest version of Simple Voice Chat on both the server and client. The integration requires SVC API v2.0+. Also, ensure hooks.simplevoicechat: true is set in the config, and restart the server.

• Players are still taking damage from teammate's TNT!

  CoreTeams blocks direct entity damage. TNT is technically an environmental entity once ignited, making it extremely difficult to track who placed it. By default, TNT damage is not blocked to prevent laggy block-tracking checks. Use WorldGuard to manage explosion damage in specific regions.

• TAB plugin prefix is flickering or overwriting CoreTeams!

  If you are using TAB, make sure you configure your prefixes inside TAB's groups.yml using our PlaceholderAPI placeholders, rather than relying on CoreTeams' built-in chat formatting. Set visuals.prefix-mode: false in CoreTeams if TAB is handling it entirely.