CS5003 — MASTERS

PROGRAMMING

PROJECTS

CS5003 PRACTICAL 1: HIGHER OR LOWER?

Deadline: Friday the 11th February 2022 at 21:00

Credits: 22% of the coursework (and the module)

MMS is the definitive source for deadline and credit details

You are expected to have read and understood all the information in this specification and any accompanying documents at least a week before the deadline. You must contact the lecturer regarding any queries well in advance of the deadline.

AIMS

The main aim of this project is to write a clearly structured single-page web application. You will practice using APIs to access remote services, manipulating JSON and arrays, and incorporating the results into your web application.

OVERVIEW

In this project, you will create a web version of a card game in which a player attempts to guess whether the next card drawn from the deck ranks higher or lower than the current card. Your game will use           standard ranking for numerical cards (e.g. Two=2, Three=3, etc.), and Ace=1, Jack=11, Queen=12 and   King=13 for the face cards.

Your game must use the Deck of Cards API at https://deckofcardsapi.com/ to manage the deck of          cards. You will need to investigate and choose which endpoints and parameters to use. Your client-side  JavaScript must not store or manipulate the deck — all interactions with deck must go through the API. Your client-side JavaScript may store information about cards that have been drawn from the deck.

Your submission must be written in modern JavaScript (i.e. ECMAScript version 6+) with appropriate  HTML and CSS. You may use pure CSS frameworks to improve the look of your web application, but you must not use any JavaScript libraries or any other language, JavaScript dialect or templating       language (e.g. jQuery, TypeScript, CoffeeScript, HAML, Pug, React, Vue, ejs, etc.).

REQUIREMENTS

Your application should provide the functionality described below. You must make sure you have completed all the requirements in each section before moving onto the next.

BASIC

Remember: Your implementation must use the Deck of Cards API at https://deckofcardsapi.com/ to   manage the deck of cards — all interactions with deck (e.g. generating, shuffling, drawing cards, etc.) must go through the API.

Your application should provide the following:

• Generate a deck of cards containing only the Hearts suit (from Ace up to King).

• Let the player start a new game:

1. Shuffle the deck of cards. Draw the top card from the deck. Display the card face-up so the player can see it.

2. Allow the player to guess whether the next card in the deck will rank higher or lower than    the one displayed. Draw the next card from the deck and check to see if the player's guess was correct. Remember, in this variant of the game Ace ranks low (not high).

▪  If the player guessed correctly, display the card just drawn from the deck, and repeat step 2 until there are no more cards in the deck or the player guesses incorrectly.

▪  If the player guessed incorrectly, end the game with a suitable message to the player.

3. If there are no more cards to draw from the deck, then the player has won, so end the game with a suitable message to the player.

• At any point during a game, allow the player to quit. Display a suitable message to the player (e.g. "Play again soon!").

• Keep track of how many correct guesses a player has made during a game and include this any message displayed at the end of a game (win, lose or quit).

HINT: It might take a while to test the 'win' condition for this game. You could temporarily reduce the size of your deck to make it easier (e.g. only include the Ace, 2, and 3 of Hearts). Remember to return to the  normal deck of Hearts once you are happy the code works!

INTERMEDIATE

Your application should provide all the requirements described in Section Basic, plus the following:

• Let the player start a new game without refreshing the page. Where possible, you should reset, shuffle and re-use the deck from the last game rather than generating a new deck.

• Track and display the player's ‘best’ score so far (i.e. the highest number of correct guesses the player has made before ending a game). The score should persist until the player refreshes the page.

• Let the player select which deck they want to use:

◦ Hearts Deck: a deck of cards containing only the Hearts suit (from Ace up to King).

◦ Full Deck: using all 52 cards from a standard deck. With this deck, there is a small chance consecutive cards will have the same rank (e.g. an Ace followed immediately by another     Ace). The strict ordering of higher/lower should be maintained in this case, meaning no       matter what the player chooses, they will lose (because Ace is not higher than Ace, and      Ace is not lower than Ace).

• Let the player ‘skip’ a guess (instead of guessing higher or lower). The next card in the deck      should be drawn and the player should be able to continue to play as if they had guessed          correctly. Any skipped cards should not count towards the correct guesses in the scoring. This  would allow a player to ‘win’ a game by simply skipping every guess, but their final score would be 0.

ADVANCED

Your application should provide all the requirements described in Sections Basic and Intermediate, plus the following:

• Let the player ask for a hint. The hint should show the player the likelihood of the next card being higher and the likelihood of it being lower. Make sure you take into account, duplicate ranks, and  the number and rank of the cards that have already been played. For example:

◦  If you are playing with the Hearts Deck and the first card you draw is an Ace, the likelihood of the next card being higher is 100% and lower is 0%.

◦  If you are playing with the Hearts Deck and the first card you draw is an Ace and the   second is a Two, the likelihood of the next card being higher is 100% and lower is 0% (because the Ace has already been drawn).

◦  If you are playing with the Full Deck and the first card you draw is an Ace, the likelihood of the next card being higher is approximately 94% and lower is 0% (because there is            approximately 6% chance of another Ace being drawn).

• Devise a new scoring scheme that takes into account the likelihood of the player guessing            correctly. For example, If a Seven is the first card you draw there is an equal chance that the next card will be higher or lower (47%). If you guess this correctly, you should get a higher score than  guessing that a card coming after an Ace will be higher. When recording a player's score for a      game, include both the number of correct guesses they made and their score (according to your   scoring scheme).

• Research and use localstorage to persist high scores when the page is refreshed.

• Research and use closure, modules and/or classes to improve code structure (and prevent      players cheating using the browser console!). Think carefully about the major elements in your program and define classes or closures to represent these distinct concepts, including their      related data and operations.

REPORT

You should write a short report (approximately 1000 words) detailing the design of your solution. You should include the following sections:

• Overview — a brief description of what has been achieved in the submission. This should include a list of which requirements have been met and to what extent.

• Technologies & Resources — a brief description of what external technologies and resources  you used during the development of your solution and what you used them for. This should         include references to any external CSS libraries, tutorials, forums, websites, books, etc. that you used to produce your solution. It should also clearly state what browser(s) were used to run and  test your solution.

• Design — a brief discussion of any interpretation of requirements and any design decisions    taken. Focus on the reasons for your decisions rather than just providing a description of what you did.

• Evaluation — a brief reflection on the success of your application. What went well and what could be improved? What might you do differently next time or if you had more time?

DELIVERABLES

A single .zip file must be submitted electronically via MMS by the deadline. It should contain:

• The source code for your application, including your CSS, HTML and Javascript.

• Your report in PDF format

Submissions in any other formats may be rejected.

MARKING CRITERIA

Marking will follow the guidelines given in the school student handbook:

https://info.cs.st-andrews.ac.uk/student-handbook/learning-teaching/feedback.html#Mark_Descriptors

Your submission will not be evaluated based on aesthetic appeal (this is not a visual design course), but use of CSS and DOM scripting which enhances the experience and interactivity will be rewarded. Some specific descriptors for this assignment are given below:

• A poor implementation in the 0–7 mark band will be missing nearly all required functionality. It   may contain code attempting a significant part of a solution, but with little success, together with a report describing the problems and the attempts made at a solution.

• A reasonable implementation in the 8–10 mark band should provide some of the functionality  described in Section Basic, demonstrate reasonable use of HTML and JavaScript, allowing a       player to partially complete a game but perhaps with some bugs. The code should be                   documented well enough to allow the marker to understand the logic. The report should describe what was done but might lack detail or clarity.

• A competent implementation in the 11–13 mark band should provide all the functionality           described in Section Basic, demonstrate competent use of HTML, CSS (e.g. for layout and            positioning) and Javascript, allowing a player to complete a game and receive the ‘win’, ‘lose’ and ‘quit’ messages. The code should be documented well enough to allow the marker to understand  the logic and should be contained in JavaScript files that are separate from the HTML and CSS    code. The report should describe clearly what was done, with good style.

• A good implementation in the 14–16 mark band should provide all the functionality described   in Section Basic and some or all of the functionality from Section Intermediate. It should                demonstrate good code quality, good comments, and proper error handling. Good use of CSS for layout and styling is expected for a submission in this range (not unmodified defaults). The report should describe clearly what was done with some justification for decision, with good style,           showing a good level of understanding.

• An excellent implementation in the 17 and higher mark band should provide all the                functionality described in Sections Basic and Intermediate, and some or all of the functionality     from Section Advanced. It should demonstrate high-quality code and be accompanied by a clear and well written report showing real insight into the subject matter.

Note: For this practical you do not need to invent your own extensions. Concentrate on providing high quality, sophisticated implementations of the requirements in this specification and writing an insightful report demonstrating understanding.