---
# System prepended metadata

title: Design Plan

---

# Design Plan

## Introduction
In writing this program our goal is to create a data-driven poker emulator that supports various rulesets for poker. We want our design to be most flexible in its ability to handle various versions of the game, supporting the loading of new rulesets as a configuration file. We also want to prioritze making the UI interactive and intuitive. Our code will be divided into three packages, the Game Engine, Data, and the View. We hope to keep these sections as closed as possible, using tools like Observables and Handler classes to communicate between the different parts of the project.

## Overview
As mentioned in the introduction, there are three main packages in our project and classes outside of those packages used to enhance communication between the front and the backend.

#### Game Engine
The purpose of the game engine is to implement the poker game dictated by the data file. The engine package contains the interfaces for the necessary components that comprise the game. The lowest level interfaces are Card, Player, and Poker Action, which handle the most essential game features. The Action Manager controls which Actions ae avaible as options to the active player during their turn, depending on the current game rules or game status. The Deck maintains the collections of card objects that are availble in the game, while the Table interface keeps track of the different active Decks, including the Community Pool, Dealer, and Discard Pile. The BetManager handles all of the bets for the game, keeping track of the current bets and allowing Player objects to update their bets. Finally, the core of this package is the Round interface, which handles the primary actions the game engine needs to take in a given round of the game.

#### Data
Since our design is largely data driven, the data package is responsible for setting up the rules and player preferences for each game. All of the data will come from XML files, which can be generated by player preferences dictated using the GUI or loaded into/saved from the program using the ToXML and FromXML classes. Once the program has an XML file, the data module will parse the XML file using a Parser class. Using the information obtained from parsing, the data interface will create a variety of necessary game objects, such as Cards and Rules. Creating these objects in the data module allows our program to be dynamic and allows the data files to be the primary driver of different poker variations, which may have unexpected impacts on how the game is run in the engine.

#### View
The View creates and maintains the GUI. With a data driven approach in mind, the View will utilize properties as well as XML files to modify the interface based on player preferences and the specified setup of each ruleset. The View will have its own Controller to integrate the various components of the class, including Preferences and Startup Panes as well as each player's view of the table and their own cards. 

#### Controller/Observables
In order to connect these three packages, particularly the game engine and View, we plan to utilize a Controller class as well as Observables. By extending the observable class in both packages, we can creating seamless communication between the front and back ends of the program. Using the add and remove Listener methods, each class can have a flexible list of listeners to either pass or retrieve neccessary information externally using the notifyListeners method, as it's being updated. Some examples of the game values/state changes that require listeners include when a new round is starting, which player is active, when community cards need to be dealt, and when the winner is determined. 

## Design Details

### Game Data

All of the data for each Poker game will come from XML files. Accordingly, the data module will need to be able to parse these XML files and build classes from them that can be passed to the engine and used to play the game. Additionally, the data module will need to be able to take input from the front end and create XML files for a custom poker game from it. These read/write XML classes will each have a public method to allow the front end to initiate the start of a new game by loading in a file or letting the user create a new file, which will make these functions part of the data module's external API. To avoid having to give the write class a bunch of setters to allow the user to select different functionality, we will use the Observable pattern on the form fields in the view. The view will instantiate an instance of the ToXML class and pass it the listeners it needs, then when the submit button is clicked all of the field listeners will be notified and the back end can create the XML file with this information.

Card objects are one of the main types of objects that the engine will need to receive from the data module in order to run. In the XML file, the value and type of each card can be indicated so that custom card types can be created easily. Card objects can then be created using the Factory Pattern and reflections to pass the XML values in as parameters to the Card constructor. Then, the Deck object can be created and will store these card objects in a collection for game play. The deck will then be added to a Table object, as all cards start on the table before being dealt.

The XML file will also specify data for Round objects so that the engine can be passed a list of rounds and cycle through them to advance game play. Round objects will contain information such as how many cards should be dealt to each player face up, how many should be dealt to each player face down, and how many should be dealt to the table for community use. Round objects can also specify whether players are allowed to pass or exchange a certain number of cards during that time period, which is important to specify in order to create variations.

Another class that will be essential to creating variations is Rule. Special game rules, such as wild card or being able to purchase a new card, will have their own classes, and the XML file will be able to choose which of those classes should be put into game play. The XML file will also choose which Action classes should be involved in the game, as in addition to the standard actions (Raise, Call, Bet, Check, etc.), there are sometimes new actions used by variations such as Accept and Reject for implementing passing cards.

If all of these objects were created in the engine directly, the engine would then have a lot of dependencies. Any time the instantiation details of these classes changed, it would affect the functionality of the engine. In order to avoid this, we can use the Dependency Injection Pattern. Specifically, the data module itself will handle creation of these objects in their initial form and make them accessible to the engine through a data interface. The Builder Pattern will also be very useful to the game data module so that the XML parser can create the new objects the parser needs with dynamic input.

## Design Considerations

### Game Data

In order to determine the design for the XML file for the game, we needed to research what kinds of poker variations exist. Our main source for that research was the [Paget Poker Site](https://www.pagat.com/poker/variants/). From this resource, we determined that the main components that differentiate poker games from each other are betting type (Ante or Blind), hand size, cards dealt to each player and to the table each round, whether cards can be passed or discarded, if special features such as buying new cards or wild cards are allowed, whether high or low cards win, and how many hole/community cards can be included in a winning hand. Since these pieces of the game all need to be customizable in order to create new games from the basic rules, each of these features is given an element in the XML layout where its status can be specified. While there are lots of options on this Paget site, if variations outside of this set are to be added more functionality might have to be added to the XML. 

## Example Games

## Test Plan

For the data section, a test plan is to write an xml file in the desired format and call getRounds() on the data file that loadNewGame() has already been called on. AssertEquals would check to see if the rounds returned are equal to what was inputted into the xml file. A negative interaction is to put a bad input into the xml file and use assertThrows to see if it throws an exception. For example,  if getRules() was called and any of the rules had been inputted in an improper format into the xml file, an exception would be thrown and assertThrows would be able to check that. Another feature that will be tested is the createXMLFile(), which will show if the Observable pattern on the frontend is working. Using assertEquals, we can test if when the frontend changes the backend changes and is properly updating the xml file.
