Skip to content

Scrabble

Jump to bottom
Mike Leonard edited this page Jul 12, 2016 · 12 revisions

Introduction

Scrabble is still a working draft and is not yet supported on merknera.com. The specification below is subject to change.

Scrabble is a word game in which two to four players score points by placing tiles, each bearing a single letter, onto a gameboard which is divided into a 15×15 grid of squares. The tiles must form words which, in crossword fashion, flow left to right in rows or downwards in columns. The words must be defined in a standard dictionary. - Wikipedia, Scrabble

To implement a Tic-Tac-Toe, your bot must support receiving of RPCs - the current game state will be passed to you each time TicTacToe.NextMove is RPC'd and you need to return the position of your next move.

The RPCs you need to support are:

Bot Registration

To register your bot with Merknera you will need to call RegistrationService.Register. This must be called each time you bot starts up. Details of this RPC can be found here.

Use SCRABBLE as the value of the game property in the Register request body.

RPCs

Your bot must support the following RPCs on the same URL endpoint. All requests will be of the HTTP method POST and will send the Content-Type: application/json header.

Status.Ping (server)

With this request your bot acts as the client.

Status.Ping will be invoked on your bot to ensure that it is currently online. This RPC is standard across all bots and full documentation can be found here.

Scrabble.NewGame (server)

With this request your bot acts as the server.

Scrabble.NewGame will be invoked when a new game is scheduled and it will tell you basic details about the game - notably which game board, letters and dictionary are being used. For each of these you should check the SHA1 hash provided and download the file if you do not already have it. Files, along with their hashes, should be cached to save re-downloading them each time a game is played.

Request Body
{
    "jsonrpc": "2.0",
    "method": "Scrabble.NewGame",
    "params": {
        "gameid": 78,
        "players": "3",
        "gameboard": {
            "sha1": "d34898ec4cadc2b7b85da262e9320a9646655931",
            "url": "https://assets.merknera.com/scrabble/board_standard.json"
        },
        "dictionary": {
            "sha1": "caf2417c1d9fc2f2512922ae0514ebbc151fe789",
            "url": "https://assets.merknera.com/scrabble/dictionary_sowpods.txt"
        },
        "letters": {
            "sha1": "76d20712668ae0eb85d825b93acb71875a059a00",
            "url": "https://assets.merknera.com/scrabble/letters_standard.json"
        } 
    },
    "id": 1
}
Parameter Description
gameid The ID of the current game. This will be the same for all calls of Scrabble RPCs within the same game.
players The number of players in this games.
gameboard.sha1 The SHA1 hash of the game board file being used. You should check this hash and only download the game board if you do not already have it.
gameboard.url The URL where the game board for the current game can be downloaded. This will contain information about the placement of the word and letter multipliers. This will be a JSON file.
dictionary.sha1 The SHA1 hash of the dictionary file being used. You should check this hash and only download the dictionary if you do not already have it.
dictionary.url The URL where the dictionary for the current game can be downloaded. This will be a plain text file and have one word per line and all words upper-cased.
letters.sha1 The SHA1 hash of the letters file being used. You should check this hash and only download the letters file if you do not already have it.
letters.url The URL where the letters file for the current game can be downloaded. This will be a JSON file.
Response Body
{
   "jsonrpc": "2.0",
   "result": {
       "status": "READY" // or "PREPARING"
   },
   "error": null, // Only present if an error occurs
   "id": 1
}
Result Description
status Return READY if your bot already has all three files, otherwise return PENDING to indicate that you need time to download them - you should not download the files during the Scrabble.NewGame RPC processing. Whilst Merknera currently imposes no time limit on RPC calls it is anticipated that in the future it will. Your bot will not start playing any moves until your bot invokes the Scrabble.Ready RPC call.

Scrabble.Ready (client)

With this request your bot acts as the client.

If your bot was not ready to play when Scrabble.NewGame was called because you did not have a copy of all the relevant game files you would have responded with a status of PREPARING. To inform Merknera that you are now ready to play you should invoke Scrabble.Ready. As parameters you pass the hashes of the files you have downloaded for this game, Merknera will validate these hashes for you and return an error if they are not valid - this can help ensure that the files were not corrupted during transfer.

Request Body
{
    "jsonrpc": "2.0",
    "method": "Scrabble.Ready",
    "params": {
        "gameid": 7,
        "gameboard": "d34898ec4cadc2b7b85da262e9320a9646655931",
        "dictionary": "caf2417c1d9fc2f2512922ae0514ebbc151fe789",
        "letters": "76d20712668ae0eb85d825b93acb71875a059a00"
    },
    "id": 1
}
Parameter Description
gameid The ID of the current game. This will be the same for all calls of Scrabble RPCs within the same game.
players The number of players in this games.
gameboard The SHA1 hash of the game board file being used.
dictionary The SHA1 hash of the dictionary file being used.
letters The SHA1 hash of the letters file being used.
Response Body
{
   "jsonrpc": "2.0",
   "result": {
       "status": "OK"
   },
   "error": null, // Only present if an error occurs
   "id": 1
}
Result Description
status Return OK if all of the hashes were present and correct. If there were any issues with the hashes then these will be returned in error. If OK is returned your bot will be queued for games.

Scrabble.NextMove (server)

With this request your bot acts as the server.

Scrabble.NextMove will be called to get the type of play you wish to make and any tiles you wish to play. You will be passed the current state of the board and the tiles currently in your hand - you will always have 7 tiles in your hand so long as there are enough tiles left in the bag to facilitate this. This RPC will be called when it is your turn to play.

The possible types of play are:

  • PLAY: This is taking your turn in the standard way and placing tiles on the board. You must supply one or more tiles that you wish to play or an error will occur. On your next turn you will have been given new tiles to return your hand to 7 tiles if there are enough tiles left in the bag. You may only place one set of tiles per turn and tiles must be played either horizontally or vertically.
  • PASS: If you are unable to make a word with the tiles in your hand you must PASS. No tiles are expected with this move type if are tiles are passed they will be ignored. This ends your turn and you may not place any tiles until the next turn.
  • EXCHANGE: If you are unable to make a move with the tiles in your hand you may exchange the tiles in your hand for new ones. You will have to nominate which tiles you wish to exchange (between 1 and 7 inclusive). This ends your turn and you may not place any tiles until the next turn.
Request Body
{
   "jsonrpc": "2.0",
   "method": "TicTacToe.NextMove",
   "params": {
       "gameid": 78,
       "tiles": ["G", "T", "C", "D", "*", "A", "A"],
       "gamestate": [
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "C", "", "", "", "", "", "", ""],
            ["", "", "", "P", "A", "S", "T", "A", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "L", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "C", "O", "U", "C", "H", "", "", ""],
            ["", "", "", "", "", "", "", "U", "", "", "", "O", "", "", ""],
            ["", "", "", "", "", "", "", "L", "", "", "", "U", "", "", ""],
            ["", "", "", "", "", "", "", "A", "", "", "", "S", "O", "*", "T"],
            ["", "", "", "", "", "", "", "T", "", "", "", "E", "", "", ""],
            ["", "", "", "", "", "", "", "E", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
            ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
       ]
   },
   "id": 1
}
Parameter Description
gameid The ID of the current game. This will be the same for all calls of TicTacToe.NextMove within the same game.
tiles An array of strings of the current tiles in your hand. * denotes a blank tile that can be used as a substitute for any letter.
gamestate A 2D array of row and columns indicating any tile currently played in that position. * denotes a blank tile that can be used as a substitute for any letter.
Response Body
{
   "jsonrpc": "2.0",
   "result": {
       "type": "PLAY" // or "PASS" or "EXCHANGE"
       
       "exchangetiles": ["I", "O", "G"] // Only for use with type = EXCHANGE

       "playtiles": [
           { "row": 4, "col": 4, "tile": "H" },
           { "row": 5, "col": 4, "tile": "A" },
           { "row": 7, "col": 4, "tile": "P" },
           { "row": 8, "col": 4, "tile": "Y" }
       ] // Only for use with type = PLAY
   },
   "error": null, // Only present if an error occurs
   "id": 1
}
Result Description
type The type of move you are going to make. Either PLAY, PASS or EXCHANGE as per the details above.
exchangeTiles If you are making a move of type EXCHANGE then you must supply the list of tiles you are exchanging.
playTiles If you are making a move of type PLAY then you must supply here a list of tiles you are play and in which position on the board. The rows and columns are both 0 indexed, that is, valid values for both row and col are 0-14 inclusive. The tiles played must be either in the same column or row (i.e. horizontal or vertical) and must be contiguous except for any tiles you are taking advantage of that are already on the board.

Introduction

Home

Tutorial: Creating a Tic-Tac-Toe Bot

Bot Registration

Obtaining a Token

Registration Service

Merknera Online

Games

Tic-Tac-Toe

Scrabble

Clone this wiki locally