Game Controller Implementation Specs

This page describes the design and specs for a simple reference implementation of a game controller. This controller is intended for testing the fluency games. It will:

  • allow an experimenter to specify a pre-defined sequence of games
  • present that sequence of games to the student
  • log the user data with an ID identifying the student

The implementation will be a simple web server that lets users run static problems for supported game engines.


The user will start on a page that prompts for 3 things:

  • The player's name (text field).
  • The type of game engine (dropdown).
  • The problem sequence (aka stage).

The stage choices might be presented as a dropdown menu or a plain text field. The latter would mean only people who know the stage IDs can run the games, which might be a good idea to avoid collected log data from uninvited players.

After entering those pieces of info, the game controller would instantiate the game engine and allow the user to play through the selected sequence of problems.

After finishing the game, the log data should be sent back to the server for storage. It might be nice to provide a way to retrieve the log data without having to ssh into the server.


From the outside world, a game controller running on a server should be accessible via a REST API. This section describes the API entry points relative to a base URL. An example is hosted here at fluencydemo.

The specs below is a very early draft of how this might be set up. In particular, perhaps we should have the playerID always be an explicit toplevel parameter instead of relying on session data. And TBD is how game results are stored.

GET /stage/:stageID?

When a stageID is specified, this returns the Stage specified. Without a stageID, this returns a dictionary with one key, stageIDs, that lists the IDs of stages available to the player.

GET /stage/:stageID/questionSet/:questionSetID?

When a questionSetID is specified, this returns the QuestionSet? specified. Otherwise, it returns a dictionary with one key, questionSetIDs, that lists the IDs of question sets in the given stage available to the player.

GET /stage/:stageID/questionSet/:questionSetID/engine

Returns the GameEngine? that is suitable for running the given question set.

POST /stage/:stageID/questionSet/:questionSetID/results

Use this method to save the results of a run through the given QuestionSet?. The request body should be the raw output from the game engine.