| Sokoban home page | Download More Levels | Praise for Sokoban | Read Documentation |
| Sokoban for other Computers | Papers about Sokoban | Scott's home page | Scott's other Mac programs |
This is the online version of the documentation for version 2.4 of my Macintosh version of Sokoban.
In Sokoban, you are a warehouse keeper trying to get boxes through a maze of a warehouse to their proper locations. The boxes are so heavy that you can only push one of them at a time. Be careful that you don't get a box trapped in a corner: the boxes have no handles so they can't be pulled at all. If you prefer a more glamorous description, replace "box" by "treasure chest"; in fact, I think I'll do that in the rest of these docs.
There are over 400 different levels included (separated into several collections), and you can make your own levels, too. If you design good levels, I'll include them in the next version and give you credit.
Run Sokoban, enter your name as the new player, move using the mouse or arrow keys or numeric keypad, and push all of the round treasures into the outlined squares.
Keyboard: numeric keypad (8 keys), arrow keys, or your own key choices. Add control or shift to move farther, option to zip to a square.
Mouse: click to move or drag a chest (the program will move you to the place you clicked or push the piece you dragged, if possible). Command-click to drag a piece next to you.
Undo/Redo: Cmd-Z, ESC, F1, or ` to undo; space or Cmd-Y to redo; option-undo to undo a single step. They will auto-repeat if you hold the keys down.
Throw away the old version of Sokoban and start playing this version. Be sure to keep the Sokoban Scores file or you'll have to start over at the beginning! If you want, you may move the Sokoban Scores file from your System Folder or Preferences Folder and put it in the same folder as Sokoban 2.4. If you're upgrading from version 1.2, the old levels 51-85 are now part of the "Extra" collection; don't worry, the game will still know if you completed them (with 3 exceptions: the incredibly easy levels 51, 52, and 53 were replaced by new harder levels, so the game marks them as being uncompleted).
The first time you run Sokoban, it will prompt you to enter a new player's name. If it doesn't, either select your name from the Players menu to pick up where you left off, or select New Player... from the Players menu and make an entry for yourself. Sokoban keeps track of which levels you have solved in the "Sokoban Scores" file; this is normally in the same folder as Sokoban, but may also be placed in your Preferences folder inside the System Folder. If you quit in the middle of a level, then the next time you play Sokoban will load the level you were working on and show you what moves you made. To speed up the process, hold down the shift key.
The first level looks like this:
The treasures are the solid round things lying all over the place. Your job is to push them to the outlined squares using the pusher, which is the round ball with the arrows. There are many ways to move. The most intuitive may be to use the arrow keys to move up, down, left, or right. Shift-arrow key will move you as far as possible in that direction, including pushing treasures. Control-arrow key (if you have a control key) will move you as far as possible without pushing.
Instead of using the arrow keys, you can also use the numeric keypad 2, 4, 6, 8 or w, a, s, and d. Choosing "Set Keys..." from the Edit menu lets you change w, a, s, and d to whatever other keys you want (the numeric keypad and arrow keys can't be changed). Of course, shift and control work with all the different key sets.
You can also use the mouse to move. The cursor indicates which way you'll move if you press the button (and you can drag yourself around, too). If you see a cross hair cursor, then clicking will move you to where you clicked by the shortest possible route. Or if you'd rather use the keyboard to move long distances, hold down the option key then move the marquee around (with your favorite movement keys). When you let go of the option key, the player will zip to the square you selected (if there's a clear path).
If you want to zip to a square diagonally next to you, there is a shortcut. Instead of clicking there or pressing <option> left-up, pressing one of the diagonally located keys on the keypad (7, 9, 1, or 3) will do the same thing. You can also use the q, e, z, or x keys if you're left handed (unless you changed them with the "Set Keys..." command).
The snazziest movement option (and my favorite) is drag-and-drop movement. You can grab a chest with the mouse and drag to it a destination square. If there's a simple way to push the chest there (without pushing any other chests), it will be moved to the destination. This can be a real time saver on complex levels when you don't want to maneuver several chests over the same long path by hand. Normally if you click on a square adjacent to you, you'll move in that direction. If you want to pick up and drag the chest there, just hold down the command key when you click (you'll see a hand cursor indicating that you can pick up the chest and drag it). You may want to disable the drag-and-drop movement if you set up Sokoban for young children because it can make the children's levels much too easy; press command-shift-H to disable or enable using the hand to pick up chests. It's enabled by default.
There are also several menu items that will help you. From the Level menu, you can restart the level if you get stuck. You can also make a temporary save before you mess up, and revert to it when you get stuck later. Or if you're really stuck, you can move on and try another level, then come back later and work on the unsolved levels.
From the Edit menu, you can undo (and then redo) up to 10 000 of your last moves. There are many shortcuts for undoing: press function key F1 (labeled "undo" on some keyboards), or the ESC or ` key (in the upper left corner of your keyboard). The space bar, shift-F1, shift-ESC, and shift-` are all shortcuts for redo. Sometimes you may only want to undo part of a move (suppose you dragged a chest one square too far). Option-undo will undo one single step of a move (you can also use the option-key with redo, and it works with both the keyboard equivalents and the menu commands themselves).
You can copy or paste in a sequence of moves to a level. Create text using the characters U, D, L, and R (for Up, Down, Left, and Right) from a word processor, paste it into Sokoban, then use Redo to look at the moves. Case doesn't matter, and other characters are ignored, so you may paste something like "d, r, D, d, L" and the commas and spaces will be ignored. Or you can copy your move history and paste it into your favorite word processor to show your friends.
When someone first completes a level, his solution is saved in the Sokoban Scores file. When you play a level again, the previous best score will be shown, and if you beat it, your solution will replace the old one. To look at your old solution, choose the Load Best Score command in the Level menu and replay the solution by hitting Redo (the easiest way is to hold down the space bar). Sometimes you'll notice two best scores for a level. That's because there are really two scores for a level: number of moves used and number of pushes used. Usually, the solution with the fewest moves also has the fewest pushes, but not always. For example, one solution might use 347 moves and 97 pushes, while another uses only 331 moves but 104 pushes.
For information on other menu commands, turn on balloon help while you're playing Sokoban.
If you want to make your own levels, it's easy. Just create a text file in your favorite word processor (SimpleText works well and is included with your system software) and use the 'Play Screen From File...' command in the File menu to try it out, or just drop the text file on Sokoban's icon. If you are running System 7.5 or higher (or another system that supports the Drag Manager), you can select the text in your word processor and drag it to Sokoban's window to play the level. To copy a level that appears in Sokoban's window, drag it to your word processor or to the Finder to create a text clipping. To copy an entire collection from Sokoban (even one of the built-in collections), hold down the shift key when you start dragging. You'll see the window title bar changing as Sokoban converts the levels so you can drag them.
The included Sokoban font can be helpful for designing your own levels because you can see what the level will look like directly in your word processor: type the level in the Sokoban font instead of using Monaco. Just remember that you may have to save the file as text only to use it. For more information about the Sokoban font, see the file "Sokoban font docs".
This is what a file for level 1 of the Original Levels looks like
(using a monospaced font), along with an explanation of the symbols
to use.
#####
# #
#$ #
### $##
# $ $ #
### # ## # ######
# # ## ##### ..#
# $ $ ..#
##### ### #@## ..#
# #########
#######
Symbols used in the screen files:
" " (space)--An empty space (floor)
"#"--Walls (the walls will be curved and shadowed automatically)
"."--Target or goal square
"$"--Treasure
"*"--Treasure on a goal area
"@"--You (the player)
"+"--You standing on a goal square.
There is a limit of 31 columns and 18 rows; additional rows and columns will be ignored. If you make your own screens, send them to me and I'll credit you and include them in the next release of the program.
If you want to put more than one level in a file, that's OK. Look at the "Make your own levels" file included with Sokoban for instructions and examples.
For that extra finishing touch, use ResEdit or another utility program to change the creator of your level file to "SSok" (be sure you have the capitalization correct). Then the file will get a nice icon and can be played by double-clicking on it.
Sokoban can also open levels used by the other two Macintosh sokoban implementations, MacSokoban (by Ingemar Ragnemalm) and JSokoban (by Jason Townsend).
If you want to play Sokoban on more than one computer (for example, if you have to go to a computer lab to play and never use the same computer twice), just keep the "Sokoban Scores" file in the same folder as Sokoban. It will find it there and record which levels you have completed in that file. You can also start playing by double-clicking on the score file you wish to use.
Sometimes if your computer crashes while Sokoban is in the background, the score file gets corrupted. (Sokoban itself is very stable; the only time I have seen it crash is when I set the memory partition below the minimum size). I added code in version 2.3 that should make such corruption very rare if it still occurs at all (for you programmers, I call FlushVol after writing to the disk). If you get the error message "The 'Sokoban Scores' file can't be opened. See the documentation for possible solutions," try moving the "Sokoban Scores" file out of the Sokoban folder. When you next run Sokoban, it will create a fresh new score file; this new file should work fine, but will not contain a record of the levels you have completed. If you're handy with ResEdit, copy the 'USER' resources from the old Sokoban Scores file into the new one to restore the memory of the completed levels.
When making your own levels, be sure to use the correct symbols and especially to save the file as text only (this is done automatically if you use SimpleText to write your levels).
Sokoban was invented in Japan and first released around 1982 or 1984 by Thinking Rabbit. "Sokoban" is Japanese for "warehouse keeper" and the object was to push corrugated cardboard boxes around. In 1984, Spectrum Holobyte produced an English version for IBM-PC computers; the "Original Levels" collection contains the levels from this version.
Two major sokoban versions were released in Japan only: "sokoban perfect" (Thinking Rabbit 1989) with 306 levels, and "sokoban revenge" (Thinking Rabbit 1991) with another 306 levels. Some of these levels appear in the "IQ Carrier" and "Boxxle" collections, but the rest are still available only in Japan. In fact, these two versions are still being sold commercially in Japan by Powerhouse http://www.powerhouse.co.jp. I hope to make these levels available in Macintosh format some day, but must first get permission to distribute them.
Not long after the Spectrum Holobyte version appeared, someone wrote versions of Sokoban for MS-DOS and Unix machines. The version I first played only had levels 1-50. Then Joseph L. Traub collected another 35 levels and included them with XSokoban, his version for Xwindows. These levels, along with a few more from the current XSokoban distribution, form my "Extra" collection.
In 1993, Phil Shapiro <pshapiro@aol.com> made the levels in "Simple Sokoban" for those who found the original levels too difficult. He included the article "Educational Value of Sokoban," which describes his motivations and why you should be happy if your child spends all his time playing Sokoban.
"Dimitri & Yorick" levels were made by Jacques Duthen <duthen@club-internet.fr>, who also made the Sokoban font. The collection is named after his children. He suggests that the levels are best for kids ages 4-8.
"Still More!" consists of levels by J. Franklin Mentzer <wryter@aol.com>.
Radio Shack made a game called "IQ Carrier," which is a handheld sokoban game with 28 levels. A fan of both games sent me the levels from IQ Carrier and recommended the game for those who would like a nice portable version of sokoban. Those levels were first included in version 2.0.
"Boxxle" is a game for the Nintendo Gameboy. The Gameboy version has two volumes containing about 230 levels. However, all but the 165 I've included are duplicates of original levels or IQ Carrier levels. Many thanks are due to John Polhemus <fretsawyer@worldnet.att.net> for typing in all 230 levels and finding almost all of the duplicated levels.
This is my own implementation for the Macintosh. It does not use any source code from other versions, just their levels.
I know of two other Macintosh sokoban implementations: MacSokoban by Ingemar Ragnemalm <ingemar@lysator.liu.se>, and JSokoban by Jason Townsend <JasonTownsend@mail.utexas.edu>.
I don't plan to port this program to Windows, but a few free Windows versions of the game (by other people) do exist. In my not-so-humble opinion,they're not nearly as good as this Mac version. The Windows versions can probably be found at your local users' group or online service, or else visit my Sokoban web page for places to download them.
[If you have any good ones to share, let me know]
All of the levels included are solvable. Before I had solved all of them myself, John Polhemus solved all the levels I hadn't (and in the process found a couple errors I'd made in copying the levels). Part of the fun of the game is accomplishing something difficult yourself, so I rarely give hints. When you get stuck on one of the Original Levels, you might be able to try a simpler version of the level in the Simple Sokoban collection. If a simpler version is available, the "Try Simpler Level" command in the Level menu will take you to it. To return, choose "Original Levels" from the Collections menu.
This implementation is Freeware, but is © 1998 by Scott Lindhurst. Distribution by nonprofit groups or online distribution by online services or BBSs is permitted as long as this documentation file is included unchanged. For-profit distribution on CD-ROM or other media is permitted if you send me a copy of the disc or an opportunity to purchase the disc at a nominal price. I can be reached by e-mail:
ScottL@alumni.Princeton.edu
or US Mail:
90 Bacon St. Apt. 2
Waltham MA 02451.
The latest version of Sokoban will be available through my Sokoban page on the World Wide Web at http://sneezingtiger.com/sokoban/ or by FTP from better FTP sites worldwide (especially at info-mac mirrors and mac.archive.umich.edu). I also attempt to e-mail announcements of new versions (not more than one or two a year) to fans who have sent me email.
You can copy my e-mail, US mail, or Web page address from the Edit menu; if you have the free Internet Config extension installed, you will also have the option to send these addresses to your Web browser or e-mail application.
I will mail you the latest version of Sokoban if you send me a disk and envelope with sufficient postage or $3 to cover the cost of a disk, mailer, postage, and the hassle of going to the post office. If you don't live in the US, please be sure to send enough to cover return postage--I already spend much of my free time on Sokoban, and I don't want to spend all my money supporting it.
These can all be reported to me at the above address. If you are the first to report a bug, I'll publicly thank you in the About box of the next version of Sokoban. I also love to get fan mail about Sokoban.
The best way to contact me is by e-mail. I usually respond within a couple days unless I'm out of town. If you contact me by US mail, please include a SASE or at least a stamp for a faster reply. That way I'll feel bad if I don't respond to your letter and I won't have to go out to buy stamps before I can reply.
I recently earned my Ph.D. in mathematics at the University of Wisconsin-Madison and even more recently got married. I'm interested in computational number theory (mostly computation in finite fields, but also factoring and other algorithms). Programming has been a hobby of mine since my parents got an Apple ][+ back in 1980 or so. When I got my Mac Plus, I wanted to learn all about it. Eventually (after about 4 years and some minor projects), I decided to implement Sokoban and finally learn about programming with the Macintosh toolbox. And it worked.
For more information, a résumé, and a short autobiography, visit my web pages at http://scott.lindhurst.com/
Sokoban was originally written in Think Pascal 3.0, on a Mac Plus running System 6, then System 7, and now System 7.5. Versions 1.2 and higher were done on a Power Macintosh 7100/66 with Think Pascal 4.0.2 and 4.5d4.
Sokoban works best under System 7 or later (including MacOS 8), and runs on every machine capable of running System 7 (including my 12 year old Mac Plus!). Sokoban takes up so little memory that it should work under System 7 on a machine with as little as 2 megabyes of RAM. It also works under System 6.0.7, but hasn't been extensively tested with such old system software.
2.4 (March 6, 1998)
2.3 (Jan 15, 1997)
2.2 (April 30, 1996)
2.1 (February 24, 1996)
2.0 (February 2, 1996)
1.2 (Oct. 3, 1994)
1.1.1 (Sept. 8, 1993)
1.1 (April 27, 1993): Thanks to Russell Owen for all his suggestions and icons.
1.0: (April 18, 1992): First public release.
Sokoban home page | Download More Levels | Praise for Sokoban | Read Documentation | Sokoban for other Computers | Papers about Sokoban | Scott's home page | Scott's other Mac programs