Using the Bot Playtesting Toolkit - Itangalo/Bot-Playtesting-Toolkit Wiki

The Bot Playtesting Toolkit (BPT) is built as scripts to run with Google spreadsheets. Any large amount of data used by your game, for example data for cards, player stats, and board/map layout, can be kept in spreadsheets. This is complemented by code, written in the coding environment that comes with Google spreadsheets. The Bot Playtesting Toolkit consists of a framework and number of pre-made tools to use. You complement this by writing a so-called module, that BPT calls when simulating games. You will have to write quite a bit of code, depending on how complex your game is, but you will also note that BPT saves you a lot of time and also helps you keep the code well structured.

Getting started

If you want to try out BPT, these are good steps:

  1. Make a copy of the BPT spreadsheet template. It includes all the scripts for BPT, as well as two example modules.
  2. In the extensions menu, click apps script to open the coding environment. You will now see a lot of files in the left sidebar and some JavaScript code in the main window.
  3. In the first file (already selected), click the run button. This will run a simulation of the game example1, but more importantly it will open a dialogue where you can approve that the script reads from your Google spreadsheets. (This is required to be able to read from data from the spreadsheet, and there was no way of restricting access to only the current sheet. Sorry.)
  4. Start experimenting. You will want to look in the examples files, as well as in the documentation here in the wiki.

If you like the Bot Playtesting Toolkit, and are used to working with version control, you will sooner or later want to install the Chrome extension Google Apps Script GitHub Assistant. It allows working against a GitHub repository (such as this) in the Google apps script coding environment.

Modules and the big picture

The Bot Playtesting Toolkit follows the overall flow described below when simulating games. At each step it calls some particular functions that hold the code that is specific for your game.

  1. Some global variables are set up, mostly being empty. Which module (game) to use is determined, as well as how many iterations to run.
  2. A 'seed' for the initial game state is stored. The seed is built by the function buildInitialData(), to a large degree by reading information from the spreadsheet. The function can also store any information that does not change within or between games in the global variables.
  3. A first game session is prepared. Some parts of the initial game state seed are processed automatically, and any extra preparations are done by the function preIteration(). After this, the global variable gameState holds all the information of the game.
  4. The function gameOver() is called. If it returns false, the toolkit notes that a new round starts and calls playRound(). Then it runs step 4 in this list again, until the game is over.
  5. When the game is finished, buildStatistics() is called. This returns any data from gameState that should be used for statistics over all the games.
  6. If the required number of game iterations has not yet been reached, the toolkit goes back to step 3 in this list.
  7. When all game iterations are done, the stored data is processed and displayed.

The code you write to run your game is stored in a module. This has two points. One is that the toolkit itself can be updated and changed without you having to rewrite your code, and the other is that it makes it possible to quickly switch between two versions of your game if you want to compare them.

The module needs the following.

BPT comes with (currently) two example modules, which help show how modules can be built and stored in a number of files to help navigating the code even when it grows. You could copy the files from one of these examples as a starting point.

Which module to use is set when calling the simulate function. Calling simulate('myModule', 1000), for example, will run 1000 simulations of the game in myModule. If the simulate function is called from the spreadsheet, the result is output in the spreadsheet. If it is called from the coding environment, the result and log messages are displayed in the log window.

Why Google spreadsheet?

Building BPT on Google spreadsheet brings some limitations, not least a maximum 30 seconds execution time. But it lowers the threshold for getting started. There might be a future version of BPT written in Python (or something else) and is run locally on your computer, allowing long execution times and both reading and saving data to files.