Player Model

The Player object represents a player in NeatQueue and appears in most webhook events. This object contains player identity, rating, role information, and match-related metadata.

Structure

{
  "name": "Player#1234",
  "id": "111222333444555666",
  "mmr": 1500,
  "role": "Duelist",
  "team_num": 0,
  "top_role_index": 0,
  "ign": "PlayerIGN",
  "timestamp": 1707523200.0,
  "pulled_from": null
}

Fields

Field	Type	Description
name	string	Discord username with discriminator (e.g., "Player#1234")
id	string	Discord user ID (unique identifier)
mmr	number	Player's MMR (Matchmaking Rating)
role	string	Player's selected role or position
team_num	number	Team assignment. -1 if not yet assigned, 0 for Team 1, 1 for Team 2, etc.
top_role_index	number	Index of the player's primary role preference
ign	string|null	In-game name if the player has registered, otherwise null
timestamp	number	Unix timestamp (in seconds) when the player joined the queue
pulled_from	string|null	Name of the source queue if the player was pulled from another queue, otherwise null

Field Details

name

The player's Discord username including their discriminator. This is the display name shown in Discord.

Example: "CoolGamer#1234"

id

A unique Discord user ID. Use this as the primary identifier for players when storing data or tracking users across events.

Example: "111222333444555666"

mmr

The player's current MMR (Matchmaking Rating). This numeric value represents skill level and is used for team balancing.

Example: 1500

role

The role or position the player selected when joining the queue. The available roles depend on your queue configuration.

Examples: "Duelist", "Controller", "Tank", "DPS"

team_num

Indicates which team the player is assigned to:

• -1: Not yet assigned to a team (during queue phase)
• 0: Team 1 (first team)
• 1: Team 2 (second team)
• 2+: Additional teams (for multi-team modes)

Example: 0 (player is on Team 1)

top_role_index

An index representing the player's primary role preference. Lower values indicate higher priority roles.

Example: 0 (this is the player's first choice role)

ign

The player's in-game name (IGN) if they have registered it using NeatQueue's registration system. This field is null if the player hasn't registered an IGN.

Examples:

• "PlayerIGN" (registered)
• null (not registered)

timestamp

Unix timestamp (in seconds with decimal precision) indicating when the player joined the queue.

Example: 1707523200.0 (February 10, 2024)

Converting to datetime (Python):

from datetime import datetime
dt = datetime.fromtimestamp(player['timestamp'])

Converting to Date (JavaScript):

const date = new Date(player.timestamp * 1000);

pulled_from

If the player was automatically moved from another queue, this field contains the name of the source queue. Otherwise, it's null.

Examples:

• "casual-queue" (pulled from casual queue)
• null (joined directly)

Usage in Events

The Player object appears in these events:

• JOIN_QUEUE - In players and new_players arrays
• LEAVE_QUEUE - In players and removed_players arrays
• MATCH_STARTED - In players array (all players have team_num: -1)
• TEAMS_CREATED - In teams 2D array (players have assigned team_num)
• MATCH_COMPLETED - In teams 2D array
• MATCH_CANCELLED - In teams 2D array
• SUBSTITUTION - As player_subbed_out and player_subbed_in objects

Example Usage

Extracting Player Information

def process_player(player):
    # Get basic info
    discord_name = player['name']
    discord_id = player['id']
    mmr = player['mmr']
    
    # Check if player has registered IGN
    if player['ign']:
        print(f"{discord_name} (IGN: {player['ign']}) - MMR: {mmr}")
    else:
        print(f"{discord_name} - MMR: {mmr} (No IGN registered)")
    
    # Check team assignment
    if player['team_num'] == -1:
        print("Not yet assigned to a team")
    else:
        print(f"Assigned to Team {player['team_num'] + 1}")

Calculating Team Statistics

def calculate_team_stats(team):
    """Calculate average MMR for a team"""
    total_mmr = sum(player['mmr'] for player in team)
    avg_mmr = total_mmr / len(team)
    
    print(f"Team size: {len(team)}")
    print(f"Average MMR: {avg_mmr:.1f}")
    print(f"Total MMR: {total_mmr}")
    
    return avg_mmr

Finding Players by Role

def get_players_by_role(players, role):
    """Filter players by their selected role"""
    return [p for p in players if p['role'] == role]

# Example
duelists = get_players_by_role(match_players, "Duelist")
print(f"Found {len(duelists)} Duelists")