CS5001 Final Project: Puzzle Slider Game
Final Project
Programming Component + Written Design Description (100% of this assignment)
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.
IMPORTANT NOTE:
You may NOT use late days for this assignment. Any project turned in after the deadline will
receive an automatic zero! There are no exceptions to this except University-level approved illness
or family crisis (e.g. death, etc.). Manage your time well and be sure to submit something well
before the deadline.
What to Submit
Your files to turn in:
puzzle_game.py (includes a main() function that lets us run your game)
Other helper files (as many .py files as you need to implement the system)
design.txt (short plaintext file – 2 to 3 paragraphs – explaining your design and any trade-off
decisions you made). NB: If you try to achieve bonus points, you'll need 1-2 additional
sentences to describe your extra work there.
If you make UI customizations (described below) you must include the assets you've created so we can run your program appropriately. The file structure must match what is described in this project specification, and your code must run "as-is" without us having to do any "fixup" to make it work on our systems.
There are NO server-side auto-tests for this project.
Gradescope allows for .zip files to be submitted.
For this assignment, do NOT drag-n-drop your files to Gradescope!!!
To preserve the required directory structure, Zip your entire solution consisting of the .py files, the .puz files, the Image and Resource directories and your design.txt and submit the zip to Gradescope. We should be able to download your .zip from Gradescope, unzip it and run your program (see the description of project assets below).
You are the designer and implementer of this system, so you have a wide degree of latitude in how you approach this problem. The code may be written as classes and objects or procedurally. The choice of data structures is entirely up to you.
I've included some starter assets for the game. The file structure is explained below, and should be maintained as given. If you prefer to use other button images to have a customized "skin" for your game, that is acceptable. However, all UI element placement and the general look-and-feel must be consistent with the exemplar game given. We should be able run puzzle_game.py in IDLE and play your game as the original game was intended to be played.
Starter Assets
You can download a zip file with all of the starter assets from here . The zip file contains the subdirectory structure described below in this project specification. Ensure that the Python code you write (at least your main()) is at the root level with all of the puzzle (.puz) files. You are free to substitute your own visual assets (provide your own "skin") rather than using mine, but the UI element placement and functionality must match what you've seen in the demo movies and what is described in this specification.
The Game: Puzzle Slider
Puzzle Slider Game (https://en.wikipedia.org/wiki/Sliding_puzzle) is a combination puzzle where a player must slide pieces vertically or horizontally on a board to establish an end result that matches a solution. The pieces moved may consist of shapes, pictures, patterns, letters or
numbers. As a youth, you may have played a mechanical version of this game, called "15-puzzle" or "15-slide" where you needed to get fifteen numbers (1..15) in their proper numerical order.
Our Version
We’ll be designing a computer version
Prof Keith posted walkthroughs and examples of the game play. Watch the videos here: Game Play Functionality and Requirements
-
Show the Splash Screen before gameplay starts. The splash screen should "linger" for 3-4 seconds before you erase it, so your user can bask in the glow of your game's awesomeness. We're big-time game designers now and every big-time game has a splash screen.
-
The player should be able to input their name to your game through a pop-up window rather than in the terminal.
-
The player should be allowed to select the number of "moves" they can have to unscramble the puzzle. The lower limit is 5, the upper limit is 200. If the player unscrambles the puzzle in less than (or equal to) the number of moves they've chosen, they win the game. If they do not unscramble the puzzle within the number of allowed moves specified, they lose the game. NOTE: Some 15-puzzles (about 50%) are unsolvable. Using a simplistic tile swap or Python's shuffle() will often result in unsolvable puzzles. For this project, you do NOT need to guarantee a solvable puzzle. However, you may earn extra credit for identifying a non- solvable puzzle and/or for presenting your user with a guaranteed solvable puzzle (you'll need to do a bit of research on how to do this).
-
Moves are completed when the player clicks on a piece (I call them Tiles in my game) that is adjacent to a blank square (empty Tile). Logical description (you can implement this any way you wish): The Tile that is clicked shifts to the place where the blank was, and the blank shifts to where the clicked Tile was. Legal shifts are ONLY horizontal or vertical (no diagonal shifts are allowed). A status area on the playing surface updates and displays the number of moves a player has completed.
-
If the player clicks on a Tile that is NOT adjacent to a blank, nothing happens. No shifts occur and the click does NOT count as a move. Only actual shifts of the Tiles count as a move.
-
A status line in the game is updated when each move is completed by the player. If the player uses more moves than the "max moves" they've selected in rule #3 above, they "lose" the game. A message indicating that should be shown, and the program should end. If the player unscrambles the puzzle in less moves than selected in rule #3 above, they "win" the game. A message indicating that victory should be shown, and the program should end.
-
A player must be allowed to use the "Reset" button to auto-unscramble the puzzle. The game does NOT end if they press Reset, but the puzzle is displayed in its completed form (think of the reset as a "cheat code" for those of us who get frustrated with puzzles).
-
A player must be allowed to load a different puzzle from the file system using the Load button. Do not hardcode the "starter pack" puzzle names - your code should be able to read any puzzle file from the file system - including new puzzles created by your users (or the instruction team during our testing).
Puzzle files are multi-faceted. The description/meta-data is contained in a .puz file, and the actual resources are contained in directories within the Images directory given to you (more information on this follows below). If the user loads a different puzzle, the move count resets to zero (0) and the current puzzle to solve is updated with the user selection. -
If the user attempts to load a non-existent file, OR a puzzle (.puz) file that has malformed data, your program should display an error message and continue processing. Missing files are recoverable errors that should NOT crash your system.
-
Your program should also log any errors to an error file called 5001_puzzle.err. This is a text file which your support team will use to help investigate issues as you work on version 2 (because we know version 1 will be a blockbuster!). An example of my error file is given below
-
A player can quit and exit the game at any time using the Quit button.
-
OPTIONAL: When the program exits show a Credits screen before the program terminates.
You can use the Credits resource I've provided, or create your own
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, and/or when the player asks to load a different puzzle).
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.
Important Cross-Platform Note: Many of our TA/Graders use Linux or MacOS (a Linux/Unix
variant). Windows users - note that Python's "native tongue" for file paths is "/" NOT "\". In
particular, do NOT hardcode directory paths using Windows-style backslashes.
Any project submission that does not support cross-platform execution will have marks
deducted.
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 puzzle sliding 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
Suitableness for cross-platform execution. This primarily applies to Windows users since the "native tongue" for much of Python is Linux-style access (especially for files and directories). If we need to make edits to your code to get it to run on our systems, marks will be deducted.
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.
BONUS POINTS: Meeting the criteria outlined above allows you to earn up to 100 points for this
assignment.
In addition, you may earn up to 10 extra points on this assignment by completing the
following:
+5 ->
(a) supply additional code that determines if the current puzzle is solvable or unsolvable. There
is an algorithm to do this, and you'll need to research and implement it completely to earn these
bonus points.
(b) In addition, your Design Description must clearly state that you have implemented this
feature, and how we can view the status of "solvable-ness". You can opt to display the result of
your assessment via a simple console print, or somewhere in the Turtle GUI, but your
documentation must precisely describe what we should be looking for.
(c) You also must include a PyUnit test that validates your algorithm so that we can run it
against your code and do our own independent verification.
(a), (b), and (c) must be complete and correct to earn the credit. No "partial bonus" will be given
- the extra credit is all-or-nothing
+10 ->
You must include everything from +5 above, plus:
(d): supply additional code to guarantee the puzzle you supply to the player is solvable. As with
the previous bonus, you need to provide a PyUnit test that validates your "puzzle scrambler"
such that we can verify it is "solvable"
Bonus points are all-or-nothing. No partial credit will be given except in the case where you have attempted to achieve the +10 bonus, but only successfully completed (a), (b), and (c). In that case, you will be awarded +5, even though you did not fully complete +10.
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
(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:
You have about 3 weeks to complete this assignment. Work a little bit EVERY day (even if it’s refactoring your code) to make progress.
Have a plan and work towards smaller milestones to keep your development on pace for completion. If you haven’t planned a project before, a sample work plan is below. Feel free to use it
as a rough guide if you’re not sure how to get started. (You’ll need to act as your own project manager and writing down some timeboxed goals will likely be helpful).
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 1: 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.
[1 day] ------
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.
[1 day ] -----
Milestone 3: Tile placement & behavior: Write the code to manage proper Tile placement for the game for showing an unscrambled picture AND the "scrambled" version. Check your layout algorithm to make sure it works for placing Tiles and for showing/erasing images. Ensure that Tiles "swap" places appropriately.
[3 days] -----
Milestone 4: Game behavior: Write the code to implement the game rules. Scramble the puzzle. Accept clicks on Tiles to swap positions. React appropriately to the Reset button (to reset the puzzle) and Quit button to exit the game.
[3 days] -----
Milestone 5: Leaderboard: Write the code to implement saving/retrieving and showing real contents of the leader board. Continue to test.
[2 days] ------
Milestone 6: Load puzzles & clean up: Write the code to implement loading and rendering other puzzles besides the default Mario. Handle any size issues with rendering. Clean up code, continue to test.
[2 days] ------
Milestone 7: Error logger: Write the code to log errors to 5001_puzzle.err. Clean up code, continue to test.
[0.5 day] --------
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.
[0.5 day ]
Release: Before 11:59pm, December 09th: Make a "staging area" with all the code and assets you need to run your game. Run the game ONE final time to make sure it works and you haven't left anything out. Ensure the staging area has your design.txt document too (that's part of your grade). Double-triple check you have everything required for launch and - Ship It!
Project Assets
I am providing you with some project starter assets (images, etc.) that you can use for your game. As previously mentioned, if you want to develop your own "skins" for the game, that is acceptable. However, if you do so the game must be functionally equivalent, and the UI components must be in the same positions as what you see in my videos. Also note that your game must work with MY puzzles. If you want to create your own additional puzzles, that's fine - but if your program cannot utilize the puzzles I provide, you will lose marks.
File directories:
Your main driver and all .puz files should be at the root (top) directory level. Sub-directories called Images and Resources are provided. Your game must operate with the game resources and
images stored in the same directory structure as indicated. In other words, the actual .gif images for the puzzles must be in subdirectories within the Images directory as shown below
Puzzle file format:
Puzzle files describe the puzzle characteristics. They act as metadata for the "real" data that is held in the various subdirectories. Each puzzle file has a name that matches a subdirectory within the Images directory. The format is as follows:
Here, name is the name of the puzzle. Number represents the number of Tiles for the puzzle. Our puzzles are always squares. Valid numbers are 16 (for a 4x4 puzzle), 9 (for 3x3) and 4 (for 2x2). In the mario puzzle, Tiles are listed from 1 to 16, with the "unscrambled" image file associated with each number given. Thus, Tile 2 holds the image contained in file "Images/mario/15.gif". If we place the images in their numeric order, Mario is shown "unscrambled". Finally, the thumbnail image is the small image shown above the Leaderboard section and the size represents the pixel size of the images. Your Tiles should expand and contract to show the images appropriately. Valid sizes for this assignment range from 50 to 110. You may assume that we will NOT give you puzzle Tile sizes outside of this range. However, we MAY give you a malformed puzzle file (perhaps with number: 12 for example). You should display an error message to the user if you are unable to find/open/process a puzzle file.
User Messages:
I've provided some informational messages that you can show to the user. Again, Tkinter is not allowed so you cannot use the TkMessageBox. You'll need to design a way to show a graphical "Turtle Dialog". If you create your own skin, you can replace these message images with your own version, as long as they are functionally equivalent
Error Logging:
You must log errors to the 5001_puzzle.err file. This is your opportunity to log more detailed information regarding errors that may have occurred (and you've displayed a message to the user as above). You have freedom in determining the exact output to this file, but errors that trigger the dialogs described above (e.g. missing leaderboard or puzzle file errors) should be logged. Here is an example of my error log after a few sample runs of my program. You should APPEND errors into the file so all historical information is retained.
Extra Stuff You Can Do When You're Done
It's holiday season, so you can create your own puzzles and have your family & friends play if you wish. Perhaps a family photo (like the one I demo in the "sequel" playing video) would make a good puzzle to share with your people when you show off your game! Here is the website I used to split pictures: ImageSplitter (https://postcron.com/image-splitter/en/)
