Social Gaming Platform
This semester, you will create a platform for developing social games that can be played amongst friends or strangers. Your focus is on creating the engine that allows users to easily and simply develop social games that are highly customizable. Those of you familiar with video game collections like the Jackbox Party Pack or social games like Coup, Werewolf, Loveletter, or Citadels will already be acquainted with the basic idea.

You will create a game server that can be configured by the person running the server to allow games to be played. The configuration of the server will be specified in JSON. Similarly, the specification for a single game will be in JSON. A game specification will define the state that a game must maintain as well as the rules of the game. You may think of the specifications as being written in a domain specific programming language that your game server will interpret.

When a user connects to the game server, they may either join a game or create a new game amongst those served. When a new game is created, it may be configured by the creating player, who is designated as the “owner” of the game session and will have admin controls over the game. The owner may configure the game and create it, after which they will receive an “invite code”. Other players connecting to the game server may join the game by specifying the invite code. Note, the owner of the game is not a player. If they wish to play the game, they must also join.

You may imagine that a typical session works as follows. Several friends get together and decide to play a game. One person connects to the game server via their computer and configures and then starts the game. The game runs on that main computer, with the primary screen observable by all players. Separately, each player may log into the server and join the game on their phones. Each individual player can interact with the game solely through their phones. Any player specific instructions or actions will be sent to specific players on their phones, while any global information will be displayed to all players on the main game screen.

To start, this is all you are given. More details on the exact nature of, e.g., the domain specific language for specifying games and other details will be provided over time. Some will be provided sooner, some will be provided later. All may even be incorrect.

Implementation Constraints
The core project including all business logic will run on a server and be written in C++. Users will be able to access the system via web applications that present a simple interactive view. One example of a simple chat room that already provides this behavior has been provided for you. Following this design, matters of presentation are handled on the client. You may be asked to contruct another (different) client as a requirement.

Does this page define your project requirements?
In short, no. This page provides initial directions that should be helpful in planning the first iteration.

The description of the project as presented here is incomplete. It is not intended to be complete. In fact, it may not even be correct or stable. You should expect the requirements of the project to be flexible and change over time as you interact with the customer. If there are deficiencies in your design, your requirements may even change to make the deficiencies hurt more.

Remember that you should iterate toward a solution, demonstrating your progress and asking for concrete feedback about current behavior of the system and desired behavior of the system. In order to do that, you always need a running system. Make that a priority. You can also identify core abstract behaviors and design your system such that concrete changes can be made with marginal burden.

Game Specification Structure
A game specification is defined in a standard JSON formatted file. The top level will always be a map containing six elements that define the general configuration of the game, the constant data used by the game, the global variable state of the game, per player state, per audience member state, and the actual rules of the game. Thus, the simplest possible valid game specification is:

{
  "configuration": {
    "name": "Zen Game",
    "player count": {"min": 0, "max": 0},
    "audience": false,
    "setup": { }
  },
  "constants": {},
  "variables": {},
  "per-player": {},
  "per-audience": {},
  "rules": {}
}
This defines a game with no players, no audience, no state, and no rules that does nothing. The configuration contains enough information that the game could be selected and started by a game owner, and it would promptly end.

Configuration
The configuration of a game controls general settings that may assist in game creation and game management for the owner. This includes such things as (1) the name of the game type to show when selecting the type of game to create (2) specifying any data that may be uploaded by the owner, e.g. for quiz based games, (3) specifying minima and maxima for the number of players, and (4) specifying whether additional game joiners beyond the players can participate as audience members.

"setup" names a map of settings that can or must be configured by the owner of the game upon game creation. This can include such things as the numbers specifying the number of rounds to play. If the value for a setting is an integer, boolean, or string literal then that value constitutes the default value. These need not be changed by the owner upon creation but can be. Otherwise, the value must be a map of the form:

{
  "kind": <<data kind>>,
  "prompt": <<Description of what data the owner should provide>>
}
Here "kind" may map to "integer", "string", "boolean", "question-answer", "multiple-choice". The latter two indicate JSON file formats whose data can be uploaded by the game owner upon creation.

Constants, Variables, Players, and the Audience
The constants, variables, per-player, and per-audience sections define state that may be accessed by the game rules during play. The constants and variables sections contain maps from names to values. The per-player and per-audience sections define maps that exist for each player of a game and each audience member. Top level names must be unique. Values may themselves be (1) maps from names to values, (2) lists of values, or (3) literal strings, numbers, or booleans. New top level names/keys within these sections cannot be added by rules. They must be predetermined within the specification.

Note that some additional forms of game state must be accessible via rules, as well. In particular, the "players" name specifies a list of the player data maps, and the "audience" name specifies a list of audience data maps. Every player map also implicitly has a "name" key that maps to the unique name that the player selected upon joining the game.

Rules
Most of the actual game behavior is controlled by the rules section and the semantics of the rules therein. Essentially, these rules define a custom embedded domain specific language for actions that may be taken within a game. Note that it may be possible to validate some basic correctness properties of rules. These rules are subject to change and will be refined via discussion. They do, however, provide an appropriate jumping off point for planning and designing a good solution.

Each individual rule is a map of attributes describing the rule. Lists of rules define a sequence of operations in which each rule must be performed in sequential order. Note that apparent parallelism will exist, but no use of explicit parallelism or threads is required as a part of this project. The different forms of rules are explored within the remaining sections of this document.

Control Structures
Control structures determine when and how different groups of instructions may execute. This includes concepts like sequencing, branching, and parallelism. Note that parallelism in this project is only from the perspective of the players. No parallel control structures actually require hardware level parallelism in software design or concurrency level primitives like threads.

Foreach
{ "rule": "foreach",
  "list": <<list, list expression, or name of a list object>>,
  "element": << name for list element object within the rules below >>
  "rules": [
    << Rules to execute on every element of the given list >>
  ]
}
Loop
{ "rule": "loop",

  "until": << Condition that may fail >>,
  OR
  "while": << Condition that may fail >>,

  "rules": [
    << Rules to execute on every element of the given list >>
  ]
}
Inparallel
{ "rule": "inparallel",
  "rules": [
    << Rules to execute *in parallel* rather than *in sequence* >>
  ]
}
Note that this creates the potential for bugs even in a single threaded scenario depending on your design. It may be refined in the future.

Parallelfor
{ "rule": "parallelfor",
  "list": <<name of a list object>>,
  "element": << name for list element object within the rules below >>,
  "rules": [
    << Rules to execute on every element of the given list. The list is executed sequentially, but each element is processed "in parallel">>
  ]
}
Switch
{ "rule": "switch",
  "value": << value to switch upon >>,
  "list": << name of a constant list of allowable values >>,
  "cases": [
    { "case": << value >>, "rules": [ << Rules to execute when the value and case match >> ] },
    ...
  ]
}
When
A when construct is analogous to if-then-else. The first case with a condition that evaluates to true has its rule list evaluated.

{ "rule": "when",
  "cases": [
    { "condition": << Boolean guard for rules >>,
      "rules": [ << Rules to execute when the value and case match >> ]
    },
    ...
  ]
}
List Operations
Extend
{ "rule": "extend",
  "target": << variable name of a list to extend with another list >>
  "list": << either an immediate list or a name of a constant variable or list >>
}
Reverse
{ "rule": "reverse",
  "list": << variable name of a list to reverse >>
}
Shuffle
{ "rule": "shuffle",
  "list": << variable name of a list to shuffle >>
}
Sort
{ "rule": "sort",
  "list": << variable name of a list to sort >>,

  OPTIONALLY
  "key": << Attribute of list elements to use for comparison.
            Only valid when the list contains maps. >>
}
Sorts a list in ascending order

Deal
{ "rule": "deal",
  "from": << variable name of a list to deal from >>,
  "to": << variable name of a list or list attribute to deal to >>,
  "count": << number of elements to deal >>
}
Discard
{ "rule": "discard",
  "from": << variable name of a list to discard from >>,
  "count": << number of elements to discard >>
}
List Attributes
When given a list name, attributes of a list can be referred to and elements of a list can be sliced to represent new lists. For example, suppose that the following list is defined in the constants:

  "roles": [
    { "name": "Duke", "action": "Tax. The duke may take 3 coins from the treasury."},
    { "name": "Assassin", "action": "Assassinate. The assassin may force another player to give up an influence."},
    ...
  ]
The name of the list is "roles" and can be referred to within the rules. The size of the list may be accessed through the attribute "roles.size". Lists may be implicitly created, as well. If the elements of the list are maps, then the keys of the maps define additional lists. For instance, "roles.elements.name" defines the list of names contained within the above list. Additional useful attributes are "contains" and "collect".

Arithmetic Operations
Add
{ "rule": "add",
  "to": << variable name of an integer to add to >>,
  "value": << integer literal or name of a variable or constant containing the value to add >>,
}
Numerical Attributes
Given a number, I can access attributes of the number similar to attributes of a list. For instance, I can treat a number as a list by saying "count.upfrom(1)". That defines the list of numbers 1, 2, …, count.

Timing
Timer
{ "rule": "timer",
  "duration": << seconds >>,
  "mode": "exact" OR "at most" OR "track",
  "rules": [
    << sequence of rules to execute with respect to the timer.
       An "at most" timer will stop executing and time out input requests.
       An "exact" timer will pad the execution time to the given duration.
       A "track" timer will continue executing but set a flag. >>
  ],

  OPTIONAL
  "flag": << variable that evaluates to false when a "track" timer has not expired and false afterward. >>
}
Human Input
Input choice
{ "rule": "input-choice",
  "to": << a single player or audience member >>,
  "prompt": << Message to send with request, as in "output" below  >>,
  "choices": << list or name of a list to choose from >>
  "result": << variable name in which to store the response >>

  OPTIONAL
  "timeout": << duration to wait for a response >>
}
This allows the player to make a multiple choice selection.

Input text
{ "rule": "input-text",
  "to": << a single player or audience member >>,
  "prompt": << Message to send with request, as in "output" below  >>,
  "result": << variable name in which to store the response >>

  OPTIONAL
  "timeout": << duration to wait for a response >>
}
Input vote
{ "rule": "input-vote",
  "to": << a list of players and/or audience members >>,
  "prompt": << Message to send with request, as in "output" below  >>,
  "choices": << list or name of a list to choose from >>
  "result": << variable name in which to store a map from choices to vote counts >>

  OPTIONAL
  "timeout": << duration to wait for a response >>
}
Output
Message
{ "rule": "message",
  "to": << list of recipients or a single player or audience member >>,
  "value": << Message to send. Python style {} variable accesses are permitted.
             E.g. "Great job, {player.name}!"  >>
}
Globalmessage
{ "rule": "global-message",
  "value": << Message to send. Python style {} variable accesses are permitted.
             E.g. "Great job, {player.name}!"  >>
}
This sends a message to the main screen of the game instead of any player.

Scores
{ "rule": "scores",
  "score": << Numerical attribute of players to use as score >>,
  "ascending": << boolean attribute. True when the scores run from low to high >>
}
Prints a scoareboard on the global display using the given attribute of each player.

Scores are sorted ascending or descenfing as specified.

Example
This demonstrates a simple rock paper scissors game. It is a good place to aim initially. Several smaller portions capture individual goals that may be risky for each group.

{
  "configuration": {
    "name": "Rock, Paper, Scissors",
    "player count": {"min": 2, "max": 4},
    "audience": false,
    "setup": {
      "Rounds": 10
    }
  },

  "constants": {
    "weapons": [
      { "name": "Rock",     "beats": "Scissors"},
      { "name": "Paper",    "beats": "Rock"},
      { "name": "Scissors", "beats": "Paper"}
    ]
  },

  "variables": {
    "winners": []
  },

  "per-player": {
    "wins": 0
  },

  "per-audience": {},

  "rules": [
    { "rule": "foreach",
      "list": "configuration.Rounds.upfrom(1)",
      "element": "round",
      "rules": [

        { "rule": "global-message",
          "value": "Round {round}. Choose your weapon!"
        },

        { "rule": "parallelfor",
          "list": "players",
          "element": "player",
          "rules": [

            { "rule": "input-choice",
              "to": "player",
              "prompt": "{player.name}, choose your weapon!",
              "choices": "weapons.name",
              "result": "player.weapon",
              "timeout": 10
            }

          ]
        },

        { "rule": "discard",
          "from": "winners",
          "count": "winners.size"
        },

        { "rule": "foreach",
          "list": "weapons",
          "element": "weapon",
          "rules": [

            { "rule": "when",
              "cases": [
                { "condition": "!players.elements.weapon.contains(weapon.name)",
                  "rules": [

                    { "rule": "extend",
                      "target": "winners",
                      "list": "players.elements.collect(player, player.weapon == weapon.beats)"
                    }

                  ]
                }
              ]
            }

          ]
        },

        { "rule": "when",
          "cases": [
            { "condition": "winners.size == players.size",
              "rules": [
                { "rule": "global-message",
                  "value": "Tie game!"
                }
              ]
            },
            { "condition": "winners.size == 0",
              "rules": [
                { "rule": "global-message",
                  "value": "Tie game!"
                }
              ]
            },
            { "condition": true,
              "rules": [
                { "rule": "global-message",
                  "value": "Winners: {winners.elements.name}"
                },
                { "rule": "foreach",
                  "list": "winners",
                  "element": "winner",
                  "rules": [
                    { "rule": "add",
                      "to": "winner.wins",
                      "value": 1
                    }
                  ]
                }
              ]
            }
          ]
        }

      ]
    },

    { "rule": "scores",
      "score": "wins",
      "ascending": false
    }
  ]
}