Design and Implementation Notes


A glossary and operational definitions for the various parts in implementing fluency tasks.

Game Controller

See DesignAndImplementation/GameController for a spec of an example implementation.

The game controller is the toplevel entity that determines which levels are presented to the user, and instantiates levels and game engines. The game controller may be a website, standalone application, or a part of a different product such as when presenting fluency tasks in the Middle School Math Cognitive Tutor.

In order to start a game, the game controller selects a level and instantiates a game engine. It is TBD how levels and game engines are linked together:

  • One possibility is to have the level specify a specific game engine and skin.
  • Another is to have an abstract "task" entity which is referenced by questions and by game engines. This creates a many-to-many relationship between questions (or question sets) and game engines, which allows the game controller to choose from multiple game engines to complete a single level or question set. DD: Personally I think this is overkill.

Question Hierarchy

The question hierarchy defines grouping of mathematical tasks the player experiences.

  • Level or Stage: groups together question sets of similar difficulty and skills; specifies medal cutoffs; shares parameters. Levels are presented to the player by the Game Controller, which may present them sequentially, by user selection, or some other criteria.
    • Question Set: One "run" of the game for the player. Scores are tallied up after each question set.
      • Question Subset: A group of consecutive questions that share some characteristic, e.g. the target fraction in the fraction-comparison driving game engine. This might not be applicable to all game engines, in which case we can just have a single question subset.
        • Question: A task for the player that requires a single action or decision.


  • "Stage" may be a better name than "Level" so as to avoid confusion when talking about "levels of the question hierarchy".
  • This hierarchy is very similar to what Cognitive Tutor currently uses in unit files. Perhaps we should adopt the same terminology.
  • The naming and structure affects data collection and processing. We may want to adopt terminology from DataShop? to ease data export to that format.

Game Engine

A game engine is the code and resources that runs a single type of fluency task that employs particular game mechanics. Examples include the fraction comparison engine and number line engine.

Game engines can have variants called skins. Each skin looks different but share the same game mechanics. An example is the snowboarding and racing car variants of the fraction comparison game engine.

Game engines will be implemented with HTML5 technology (HTML, CSS, JavaScript), using open-source JavaScript Libraries.