Developer’s Guide

Basic Client Sequence

with selected backend
against other players
game session
to update ratings

Authentication

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.

Matching

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:

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 (NoVehicles).

Note

This is a bad example actually (and is put here purely for explanatory purposes), as you probably should not put that many parameters into match tag. Making match tag more specific means your playerbase becomes more fragmented, and players may have hard time matching an opponent or teammate. Consider putting into match tag only strictly required parameters.

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.

Playing

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.

Tip

Encode player's connection parameters like IP address and port into player info string when requesting match, to make this information available to all players in a match. Servers can specify their server info too.

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.

Uploading Results

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.

Cancelling Match

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.

Game Servers

BattlePlace.io supports forwarding players to your own game servers. It works in the following way: