GameInterface

public interface GameInterface

To write a new game for the Bot!Battle! system, a java class must be written that extends this interface with exactly the following signature.

public class Game implements GameInterface

External Libraries and Class Path

For your convenience in generating JSON strings, version 1.1.1 of the following library is provided in the class path of the GameManager.

https://code.google.com/p/json-simple/

If you'd like or require additional libraries they can be added to the class path easily by modifying the following export in /BotBattleApp/custom_modules/BotBattlePaths.js

module.exports.gameManagerClassPath

Simplified Pseudocode for the Main Game Loop

This has been simplified to emphasize the order in which the game interface methods are called. The actual Main Game Loop can be found in ArenaGameInstance.java. Familiarizing yourself with the game loop's structure and the order and timing in which the interface methods are called should make the life of a game developer much easier.

        runArenaGame() {
         
          game.initializeGame(gameType)
          
          game.getInitialGameStateJSON()
          
          while (!game.isGameOver()) {
            int player = game.getPlayerForCurrentTurn()
            
            if (player == 1) {
                board = game.getPlayerOneBoard()
                timeout = game.getBotTimeoutInMilliseconds()   
            } else {
                board = game.getPlayerTwoBoard()
                if (gameType == BOT_VS_HUMAN)
                    timeout = game.getHumanTimeoutInMilliseconds()
                else
                    timeout = game.getBotTimeoutInMilliseconds()
            }
            
            move = Get move from player(board, timeout)
        
            reasonMoveWasInvalid = game.validateMove(move, player);
            
            if (reasonMoveWasInvalid == null) 
              game.updateBoard(move, stderr, player);
              game.getMidGameStateJSON(jsonSafeMove, jsonSafeStderrArray, player)
            } else {
              Send invalid move message to TestArena
            }
          }
          
          game.getFinalGameStateJSON()
        }

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`getBotTimeoutInMilliseconds()` Number of milliseconds to wait for a bot's move (via their stdout stream) before giving up and reporting a "null" move.
`java.lang.String`	`getCompleteBoard()` Currently unused The idea was to combine both player 1 and player 2's view of the board into an overall string representation of the board.
`java.lang.String`	`getFinalGameStateJSON()` A string containing a valid FinalGameState as defined in the documentation.
`int`	`getHumanTimeoutInMilliseconds()` Number of milliseconds to wait for a human's move (via their stdout stream) before giving up and reporting a "null" move.
`java.lang.String`	`getInitialGameStateJSON()` A string containing a valid InitialGameState as defined in the documentation.
`java.lang.String`	`getMidGameStateJSON(java.lang.String jsonSafeMove, java.lang.String jsonSafeStderrArray, int player)` A string containing a valid MidGameState as defined in the documentation.
`java.lang.String`	`getName()` Currently unused.
`int`	`getPlayerForCurrentTurn()` Return the player number of the current turn (iteration of the game loop).
`java.lang.String`	`getPlayerOneBoard()` Called when getPlayerForCurrentTurn() has indicated that it's player 1's turn.
`java.lang.String`	`getPlayerTwoBoard()` Called when getPlayerForCurrentTurn() has indicated that it's player 2's turn.
`void`	`initializeGame(GameType gameType)` Called before any other interface methods.
`boolean`	`isGameOver()` Used as the control for the main game loop.
`void`	`updateBoard(java.lang.String move, int player)` Update internal state of the board based on a valid move.
`java.lang.String`	`validateMove(java.lang.String move, int player)` Determine if the player's move was valid, and provide the reason if not.

- Method Detail
  - getName
```
java.lang.String getName()
```
    Currently unused.
    
    Returns:
    
    A user friendly game name. E.g. Save The Island or Tic-Tac-Toe
  - initializeGame
```
void initializeGame(GameType gameType)
```
    Called before any other interface methods. Must setup the game to be ready to play. Most likely involves initializing the board and any private members. The default no-arg constructor is also called before this if you'd like to perform some setup there.
    
    Parameters:
    
    gameType - A GameType enum specifying BotVsBot or BotVsHuman.
  - getInitialGameStateJSON
```
java.lang.String getInitialGameStateJSON()
```
    A string containing a valid InitialGameState as defined in the documentation.
    
    Returns:
    
    A string containing a valid Initial GameState as defined in the documentation.
  - getMidGameStateJSON
```
java.lang.String getMidGameStateJSON(java.lang.String jsonSafeMove,
                                     java.lang.String jsonSafeStderrArray,
                                     int player)
```
    A string containing a valid MidGameState as defined in the documentation. The move and stderr messages are recommended to be included in the debugData attribute of the returned JSON String. Your client side game.js file can then display these in the lists at the bottom of the Test Arena, as done for the Save The Island game.
    
    Parameters:
    
    jsonSafeMove - The player's move, cleaned with JSONSimple's JSONValue.toJSONString(...) method.
    
    jsonSafeStderrArray - A String representing a JSON array of new line separated strings received from the player since the last turn, cleaned with JSONSimple's JSONValue.toJSONString(...) method.
    
    player - Either 1 or 2.
    
    Returns:
    
    A string containing a valid Mid GameState as defined in the documentation.
  - getFinalGameStateJSON
```
java.lang.String getFinalGameStateJSON()
```
    A string containing a valid FinalGameState as defined in the documentation.
    
    Returns:
    
    A string containing a valid final GameState as defined in the documentation.
  - validateMove
```
java.lang.String validateMove(java.lang.String move,
                              int player)
```
    Determine if the player's move was valid, and provide the reason if not. If the move was invalid, please provide a helpful description of the violation. This description will be sent to the Test Arena, along with the exact move text generated by the bot or human player to be logged in the Event Log.
    
    Parameters:
    
    move - The last line received from the players standard output stream
    
    player - Either 1 or 2.
    
    Returns:
    
    If the move was valid: null If the move was invalid: [String describing the reason the move was invalid]
  - updateBoard
```
void updateBoard(java.lang.String move,
                 int player)
```
    Update internal state of the board based on a valid move. Will be called only if move was valid according to validateMove. Expected to evaluate and store any changes to the game state as a result of this move. Note: getMidGamestate will be called immediately after this.
    
    Parameters:
    
    move - The last line received from the players standard output stream
    
    player - Either 1 or 2.
  - isGameOver
```
boolean isGameOver()
```
    Used as the control for the main game loop. Once this returns true, the game is considered over and the GameInstance will call getFinalGameStateJSON.
    
    Returns:
    
    true if the game is over, false otherwise.
  - getBotTimeoutInMilliseconds
```
int getBotTimeoutInMilliseconds()
```
    Number of milliseconds to wait for a bot's move (via their stdout stream) before giving up and reporting a "null" move.
    
    Returns:
    
    Timeout for bot players.
  - getHumanTimeoutInMilliseconds
```
int getHumanTimeoutInMilliseconds()
```
    Number of milliseconds to wait for a human's move (via their stdout stream) before giving up and reporting a "null" move.
    
    Returns:
    
    timeout for human test arena player
  - getPlayerForCurrentTurn
```
int getPlayerForCurrentTurn()
```
    Return the player number of the current turn (iteration of the game loop). This player will be asked for a move, and that move will be submitted to the next calls to validateMove and updateBoard.
    
    Returns:
    
    Either 1 or 2
  - getPlayerOneBoard
```
java.lang.String getPlayerOneBoard()
```
    Called when getPlayerForCurrentTurn() has indicated that it's player 1's turn. This string will be sent verbatim to standard input stream of the bot playing as player 1.
    
    Returns:
    
    Player 1's view of the game board.
  - getPlayerTwoBoard
```
java.lang.String getPlayerTwoBoard()
```
    Called when getPlayerForCurrentTurn() has indicated that it's player 2's turn. This string will be sent verbatim to standard input stream of the bot playing as player 2. Or ignored if player two is a human. Note in the case of human players in the test arena, it's the job of game.js to display the human input elements to the user. The recommendation is to include the necessary information to generate the human input elements in the gameData attribute of the midGameState preceding the human's turn.
    
    Returns:
    
    Player 2's view of the game board.
  - getCompleteBoard
```
java.lang.String getCompleteBoard()
```
    Currently unused The idea was to combine both player 1 and player 2's view of the board into an overall string representation of the board. User feedback of the test arena indicated they'd rather see the actual playerOne and playerTwo boards using the other getters above. In all likelihood this method is not needed at all and could be removed from the interface.
    
    Returns:
    
    An overall view of the game board.

Interface GameInterface

External Libraries and Class Path

Simplified Pseudocode for the Main Game Loop

Method Summary

Method Detail

getName

initializeGame

getInitialGameStateJSON

getMidGameStateJSON

getFinalGameStateJSON

validateMove

updateBoard

isGameOver

getBotTimeoutInMilliseconds

getHumanTimeoutInMilliseconds

getPlayerForCurrentTurn

getPlayerOneBoard

getPlayerTwoBoard

getCompleteBoard