Specialized components
Matchmaking system
Frontend service interaction
19 min
overview the frontend service interaction component serves as the entry point to the ir engine's matchmaking system it provides the api interface through which game clients communicate with the matchmaking infrastructure, enabling players to request matches and receive game assignments by abstracting the complexity of the underlying matchmaking processes, this component creates a straightforward way for games to integrate with the matchmaking system this chapter explores the implementation, workflow, and integration of the frontend service within the ir engine's matchmaking architecture core concepts client server communication the frontend service establishes a communication channel between game clients and the matchmaking system request submission game clients send match requests to the matchmaking system response handling the matchmaking system provides responses with ticket ids or assignments status polling clients periodically check for updates on their match requests connection details when matches are found, clients receive server connection information this communication follows standard api patterns, typically using http requests and json data formats match request lifecycle a match request follows a defined lifecycle through the frontend service creation client submits a request for a match with specific criteria acknowledgment system creates a ticket and returns a unique identifier processing matchmaking system works to find suitable matches (invisible to client) assignment when a match is found, connection details are provided to the client completion client connects to the assigned game server this lifecycle provides a structured approach to handling match requests from submission to fulfillment implementation creating a match ticket the first step in the matchmaking process is creating a ticket // from src/functions ts import { matchtickettype } from ' /match ticket schema'; // other imports and setup const frontend service url = 'http //localhost 51504/v1/frontendservice'; / creates a match ticket for the specified game mode @param gamemode the desired game mode (e g , "capturetheflag") @returns a promise resolving to the created match ticket / async function createticket(gamemode string) promise\<matchtickettype> { console log(`creating ticket for game mode ${gamemode}`); try { // send post request to create a ticket const response = await axios post(`${frontend service url}/tickets`, { searchfields { tags \[gamemode] } }); // return the ticket data return response data as matchtickettype; } catch (error) { console error('failed to create match ticket ', error); throw new error('failed to create match ticket'); } } this function takes a game mode parameter that specifies what type of game the player wants sends an http post request to the frontend service's /tickets endpoint includes search fields (like game mode tags) that will be used for matchmaking returns a match ticket object with a unique id for future reference checking for match assignments after creating a ticket, clients need to check if a match has been found // from src/functions ts import { matchticketassignmenttype } from ' /match ticket assignment schema'; // other imports and setup / gets the assignment for a specific ticket @param ticketid the id of the ticket to check @returns a promise resolving to the ticket assignment (if any) / async function getticketsassignment(ticketid string) promise\<matchticketassignmenttype> { console log(`checking assignment for ticket ${ticketid}`); try { // create an abortcontroller for timeout handling const controller = new abortcontroller(); const timeoutid = settimeout(() => controller abort(), 10000); // 10 second timeout // send get request to check for assignment const response = await fetch( `${frontend service url}/tickets/${ticketid}/assignments`, { signal controller signal } ); // clear the timeout cleartimeout(timeoutid); // check for errors if (!response ok) { throw new error(`http error ${response status}`); } // parse the response const data = await readstreamfirstdata(response body); return data as matchticketassignmenttype; } catch (error) { if (error name === 'aborterror') { console error('request timed out'); return { connection '' } as matchticketassignmenttype; } console error('failed to get ticket assignment ', error); throw new error('failed to get ticket assignment'); } } / helper function to read the first chunk of data from a stream / async function readstreamfirstdata(stream) { const reader = stream getreader(); const { value, done } = await reader read(); reader releaselock(); if (done) { return null; } // parse the json data const text = new textdecoder() decode(value); return json parse(text); } this function takes a ticket id parameter that was received from the createticket function sends an http get request to the /tickets/{ticketid}/assignments endpoint includes timeout handling to prevent indefinite waiting parses the response to extract assignment information returns an assignment object that may contain connection details if a match was found polling for assignments since matchmaking takes time, clients typically poll for assignments // example usage in a game client async function findmatch(gamemode string) promise\<string> { // step 1 create a ticket console log(`finding a match for game mode ${gamemode}`); const ticket = await createticket(gamemode); console log(`ticket created with id ${ticket id}`); // step 2 poll for assignment let assignment = await getticketsassignment(ticket id); let attempts = 0; const max attempts = 30; // maximum polling attempts while (assignment connection === '' && attempts < max attempts) { console log(`no assignment yet, waiting (attempt ${attempts + 1}/${max attempts}) `); // wait before trying again await new promise(resolve => settimeout(resolve, 5000)); // 5 second delay // check again assignment = await getticketsassignment(ticket id); attempts++; } // step 3 handle the result if (assignment connection !== '') { console log(`match found! server connection ${assignment connection}`); return assignment connection; } else { console log('failed to find a match within the time limit'); throw new error('matchmaking timeout'); } } this function creates a match ticket for the specified game mode repeatedly checks for an assignment with a delay between attempts limits the number of attempts to prevent infinite polling returns the connection details when a match is found throws an error if no match is found within the time limit communication flow the complete frontend service interaction follows this sequence sequencediagram participant client as game client participant frontend as frontend service participant backend as matchmaking backend client >>frontend create ticket (post /tickets) frontend >>backend register ticket backend >>frontend ticket created frontend >>client return ticket id loop until match found or timeout client >>frontend check assignment (get /tickets/{id}/assignments) frontend >>backend query assignment status backend >>frontend assignment status alt no assignment yet frontend >>client empty connection else assignment found frontend >>client server connection details end end client >>client connect to game server this diagram illustrates the client creates a ticket through the frontend service the frontend service registers the ticket with the matchmaking backend the client periodically checks for an assignment the frontend service queries the backend for the current status when a match is found, the frontend service provides connection details the client connects to the assigned game server api endpoints the frontend service exposes several key endpoints endpoint method description request body response /tickets post create a new match ticket game criteria (mode, etc ) ticket object with id /tickets/{id} get get ticket details none ticket object /tickets/{id} delete cancel a ticket none success status /tickets/{id}/assignments get get assignment for a ticket none assignment object these endpoints provide a complete interface for managing the matchmaking process from the client perspective configuration the frontend service is configured through environment variables // from src/config ts export const config = { frontendservice { url process env frontend service url || 'http //localhost 51504/v1/frontendservice', timeout parseint(process env frontend service timeout || '10000', 10), retrycount parseint(process env frontend service retry count || '3', 10), retrydelay parseint(process env frontend service retry delay || '1000', 10) } }; this configuration sets the base url for the frontend service defines timeout values for requests configures retry behavior for failed requests provides defaults while allowing customization through environment variables integration with other components the frontend service interacts with several other components of the matchmaking system match ticket the frontend service creates and manages match tickets // from src/match ticket schema ts export interface matchtickettype { id string; searchfields? { tags? string\[]; doubleargs? record\<string, number>; stringargs? record\<string, string>; }; extensions? record\<string, any>; createtime? string; } this integration defines the structure of match tickets ensures consistent data format between client and server provides fields for specifying match criteria match assignment the frontend service delivers match assignments to clients // from src/match ticket assignment schema ts export interface matchticketassignmenttype { connection string; extensions? record\<string, any>; } this integration defines the structure of match assignments provides connection details for game servers allows for extension data for additional information benefits of frontend service interaction the frontend service interaction component provides several key advantages abstraction hides the complexity of the matchmaking system from game clients standardization provides a consistent api for all games to integrate with decoupling separates client concerns from backend matchmaking logic scalability allows the backend to scale independently of client interactions flexibility supports various game types and matchmaking criteria monitoring provides a clear entry point for logging and monitoring error handling centralizes error management for client facing operations these benefits make the frontend service an essential component for creating a robust and user friendly matchmaking experience next steps with an understanding of how game clients interact with the matchmaking system, the next chapter explores the structure and purpose of match tickets in detail next match ticket docid\ gj92q3bhh0zolz6aqsutj