config.yml 📝

📄 Introduction

The config.yml file is the main configuration file of the xTeams plugin. It controls how players are identified internally, defines your teams, and configures integrations with LuckPerms, vanilla Minecraft scoreboard teams, and the auto-team feature.

💡 Breakdown of the config.yml file

settings:
  # Player identification mode:
  # - "nickname" → for non-premium servers (offline mode)
  # - "uuid"     → for premium servers (online mode), more robust against name changes
  identifier_mode: "uuid"

hooks:
  luckperms:
    enabled: false
    team_groups: # [xTeams team]: <LuckPerms group>
      blue: blue
      red: red
      yellow: yellow
  minecraft_team:
    enabled: false
    team_groups: # [xTeams team]: <Minecraft scoreboard team>
      blue: blue
      red: red
      yellow: yellow
  auto_team:
    enabled: false
    op_bypass: false
    team: red

teams:
  red:
    displayName: "&e&lRed Team"
    priority: 2
    members:
      - player1
      - player2
  blue:
    displayName: "&e&lBlue Team"
    priority: 1
    members:
      - player3
      - player4
  yellow:
    displayName: "&e&lYellow Team"
    priority: 0
    members:
      - player5
      - player6

🔎 Explanation

settings

• identifier_mode: How xTeams stores team members internally.
  • "uuid" — recommended for premium / online-mode servers. Players keep their team membership even if they change their nickname.
  • "nickname" — recommended for non-premium / offline-mode servers, where UUIDs are not stable.
  • You typically pick this once at install time. Switching modes later does not convert existing entries automatically.

hooks

Integrations with external systems. Each hook can be toggled independently.

• luckperms — links xTeams teams with LuckPerms groups.

  • enabled: turn the hook on/off. Requires LuckPerms to be installed.
  • team_groups: a map of xTeams team → LuckPerms group. When a player joins an xTeams team, they get the matching LuckPerms group; when they leave, the group is removed.

• minecraft_team — syncs xTeams teams with vanilla scoreboard teams (the ones that color nameplates and tab list).

  • enabled: turn the hook on/off.
  • team_groups: a map of xTeams team → scoreboard team id. When a player joins an xTeams team, they are added to the scoreboard team; when they leave, they are removed. The scoreboard team's display name is taken from the xTeams team's displayName.

• auto_team — automatically puts new players into a default team when they log in for the first time (or any time they have no team).

  • enabled: turn the hook on/off.
  • op_bypass: if true, server operators are not auto-assigned.
  • team: the team players are added to. Must match an existing entry under teams.

teams

Where you define every team.

• The top-level key (red, blue, yellow) is the internal team name — used in commands, placeholders and the API.
• displayName: the formatted name shown to players. Supports & color codes and #RRGGBB hex.
• priority: an integer. Higher values = higher priority. Used by getPlayerTeam and the placeholders for the player's "main team" when they belong to several.
• members: list of players in the team. Stored as UUIDs or nicknames depending on settings.identifier_mode. You normally don't edit this by hand — use /xteams join and /xteams leave.

💡 Reload tip: running /xteams reload re-reads this file and applies changes to teams, hooks and the auto-team setting without restarting the server.