GS2-Matchmaking API Reference

This service realizes opponents and cooperative partners.

The matchmaking process is as follows

Host creates a gathering ↓ Participants search for a gathering that meets their criteria. ↓ Matchmaking is complete when the specified number of people have been reached.

GS2-Matchmaking is designed to meet as many of these needs as possible regarding `participant search for matching gatherings. Here is an example of the design with use cases.

• Finding opponents who want to play the same game mode

There are two game modes in the game, one for casual players and the other for core gamers. Suppose we want to perform the matchmaking process without mixing these players.

You can specify up to five attribute values when creating a gathering or when searching for a gathering. When creating a gathering, you can specify a range of attribute values for the players to be recruited, and When searching for a gathering, the request for processing is made by specifying the value of its own attribute value.

In other words, when the host creates a gathering, he/she specifies the game mode to be recruited in the attribute value 1, and when he/she searches for a gathering, he/she specifies his/her own attribute value. By specifying the game mode that the searcher wishes to participate in as attribute value 1, players with the same desired game mode will be matched with each other.

• In addition to attribute 1, I want to find opponents in the same level range.

The host specifies the minimum and maximum levels to be recruited in attribute value 2 when creating the gathering. The searcher can specify his/her own level in attribute value 2 to matchmaking with other players in the same level range.

If multiple attribute values are specified, the search will be processed to find a match that meets the range of all attribute values.

• In addition to 2, when the waiting time becomes long, you may want to expand the level range for recruiting.

Suppose you start out recruiting within a narrow range and try to make matches between players of the same level, but if you have trouble finding opponents, you want to expand the range of levels in which you can recruit. There is a GS2-Script event that fires approximately every minute after the Gathering is created. This script can be used to gradually relax the desired conditions by relaxing the range of the Gathering’s attribute values.

• Create a Gathering in which only friends can participate

An option when creating a gathering is to specify list of user IDs that are allowed to participate. This can be used to limit the number of participants by specifying list of friends’ user IDs.

• I want to prevent matchmaking with a player who has harassed me.

You can specify a blacklist of user IDs when creating or searching for a Gathering. The blacklist specified at search time will discover Gatherings that match the criteria and will be added to the blacklist of Gatherings in which you have participated. If you are on the blacklist when searching, you will be excluded from matchmaking.

• Matchmaking by role

In some games, you may want to make a matchmaking with one shield, one healer, and two attackers. The role attribute can be used in this case.

Assume a tank as a shield, a healer as a healer, and an attacker as an attacker. When you create a gathering, you set the number of recruits for each role. By setting this for your role when searching for a gathering, only those gatherings that have openings for that role will be treated as open gatherings.

You can also set an alias for the recruiting role. For example, tank could be represented by a more specific role, and the search for a gathering could be performed as either paladin, warrior, or dark_knight. When creating a gathering, if you specify paladin and dark_knight as aliases for tank, you can create a gathering in which warrior cannot participate.

• Additional recruitment

Used when one player leaves the matchmaking process and only one player needs to be replaced after the match is completed. The party token is used in this case. To issue a party token, you must have the player token of the player who is organizing the party. Player tokens are tokens that allow the player himself to allow a party representative to perform matchmaking on his behalf, and they have a three-minute validity period. Each party member obtains a player token by making a request to the API that issues player tokens and sends it to the party representative. The party representative receives the player token from the party member and sends it to the party token issuing API within 3 minutes to obtain a party token. The party token has a validity period of 10 minutes, and the party token is used to call the gathering creation process or the gathering search process within 10 minutes. In this way, you can create a gathering with all party members participating or join a gathering in which all party members can participate.

• Matchmaking between parties

In a 4 vs. 4 game, you may want to play against a prearranged party without dispersing the party to the opposing side. For example, you may want to matchmake a prearranged party of 3 players, a prearranged party of 4 players, and one stray player to Suppose you want to realize a match party of 3 players + 1 stray player vs party of 4 players in advance. In such a case, we first execute the matchmaking for the 4 players. Then you will have two gatherings: a party of 3 players + 1 stray player and a party of 4 players organized in advance. Then, a representative from each party performs matchmaking with a capacity of 2 players, and the parties are matched against each other. In this way, you can have a pre-arranged party of 3 players + 1 stray player vs. a pre-arranged party of 4 players.

• Communication between players during matchmaking

It may be necessary for players to communicate with each other without matchmaking being completed. GS2-Matchmaking provides two means of communication between players during the creation of a gathering.

• Chat room creation in conjunction with GS2-Chat
• Game server startup in conjunction with GS2-Realtime

If you want to exchange metadata between players at a low frequency, even when recruitment is not finished, you can use the former method, and if you want to exchange metadata between players at a high frequency, you can use the latter method. Use the latter if you want to have the game played with NPCs or with insufficient numbers of players while recruiting.

GS2-Chat’s limitations can be used as a criterion for determining low or high frequency. GS2-Chat allows only 3 comments per second per chat room. If this frequency is exceeded, GS2-Realtime should be used.

• How to process after matchmaking is complete

When matchmaking is completed, you can notify players of the completion of matchmaking by in-game push notification using GS2-Gatewayorjob registration using GS2-JobQueue. You can also run arbitrary scripts using GS2-Script'. If you want to use GS2-Realtime to realize competitive or cooperative play after matchmaking, you can use GS2-Script, which is executed after matchmaking is completed, to You can create a GS2-Realtime gathering and direct it to the game server by notifying the gathering's IP address and port information using GS2-Gateway in-game push notificationorGS2-JobQueue job registration`.