Design and Implementation of the Puzzle Slider Game

•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)

•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 assignment specification, and your code must run "as-is" without us having to do any "fixup" to make it work on our systems.

Gradescope allows for .zip files to be submitted. 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 assignment 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.

You can download a zip file with all of the starter assets from here   Download here. The zip file contains the subdirectory structure described below in this assignment 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.

Puzzle Slider Game (Links to an external site.) 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.

Starter Assets

We’ll be designing a computer version

Prof Keith posted walkthroughs and examples of the game play. Watch the videos here:

•PuzzlePlay - The Movie (Links to an external site.)
•PuzzlePlay - The Sequel (Links to an external site.)

1.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.

2.The player should be able to input their name to your game through a pop-up window rather than in the terminal.

3.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

4.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.

5.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.

6.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.

7.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).

The Game: Puzzle Slider

8.A player must be allowed to load a different puzzle from the file system using the Load button. 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. 

9.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.

10.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

11.A player can quit and exit the game at any time using the Quit button.

12.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

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 assignment grade if you use them.

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!

Our Version

•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

Important: Your assignment 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 assignment.

Breathe!

This is a big assignment 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...

This assignment 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 assignment, because we have a deadline for turning in grades. Plan to start early!

At the same time, don’t panic. The assignment 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.

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:

I promise you, you will not be able to complete this assignment if you wait until the last minute.
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.

Game Play Functionality and Requirements

Have a plan and work towards smaller milestones to keep your development on pace for completion. If you haven’t planned a assignment 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 assignment manager and writing down some timeboxed goals will likely be helpful).

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).

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 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: 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.

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.

Milestone 5: Leaderboard: Write the code to implement saving/retrieving and showing real contents of the leader board. Continue to test.

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.

Milestone 7: Error logger: Write the code to log errors to 5001_puzzle.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.

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!

I am providing you with some assignment 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.

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 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 Titles 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.

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

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.

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!

Simply upload your jpeg or png image to this site, then ask it to split your picture into the number of separate "slices" you want (remember our game is a perfect square). Download the separate pieces and convert those to .gif images (which is what Turtle requires). Finally, create your metadata .puz file to correspond to the puzzle data you've created, and you're good to go. It's a great holiday gift to show off to your family. 
You're welcome!