🎮 League of Legends Custom 5v5 Matchmaking and Elo Tracker

A custom Elo tracking and matchmaking system for League of Legends 5v5 custom games.

The system extracts match data from custom game replay files, calculates player performance scores, adjusts player Elo/MMR using formulas adapted from TrueSkill 2, and stores player data in Google Sheets. It also includes matchmaking tools to generate balanced 10-player custom lobbies.

---

📦 Project Structure

LOL-Custom-5v5-Elo-System/
├── puuid.py            # Fetches player PUUIDs using the Riot API
├── trueSkill2.py       # Extracts match data, calculates performance scores, and updates Elo/MMR
├── team.py             # Generates balanced 5v5 teams
├── Key.json            # Example Google API credentials file
├── data.json           # Extracted match data output
└── README.md           # Project documentation

---

✨ Features

📊 Performance-Based Elo System

The Elo system updates player ratings based on both match results and individual performance.

Key features:

• Extracts League of Legends custom match records from replay files
• Aggregates player statistics into a performance score
• Adjusts Elo/MMR gains and losses using formulas adapted from TrueSkill 2
• Tracks player rating history across multiple custom games
• Stores updated player data and match history in Google Sheets

⚖️ 5v5 Matchmaking System

The matchmaking system helps generate balanced teams for 10-player custom lobbies.

Key features:

• Creates balanced 5v5 teams using player ratings
• Supports role-based matchmaking for players with fixed or preferred roles
• Provides an alternative Google Sheets-based matchmaking option that does not look at roles
• Helps reduce rating imbalance between teams before each custom game

🗂️ Google Sheets Player Database

Player data is managed through a Google Sheets database.

The database stores:

• Player names
• In-game names
• Taglines
• Roles
• PUUIDs
• Current MMR/Elo
• Match history
• Performance scores of previous matches

The Google Sheet also includes formulas to help analyse player performance and team combinations.

Key features:

• Tracks each player's individual Elo/MMR over time
• Generates graphs showing Elo progression for all players
• Allows users to view how often each player wins when paired with every other player

---

🧰 Requirements

Before running the project, you will need:

• Python
• Riot API key (https://developer.riotgames.com/apis)
• Google API credentials (https://cloud.google.com/apis)
• League of Legends custom game replay files
• Google Sheets database template (https://docs.google.com/spreadsheets/d/15idPP36VnK5rOc3jFdmqFw-rpI3epCxP4f4Pi068b-8/edit?usp=sharing)

---

🚀 Getting Started

🗄️ Set Up the Google Sheets Database

Make a copy of the Google Sheets template:

https://docs.google.com/spreadsheets/d/15idPP36VnK5rOc3jFdmqFw-rpI3epCxP4f4Pi068b-8/edit?usp=sharing

1. Go to the Matches sheet.
2. Replace the player names in Row 1 with your own player list.
3. Add more columns if your player base has more players.
4. Delete the template data in:
   • Matches
   • testPerformance
5. Go to playerData and press Reset to reset all player MMR values to 1000.
6. Fill in player details in Sheet3, including:
   • Player role
   • In-game name
   • Tagline

Do NOTE: Python Files use the Google Sheet Name to find it. If you do edit the Google Sheet Name, Change sheet = client.open('5v5 record Template') in puuid.py, team.py and trueskill2.py before proceeding

---

🔑 API Configuration

Riot API Key

The Riot API key is used to retrieve each player's PUUID.

Run:

python puuid.py

This script fetches the PUUID of each player and appends it to the Google Sheets database.

Make sure your Riot API key is added correctly before running the script.

Google API Credentials

Edit the Key.json file with your Google API credentials.

This allows the Python scripts to read from and write to the Google Sheets database.

---

🎞️ Replay Setup

Play at least one League of Legends custom game and download the replay file.

Then update the replay directory in trueSkill2.py:

root_dir = "D:/Documents/League of Legends/Replays"

Change this path to the folder where your League of Legends replay files are stored.

Example:

root_dir = "C:/Users/YourName/Documents/League of Legends/Replays"

---

📈 Performance Score Configuration

In trueSkill2.py, the performance score formula can be adjusted in:

calculate_performance(player, game)

The formula may need to be tuned depending on:

• League of Legends patch changes
• Average skill level of the player group
• How strongly individual performance should affect Elo gain or loss
• Differences in role impact, such as Support vision score or Jungle objective control

The performance score is used alongside match outcome to determine rating adjustments.

Stats Currently Taken into Account

• Damage
• KDA
• Gold Earned
• vision score

---

▶️ Running the System

1. Fetch Player PUUIDs

Run:

python puuid.py

This retrieves player PUUIDs using the Riot API and updates the Google Sheets database.

2. Process Match Data and Update Elo

Run:

python trueSkill2.py

This script will:

1. Read League of Legends replay files
2. Extract custom match data
3. Save extracted match data to data.json
4. Calculate player performance scores
5. Apply rating adjustments using formulas adapted from TrueSkill 2
6. Append updated match and player data to Google Sheets

---

⚔️ Matchmaking

The project supports two matchmaking methods.

Option 1: Role-Based Matchmaking

Use:

python team.py

This is useful when players have fixed roles or strong role preferences.

Example use cases:

• A player can only play Jungle
• A player only plays Support
• Teams need to be balanced by both role and rating

Option 2: Google Sheets Matchmaking

The Google Sheets database also includes a matchmaking option.

This is useful when roles are not a major factor and teams only need to be balanced based on player ratings.

---

🗂️ File Overview

File	Description
puuid.py	Fetches player PUUIDs using the Riot API
trueSkill2.py	Extracts replay data, calculates performance scores, and updates Elo/MMR
team.py	Generates balanced 5v5 teams for custom games
Key.example.json	Example redacted Google API credentials file
data.json	Stores extracted match data

---

🛠️ Tech Stack

Layer	Technology
Backend Scripts	Python
Game Data	Riot API, League of Legends replay files
Rating System	TrueSkill 2-inspired formulas
Database	Google Sheets
Matchmaking	Python, Google Sheets

---

📋 Usage Flow

1. Add player information to the Google Sheets database.
2. Run puuid.py to retrieve player PUUIDs.
3. Play and download a League of Legends custom game replay.
4. Update the replay folder path in trueSkill2.py.
5. Run trueSkill2.py to extract match data and update Elo ratings.
6. Use team.py or the Google Sheets matchmaking tool to generate balanced teams for the next game.

---

🗺️ Roadmap

• Add automatic replay folder detection
• Improve role-specific performance score weighting
• Add champion-specific performance adjustments
• Create a web dashboard for player ratings and match history
• Add visual graphs for Elo progression over time
• Improve matchmaking algorithm for larger player pools

---

⚠️ Notes

• New players start with a default MMR of 1000.
• Rating adjustments are based on match outcome and individual performance.
• Performance formulas are adapted from TrueSkill 2 concepts.
• Performance score weights may need to be updated after major League of Legends patches.

---