<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kappname "&ksokoban;">
 <!ENTITY % English "INCLUDE">
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
 %ents;
]>

<book lang="&language;">
<bookinfo>
<title>The &ksokoban; Handbook</title>

<authorgroup>
<author>
<firstname>Anders</firstname>
<surname>Widell</surname>
<affiliation>
<address><email>awl@hem.passagen.se</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2000</year>
<holder>Anders Widell</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>16/12/2000</date>
<releaseinfo>1.00.00</releaseinfo>

<abstract>
<para>
&ksokoban; is a KDE implementation of the Japanese warehouse keeper game
&quot;sokoban&quot;. This document describes &ksokoban; version 0.4.0.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdegames</keyword>
<keyword>game</keyword>
<keyword>sokoban</keyword>
<keyword>ksokoban</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
The first sokoban game was created in 1982 by Hiroyuki Imabayashi
at the Japanese company Thinking Rabbit, Inc.
&quot;Sokoban&quot; is japanese for &quot;warehouse keeper&quot;.
The idea is that you are a warehouse keeper trying to push crates to their
proper locations in a warehouse.
</para>

<para>
The problem is that you cannot pull the crates or step over them. If
you are not careful, some of the crates can get stuck in wrong places
and/or block your way.
</para>

<para>
It can be rather difficult just to solve a level. But if you want to make
it even harder, you can try to minimise the number of moves and/or pushes
you use to solve the level.
</para>

<para>
To make the game more fun for small kids (below 10 years or so), some
collections with easier levels are also included in &ksokoban;. These
are marked <emphasis remap="bf">(easy)</emphasis> in the level collection menu.
Of course, these levels can be fun for adults too, for example if you don't
want to expose yourself to too much mental strain.
</para>
</chapter>

<chapter id="how-to-play">
<title>The Game</title>

<para>
The objective of the game is to push all the red gems to the goal
squares, which are marked with green glassy round things on the floor.
</para>

<para>
Use the cursor keys or the mouse to move about. If you move onto a gem
using the cursor keys or the middle mouse button, and there is noting
blocking it on the opposite side, then you will push the gem.  It
isn't possible to pull the gems, so if you push a gem into a corner it
will be stuck there. You can't step over the gems either, so you can
also get trapped in a part of the maze by blocking the way with gems.
Also note that it isn't possible to push more than one gem at a time.
</para>

<para>
If you notice that you have moved the gems in such a way that the
level is impossible to solve, then you can always use the undo feature
to go back to a position where the mistake has not yet been made. You
can of course also restart the level from the very beginning.
</para>

<sect1 id="controls">
<title>Controls</title>

<para>
<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Key</entry><entry>Action</entry></row>
</thead>

<tbody>
<row><entry>Cursor keys </entry><entry>Move one square in a direction </entry></row>
<row><entry><emphasis remap="bf">CONTROL</emphasis> + Cursor keys </entry><entry>Move as far as possible in a direction without pushing any gems </entry></row>
<row><entry><emphasis remap="bf">SHIFT</emphasis> + Cursor keys </entry><entry>Move as far as possible in a direction, pushing any gem in the way </entry></row>
<row><entry>Left mouse button </entry><entry>Move to any place in the maze that can be reached without pushing any gems </entry></row>
<row><entry>Middle mouse button </entry><entry>Move up/down/left/right in a straight line, pushing any gem in the way </entry></row>
<row><entry>Right mouse button or <emphasis remap="bf">U</emphasis> </entry><entry>Undo the last move </entry></row>
<row><entry><emphasis remap="bf">R</emphasis> </entry><entry>Redo the last undone move </entry></row>
<row><entry><emphasis remap="bf">N</emphasis> </entry><entry>Go to the next level in the current level collection </entry></row>
<row><entry><emphasis remap="bf">P</emphasis> </entry><entry>Go to the previous level in the current level collection </entry></row>
<row><entry><emphasis remap="bf">Escape</emphasis> </entry><entry>Restart the current level </entry></row>
<row><entry><emphasis remap="bf">Q</emphasis> </entry><entry>Quit the game </entry></row>
</tbody>
</tgroup>
</informaltable>
</para>
</sect1>

<sect1 id="loading-external-levels">
<title>Loading external levels</title>

<para>
&ksokoban; has the ability to load external sokoban levels from text files.
You can load levels using the menu
<menuchoice>
<guimenu>Game</guimenu>
<guimenuitem>Load levels...</guimenuitem>
</menuchoice>,
or by specifying the level file URL as a command line argument
when starting &ksokoban; from a shell.
</para>

<para>
The external levels must be defined using the standard characters
shown in the table below. If the file contains more than one level, the
levels should be separated by blank lines. The file may also contain text
between the levels.
</para>

<para>
<informaltable>
<tgroup cols="2">
<thead>
<row><entry>Character</entry><entry>Meaning</entry></row>
</thead>

<tbody>
<row><entry>#</entry><entry>Wall</entry></row>
<row><entry><emphasis remap="bf">(space)</emphasis></entry><entry>Empty square</entry></row>
<row><entry>.</entry><entry>Goal square</entry></row>
<row><entry>$</entry><entry>Object on an empty square</entry></row>
<row><entry>*</entry><entry>Object on a goal square</entry></row>
<row><entry>@</entry><entry>Start position on an empty square</entry></row>
<row><entry>+</entry><entry>Start position on a goal square</entry></row>
</tbody>
</tgroup>
</informaltable>
</para>

<para>
As an example, below is a text representation of the first level in the
<emphasis remap="bf">Microban</emphasis> level collection:
</para>

<para>
<screen>
####
# .#
#  ###
#*@  #
#  $ #
#  ###
####
</screen>
</para>
</sect1>
</chapter>

<chapter id="credits">
<title>Credits and License</title>

<para>
&ksokoban; is copyright &copy; 1998-2000 by Anders Widell
&lt;<ulink url="mailto:awl@hem.passagen.se">awl@hem.passagen.se</ulink>&gt;.
For the latest info on &ksokoban;, see the &ksokoban; home page at
<ulink url="http://hem.passagen.se/awl/ksokoban/">
http://hem.passagen.se/awl/ksokoban/</ulink>
</para>

<para>
The background graphics &quot;starfield&quot; was taken from the
<ulink url="http://www.gimp.org/">Gimp</ulink>. All other graphics were
created by Anders Widell
&lt;<ulink url="mailto:awl@hem.passagen.se">awl@hem.passagen.se</ulink>&gt;
using the <ulink url="http://www.povray.org/">Povray</ulink> ray tracer.
</para>

<para>
All the currently included sokoban levels were created by David W. Skinner
&lt;<ulink url="mailto:sasquatch@bentonrea.com">
sasquatch@bentonrea.com</ulink>&gt;. See his sokoban page at
<ulink url="http://bentonrea.com/~sasquatch/sokoban/">
http://bentonrea.com/~sasquatch/sokoban/</ulink>
</para>
&underFDL;
&underGPL;
</chapter>

<![ %addindex; [ &kdedocindex; ]]>
</book>
