Everything starts at authentication with appropriate game backend. Authentication is mandatory with BattlePlace.io: it’s needed to have a reliable identifier for player, so we can store player’s score (and also ban abusers). It also may optionally check whether a given player owns your game.
In order to perform authentication, game client must call Client Authentication API endpoint. If it succeeds, it returns a client token.
A competitive network game requires at least two players playing against each other; in some games players can team up and play collegially; also there could be more than two competing parties in a session. In BattlePlace.io’s terminology, every competing party is called a team, and players withing each team are allies. BattlePlace.io provides an API helping players with similar skills to find each other and form a fair game session, or at least rate the results of the game session fairly.
In order to request a match call Client Request Match API endpoint, using a client token received from authentication step. Additional parameters include team sizes, optional match tag and optional player info string.
Team sizes is a mandatory array-of-integers parameter, representing numbers of players in each team. For example,
[2, 3, 2] would mean you want to match total 7 players in a game session, putting 2 of them in a first team, 3 in a second, and 2 in a third.
Note that every team is always considered playing against every other; if you want several teams to be allies, simply merge them into a single team (as from matchmaker’s point of view there’s no difference), and handle multiple-ally-teams logic in your game code.
A few examples:
[1, 1, ..., 1], i.e. put every player into their own team.
) is allowed. Uploading results after such a match is forbidden (as there’s no competition).
is allowed as well. Uploading results is forbidden too. It may be useful for matching with a server, if your single player game requires it.
Match tag is an optional string parameter for additional segregation of players. For example you can put game version + player’s region + game map + game mode into this parameter separated by underscore
_, so for one particular player it may look like
12.34_EUWest_TwoTowers_NoVehicles - therefore the player will only be able to match with other players playing the same version of the game (
12.34), located in the same region (
EUWest), and playing the same map (
TwoTowers) in the same mode (
Team sizes and match tag parameters constitute an identifier of match queue. Only players in the same queue may be matched together, i.e. their both team sizes and match tag must be the same.
Player info is an optional parameter containing arbitrary information about player. This information will be shared with all players in a successful match. You can put things like player’s IP address and port into this string, so players can connect each other using this information.
In return game client gets a match token. This token allows client to check status of matching.
To retrieve match status, use Get Match Status API endpoint.
If the game uses servers, the successful match response will also cointain information about server. See Game Servers for more information.
Now players can connect to each other using P2P connections or centralized server. BattlePlace.io doesn’t help with connections yet, so you need to implement that yourself.
BattlePlace.io generates a pair of random authentication tokens for every pair of players for your convenience. Clients may use these tokens to easily confirm peer’s identity. Also a pair of tokens is generated for every player for mutual authentication with server, if there’s one.
After match players or server should upload match results (using client or server API endpoints respectively). If there’s a server, clients are forbidden from uploading results. If multiple clients uploaded results, one result is selected randomly. All client results are recorded, so result cheating may be discovered later and cheaters be punished.
If game session didn’t happen (e.g. because players are unable to connect to each other for some reason), players should notify the system using the same API as for uploading results. Cancelled match doesn’t change players’ skill levels in any way.
Specific circumstances for considering match to be cancelled are up to you, the game developer: for example, you may want to count disconnection during the game as cancelling and not losing (even though it may be intentional). “Match cancelled” result is just one of the types of match results: if some players say match was cancelled, but others say it wasn’t, the same rules apply as for general case of different results.
If no players have uploaded match results, match is also considered cancelled.
BattlePlace.io supports forwarding players to your own game servers. It works in the following way:
Require Servercheckbox in the project’s settings.