MatchmakingEx is a powerful and extensible matchmaking system designed for Elixir applications, leveraging OTP principles to deliver high performance and scalability. This project aims to efficiently match users based on compatible profiles or criteria, automating the process of forming pairs or groups according to customizable rules.

Key Features

• Simple API: Provides easy-to-use functions for finding matches and managing player states.
• Filter-Based Matching: Enables matching players based on custom filters like skill level, rank, or game mode.
• Two-Way Match Confirmation: Implements a confirmation system where both players must accept a match to proceed.
• Configurable Timeouts: Allows automatic cancellation of matches if not confirmed within a designated time frame.
• Automatic Re-queuing: Players who accept a cancelled match are seamlessly placed back into the matchmaking queue.
• Robust and Scalable Architecture: Built using GenServers, Supervisors, and a Registry for fault tolerance and high performance.

How It Works

Integrating MatchmakingEx into an application requires setting up a supervision tree, starting player processes, and managing the matchmaking flow.

Matchmaking Flow

1. Find a Match

Players can search for matches with or without filters:

# Simple search with no filters
MatchmakingEx.Player.search("player-123")

# Search with filters
filters = %{rank: "gold", mode: "1v1"}
MatchmakingEx.Player.search("player-456", filters)

2. Handle Match Confirmation

Upon finding a match, both players receive a message to confirm:

# Accept the match
MatchmakingEx.Player.accept("player-123")

# Or decline the match
MatchmakingEx.Player.decline("player-456")

3. Manage Match Outcomes

If both players accept, the match is confirmed. If one player declines or a timeout occurs, the match is cancelled, and accepted players are re-queued.

Matchmaking State Machine (FSM)

The matchmaking process is represented in a state diagram, detailing how matches transition based on player responses, including scenarios for acceptances, declines, and timeouts.

Truth Table for Match Confirmation

This table illustrates the outcomes based on various combinations of player responses, facilitating clarity on how the system manages different scenarios:

Logical Rules

• Confirmed Match: Achieved only when both players accept.
• Rejection Is Punitive: Players who reject a match incur a cooldown period and are removed from the queue.
• Timeout Is Non-Punitive: Timing out does not incur penalties.
• Innocent Requeue: Players who accept a match but experience a failure are re-queued.
• Rejection Overrides Timeout: If one player rejects while the other times out, the rejection prevails.

Full Example in iex

For a practical demonstration, processes can be started within an interactive Elixir shell:

# 1. Start processes for two players
iex> MatchmakingEx.Player.start_link("aragorn")
{:ok, #PID<...>}

iex> MatchmakingEx.Player.start_link("gimli")
{:ok, #PID<...>}

# 2. Both search with compatible filters
iex> MatchmakingEx.Player.search("aragorn", %{quest: "fellowship"})
:ok

iex> MatchmakingEx.Player.search("gimli", %{quest: "fellowship"})
:ok

Console output will indicate readiness for confirmation, outlining the next steps for players to accept or decline.