Skip to main content

Player vs player session

With the API, you can create a game session that returns embeddable URLs that can be used by your application to connect two remote players.

Parameters

The POST Create an embeddable game session endpoint allows you to specify the configuration that fit the needs of your App.

ParameterTypePlanComments
gameTyperequiredEnum (TicTacToe, Connect4 , Gomoku, Battleships, Chess)All
languagerequiredEnum (en, fr, es, vi, ru, pt-br, cz, id, de)All
inactivityTimeoutoptionalNumberULTRA & MEGATime per turn in seconds. How much time each player has to make a move. Set to 0 if you want infinite time per turn.
timerTimeoutoptionalNumberULTRA & MEGATotal time per player in seconds. How much time each player receives to complete a single game. Set to 0 if you want infinite time per player.
boardSizeoptionalStringULTRA & MEGAThe size of the board, appliable only for Tic-Tac-Toe (3x3, 5x5) and Connect 4 (7x6, 8x7, 8x8, 9x7, 9x9). If no boardSize is specified, or if the value is wrong, it fallbacks to the classic size.
maxGamesoptionalNumberULTRA & MEGAMaximum number of games per session. If not specified, the game session has unlimited games. We recommend setting it to odd values (1, 3, 5) to try to have a winner.
info

Keep in mind that the timerTimeout parameter should always be greater than the inactivityTimeout.

Sample payload

{
"gameType": "TicTacToe",
"language": "en",
"inactivityTimeout": 30,
"timerTimeout": 60
}

Sample response

{
"uid": "wdnH6gXc1",
"playUrl": "https://papergames.io/en/r/wdnH6gXc1/embed/play",
"watchUrl": "https://papergames.io/en/r/wdnH6gXc1/embed"
}

The playUrl field contains an embeddable URL that can be integrated into an iframe for a user to play.
The watchUrl field contains an embeddable URL that can be integrated into an iframe for a user to watch the game as a spectator. The uid field contains the identifier for the game session. It can be combined with Webhooks to update your system with the game score.

tip

To have a better understanding of the flow, head up to the Getting started section where you can test our API with a short and practical example (5 minutes ⏱).

Timing considerations

Games like Tic-Tac-Toe have a completion average of 15 seconds. Chess completion average is 10 to 15 minutes. Ensure you set the timing options to a reasonable value for average players to feel comfortable. If you're unsure about the timing values, you can follow the recommendations below.

GameinactivityTimeouttimerTimeout
Tic Tac Toe30120
Connect 440240
Battleship40180
Gomoku40300
Chess01200

If you don't want to stress out the players with timers, simply set both inactivityTimeout and timerTimeout to 0.

Game session expiration

The game sessions don't expire automatically. Therefore, you can create one and start it five days later. They expire only under the conditions below.

  • Player1 joins and leaves (e.g., when the iframe is destroyed from the DOM), without starting a game with Player1
  • Player1 and Player2 are matched together. As soon as one of them leaves the game (e.g. when the iframe is destroyed from the DOM)