Puzzler

Table of Contents:

• Introduction
• Features
• Status
• Screenshots
• Get the Code
• Author and Licence

Introduction

Puzzler is my first pygame program written more or less from scratch. It strives to be a realistic simulation of working a jigsaw puzzle. It cuts pieces in interesting ways and gives you a large virtual puzzle table to work on.

Features

• One or more pieces can be moved and rotated on a virtual desktop (or table) that can be arbitrarily sized (though this size is currently hard-coded in the app). A piece can be in one of 36 orienatations (10 degree rotation increments) which makes for a bit of challenge. Pieces can be selected by left-clicking. More than one piece may be selected by holding down the shift key and left-clicking, and pieces may be removed from the selection by holding down the control key and left-clicking.
• The puzzle is cut using a fun multi-wave algorithm that makes for (IMHO) very interesting puzzle pieces.
• Pieces give feedback when placed together correctly by "clicking" into place.
• A full table browser can be brought up by pressing F3 which shows a schematic representation of the whole table and the location of pieces on it. The main screen shows a sliding window view of the table that can scroll in all four directions.
• The table defaults to black, but can be set to any of eight different shades up to full white (using the F1 key to cycle to darker, and the F2 to cycle to lighter). This lets you easily spot pieces that might otherwise blend into the table color.
• The table has an underlying grid which can have its density increased (with the '.' key) or decreased (with the ',' key).

Status

Puzzler is currently alphaware, current version is 0.21. It works with pygame 1.5 and Python 2.2.1, and also with pygame 1.7.1 and Python 2.4.2, provided your pygame is patched with revision 1.31 of lib/sprite.py from pygame.org's CVS repository.

What I have implemented thus far seems to work well, but it needs much more functionality:

• An actual user interface to select an image file to use as a puzzle, and select a difficulty level (number of pieces and perhaps alternative cutting algorithms). All this stuff is currently hard-coded in the application, but the code is designed to take parameters for these things and is just waiting on the appropriate UI hooks.
• Save and load an in-progress puzzle. There's an easy but horribly wrong way to implement this (just pickle the pieces and save them to a file), but the better way to save file space would be to save the initial cutting state and image in a header, and then only marshal the data that represents position and orientation of the pieces.
• The application should group pieces that are already put together so that solved parts can be moved about and rotated as a single unit. Rotation of a solved section is a tricky problem because the ideal would be to compute a "center-of-mass" and rotate about that. The aim of the program is to simulate the physical act of assembling a jigsaw puzzle as much as possible.
• Related to the previous item, we also need to detect when the puzzle is completely solved so that we can notify the user and give them the satisfaction of knowing they did well.
• The table browser (q.v) should be clickable and take you right to the part of the table you click. It may also be nice to be able to move the table browser (for now, it always lives in the northwest corner of the screen.
• The rotation of pieces is a bit dodgy with the mouse. You right-click and hold, and moving the mouse left or right will rotate the piece. The right and left arrow keys also rotate when the right button is down. It is currently a bit difficult to get the piece to rotate with precision.
• A "look at the box" function would be nice to show the user the original image when they want to see it.
• No doubt many inefficiencies can be found as this program was written as I learned the pygame interface. It's not the cleanest codebase around, but it's not undocumented, either. There's some pre Python2.3 hackery for implementing class methods and other such things that could be updated.
• A decent instruction manual could be handy.

With that in mind, if you are interested in helping out with these things (designing, coding, testing, documenting) or if you have other suggestions for improvements I'd love to hear from you. If there's something you like in my code for other projects you're welcome to that as well, subject to the terms of the GPL.

Screenshots

Two pieces selected for manipulation. Table browser is visible in the upper left corner (153kB).

Get the Code

Select your format:

• tar gzipped
• zip file (forthcoming)
• Anonymous CVS (forthcoming)

Author and Licence

Randy Kaelber wrote puzzler, using python, pygame, and SDL. The author is a huge fan of all three of these packages and recommends them heartily for powerful and fun software development.

The author may be contacted via email using the name of this project ("puzzler") at nimitz dot net.

Puzzler is distributed under the GPL version 2.0 license.

The default puzzle image is a picture of the payload fairing around one of the Mars Exploration Rovers as it sits waiting for final inspection before liftoff. The author also encourages you to check out the home page of the lab he used to work at for some cool Mars-related stuff.