实现一个单人版的 MasterMind
游戏。
Description
Similar to the homework this semester, submit your project to Gradescope.
As always, you may submit multiple times right up until the deadline; we will
grade only the most recent submission.
The Game: MasterMind
Mastermind is a coding-breaking board game for two players. The “secret code”
is a set of 4 colors chosen out of a possible 6 colors, where the player needs
to guess which colors are in which positions in the 4-color secret code. After
each guess, the player learns how many colors in their guess are in the right
position, and how many had a color that’s in the code but the color is in the
wrong position. Scoring pegs of different colors were used to show them how
many correct guesses and how many correct positions they had gotten with their
guess. Red pegs meant a correct color but out of position, black pegs meant a
correct color in the correct position. These scoring pegs after each guess can
be placed in any order - the player never knows which colors are correct
and/or in the correct position. Examples of the two-player version of the game
being played can be seen
In an older version of Mastermind, called, Bulls and Cows, guesses with
correct position were called “bulls”, and correct guesses with incorrect
positions were called “cows”. We will use the “bull” and “cow” terminology
when talking about correct guesses for Mastermind.
Our Version of Mastermind: 1 player
We’ll be designing a version for one player. In your version, the program
selects the 4 color secret code. Your program will also place the scoring
pegs. In some versions of Mastermind, blank positions are allowed, and/or
duplicate colors are allowed. You can play a one-person version of the game
here, this version allows duplicate colors. Our version will not allow blank
positions or duplicate colors. Our permitted colors are:
colors = [“red”, “blue”, “green”, “yellow”, “purple”, “black”].
—|—
In the one-player game, the score is the number of guesses it takes the player
to guess the code. The player loses if they don’t guess the code in 10 tries.
Lower scores/fewer guesses are better. Our scoring pegs will be red for cows
and black for bulls.
Prof Keith posted walkthroughs and examples of the game play and expected
functions for the game, which can be found.
Game Play & Functionality
- We should be able to input the player name to your game through a popup window rather than in the terminal.
- Your program should draw a board as seen in the demo videos. This board for the Mastermind game should include: a Leaderboard on the right that lists the previous best scores in the game (lowest scores are best).
- A “Quit” button that exits the game. We provide a gif for this button in the starter code.
- A set of clickable, colored guess buttons that allows a player to choose one color at a time for a guess, and does not allow them to choose duplicate colors. We provide starter code for these buttons in Marble.py
- A green check mark button that confirms that a guess should be checked/entered. We provide a gif for this button in the starter code.
- A red “X” button that removes a guess that has not yet been checked/ entered and resets the clickable, colored guess buttons. We provide a gif for this button in the starter code.
- A representation of the board that displays the current guess and previous guesses in this game. We provide starter code for these buttons in Marble.py.
- A part of the display that shows the scoring pegs. These scoring pegs are filled in after a guess is checked, with black pegs indicating colors guessed in the right position, and red pegs indicating colors guessed correctly, but not in the right position. Blank circles can represent neither of those conditions.
- Your program should save the best scores in a leaderboard file, and when the program is re-launched, those scores should be visible with the player name in the leaderboard. A minimum of 2 best scores should be saved. The list should update with new best scores when someone achieves a new best score. Do not submit your leaderboard.txt file with your submission; a new file should be created if one does not exist yet.
- The program should display a visual error message popup if the leaderboard file cannot be found. We provide a gif for this message in the starter code.
- The program should display a visual message popup if the player presses the Quit buttons. We provide a gif for this message in the starter code.
- The program should display a visual message popup if the player wins or loses. We provide gifs for these messages in the starter code.
- All user interaction should be via your turtle-based user interface; users must use the mouse to play your game (the only keyboard actions are when you capture the player name at the start of the game)
- Any errors encountered by the program during use should be logged to a text file named “mastermind_errors.err”. You have full freedom to determine the schema of the information, but at minimum, we should be able to identify the date/time of the error logged, and the name/type of the error.
Resources & Guidance
Important: Your project MUST be runnable and do something non-trivial to get
credit for this assignment. However, it does not need to be functionally
complete to get partial credit.
Turtle is the ONLY Graphic library allowed for this assignment. You may NOT
use PyGame, TkInter, or any other graphics package
Resources
This project will have you using a bit of almost everything we learned this
semester (except recursion), so be sure to allocate appropriate time to
complete it. If you wait until the last minute to work on this, you are almost
guaranteed NOT to finish on time. You cannot use late days on this project,
because we have a deadline for turning in grades. Plan to start early!
At the same time, don’t panic. The project is bigger than anything you’ve
worked on this term, but the concepts are all within your reach. You’ll need
to do a bit of reading on Turtle to brush up on the elements you’ll likely
need for the graphics. In particular, review the turtle objects themselves and
think about how you can use multiples of them to do things on the gameboard
for you.
A link to Python Turtle documentation is here:
https://docs.python.org/3/library/turtle.html#turtle.update
Feel free to search the web for other Turtle resources to help you learn
whatever you think you might need to know for the UI portion of your
application.
What to Submit
You may submit multiple times right up until the deadline; we will grade only
the most recent submission.
Your files to turn in:
- mastermind_game.py (includes a main() function that lets us play your game)
- test_mastermind_game.py (tests for game functions, does not test turtle/view)
- readme.txt (short plaintext file - 1 or 2 paragraphs - explaining your design)
You may turn in other files with helper functions, but these above files are
the minimum required.
You are free to select your approach to this problem! The code may be written
as classes and objects or procedurally.
Include any and all files required for playing your game, including gifs
(either ones we provided for you or custom ones that you created) and any
starter code you used, whether you modified it or not. We should be able run
mastermind_game.py in IDLE and play your game as you intend it to look for us.
Test Suite
Your test file should test a number of the functions (e.g. secret code
generation, matching, etc.) in your game that don’t involve turtle (and
remember, for good design and separation of concerns, turtle drawing functions
should be separate from game functions). Test edge cases and exceptions.
Starter Code
The starter code described below can be found here Download here.
Using our starter code is optional. You can opt to create all code from
scratch if you wish. You can also modify the starter code if you wish. We will
be providing you with these files:
Point.py
This file contains a class Point with two attributes, x and y. It represents a
geometric point with x and y coordinates. It has two methods: delta_x, which
takes as input another Point, and returns the absolute distance of the
different between this point and the other point’s x coordinates, delta_y,
which takes an input another Point, and returns the absolute value of the
difference between this point and the other point’s y coordinates.
Marble.py
This file contains a class Marble with the attributes pen, color, position,
visible, is_empty, and size. This class can draw an empty Marble and set its
color, get its color, erase itself, and determine if it has been clicked. This
class requires the use of the class Point.
Many .gif files for your UI (you can create your own if you wish, as long as
they are functionally similar): checkbutton.gif, a green check mark for the
“check” button file_error.gif, a file error popup message
leaderboard_error.gif, a leaderboard access error popup message lose.gif, a
popup message for when the player loses quit.gif, a red square for the “quit”
button quitmsg.gif, popup message for when the player quits winner.gif, a
popup message for when the player wins xbutton.gif, a red “X” for the “cancel”
button
Note: none of the popup messages actually pop up, they’re just gifs that you
have to write the code to make them open in a new window, etc.
Other Information & Evaluating Your System
Other Information
All user interaction should be via your Turtle-based user interface; users
must use the mouse to play your game (the only keyboard actions are when you
capture the player name at the start of the game).
Important Note: We know that Turtle provides a “shell” over some Tk
functionality, HOWEVER, you are NOT allowed to use Tkinter. For the graphical
portion of this assignment, you may only import turtle. Any and all other
graphics packages are disallowed and will result in a heavy deduction in your
project grade if you use them.
Program Evaluation
We will be inspecting your code, playing your game and assessing your overall
design
- We’ll be looking for the functionality described in this document and shown in the demo videos for program correctness.
- Document your code extensively, following all the guidelines you’ve learned through the semester and what’s in the Style Guide for the course.
- Make your code readable, following the style guide with good variable names, good function writing, well-formed and clear classes if you’re using classes, good use of whitespace, and all the other code readability guidelines you’ve learned throughout the semester. Readability and documentation get even more important the longer and more complicated your programs get!
- Keep your code as efficient as possible - don’t do anything twice that you only need to do once, etc.
- “UI Aesthetics” and user experience is important as well. Turtle is NOT a real-time graphics system so we won’t do anything to purposely overload the event system. However, your game should “look and feel” like a proper MasterMind game. If your screen does not update properly, or if you are not rendering graphics correctly, you will have marks deducted for problems with your UI Aesthetics
Important: Your project MUST be runnable and do something non-trivial to earn
credit! However, your program does not need to be functionally complete to get
partial credit. Having something non-trivial running and working gets you more
credit than having a bunch of code that doesn’t work at all. Code that runs
but is trivial (just so you can say “I have something working”) will earn you
a zero on this project.
Pro-Tips
Breathe!
This is a big project with a lot of moving pieces, but everything I’m asking
you to do is well within your skill-level. Remember our concepts on procedural
(or object) decomposition and take things one chunk at a time. You’ve got
this. You’ll be fine. Here are some tips to help you crush this…
Manage Your Time!
This project will have you using a bit of almost everything we learned this
semester (except recursion), so be sure to allocate appropriate time to
complete it. If you wait until the last minute to work on this, you are almost
guaranteed NOT to finish on time. You cannot use late days on this project,
because we have a deadline for turning in grades. Plan to start early!
At the same time, don’t panic. The project is bigger than anything you’ve
worked on this term, but the concepts are all within your reach. You’ll need
to do a bit of reading on Turtle to brush up on the elements you’ll likely
need for the graphics. In particular, review the turtle objects themselves and
think about how you can use multiples of them to do things on the gameboard
for you.
A link to Python Turtle documentation is here:
https://docs.python.org/3/library/turtle.html#turtle.update
Feel free to search the web for other Turtle resources to help you learn
whatever you think you might need to know for the UI portion of your
application.
I said it before, but must emphasize this point:
Sample Work Plan
Here are some of the things I did when creating the sample solution - you can
adjust these to suit your working style and progress.
Milestone 0: Turtle Pre-work Exploration (In agile terms, this would be called
a “spike” where we explore any technology we’re a bit shaky on, so we can
learn & gain confidence before trying to use it).
Goal: Review how to draw shapes, capture mouse clicks, use turtle objects to
render .gif images in the proper locations, etc. If you’re like me, you may
have forgotten some of the Turtle functionality since the beginning of the
semester. Take a day to practice and write code to do the basic drawing and
event handling you’ll need. Turtle also has some rudimentary “dialog box”
functionality like what you see me use in the video to get the player name and
the maximum number of moves allowed. It’s pretty straightforward, but you’ll
need to read the documentation to see how to use it. Some of this code will be
“throw-away” but it’s a learning exercise before digging in.
Milestone 1
Bulls & Cows Text version. Goal: Implement the fundamentals for basic game
without worrying about the graphics yet. Develop the functionality to generate
a randomized “secret code” and the ability to test user input via
count_bulls_and_cows(). Don’t spend a lot of time with an elegant textual
interface; you just want to get the core of the “game model” working so you
can use it later.
Milestone 2
Develop Gameboard: Write the code to create the entire game board: The play
area, status area & leader board. Validate the code works with “dummy” data.
Milestone 3
Marble placement & behavior: Write the code to manage proper Marble placement
for the game AND the Marble “Guess Panel” (at the bottom of the screen where
the user selects the colors they want). If you’re using our included Marble
code, you’ll likely want to spend a little time examining that code and seeing
how to use it. Check your layout algorithm to make sure it works for placing
each User Guess in the correct spot. Implement code to handle mouse clicks &
selecting Marbles appropriately.
Milestone 4
Game behavior: Write the code to implement the game rules. Generate the secret
code. Accept clicks on Marbles to guess positions. React appropriately to the
Reset button (to cancel current color selections) and Quit button to exit the
game.
Milestone 5
Leaderboard: Write the code to implement saving/retrieving and showing real
contents of the leader board. Continue to test. [1 day]
Milestone 6
Clean up: Refactor any code needed to handle issues with rendering. Clean up
code, continue to test.
Milestone 7
Error logger: Write the code to log errors to mastermind_errors.err. Clean up
code, continue to test.
Milestone 8
Write design.txt: Write your design description. Do your final testing and any
extra optional work (e.g. skinning your game). Wrap up any other outstanding
task.
