==================
Sokoban - the code
==================

.. index:: BGE: sokoban_code
.. |a| image:: /images/all/blender-game-engine/code-100.png
   :width: 100px

Objectives
==========
   
.. tabularcolumns:: | c | l |
   :border: none

+-------+-------------------------------------------------------------------------+
|  |a|  |This part shows the code for a basic sokoban game implemented with       |
|       |Blender and Python.                                                      |
+-------+-------------------------------------------------------------------------+

Instructions
============
:Tasks:

1. If you haven't done it so far, download the :download:`blend-file <files/sokoban.blend>`
2. Read the code, improve it and try to understand it
3. Add materials and textures to the objects
4. Create own levels
5. Save highscores to a file

The blend-file
==============
Blender has a System with 20 Layers, which can switched on and off. You can do that with the keyboard or with the GUI.

- Keyboard:
	Change the layer: Press a (not numpad) number from 1 - 20

	Activate a layer: Press Shift + a (not numpad) number from 1 - 20
- GUI:
	Change the layer: Klick on an layer

	Activate a layer: Shift + klick on a layer

Note: The layer of the selected object includes a yellow point. Active layers are darker than unactivated. If you want to change the layer of the selected object, click M + the layers number.

If you start the game, only the 1st layer is allowed to be active. The 2nd layer with your objects must be inactive or you'll get an error.

The 1st layer
-------------
On the first layer are laying only 5 Objects:

- Two cameras, one for the game view and one for displaying different screens
- Two emptys, one for adding game objects and one for adding screens
- One lamp

The 2nd layer
-------------
All the other objects, which are needed for the game, are laying on the 2nd layer and the programm will add them to the game:

- player
- static/moveable box
- about, help and info screen
- end point
- ground

The Script
==========
The Script is called every frame (that makes an always sensor which calls the script), so we can't store global variables in our script. So we need an object which exists all the time to store our variables there. I used the »add_empty« to do this and applied the always sensor to it, too. So we can save variables like this:

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 384

»a« is our »add_empty« and we store our state, which says if the player is in the intro or playing a level. Now we are on the second point: We execute always the same script, but we want to do different actions - displaying the intro and playing levels. So we must save what we did last and where we want to continue. So we need states, in our case in named them »intro« and »play«. Each state has an own loop method, which is called when it's active. If the state changes, another method is called and adds the object for the state. This all happens in the method main():

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 378 - 413

The Splash Screen (intro state)
-------------------------------
Before starting the game, the player will see a splash screen. There he can call help and about.
First, we have to set the camera active:

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 358 - 359

On keyboard input can show help, about or start the game. Here we look if »h« was pressed and if true, we hide intro and about screen and display the help screen.

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 328 - 332

Adding objects
--------------
For adding an object, you need an object in the scene which is active yet. In our case we have the empty »add_empty« for adding objects and »screen_empty« for adding screens. The new objects will be added on the empty's position with it's rotation and scale.


I'll show you here some parts of the code, you can find the whole code at the end of the page.
Before you setup a new scene, you have to clear the old one. That can be done with the following lines:

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 63 - 66

After that, we can add new objets, for example a static box:

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 98 - 101

The variable »a« is in this case an empty on the place where the object will be added.

The Game (play state)
---------------------
After adding the objects and setting up the new camera, we convert the level in an easier format without end points. We do this because the end points could be overwritten if player or box is on it.

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 147 - 149

We don't need them because we check by the positions if a box is over an end point, for example to set other colors.

.. literalinclude:: files/sokoban_main.py
   :language: python
   :lines: 297 - 314


For more details read the comments in the code.

.. literalinclude:: files/sokoban_main.py
   :language: python