Harjoitustyö: Wolf Hall - a game to win a kingdom

The course project is done in groups of two. The course staff provides functionality that must be used in the project.

Deadlines

• Final submission: 19.4.2021
• Grace period ends: 26.4.2021

Program to Implement

A king of a town state has dies, and the heir to the throne is not yet of age. The town council needs to choose a regent in their midst. As an esteemed member of the council you consider yourself the best and most natural regent to be selected. Now you just need to gain enough power and influence on the other council members to get them to support you in the final vote…

Gameplay

When starting the program a settings dialog is shown. After entering the setting the program moves to the main window of the game where the game board depicting the town is shown. Players (two or more) place cards and game chips onto the board. There are several regions on the board (at least four), e.g. merchant’s guild, city watch etc. Each region is represented by a town council member. Each area has a game deck which contains at least the following cards:

• Influence cards: At the end of the game the cards the players have collected in their hand decide the outcome of the vote.
• Agent cards: Agent cards can be played onto the board whre they can perfom actions supporting the players goals.

A player can play an agent card from their hand onto any area on the board. When an agent card is played, the player’s chip is placed on it to show its owner. An agent in an area can perform at least the following:

• Strengthening connections: A player adds new chips on an agent card to indicate stronger connections to the players in the area. The better connections enforce performing other operations.
• Collecting resources: A player lifts card from the area’s deck into their hand.
• Negotiations: A player places new chips onto an area to show gained influence on the council member of the area.
• Withdrawal: A player lifts an agent card back to their hand.

During the game each player can on their turn play agents from their hand onto the board and/or perform operations with their agents already on the board. At the end of the game a vote is held where the vote of each of the council members is based on the chips on their area on the board and the influence cards in the players hands. The winner of the vode wins the game, and the throne.

Implementation

The game contains ready-made parts. These are lifting cards to a players hand and playing cards onto an area on the board. The team needs to implement the graphical user interface of the game, the agents and their operations and a few details to the game mechanics. Below a rough example of what the GUI of the game might look like:

Many details of the game are left intentionally open and you can implement them as you wish. These include:

• The starting point of the game: How the players get their first agents onto the board for gameplay? Are there cards in the players hand, can an agent be played onto the board without a card in the players hand, can operations be performed without an agent?
• Agent releations’ effect on the operations: Do they open new operations, do they improve the likelyhood of success, do they improve the final outcome?
• Flow of turn: What a player can do during one turn?
• End of the game: When is the final vote held? A certain amount of turns, after all card decks are empty, after a player has gotten enough power on the council?
• The deciding vote: How it the vote of each of the council members deciced?
• GUI of the game: What the game board looks like? How different actions in the game can be done?

Use Case

The following order of actions depicts the start and funtionality of the game. This is an example. Your game can be different from what is depicted here.

• The game starts with the help of a self-implemented main program. The game asks with a separate configuration window the number of players and other information needed by the game. After this a already implemented game object is created and players, cards and other start state details are added to it. Then the main window implemented by the group is opened. On it, there is the game board with the map, the players gamepieces and the cards in the hand of the player in turn.
• A player starts the game by clicking a button in the main window. The game logic implemented by the team starts the game driver implemented by the course. The driver is unable to produce the move as there is a human player using the GUI and hence returns the control to the main window.

• The player in turn clicks with a mouse an area on the game board in the main window. The logic of the game creates an move object depicting sending an agent and gives it to the driver. The driver completes the move which makes the needed changes into the game state. The objects in the game signal that the area in question and the state of the player’s hand have changed and they must be updated in the window. The driver signals the turn is completed. The driver notes it is unable to create moves for a human player and returns the control to the window.

• The player in turn clicks an agent visible on the board in the main window with a mouse and selects negotiation from the options that appear. Driver handles the operation which tells the game object that the influence has grown in that area and the state of the area is signaled to have changed and the move as completed. Control return back to the main window.
• The player ends their turn from the main window. Logic changes the turn to the next player signaling a change signal from the game. Driver is started to sort out the next player’s move.
• After each player has completed ten moves the final vote is held. Logic asks the game objects for the key state information and tells the players based on them the result of the vote and the winner of the game.

Learning Outcomes

You practice the following things:

• Getting familiar with existing code and using it by provided interfaces (applying design by contract)
• Adding functionality to an application based on given interfaces (following design by contract)
• Implementing a GUI as a part of program
• Exception handling and error control
• Unit testing of your own code.
• Implementing a program as a team effort

Compulsory Requirements

You must implement at least the listed basic features to get the project work accepted. Moreover, there some optional additional features, and by implementing them you can increase your grade. With the minimum implementation you can pass (grade 1). Implementing the requirements set for the intermediate implementation, you can get the grade 3. A higher grade requires the implementation of some additional features.

Minimum requirements (Max Grade 1):

• Successfully compiling game.
• Some kind of game-mechanics implemented (e.g. player turns, scoring)
• One dialog-window (e.g. Start menu to specify amount of players, goals etc.)
• At least one own agent card has been implemented into the game. The functionality required in defined through AgentInterface
• UnitTests have been written at least for the agent class implemented by the team.
• Final document that must contain:
  • Game-rules
  • Game-controls
  • Class responsibilities (class diagram is good tool in this)
  • Division of labour.

Note! The minimum implementation can use the GUI provided by the course as the main window.

Intermediate requirements (Max Grade 3):

• Meets minimum requirements.
• Own graphics fully implemented by the team (no using the course library drawing) that contains at least the game board, the cards on it, the chips and the cards of the player in turn.
• Agents can be played on the areas on the board and the four operation given in the game description can be performed.
• The game works, i.e. the flow of the game is kept so that the player turns change and the final vote comes on time. The winner of the game is decided taking the influence chips on the board and the influence cards in the players’ hand into account.
• Bonuspoints can compensate up to one grade’s worth of mistakes.

Top-grade requirements (Max Grade 5):

• Must meet minimum and intermediate requirements
• At least 2 additional features.
• Bonuspoints can compensate up to one grade’s worth of mistakes.

Additional Features

The features listed below do not need to be implemented but a good implementation is worth an increase in the gradfe. Each additional feature is worth 0,5 grade. The effect of a feature can be increased if it turns out to require more work than expected. In order to get the grade increase, the feature must be documented in the submission. The people grading the projects do not look for features from the code. The TAs do not search for additional features from the code.

• Agent/area features. Each agent card and/or area on the board has unique features that affect the operations performed.
• Attack operations. The agents on the board can attack eachother and this way disturb the other players’ game. The mechanics of the attach can be decided independently.
• New card types. The game decks come with new types of cards with different uses. For example: resource cards that can enhance operations.
• Cards as data. The cards used in the game are not hard coded but their data is read at the beginning of the game from a file. The files can be written for example as JSON or XML. Qt comes with classes meant for handling these.
• Dynamically built cards. The cards drawn on the game area are not fixed pictures but their outlook is built dynamically based on the features of the card. This way a change in the feature’s code (or file) becomes visible also on the game area without editing the pictures. In order to get the points it is requires that the cards really have such features; if there are no special game mechanical features, the agents can be given a unique name and title for colour.
• Scalable or zoomable game area. Either: The game board and the cards and chips on it scale with the size of the window. Or: The game area can be zoomed to close view where the card details are clearly visible or to a general view where the board is visible in its entirety. Both can be implemented but are counted as one extra feature. (max. 1 grade)
• Card preview. When placing the mouse cursor on a card in a game area the card is drawn automatically into the game window as a larger version for easier view on the details.
• Player settings. At the start of the game a settings window is opened where the amount of the players and names each of the players. The game window must show the name and the amount of cards in their hand for each player.
• AI. Some of the players can be made program handled. The AI does not need to play well as long as it is in principle capable of making any legal move. A completely randomly playing AI fills the requirement. (max. 1 arvosana)
• Storing the game and continuing from the stored state. (max. 1 arvosana)
• Own feature. An additional feature outside this list has been implemented. Note! The feature needs to clearly require coding.
• Note! Additional features must clearly require coding.
• Note! ALL ADDITIONAL FEATURES MUST BE DOCUMENTED TO GET THE POINTS

Grade calculation

Grading will consist of smaller sections and bonus-points. Final grade is limited by requirements specified in previous subsection After meeting intermediate requirements, bonus points can compensate 1 grade. After implementing 2 additional features, bonus points can give 2 extra grades.

Graded sections:

• Overall design and structure
• Class design and implementation
  • Proper principles in object-oriented programming
  • Class documentation
• Exception handling
  • Proper usage and handling of exceptions
• Code quality
  • Following good programming principles.
  • Style
• Version history & Teamwork
• Bonus points
  • Awared from additional features.

Scoring from graded sections:

• 50% => 1
• 70% => 2
• 90% => 3

Extra work qualified for bonus points:

• Additional (well implemented) unittests (up to 0.5 grades)
• Additional Tiles, Buildings and Workers (up to 0.5 grades)
• Nice graphics (up to 1 grade)
• A very good GUI (up to one grade)
• Back story and depiction of the game world (up to 0.5 grades)

Examples:

• Only minimum requirements met and perfect score in graded sections, no bonus-points ( 3 + 0 => 1)
• Minimum and intermediate requirements met 75% of graded section score, 0.5 grades worth of bonus-points ( 2 + 0.5 => 2.5)
• Minimum and intermediate requirements met 60% of graded section score, 2 additional features and total of 3.5 grades worth of bonus points (1 + 3.5 => 4 )
  • Only 3 points are taken in account from the 3.5 (1 for graded section compensation, 2 for extra grades

Environment

The working environment is in GitLab. Each team has a repository named based on the name of the team. It is worth to note that some team names were adjusted to match suitable names for a GitLab project. The parts implemented by the course are given also through version control.

Class Diagram

The relevant classses in the program.

Class Diagram

NOTE! The part depicting the students’ implementation is completely fictitious. There can be (and should be) more classes and there relationships can be completely different.

You can generate the Doxygen documentation of the interfaces directly from the project. Read the README for more information.

At least the following have been implemented by the course:

Game contains the game board and the state of each of the players. Most other objects can be accessed through it. It also signals changes in the situation of the player in turn.

• Location depicts one area in the game board with its card decks and agents. It signal changes in its state.
• DeckInterface is an interface for card decks. The implementation is not meant to be changed from the student teams’ side.
• Player depicts the state of a single player.
• CardInterface and the classes implementing it present the game cards. The council member are depicted with a Councilor card. Using them is not mandatory, but they can be used if the team wants. Game contains a deck meant for them.
• AgentInterface depict the agent card class that must be implemented and tested.
• ActionInterface``with its decendants depicts a single players moves with their impact. The ``WithdrawAction action showing the agent withdrawal is implemented as an example. It is not compulsory to use if the team wants the withdrawal to work differently.
• ControlInterface offers an interface for asking he players’ moves. Its subclasses either return the next move (AI9 or leave the selection of the move for other parts to decide (a human player using the interface). The already implemented ``ManualControl``class depicting a human player can be given the next move to return by hand.
• Runner asks the control object for moves and runs them and returns the control back to control user interface if the control object is unable to tell the next move. When this happens the next move can be told through the interface to e.g. ManualControl object and then tell Runner to try again.
• Random is a simple random number generator that can be used in the team’s implementation. It is not compulsory.
• SettingsReader reads key-value pairs from a settings file and offers them to those who ask. Can be used for handling simple settings but is not compulsory.

The loigc of the moves is illustrated in the sequence diagram:

sequence diagram

In the diagram an AI move is performed first and then a move from a human player after which the game ends. (Sequence diagrams are not part of the course contents but the diagram is understandable as it is. Help can be found täältä ).

Some of the classes implemented (e.g. Game) inherits _std::enable_shared_from_this with which they can create a shared pointer pointing to themselves. Such class instances must be placed to shared pointer ownership immediately aftre creation by creating them with make_shared. Is is key that these are not created into the stack.

The team must implement at least the following:

• main program that starts the first game window and possibly initializes the game state.
• MainWindow, the main window of the program through which the players see the state of the game and make their moves.
• Agent, the implementation of the agents according to AgentInterface.
• Most ActionInterface classes implementing the consequences of the moves.
• Some other window or dialog, e.g. settings, operation starting or showing the final result of the game.

Other classes are probably needed as well.

Hints

• Check what is implemented on the course side
• When designing the project:
  • Make your own class diagram that clarifies the structure and division of work
  • Go the functionality of the game through with the help of the class diagram and/or sequence diagram
• Start coding only once you have a clear plan in order to be able to concentrate on solving codebased problems
• You can inherit own versions of course library buildings, tiles and workers if you what to modify costs, production or add functionality
• All game objects can be given additional text based metadata
• You can ask for bug corrections and additions to the course code
  • NOTE! Additions to the library should be asked as early as possible in order to allow enough time to implement them. Do the design early and with care.

Posting submission...