Create multiplayer experiences

There's nothing quite as thrilling as a multiplayer game. Learn how you can make the most our multiplayer games.

Types of games

Not all Gamezop games support multiplayer experiences. Here is a list of our games on which you can create real-time multiplayer experiences for your users.

There are 2 types of multiplayer games:

Type	Description
Sync	Games that are inherently multiplayer, such as Chess, Pool, Ludo etc. These games are designed to be played by more than 1 player where all players play together in a common arena / board.
Async	Games that are single-player in nature. For instance, a Fruit Slice game is a single-player game. Gamezop creates a multiplayer experience for such games by matching and allowing both of them to see each other's scores while they play the single-player games. So while it's a single-player game, you and your opponent start together and you can both see each other's scores update in real-time. Each player gets a per match. At the end of the match, the player with the highest score wins.

Generating game links for multiplayer games

When you open any game url that you receive on our All Games API, the game opens a single-player experience by default.

To enable a multiplayer experience, you need to follow these steps:

1. Generate a roomDetails object

2. Base64 encode the object

3. Create the multiplayer game url

4. Get multiple users to open the multiplayer game together

Generate a roomDetails object

This carries all the details we need to create a match between your users. roomDetails is a JSON object with the following values:

Term	Description
roomId (Mandatory)	This is a free-form string that you must pass. Only players with the same roomId are matched together. Examples: If you are operating a casual games site, you can open a game with the same roomId for all users, increasing the liquidity pool. If you have a chat app and you want 2 players in a chat or a few players in a group to be matched with one other, you may have a unique roomId for each chat group. If you are a skill-gaming platform, you may want to have the roomId based on the entry-fee or skill-level, or a mix of both.
user	A JSON object with details of the user for who you are opening the game. In some games such as Pool, Chess etc., passing this value allows us to populate the profile picture / name within the game's UI as well. If you do not pass these values, our system will use some generic names and photos when the game is opened. The user object must contain: name: Name of the user sub: A unique identifier for the user photo: A URL for the user's profile photo
maxPlayers	The maximum number of players you want us to group into a single match. In case of some games like Chess, even if you pass maxPlayers as more than 2, the system will only group 2 players into a match as Chess can't be played by more than 2 players. However, in case of single-player games, we can group together up to 5 players in a room. While everyone will play the single-player game, they will all be able to see, in real-time, the current scores of the other players in the same match. The maximum acceptable value is 5. If you pass a bigger number, the system will keep it as 5. If you don't pass any value, this will generally be 2 or 5 depending on the game.
minPlayers	The minimum number of players needed for a match to start. Generally, we recommend keeping this as 2. However, if you have a use-case where you only want to start a game if at least say 3 players join, you can use this value to do so. In case of a game like Ludo, you may want to only have 4 player matches, so you can keep the minPlayers value as 4. Once again, please note that this value will not hold in case of all games. If you pass minPlayers as 4 in a Chess game, the system will still group only 2 players per game. If you don't pass any value, this will default to 2.
maxWait	The maximum amount of time (in seconds) for which the matchmaking process should go on. If minPlayers are not found within that time, the matchmaking will stop and the user will be shown a screen that says no match was found. The user will be given an option to retry finding a match. Defaults to 60 if you don't pass any value. Maximum acceptable value is 600. Minimum acceptable value is 5.
rounds	The number of attempts you want the users to have in the match. This is also game dependent. In a game like Chess, we would only allow a maximum of 1 round per match. However, in the case of single-player games, you may want to allow the user to play up to 3 times to make a high score. In that case, you can pass rounds as 3. For deciding the winner of the match, our system considers the best score of each player in the match from across all their rounds. Defaults to 1 if you don't pass any value. Maximum acceptable value is 5.
cta	Client callback method name (Android/iOS JS bridge name and method). This is the method name which Gamezop will call on client to send events related to match.
text	Text you want to show on bottom button on match over / no match found cases. This key accepts only these values empty string "", go_home or play_again Defaults to go_home if you don't pass any value.
allowBots	This is a boolean value. In case you feel that your app or website does not have enough liquidity, and you want your players to be matched with a bot if no opponent is found, then you can pass this as true. The default value is false. The user is matched with a bot at the end of your maxWait time period. To use this feature, you will need to give the Gamezop team a set of bot user objects - your Gamezop Account Manager will help you with this during the initial setup. Please note that this feature is only supported in a limited set of games.
gameConfig	Game-specific string which allows you to initialise the game in a specific mode. For instance, a Pool game may have 2 modes: 8 Ball and 9 Ball. Using the gameConfig value, you can define which mode to initialise the game in. To see the list of games that support this, along with their specific gameConfig values, visit this sheet.

Base64 encode the object

Let's assume this is the final roomDetails object you've generated and you now want to encode it:

{
        "roomId": "ABC01", 
        "user": {
                "name": "John Doe",
                "photo": "https://example.com/photos/user-1.jpg",
                "sub": "xyz-123"
        },
        "maxPlayers": 4,
        "minPlayers": 2,
        "maxWait": 60,
        "rounds": 1,
        "cta": "BRIDGE.updateState",
        "text": "go_home",
        "allowBots": false
}

If you're using Javascript, store this in a const named roomDetails, and then run:

encodeURIComponent(btoa(JSON.stringify(roomDetails)));

You'll get the following value:

eyJyb29tSWQiOiJBQkMwMSIsInVzZXIiOnsibmFtZSI6IkpvaG4gRG9lIiwicGhvdG8iOiJodHRwczovL2V4YW1wbGUuY29tL3Bob3Rvcy91c2VyLTEuanBnIiwic3ViIjoieHl6LTEyMyJ9LCJtYXhQbGF5ZXJzIjo0LCJtaW5QbGF5ZXJzIjoyLCJtYXhXYWl0Ijo2MCwicm91bmRzIjoxLCJjdGEiOiJCUklER0UudXBkYXRlU3RhdGUiLCJ0ZXh0IjoiZ29faG9tZSIsImFsbG93Qm90cyI6ZmFsc2V9

Create the multiplayer game url

If you are going to send user details or a wide variety of roomId values, you may need to generate the final game link on the client instead of the server. If you aren't using those values, then you can manually generate a link and send all your users to the same link and they will keep getting matched with one other.

Generating the link is extremly simple. Once you have the encoded roomDetails value, just append it to the URL you receive from the All Games API. The final URL will be of the following structure:

{url-from-All-Games-API} ?roomDetails= {encoded-object}

Get multiple users to open the multiplayer game together

Once you've set up the system to generate these links, you need to have multiple users from your platform open the links together. When a user opens one of these links, our matchmaking module tries to find other users from your Property ID with the same roomId, and matches the users together in a multiplayer experience.

Receive data on match winners

In case you want a callback with details of the winners at the end of each match, you will have to provide 2 APIs for it. Detailed here.