A backend service to enable turn based multiplayer games on the Quarter Spiral platform.
The service must be accessed by HTTPS. You have to activate turn based services through devcenter to make use of any API endpoint.
All endpoints that return information about a match will return it in this way.
The response body will be a JSON encoded object of match data like this:
{
"match": {
"uuid": MATCHUUID,
"game": GAMEUUID,
"players": [
{
"uuid": UUID1,
"meta": {
"faction": 1,
"color": "#FF0000"
}
}
],
"invitations": [
{
"uuid": INVITATION_UUID1,
"player": INVITED_PLAYER_UUID
},
{
"uuid": INVITATION_UUID2,
"player": ANOTHER_INVITED_PLAYER_UUID
},
],
"meta": {
"name": "Some match"
},
"started": true,
"ended": false,
"results": null,
"turns": [
{
"player": UUID1,
"moves": [
{
"player": UUID1,
"data": {
"unit": 123,
"action": "move",
"direction": "left"
}
}
]
}
],
"currentPlayer": null
}
}turns is an array of moves. For the description of a move please see the submit a move section
results is an arbitrary object that can be set by a game
Apps or user. User can only be used when the player parameter is specified and is the UUID of the user.
GET /matches
- player: UUID of a player that restricts the returned matches played by that player
- game: UUID of a game that restricts the returned matches to only matches of those game
Empty.
Array of match data (see at top).
Apps or user. User must be a player of the match that is going to be retrieved
GET /matches/:MATCH-UUID:
Empty.
Match data (see at top).
Apps or user. User only if he is the only user in the players list. This will run the createMatch script.
POST /matches
JSON encoded object of match data like this:
{
"match": {
"game": GAMEUUID,
"players": [
{
"uuid": UUID1,
"meta": {
"faction": 1,
"color": "#FF0000"
}
}
],
"meta": {
"name": "Some match"
}
}
}Match must have a game set. Players must have a uuid set. Meta data for players and for matches is any arbitrary object.
Match data (see at top).
The returned match object comes with additional info. Especially the UUID of the match will be used for further reference.
Does only work for not started games. This will run the addInvitation script.
Apps or user. User must be a player of the match.
POST /matches/:MATCH-UUID:/invitations
JSON encoded object of match data like this:
{
"invitation": {
"player": UUID1
}
}UUID1 is the UUID of the player you want to invite to the game. Inviting an already invited player has no effect but does not result in an error, either.
Match data (see at top).
Only works for not started matches. This will run the acceptInvitation script.
Apps or user. User must be the player on the invitation.
POST /matches/:MATCH-UUID:/invitations/:INVITATION-UUID:
Empty
Match data (see at top).
Does only work for not started games. This will run the declineInvitation script.
Apps or user. User must be the player on the invitation.
DELETE /matches/:MATCH-UUID:/invitations/:INVITATION-UUID:
Empty
Match data (see at top).
To start a game the next turn endpoint must be hit.
Apps or user. User must be the first player of the match.
Only works for matches that are started already and not ended yet. This will run the nextTurn script.
Apps or user. User must be the current player of the match. If a match is not started yet user must be the first player of the match to start it.
POST /matches/:MATCH-UUID:/turns
Empty
Match data (see at top).
Only works for matches that are started already and not ended yet. This will run the newMove script.
Apps or user. User must be the current player of the match.
POST /matches/:MATCH-UUID:/moves
JSON encoded object of match data like this:
{
"move": {
"player": UUID1,
"data": {
"unit": 123,
"action": "move",
"direction": "left"
}
}
}The data can be an arbitrary object.
Match data (see at top).
All scripts are written in JavaScript. Every script is called in the context of the match itself. Every script has always to return a match object which is then stored as a replacement for the match.
WIP
- addInvitation(invitation)
- acceptInvitation(invitation)
- declineInvitation(invitation)
- startGame()
- nextTurn()
- addMove(move)
All methods return the match itself so calls can be chained.
You can set errors on games using the errors field. Those will not be saved but exposed through the response of the API endpoint to the client that has sent the request.
This function is allowed to return not a game object but an empty object with just the errors property set. This way you can prevent matches from being created.
Just accept an invitation:
{
addInvitation: function(invitation) {
return this.addInvitation(invitation);
}
}Forbid the creation of an invitation:
{
addInvitation: function(invitation) {
return this;
}
}{
acceptInvitation: function(invitation) {
return this.acceptInvitation(invitation);
}
}{
declineInvitation: function(invitation) {
return this.declineInvitation(invitation);
}
}{
nextTurn: function() {
if (!this.started) {
return this.startMatch();
}
return this.nextTurn();
}
}{
newMove: function(move) {
return this.addMove(move);
}
}