Sokoban

Sokoban Registered Trademark of Falcon Co., Ltd., Japan

Sokoban Copyright 1982-2017 by Hiroyuki Imabayashi, Japan
Sokoban Copyright 1989, 1990, 2001-2017 by Falcon Co., Ltd., Japan

Sokoban YASC Copyright 2001-2017 by Brian Damgaard, Denmark

Version: 1.646
E-mail: BrianDamgaard@jubii.dk
Website: http://sourceforge.net/projects/sokobanyasc/

License
Sokoban YASC - Yet Another Sokoban Clone
Copyright 2001-2017 by Brian Damgaard, Denmark

This program is free software: you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If
not, see http://www.gnu.org/licenses/.

Additional Terms
Redistribution of the material is subject to the following GNU General Public License compliant
additional terms:

0 Preservation of the author attributions listed under the "Credits" section is required.

1 Misrepresentation of the origin is prohibited, and modified versions must be marked as such.

Credits
Please note that the links mentioned in this section are the original ones and may not exist
anymore.

Standard Sokoban skin and application icons:

Copyright 1997-2000 by Games 4 Brains.
Original website: http://www.games4brains.de

Additional Sokoban skins and illustrations:

Copyright by Gerry Wiseman.

"KSokoban" skin:
Copyright by Anders Widell.
Original website: http://hem.passagen.se/awl/ksokoban

"Macintosh" skin:
Copyright by Scott Lindhurst.
Original website: http:sneezingtiger.com/sokoban/
Built-in level collection "Crazy Monk":
Copyright by Jean-Pierre Martel and Matthias Meger.
Original level e-mail address: sokomonk@laposte.net

Built-in level collection "du Peloux":

Copyright by Aymeric du Peloux.
Original level website: http://membres.lycos.fr/nabokos

Built-in level collection ""GRIGoRusha":

Copyright by Evgeny Grigoriev.
Original level website: http://grigr.narod.ru

Built-in level collection "Haywood":

Copyright by Lee J Haywood.
Original level website: http://leehaywood.org/games/crossoban/

Built-in level collection "Holland":

Copyright by David Holland.
Original level website: http://www.clickfest88.freeserve.co.uk/

Built-in level collection "Skinner":

Copyright by David W. Skinner.
Original level website: http://users.bentonrea.com/~sasquatch/sokoban/

Built-in level collection "Sladkey":

Copyright by Rick Sladkey.
Original level website: http://home.comcast.net/~jrsladkey/sokoban/index.htm

Built-in level collection "YASGen":

Copyright by Brian Damgaard.
Original level website: http://sourceforge.net/projects/sokobanyasc/

Built-in level collection "Yoshio":

Copyright by Yoshio Murase.
Original level website: http://www.ne.jp/asahi/ai/yoshio/sokoban/

"Mandala" eyecandy:
Copyright by Anthony Steele.
Original website: http://users.iafrica.com/a/as/asteele/mandala/

PNG Image loader source code:

Copyright by Michael Vinther.
Original website: http://sourceforge.net/projects/imagefilelib/

Sokoban YASC, YASGen, YASO, and YASS source code:

Copyright by Brian Damgaard.
Original website: http://sourceforge.net/projects/sokobanyasc/

Acknowledgments
I would like to thank all who have contributed to the program, e.g., by sending comments,
suggestions, and bug reports. I am particularly indebted to:

2 David Holland, for sharing a lot of insight into how a good Sokoban program should work.
3 Fred Minklei, for so many good ideas and suggestions about game features and user-interface
and for graphical contributions.

4 Games 4 Brains, for letting me use their excellent Sokoban game graphics.

5 Gerry Wiseman, for allowing the distribution of his excellent skins and illustrations under the
GPL license.

6 John Polhemus, for his great help with the English texts and for writing an exceptionally good
skin tutorial.

7 Joris Wit, for fruitful comments and suggestions concerning the file format.

8 Lee J Haywood, for sharing a lot of ideas and for a long-standing correspondence on Sokoban
topics.

9 Matthias Meger, for a fruitful exchange of ideas about Sokoban related algorithms, e.g.,
solvers, optimizers, and deadlock detection.

10 Raymond Groenestein, for his great help with the English texts.

11 Sebastien Gouezel, for inventing the "Vicinity search" optimization method, and
generously sharing information on the method and its implementation. By sharing his ideas and
insights on the subject, he has made a significant and lasting contribution to the Sokoban game
itself, transcending the implementation of the algorithm in the YASO optimizer.

Trademarks
Company names, brand names and product names are trademarks or registered trademarks of
their respective holders.

Introduction
Welcome to the Sokoban game!

"Sokoban" is a Japanese word for warehouse keeper. Basically, the job of a warehouse keeper
is to place boxes within the warehouse in an organized manner, and this is the key idea in the
Sokoban puzzle game invented in Japan in 1982 by Hiroyuki Imabayashi, winning a computer
game contest with his program. The rules are simple and yet give rise to challenging and
beautiful puzzles ranging from simple to extraordinarily complex ones.

The Sokoban YASC program includes a large set of popular puzzles, or "levels", as they often are
called. There are many thousands more available on the internet, and thanks to the standardized
Sokoban level format, most of them can be played with this program.

The Rules
The game consists of a warehouse made up of walls that form passages. Within the warehouse
are the pusher and an equal number of boxes and storage locations. The pusher can only
push a box, never pull, and only one box can be pushed at a time. The goal is to push all the
boxes into the storage locations.
These rules present a variety of challenges. Since the pusher can't pull a box, there are some
pushes that are irreversible. A box is stuck when pushed into a corner or against a wall that it
can't be pushed out of or away from. In real life a warehouse keeper can't walk through boxes or
walls. The same is true for the pusher in the game, so the pusher can also be stuck or trapped in
an area surrounded by walls and boxes where the boxes can't be pushed out of the way.

Recommended Levels for Beginners

David W. Skinner's level sets "Microban" and "Microban II" are highly recommended for
beginners and children. Most of these puzzles are small and illustrate a particular concept. More
experienced players should also find them interesting for their variety.

The level sets "Microban" and "Microban II" can be found in the "Skinner" collection.

Aymeric du Peloux's "MiniCosmos" levels are also excellent for beginners. They systematically
and progressively introduce the beginner to typical Sokoban themes.

The "MiniCosmos" levels can be found in the "Peloux" collection.

How to Play
The pusher is moved using the arrow keys or the mouse.

Mouse Functions

12 Drag and drop a box by placing the cursor on a box, pressing and holding down the left
mouse button, dragging the box to the desired position, then releasing the button. The pusher
will figure out the best way to do all the running and pushing needed.

13 A variant to "drag and drop" is click and drop. Left-click on a box to select it, move the
cursor to the desired position and left-click again to drop it. "Click and drop" is easier for long
moves than holding down the left mouse button while using "drag and drop".

14 To move the pusher without moving boxes, apply "drag and drop" or "click and drop" to
the pusher.

15 Rotating the mousewheel down will undo the latest move.

16 Rotating the mousewheel up will redo a move from history.

17 Left-click a wall cell to show the boxes that can be moved in the current point in the
game. Click again to show the board normally.

18 Left-click an empty floor cell to select it and show the boxes that can be moved there.
Click one of those boxes to move it to the selected floor cell, or click the selected floor cell a
second time to show the board normally again.

19 Double-click a wall cell to enter replay mode. Here you can watch all the moves
comfortably instead of single-stepping through them using "Redo" and "Undo". Stop replaying
at any time with a single left mouse button click. A single right mouse button click toggles the
direction of play during replay.
20 A "Browse" button appears on the status bar after you have made one or more moves in
a game. Point at this button with the cursor to enter browse mode. Here you can comfortably
browse through the moves in the game by moving the cursor over the history slider. You can
leave the browsing mode in two ways. 1) Moving the cursor away from the history slider will
return you to the point in the game where you entered the browsing mode. 2) Clicking on the
history slider will take you to the selected point in the game.

21 Clicking the right mouse button is a very convenient shortcut that offers an alternative to
frequently used actions for normal move selections. If your mouse doesn't have a wheel the
default action of the right mouse button during normal game play is "Undo move". If your
mouse has a wheel it can be rotated to undo or redo moves. The default action for the right
mouse button on a mouse with a wheel is "Open currently selected snapshot" (if any) or "restart
the level" if no snapshot is selected. In "Settings", you can select which action to assign to right
clicks.

In reverse mode, i.e., when you try to solve a level backwards, the pusher can jump to get out
of a fenced in area. Use "drag and drop" or "click and drop" to move the pusher from the fenced
in area to an empty floor cell somewhere else on the board. Jumps can also be made using the
keyboard by combining [Ctrl] with the arrow keys.

Of course, a solution cannot include a jump after a box has been moved, hence, jumps are only
allowed before pulling the first box. You can, however, use "Settings" to enable jumps during
the entire game if you think this makes it easier to search for a solution.

Keyboard Functions

22 Move around: Arrow keys

23 Undo last move: [Delete] or [Backspace]

24 Redo move from history: [Insert]

25 Redo all moves from history: [End]

26 Restart level: [Home] (or [Enter], when no snapshots)

27 Open selected snapshot: [Enter]

28 Save position as a snapshot: [Ctrl] + [Enter]

29 Toggle window: [Shift] (Game or snapshots)

30 Toggle game mode: [Ctrl] + [Shift] ("Normal mode" or "Reverse

mode")

31 Previous level: [Page up]

32 Search previous unsolved level: [Ctrl] + [Page up]

33 Next level: [Page down]

34 Search next unsolved level: [Ctrl] + [Page down]

35 Replay moves forwards: [Ctrl] + [End] (Press again to change speed)

36 Replay moves backwards: [Ctrl] + [Home] (Press again to change speed)

37 Copy level to clipboard: [Ctrl] + [C] (Using "fill floors?" setting)

38 Copy level to clipboard: [Alt] + [C] (Using opposite "fill floors?" setting)

39 Copy level to clipboard: [Shift] + [Ctrl] + [C] (Run-length encoding)

40 Copy board to clipboard: [Ctrl] + [B] (Using "fill floors?" setting)

41 Copy board to clipboard: [Alt] + [B] (Using opposite "fill floors?" setting)

42 Copy board to clipboard: [Shift] + [Ctrl] + [B] (Run-length encoding)

43 Copy normalized board to clipboard: [Ctrl] + [Alt] + [B] (Using "fill floors?" setting)

44 Copy normalized board to clipboard: [Shift] + [Ctrl] + [Alt] + [B] (Run-length

encoding)

45 Copy solution/moves to clipboard: [Ctrl] + [M]

46 Copy solution/moves to clipboard: [Shift] + [Ctrl] +[M] (Run-length encoding)

47 Copy solution/pushes to clipboard: [Ctrl] + [P]

48 Copy solution/pushes to clipboard: [Shift] + [Ctrl] + [P] (Run-length encoding)

49 Copy moves to clipboard: [Ctrl] + [F]

50 Copy moves to clipboard: [Shift] + [Ctrl] + [F] (Run-length encoding)

51 Copy continuation moves to clipboard: [Ctrl] + [G]

52 Copy continuation moves to clipboard: [Shift] + [Ctrl] + [G] (Run-length encoding)

53 Open tools: [Ctrl] + [T]

54 New snapshot of current position: [Shift] + [Ctrl] + [T]

55 Open editor: [Ctrl] + [D]

56 Open solver: [Ctrl] + [Q]

57 Show best solution/moves: [Alt] + [M]

58 Show best solution/pushes: [Alt] + [P]

59 Replay level solutions: [Shift] + [Ctrl] + [L] (Replays solutions for solved
levels, starting with the current level)
60 Import from clipboard: [Ctrl] + [V] (Imports levels, solutions, and
snapshots)

61 Toggle "Show coordinates": [Ctrl] + [Alt] +[F2] (Shows/hides board

coordinates during gameplay)

62 Calculate pushes lower bound: [0] (The digit zero, not the letter "O")

63 Pushes lower bound => clipboard: [Ctrl] + [0] (Calculates the pushes lower bound
and copies it to the clipboard)

64 Make screenshot: [Ctrl] + [.] (Saves a screenshot in the folder

"Application data folder\Screenshots", overwriting any existing files with no warnings. Tip:
Consider setting the maximum skin scale factor to 100% for best image quality, and for getting
a consistent scale for levels which are small enough not to be downscaled)

65 Make screenshots: [Shift] + [.] (Replays moves and saves a

screenshot for each move)

66 Rotate/mirror puzzle:
67 Reset: [Ctrl] + [1]
68 Rotate 90 degrees clockwise: [Ctrl] + [2]
69 Rotate 180 degrees clockwise: [Ctrl] + [3]
70 Rotate 270 degrees clockwise: [Ctrl] + [4]
71 Flip horizontally [Ctrl] + [5]
72 Flip horizontally + rotate 90: [Ctrl] + [6]
73 Flip vertically: [Ctrl] + [7]
74 Flip horizontally + rotate 270: [Ctrl] + [8]

In reverse mode, i.e., when you try to solve a level backwards, there are two situations where
you can combine the [Ctrl] key with an arrow key.

Before pulling the first box, the pusher can jump over walls and boxes to get out of a fenced in
area:

75 Jump: [Ctrl] + [Arrow key]

When the keyboard is used for reverse mode play, it's sometimes necessary to move the pusher
without pulling a box that normally would be dragged along by the pusher. There are two ways to
accomplish this:

76 Move pusher without pulling a box: [Ctrl] + [Arrow key]

77 Alternatively, you can let the pusher bump into the box, as if you wanted to push it. This
detaches the box so you can move the pusher in the opposite direction without pulling the box.

Using the mouse to drag-and-drop a box typically moves the box and the pusher several steps in
one operation. With default settings, "Undo move" and "Redo move" mimic this behavior. Use the
[Ctrl] key in combination with "Undo move" and "Redo move" in order to perform single-step
moves instead (or combined moves, if the option in settings has been changed to single-step
moves). Using the [Ctrl] key in combination applies to mouse functions and buttons as well as
keyboard functions for "Undo move" and "Redo move". Note however that single-stepping breaks
up a combined move for the rest of the current session, but it has no long-term consequences
because an optimal combined move ordering is calculated each time a level is loaded.

Keyboard Shortcuts

78 Show help: [F1]

79 Settings: [F2] (Pressing [F2] twice opens the skin

selector)

80 Default skin - red boxes: [F3]

81 Default skin - yellow boxes: [Ctrl] + [F3]

82 Next recently used skin, if any: [F4]

83 Music player - show/hide: [F5] (Not available in this version)

84 Music player - play/pause: [F6] (Not available in this version)

85 Music player - stop: [Ctrl] + [F6] (Not available in this version)

86 Music player - previous track: [F7] (Not available in this version)

87 Music player - next track: [F8] (Not available in this version.)

88 Tools: [F9] ([Ctrl] + [F9]: New snapshot of current position)

89 Default window size: [F11]

90 Default window size, centered: [Ctrl] + [F11]

91 Toggle normal/maximized window: [F12]

Solutions
Sokoban YASC automatically saves your best solutions. The status of the "Solution" button
indicates whether you have solved the currently loaded level. A "grayed" button shows that no
solution has been found yet, while an enabled button indicates that clicking the button will replay
the best solution found so far.

Solutions can be optimized for moves or pushes and in case you have one of each, the
"Solution" button offers you the choice which one to replay.

Sokoban YASC ships with solutions for many of the built-in levels, but in order not to spoil the fun,
they are "hidden" when the program is installed. You can, however, import built-in solutions
using the "Open" window. Sokoban YASC does not distinguish between imported solutions and
your own solutions, hence, after an import you cannot see who solved the level.

Scoring Metrics
There are 2 natural metrics for the Sokoban game:

92 Moves Number of pusher moves

93 Pushes Number of box pushes

During the game these numbers are always visible on the statusbar. Additionally, 4 extra metrics
are shown when the cursor hovers over the moves or the pushes:

94 Box lines Straight line box pushes

95 Box changes Changing focus from one box to another
96 Pushing sessions Changing from moving the pusher to pushing the boxes
97 Pusher lines Straight line pusher moves

By convention, when metrics appear as text they are separated by "/" like this:
"Moves/Pushes/Box lines/Box changes/Pushing sessions/Pusher lines".

Settings
Sokoban YASC is highly configurable. In fact, you can configure almost everything: Background
images, game graphics, menu buttons, sound effects etc.

If you are a seasoned Sokoban solver, you probably want to disable move animation so you
don't have to watch every single step when you use the mouse to drag and drop a box. This
option is the very first one: "Control | Move animation | Enabled".

Skins
The skin import feature lets you change the visible appearance of the game in a single operation,
instead of changing the settings manually one option at a time.

The import is very flexible and is not limited to a fixed skin format. Instead, the import is controlled
by scripts, one script for each format. That way, it's possible for you to write and add your own
scripts when new skin formats are introduced by other Sokoban clones.

Sokoban YASC comes with 9 built-in scripts for importing skins from:

98 JSoko

99 Sokoban++ (skins with "pseudo 3D" walls are not supported)

100 Sokoban BDE

101 Sokoban for Windows

102 SokobanP

103 Sokoban YASC Settings

104 Sokofan (some features, like different pusher tiles for moves and pushes, are not
supported)

105 Visual Sokoban (skins using ".gif" images are not supported)
106 YSokoban (YSokoban uses the common skin format)

Flexibility often costs a little in terms of complexity, and in this case, the important thing to notice
is that each time you import a skin, you must also specify the skin format. You will probably
forget it sometimes, and when a skin is interpreted as being of a different type, the walls, the
boxes, etc., are bound to look very strange, leaving no doubt that something is wrong. In that
case, simply load the skin again, this time specifying the correct format.

Skin Post-processing

Sometimes, a few manual adjustments are required after importing a skin. Here are some typical
examples:

107 Skins with seamless walls, that is, walls with separate images for each type of junction,
often come with a wall cap to fill the gap that otherwise would occur between the squares in a
2 x 2 squares wall quadrant. With default settings, wall caps are placed midways between two
squares, but some skins require a different offset. In "Settings", you find this option under:
"Graphics | Board | Figures | Wall | Wall cap offset, pixels".

108 Skins with seamless walls often reserve a part of the square for a shadow. This looks
good for inner walls, but because Sokoban YASC normally uses your own background image
instead of a skin-specific background, outer walls often look better without the shadow.
Therefore, "Settings" lets you remove the shadow for outer walls. You find this option under:
"Graphics | Board | Figures | Wall | Outer wall trimming, pixels".

109 Some skins are not originally designed for smooth animation like Sokoban YASC uses.
Often, Sokoban YASC succeeds in producing acceptable results even in this case, but
sometimes it's preferable to switch off smooth animation and instead move the pusher and the
boxes stepwise. In "Settings", you find this option under: "Control | Move animation | Smooth
animation".

Skin Tips

110 If a skin requires several manual adjustments you probably don't want to do it all over
again the next time you load it. To avoid that, open "Settings" and select "Files | Save as..."
in the main menu. Now enter an appropriate name and save the settings. The next time you
want to use the skin, load your settings-file instead of the raw skin. It is also faster to load skins
from settings-files than raw skins.

111 In the game window, pressing [F2] twice opens the skin selector. This shortcut is
sometimes more convenient than choosing "Settings" and then selecting "Skins | Load skin..."
in the "Settings" main menu.

Note for Skin Designers

Sokoban YASC skins are in a format that aspires to be a common format for Sokoban skins, or at
least a sub-set of a common format. All the imagery for the different entities in the game (e.g.,
boxes, walls, and the pusher), are put together in a single image. This makes it very easy to
distribute and share skins.

The format reserves an area of the image for any extra information that is required for proper
treatment of the skin. This extra information is stored as text inside the image. The text is,
however, not visually readable; to the eye it appears as randomly colored dots. The skin format
uses a tiled layout with all cells having the same size, and the area reserved for the text is the cell
located in the 4th column in the 4th row. This cell has a 1-pixel border along the top, left, and
right sides, and a 2-pixel border along the bottom reserved for any visual skin codes, so the text
only occupies the inner area.

Sokoban YASC provides the necessary tool for editing and viewing this extra information. It is
easier to use the tool than to read the following guide, but for completeness, here is how to use it:

112 In the main window, open "Settings".

113 In the "Settings" window, select "Skins | Load skin..." in the menu.
114 Now you are in the skin selector window. Open the skin image you want to edit.
115 When the skin image has been opened, click the "Menu" button and select "Image
text...".
116 Use the mouse or the "Section" numbers to select the area of the image where the
textual information resides. The common Sokoban skin format requires it to be the cell located
in the 4th column in the 4th row. You must select the entire cell, including the pixels on the
border reserved for visual information. Often, Sokoban YASC has already selected the correct
area for you, but it is up to you to ensure that the selection is correct.
117 Now right-click the text panel in order to bring up the context menu.
118 In the context menu, look at the first item, "Edit", which toggles editing on/off. If this is the
first time you use it in this session, you will need to click it once to enable editing. (You can
verify that editing is enabled by bringing up the context menu again. There should be a check
mark next to "Edit", indicating that editing is enabled.)
119 Now edit the text, and when you are done, you can either save it by choosing "OK", or
you can drop any changes by choosing "Cancel".

You can look at the existing skins for typical examples of what textual information to put in a skin.
The text is formatted as easily understood so-called INI-files.

Level Editor
The built-in level editor is found in the "Tools" window. The editor has a long list of features,
most notably:

120 An almost unlimited "undo/redo" feature where the transactions even are saved from
one session to the next. The transactions are kept until you start editing another level.

121 An internal clipboard which allows you to store several items. The clipboard items are
independent of the level currently being edited. This means, you can use them in different
levels and the items exist until you delete them manually.

122 Cosmetic modifications of a level, e.g., rotating, mirroring, and adding or removing extra
walls, don't lose existing solutions or saved snapshots. This only works as long as the
structure of the level is intact, of course.

There are a few limitations you should be aware of:

123 The "Tools" window doesn't have the same flexible support for skins as the main window.
Skins used in the "Tools" window must have a fixed format with 7 tiles horizontally arranged:
Pusher, pusher-on-goal, box, box-on-goal, goal, wall, and floor. The floor should preferably
be blank, otherwise there may be a severe runtime penalty.

124 "Undo/redo" is not fully supported in case you cancel the editing operation. You
can leave the editor either by choosing "OK" (or "Exit" which has the same effect) which applies
 any modifications you have made, or you can leave by choosing "Cancel", in which case all
modifications are dropped. The transaction history will only be intact after canceling if it still
contains the path to the state the level was in when you opened the editor. This path is lost if
you have used "undo" to go back before the opening state and then have made new
modifications here. This sounds (and is) complicated, therefore, it's better to save your work on
the internal clipboard than to rely on "undo/redo" to restore a state later.

Solver Plugins
Sokoban YASC supports solvers adhering to the "Common Sokoban Plugins Interface" first
introduced by Joris Wit in his Sokoban++ program. This means that all solvers with that interface
can be plugged into Sokoban YASC. You can open them, one at a time, and try solving levels with
them. Solvers run in the background so you can continue playing while they search for a solution.

To select and use a solver, open the "Tools" window and choose the "Solver" tool.

Sokoban YASC ships with the YASS solver plugin. YASS is an acronym for "Yet Another
Sokoban Solver" and it excels in finding push-optimal solutions for small levels.

Optimizer Plugins
Sokoban YASC supports optimizers adhering to the "Common Sokoban Plugins Interface". This
means that all optimizers with that interface can be plugged into Sokoban YASC. You can open
them, one at a time, and try optimizing solutions with them. Optimizers run in the background so
you can continue playing while they search for optimizations.

To select and use an optimizer, open the "Tools" window and choose the "Optimizer" tool.

Sokoban YASC ships with the YASO optimizer plugin. YASO is an acronym for "Yet Another
Sokoban Optimizer" and it can optimize moves, pushes, or box lines, using the secondary metrics
(box lines, box changes, pushing sessions, and pusher lines) as tie-breakers. The YASO
optimizer typically finds local optimizations which only require re-ordering the pushes for a few
boxes. There are better optimizers available however, so it is recommended to search the internet
for other optimizers.

Contrary to what one might expect, an optimizer may work in a way where it sometimes pays off
to run the optimizer again on the output from a previous run, even if its termination wasn't caused
by manual intervention or by a time limit. Therefore, it's recommended to check if that applies to
the optimizers you use.

Please note that the term "optimizer" is a bit of misnomer in that an optimizer seldom can
guarantee optimal results. An optimizer searches for improvements of existing solutions and
snapshots, and optimality can only be guaranteed for the smallest levels.

Level Generator
The Sokoban game is well-suited for level generation using a so-called genetic algorithm (GA),
with techniques like inheritance and mutation known from evolutionary biology. The built-in
YASGen level generator uses this approach.

Generating New Candidates

The generator operates with a set of equally sized candidates (levels) sorted in decreasing order
on their measured quality, or "fitness" as it is called in GA parlance. In biology, a "locus" (plural
"loci") is a position on a chromosome, and an "allele" is the contents at a given locus. Using these
terms, each candidate consists of a "chromosome" (a Sokoban board) with a given number of
"loci" (board squares). New candidates are created by selecting 2 existing candidates as
"parents", mixing their "alleles" (the contents of the board squares), and adding some random
mutations to create 2 "children".

Technical note: The selection method in YASGen is the so-called "rank selection", meaning that
the candidates are chosen probabilistically depending on their position in the sorted candidate
set. The better candidates have a higher chance of being selected, but all candidates have a
chance. This helps in keeping the diversity of the population large. The "mixing of the alleles" is a
so-called "one-point crossover" where a point is chosen randomly, and then the first child inherits
all alleles to the left of, and including, that point from the first parent, and all alleles to the right of
that point from the second parent, and vice versa for the second child.

Fitness Function
Measuring the quality of a candidate requires a fitness function. YASGen offers the choice
between measuring "number of pushes" and "number of box lines + box changes". The latter is
only an estimate and not an exact measure like the number of pushes. However, box lines and
box changes may sometimes be a better measure of the level complexity.

Evaluating New Candidates

After having generated a new candidate using crossover and mutations, the next step is to
calculate its quality according to the selected fitness function. The calculation is best explained by
an example with "pushes" as fitness function, and "backward search" as calculation method, in
which case the new unevaluated candidate is a level with walls and goals only.

The evaluation starts with putting boxes on all the goal-squares. It then begins pulling the boxes
around on the board, as if it is playing Sokoban in reverse mode, the difference being that
the board has no box starting positions, meaning that the search is not targeting a particular
position. Instead, it is assumed that the more pulls it takes to reach a position, the more difficult it
will be later for a human player to find the pushes to go forwards from that position to the terminal
position. So when the search cannot find more positions by pulling boxes, then one of the
positions requiring the highest number of pulls is elevated to the start position for the
candidate.

The result is that the number of backward pulls is the fitness measure for the candidate. This is
also the number of pushes for an optimal forward solution.

What follows is a description of the level generator settings.

Generator Settings - Evolution

The number of candidates in the population is fixed during the generation. A new candidate
enters the population if its measured quality (its fitness) is better than the lowest valued member
of the existing population. The population should have a reasonable size to help keep the
diversity large.

The open limit prevents the generator from spending too much time on a candidate. For
instance, a board with a wide open area has many permutations but very little complexity.

Sooner or later the population converges towards a local optimum where new candidates rarely
qualify as new members of the population. To improve the diversity, the generator operates with
"aging". When a certain number of successive candidates do not qualify as new members of the
population, then the candidate in the population which had the greatest number of chances to
reproduce is evicted, making room for a new candidate, no matter what quality it has. The
inactivity threshold controls how often the eviction occurs.

The generator operates with two level types: Goals must be connected, or they may be scattered
at random.

Generator Settings - Fitness

The fitness is a measure of the quality of the candidates. The number of pushes is a suitable
measure, but sometimes the number of box lines and box changes give a better picture of the
complexity of a level. However, for efficiency the generator only makes an estimate of the number
of box lines and box changes.

A level may begin with one or more trivial forced pushes. Discarding trivial opening pushes
gives a better picture of the complexity. This feature, as well as discounting trivial tail pushes, is
only in use when the fitness is calculated using a backward search. Please see further down.

Levels may have a "tail" of easy pushes at the end of the game. Discounting tail pushes may
give a better picture of the complexity. The setting for this option is the number of box contacts
per box at the end of the game. An example: When 2 box contacts per box are discounted, the
fitness calculation ignores final pushes for 3 boxes A, B, and C like "AAABBACCBBBCCCC"
because no box is contacted more than twice in this ending.

The fitness of a level candidate is calculated by finding the longest optimal game on the board. A
forward search finds the longest game by pushing the boxes away from their starting positions.
A backward search finds the longest game by pulling boxes away from their final target
positions.

The backward search is strongly recommended because it is much more efficient than the
forward search. The backward search only requires a single search, whereas the forward search
requires several searches, one for each pusher zone on the board starting position.

The only practical use for the forward search is to post-process an existing level in case its
starting position has some qualities (e.g., symmetry) which should be retained.

Generator Settings - Reproduction

In each generation, two existing candidates are selected for reproduction, and two "children" are
created by means of crossover and mutations. Probabilities expressed as percentages control
how often these genetic operators are used. When the level generator is seeded with a single
level (e.g., via the editor), this level can be treated as a fixed template with immutable walls and
goals or boxes (depending on the search direction). Whenever possible, all generated candidate
levels will include the immutable objects.

Generator Settings - Random Boards

To start the level generator, it must be seeded with a board. This seed can either be a board from
an existing level or a randomly generated board. The size of the seeding board defines the shape
of all the generated candidates.

Generator Settings - Generator

The fitness of a candidate is calculated by finding the longest optimal game on the board. For
instance, when the calculation uses a backward search, the search begins with all boxes on their
final target positions, then the search pulls the boxes around on the board, counting how many
pulls it takes to get to each of the new positions.

The transposition table contains all the positions found during the search. Consulting this table,
the search can avoid analyzing the same position more than once, i.e., the search avoids getting
caught in infinite loops, moving boxes back and forth between identical positions. If the table
becomes full, then the search must stop. This means that the size of the transposition table
can have a direct impact on the length of the longest found game.

The generator runs in the background, so you can continue playing while it performs its
calculations. The task priority controls how much computing time the generator gets, compared
to the other tasks running on the computer.

All choices made by the generator (e.g., which mutations to perform, which candidates to select
for reproduction) are based on a so-called pseudo random number generator, a function
producing a sequence of seemingly random numbers.

Normally, the number seed should be chosen randomly because it makes the generator produce
a new sequence of events, even when all the other settings are the same.

If there is a need for reproducible results, then a fixed number seed can be chosen. This causes
the generator to produce the same sequence of events in two runs with identical settings and
identical start candidates.

Level and Skin Capture

This tool lets you extract Sokoban levels and skins from images, which can be loaded from files,
the clipboard, or the screen. After loading the image, the extraction is a three step process:

125 Specify where the level is in the image.

126 Specify the number of columns and rows in the level.
127 Specify the contents of each square in the level.

Now the level and the skin can be used in the game, saved as files, or copied to the clipboard.

The skin may require further processing, such as adding directional pusher images, or editing the
wall cap if the level did not provide one. You can edit the skin in any image editor.

When a skin has been captured and saved, it can be used for subsequent extractions of levels
from other images having the same skin. All that is needed is to specify which skin to use for the
extraction. There are two different forms:

128 Extract a level using a skin with exactly the same scale (i.e., column width and row
height) as the level to be extracted from the image.
129 Extract a level using a skin with a different scale than the level to be extracted from the
image.

The former can be applied as soon as the image has been loaded. The latter requires entering
the board position and the number of columns and rows before it is applicable, and since it is
slightly more error-prone, a careful inspection of the extracted level is necessary. The two
methods represent a compromise between recognition quality, user friendliness, and ease of
implementation. They are not in any way near the state of the art in image recognition software.

Duplicate Finder
Contrary to what one might expect, the duplicate finder is not located in the "Tools" window but in
the "Open" window. To launch the duplicate finder, open the "Open" window, select the "Menu"
button, and then select "Find duplicate levels...".

The duplicate finder tool comes in three flavors:

130 Find levels similar to the current level.

131 Find duplicates of levels in the current collection.
132 Find all duplicate levels.

Level File Format

Levels are stored as normal text files and can be edited in all text editors capable of handling files
in plain ASCII format. Windows' own "Notepad" is such an editor.

The syntax follows the de facto standard used by most other Sokoban programs. Thus, it is
possible to import levels from many other programs.

Levels can be 50 x 50 squares with maximum 1200 boxes.

Each game is limited to 100000 moves.

These limits are specific to Sokoban YASC. The Sokoban game itself does not impose any limits.

Caution

Sokoban YASC automatically updates level files with your solutions, snapshots, and current game
history. Normally this is what you want, but it is a problem if some of your private level
collections must keep their old file format for compatibility with other programs. When you use
the "Open" window to browse and select levels you can choose to open a copy of the level
instead of the original. Please note that this applies to that level only, and not to other levels if you
later use the browse buttons in the main menu to change level. You can, however, use "Settings"
to disable the auto-save feature more permanently by setting the value of the following options
accordingly:

"Control | Solutions | Save best solutions automatically"

"Control | Snapshots | Save snapshots automatically"

"Control | Timing | Enabled"

Please remember that disabling these features makes it up to you to secure any solutions you
find, for example by using the "Save as..." button to save a level to a new file.

File Format

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Sokoban (c) by Falcon Co., Ltd., Japan ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: File Format 0.17 ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: ::
:: File Notes Optional ::
:: Puzzle 1 Required ::
:: Title Optional* ::
:: Board See legend ::
:: Puzzle Notes Optional ::
:: Saved Game or Solution 1 Optional ::
:: Title Optional* ::
:: Moves See legend ::
:: Notes Optional ::
:: Saved Game or Solution 2 Optional ::
:: ... (more saved games and solutions) ::
:: Puzzle 2 Optional ::
:: ... (more puzzles) ::
:: ::
:: Remarks: ::
:: ::
:: File Notes ::
:: File notes consist of unstructured text and ::
:: key/value properties, such as "Author: Name". Lines ::
:: beginning with "::" are comments meant to be read ::
:: only by a person examining the file in a text ::
:: editor, and should not be displayed by the Sokoban ::
:: program. ::
:: ::
:: The optional but recommended property ::
:: "Collection: Name" assigns a name to the puzzle ::
:: collection. When a collection is copied from the ::
:: internet, for example, and pasted into a Sokoban ::
:: program, this information allows the collection to ::
:: be saved with the proper name. ::
:: ::
:: Titles ::
:: A title line is the last non-blank text line before ::
:: a board, a saved game, or a solution, provided the ::
:: line is preceded by a blank line or it is the only ::
:: text line at this position in the file. ::
:: ::
:: Title lines are optional unless a single or a last ::
:: text line from a preceding puzzle, saved game, ::
:: solution, or file header can be mistaken for a title ::
:: line. ::
:: ::
:: Puzzle Notes ::
:: Two special key/value pairs are supported in puzzle ::
:: notes: "Title" and "Author", hence, titles can ::
:: either come from a title line or from a key/value ::
:: pair. ::
:: ::
::::::::::::::::::::::::::: Board ::::::::::::::::::::::::::
:: Legend.................: :.................Legend ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Wall...................: # # :...................Wall ::
:: Pusher.................: p @ :.................Pusher ::
:: Pusher on goal square..: P + :..Pusher on goal square ::
:: Box....................: b $ :....................Box ::
:: Box on goal square.....: B * :.....Box on goal square ::
:: Goal square............: . . :............Goal square ::
:: Floor..................: :..................Floor ::
:: Floor..................: - _ :..................Floor ::
:: ::
:: Remarks: ::
:: ::
:: The first and the last non-empty square in each row ::
:: must be a wall or a box on a goal. An empty interior ::
:: row is written with at least one "-" or "_". ::
:: ::
:: Boards may be run-length encoded (RLE), e.g., ::
:: "###----p.#" may be encoded as "3#4-p.#", and ::
:: "#-#-#-##-#-#-#" may be encoded as "2(3(#-)#)". ::
:: A row cannot be split over multiple lines. ::
:: ::
:: Rows may be combined on a single line by using "|" ::
:: as a row separator, e.g., "--3#|3#-#|#pb.#|5#". ::
:: A "|" at the end of a line is optional and may be ::
:: omitted. ::
:: ::
::::::::::::::::::::::::::: Moves ::::::::::::::::::::::::::
:: Legend.................: :.................Legend ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: Move pusher up.........: u U :.......Push/pull box up ::
:: Move pusher down.......: d D :.....Push/pull box down ::
:: Move pusher left.......: l L :.....Push/pull box left ::
:: Move pusher right......: r R :....Push/pull box right ::
:: Begin jump.............: [ ] :...............End jump ::
:: Begin pusher change....: { } :......End pusher change ::
:: Current position.......: * * :.......Current position ::
:: ::
:: Remarks: ::
:: ::
:: Moves may be run-length encoded, e.g., "3r4U" means ::
:: "rrrUUUU", and "2(3(dr)R)" means "drdrdrRdrdrdrR". ::
:: Each line must, however, have at least one proper ::
:: non-digit character. Spaces between moves are ::
:: allowed. ::
:: ::
:: Jumps and pulls: Only in reverse mode saved games ::
:: and solutions. ::
:: ::
:: Reverse mode saved games and solutions must begin ::
:: with a jump, even if it is empty. An example: ::
:: "[]U[rr]d". ::
:: ::
:: Pusher changes: Only in puzzles with multiple ::
:: pushers, e.g., Multiban. Moves inside the braces ::
:: depict the relative movement to get from the ::
:: currently active pusher to the next active pusher. ::
:: At game start, a "{...}" sequence activates the ::
:: pusher relative to the top-left pusher. An example: ::
:: "{rddd}Urr{uul}uLU". If the top-left pusher is the ::
:: first active pusher, then the empty "{}" can be ::
:: omitted. ::
:: ::
:: The current position is optional and defaults to the ::
:: position after the last move. ::
:: ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

An example file:

----------------------------------------------------------------------
Collection: YASGen
Author: YASGen & Brian Damgaard
Copyright (c) 2003 by Brian Damgaard
These levels may be freely distributed provided they are credited with
the author's name.

Chaos

#####
###p .#
# b #.#
# bb #
#. # #
# b.#
#######

Solution/Moves
dDuurrddLLrrddLLUlluuRDRddrruuLLrruullDlldddRRuULrrruullDldRddlUruuurr
ddddLLuuRlddrruUUdlldlldRRuuulDrddlluRurrrddLLUluRRlddrruUlldlldRRRllu
uulD
----------------------------------------------------------------------

--oOo--

The boxes and events presented in this game are fictional.

Any similarity to actual boxes, living or dead, is purely coincidental.