Sokoban Tutorial 1

From Gamewiki

Contents 1 Overview 2 Creating A New Project 3 Creating Agents 3.1 Creating the Sokoban 3.2 Creating the Floor 3.3 Creating the Wall 4 Creating a Worksheet 4.1 Placing Walls 4.2 Placing Floors 4.3 Placing the Sokoban 5 Programming the Sokoban Up Movement 6 Moving in the Other Directions 7 Not Moving Through Walls 8 Creating the Crate 9 Programming Sokoban to push the Crates 10 Reacting to Push Messages 11 Programming Crates 12 Programming Sokoban to React to Messages from Crate 13 Finishing Up 14 External links

Overview

The purpose of this tutorial is to build a Sokoban-style game. By the end of this tutorial you will have created a playable game that resembles the following picture. Throughout this tutorial, if you are confused as to how your game should look, you can use the above picture for guidance.

The game you will create in this tutorial is modeled after the classic transport puzzle game ‘Sokoban.’ Hiroyuki Imabayashi originally created the game in 1980 and a description of the game follows:

You are a warehouse keeper (Sokoban) who is in a maze viewed from above. You must push boxes around the maze while trying to put them in the designated locations. Only one box may be pushed at a time, and boxes cannot be pulled. When boxes are covering all of the destinations the level is complete.

The Sokoban (Soko for short) starts at a specified location in the game level. The person playing the game can move Soko in four directions: up, down, left, and right. The object of the game is to cover all of the destination areas with crates. Soko can only push the crates, which can make solving the levels quite challenging. When all of the destinations are covered, the level has been won.

Follow the instructions below exactly, being very careful not to miss any steps. In building this game you will quickly learn many programming and logic concepts and will eventually be able to create your own original games using your imagination!

Creating A New Project

Double click the AgentSheets icon to start the program.

Select File->New Project... to start a new AgentSheets project. This will bring up a file dialog to define what the name of the new project is and where to save it.

Name the project "Sokoban" in the file dialog that comes up (if the name "Sokoban" is taken, add your initials behind it like "Sokoban_JSL") and click OK. A "Define Agent Size" dialog box should appear.
Choose the size of your agents. For the game we are creating, you don't need to change anything - the default size of 32x32 pixels will work, so just click OK again.
A window should appear in the top left; this is the Gallery Window.

Creating Agents

We will now create the Sokoban, Wall, and Floor agents.

Creating the Sokoban

Click the "New Agent" button to create the Sokoban agent: At the bottom of the Gallery window click the "New Agent" button. Name the agent “Sokoban.” The Sokoban agent should appear in the gallery and we will now draw the Sokoban.

Click the "Edit Depiction" button to draw the Sokoban: Select the Sokoban agent in the Gallery and click the "Edit Depiction" button at the bottom of the window. The Depiction Editor should now open. In the Depiction Editor we will draw what our Sokoban will look like.

Press the "Clear" button to clear default depiction: Click the "Clear" button at the bottom of the window or use the Edit->Clear menu option in the Depiction Editor window. This will clear the default drawing in the window to give you a blank canvas to draw your Sokoban.

Select a color and the "Pencil" tool to draw your Sokoban. Select any color from the color palette at the top and the Pencil tool on the left and draw what you would like your Sokoban character to look like (in this case we made a robot). If you make a mistake you can use the Undo button, the Eraser tool on the left, or the clear button at the bottom to completely clear the drawing. You can also use the shape tools on the left to make circles or rectangles.

Click the "Done" button at the bottom of the window when you are finished. We have now created the Sokoban agent and drew what it looks like. If you are still not satisfied with how your Sokoban looks, you can click on the "Edit Depiction" button again in the Gallery Window and modify the picture. Now, it's time to make more agents!

Creating the Floor

Now let’s make the Floor agent. Similar to how you created the Sokoban agent,

Click the "New Agent" button to create the Floor agent. Name the Agent “Floor.”

Open the Depiction Editor Window to draw your Floor in the same way you drew the Sokoban. Your floor does not have to look exactly like the one shown; have fun and experiment!

We Now have Two Agents: The Sokoban and the Floor! We need to make one more agent before we can move on to designing our game level.

Creating the Wall

Now let’s make the Wall agent. We are going to make a solid wall piece to make things easier. Similar to how you created the Sokoban and Floor agents,

Click the "New Agent" button to create the Wall agent. Name the Agent “Wall.”

Open the Depiction Editor Window to draw your Wall in the same way you drew the Sokoban. Your wall does not have to look exactly like the one shown; have fun and experiment!

We Now have three Agents: The Sokoban, Floor, and Wall! Great Job! Our next task is to make the game level. This is called a “Worksheet.”

Creating a Worksheet

The Worksheet is our game level or stage where we place our agents.

Select File->New Worksheet to create a new worksheet: This will create a new, empty worksheet. Resize the Worksheet Window to the size you want your level to be (by clicking and dragging the bottom right of the window). The empty worksheet is where we will create the level for our game. Our level will include the Sokoban, the Floor, the Wall, and (eventually) Crates. Let’s first create some Walls. The Walls will surround our game level and define the level's structure; this is similar to how a picture frame goes around a picture. We will do this by placing the Wall agents on the worksheet.

Placing Walls

Use Pencil tool to place Walls in the Worksheet: Select the Wall agent in the Gallery window by clicking on it. In the Worksheet window, use the Pencil tool to place Walls in an arrangement similar to the picture at the top of the tutorial. If you want the Walls to cover a region, click on the filled “Draw Rectangle” tool (the rectangle which has textured middle) and make a Rectangle that covers a section of the screen you want the Walls to appear. This should create multiple “walls” across the screen. If you make a mistake you can use the Clear button located in the bottom right to clear everything or the Eraser tool on the left to clear specific agents.

Placing Floors

Fill in the area between the walls with Floor agents: Select the Floor agent in the Gallery window by clicking on it. In the Worksheet window, use the Pencil tool to place the floor in area surrounded by walls. If you want the Floor to cover a region, click on the filled “Draw Rectangle” tool (the rectangle which has textured middle) and make a Rectangle that covers a section of the screen you want the Floor to appear. This should create multiple “floor” tiles across the screen. If you make a mistake you can use the Clear button located in the bottom right to clear everything or the Eraser tool on the left to clear specific agents.

Placing the Sokoban

Place your Sokoban agent in the Worksheet: In a similar fashion, place one Sokoban in the Worksheet window. You only want to place a single Sokoban, since it will be cursor controlled. Make sure the agents are in the default starting position (e.g. the Sokoban is where you want it in the level). It is important that you do not draw over the Sokoban with the Wall or Floor agents. This means if you place a Sokoban on the worksheet, do not draw the another agent over it without erasing the Sokoban first.

This is a good time to save the worksheet!

IMPORTANT: Saving the Worksheet

While the Worksheet Window is selected, go to File->Save; DO NOT CHANGE THE DIRECTORY UNDER ANY CIRCUMSTANCES! IF YOU DO THIS THE PROGRAM WILL NOT WORK. Name the worksheet "Level 1" and press Save. You can test if saving worked, by pressing the "Reset" button in the worksheet window: if the screen doesn't clear (meaning no agents disappeared), you have successfully saved the worksheet window. If the screen did clear, place the agents in the positions they originally were and try to save again following the directions above. If the screen still clears, Ask for Help.

Play Test: Running the Program

GOOD JOB! You have now created and saved the first version of the level. Now let's test our program by running it and trying to play the game to see if it works the way we think it should. In the worksheet window, press the 'Run' button located at the bottom left. What happens? Does the Sokoban do anything or does it just stay in one place? Can you control the Sokoban movements? For example, if you press the up arrow, does the Sokoban agent move up? No, the Sokoban does not move. To give our Sokoban the ability to move, we have to give a "behavior" to our Sokoban agent. As you will see, behaviors allow us to make our agents act in specific ways.

Programming the Sokoban Up Movement

We now need to figure out what our agents do while the game is running. The Sokoban must move in the correct direction when the Up, Down, Left, and Right keys are pressed on the keyboard. Let’s add the ability to move Up.

Use the "Edit Behavior" button to open the Sokoban behavior editor: In the Gallery window select the Sokoban agent and click the "Edit Behavior" button located at the bottom of the Gallery window; This will bring up the Behavior Editor for the Sokoban, which at this point will contain no behaviors.

The kind of behaviors that we will give to our Agents are called rules. Rules are made up of an IF-THEN statement. For controlling the Sokoban using the cursor keys, one of the rules we need should be that “IF the Up key is pressed, THEN the Sokoban will move up.” Overall we should have 4 rules, one for each direction (Up, Down, Left, Right).

Double click the “If” box to get the Conditions Palette. Alternatively, go to Tools->Conditions Palette. This will open the Conditions window that contains all the available conditions (blue language pieces).

Double click on the “Then” box to get the Actions Palette. Alternatively, go to Tools->Actions Palette. This will open the Actions window that contains all the available actions (red language pieces).

Add the "Key" condition to the Sokoban's behavior: Click on the “Key” label of the Key condition in the Conditions Palette and drag it into the “If” part of the rule in the Behavior Editor. Click on the letter within the Key condition (the default is 'A') and when it says “Press Any Key”, press the "Up" arrow on the keyboard.

Add the "Move" action to the Sokoban's behavior: Drag the “Move” action from the Actions Palette to the “Then” part of the rule in the Behavior Editor.

Click the arrow in the “Move” command box and change the direction to "Up". When you’re all done, the Behavior Editor for the Sokoban should look like the following:

Click the “Apply” Button located at the bottom right of the Behavior Editor to make these changes take effect for the Sokoban agent.

Play Test: Testing The Sokoban Up Movement

Now let's test our program by running it. In the worksheet window, hit the 'Run' button located at the bottom left and hit the up arrow. What happens? The Sokoban should now move up. If your Sokoban does not move up, go back through the instructions and try to figure out where you might have gone wrong. If the Sokoban does move up, are we done with the Sokoban movement? What other Sokoban movement behaviors are necessary? When you are done testing, you can press the Reset button located in the bottom right of the Worksheet Window to restore your level (ie: put the Sokoban back at the default starting position).

Moving in the Other Directions

Notice we’ve only programmed the up movement — we now need to program the other three directions. To do that, we have to add three more rules for the “Down”, “Left”, and “Right” directions. Since these behaviors are similar to the "Up" behavior, you can use the "Duplicate" button located at the bottom of the behavior window.

Duplicate the UP movement behavior for all other directions: In the Sokoban’s behavior editor select the “Up” rule (by clicking in the middle) and hit the Duplicate button 3 times. Now modify these new rules for “Down”, “Left”, and “Right.” (IF the DOWN button is pressed THEN the Sokoban moves DOWN etc.). When you’re done, the Sokoban’s behavior editor should look like the following.

Play Test: Testing The Four Directions of Sokoban Movement

Take a few seconds to run your program once again and make sure you can move your Sokoban in all directions - Up, Down, Left, and Right. If you cannot move in all four directions, review the Sokoban agent's behaviors for possible mistakes and retest. If it does work, AWESOME JOB! Does the Sokoban go through walls? Should it be able to do this?

Not Moving Through Walls

Currently our Sokoban can go through walls without any problem. We now need to prevent the Sokoban from passing through walls by allowing the Sokoban to only move on floor Agents. To do this, we will use the See condition to modify the four movement rules for the "Up", “Down”, “Left”, and “Right” directions. The See condition has two properties; first you will select a direction to look and second you will select what to look for (Important Note: a dot for the See direction indicates that you want to See or look at yourself!).

Add the "See" condition to the Sokoban's movement behaviors: Click on the “See” label of the See condition in the Conditions Palette and drag it into the “If” part of the "Up" rule in the Behavior Editor. Click the dot in the “See” command box and change the direction to "Up". Next, change the See depiction to the Floor agent that we created earlier. Click the currently visible depiction and from the list of Agents select the Floor agent that you previously made. Now, add See conditions to the other three movement rules: "Right", "Left", and "Down" with the proper direction to look. When you’re done the Sokoban’s behavior editor should look like the following.

Play Test: Testing movement through walls

Take a few seconds to run your program once again and make that your Sokoban cannot move through walls in any direction. If you can't move in all directions over Floor agents or you can still pass through walls, review the Sokoban agent's behaviors for possible mistakes and retest. If everything works, GREAT JOB!

Creating the Crate

We now have a Sokoban that can move "Up", "Down", "Left", and "Right" over Floor agents. By creating the Sokoban we have now gained the basic skills necessary for creating an agent and adding basic behaviors. We will now create a Crate agent that can be pushed by the Sokoban.

Create and draw the Crate Agent: Create a new agent called "Crate", the same way you created the Sokoban and the Walls. As you did when you created the Sokoban, draw the picture you’d like to use to represent the Crate.

Place a Crate Agent in the worksheet: Now use the pencil tool to add at least one crate to the worksheet over a Floor Agent (the Crate will be stacked above the floor).

Save the worksheet: Now is a great time to save the worksheet again!

Play Test: How does your Sokoban interact with the new Crate agent?

Now let's test our program to see how the Sokoban interacts with the Crate agent. Press the "Run" button to begin testing. Can the Sokoban push the crate? What happens when the Sokoban attempts to push the crate?

We will now make our Sokoban push crates!

Programming Sokoban to push the Crates

We're close to being done, but we're missing one extremely important behavior: the behavior allows the Sokoban to push crates in the level!

Computational Thinking Pattern: Push

Push: When the Sokoban tries to "push" a Crate, the Crate will look ahead in the same direction as the "push". If the space ahead of the box is clear (no Walls) the Crate will signal the Sokoban to move one space in the "push" direction and the Crate will also move one space in the same direction. You can look at the complete Push Description for more information.

Add Crate-Push in the Sokoban's behavior: To have the Sokoban push crates, we have to learn about a new behavior action: "Make". The Make action allows sending messages between agents, even back to yourself!

Duplicate the Sokoban movement behaviors: Once again we want to start by duplicating the current Sokoban movement behavior. Open the Sokoban behavior edit window as done before. In the Sokoban’s behavior editor select the bottom movement rule (by clicking in the middle) and press the Duplicate button 4 times. Now modify these new rules so that they match the original movement rules (Hint: you will have to modify the movement direction and the See direction for three of the rules).

Modify See conditions of new movement rules: Next we need to modify what the See condition is looking for. For the four new movement rules (bottom four), click the depiction that the See condition is currently looking for and from the list of Agents displayed select the Crate agent that you previously made. When you’re done the Sokoban’s behavior editor should have the original four movement rules for moving over Floor agents and now four rules for moving over crates. However, we don't want the Sokoban to move over the crates, we want it to push them!

Delete the Move Action of the new rules: Now we need to modify the new rules so that the Sokoban does not move over the crates. For the four new rules, delete the Move action in the Then portion of the rules (click on the Move label and drag it to the trash can in the behavior editor or click on the Move action and press the Delete key on the keyboard).

Add the Make Action to the new "UP" rule: Now that we have deleted the Move actions from our new crate rules, we need to actually have the Sokoban perform some action when it sees a crate in the direction of movement. We will now use the Make action to send a message to the crate we are attempting to push. In the Actions dialog box, click the Make label and drag the action to the new "UP" rule. Change the direction of the Make action to point "UP". Now we need to decide what message to send to the crate. Type "push_up" into the text box for the Make action.

Add the Make Action to the other three new rules for "DOWN", "LEFT", and "RIGHT": There is an easy way to copy the new Make action to the other three rules. In the "UP" rule modified in the previous step, click on the Make action label and drag the rule to the Then portion of one of the other rules. This will copy the action in the other rule's Then area. Modify the Make action so that the direction is pointing in the same direction as the Key and See condition direction. Additionally, the message to send to the crate must also be different. For "DOWN" send "push_down", for "LEFT" send "push_left", and for "RIGHT" send "push_right".

This is a good time to apply your rules to the Sokoban agent. Press the Apply button in the behavior editor window.

When finished, your new rules should look like this:

Explanation: We have now added behavior rules to the Sokoban so that when it attempts to move into the position that a crate occupies, the Sokoban will send a message in the same direction of movement to the crate. This is the first step towards allowing the Sokoban to push the crate successfully.

Play Test: Testing The Sokoban Pushing Crates

Push "RUN" in the worksheet editor to start your game again after receiving an error from the crate. Try to push a crate in every direction. What happens? You should see four different errors from the crate in the message area when you attempt to push the crate in each direction. If you do not see each of these four messages, then review the Sokoban behaviors for possible mistakes and retest. Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_down' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_up' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_right' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_left' If you receive a error message in the message area that the Crate does not know how to respond to each of the four messages, SUPER JOB!

Reacting to Push Messages

We're closer to being done, but we're missing another extremely important behavior: the behavior that allows the crates to react to messages received from the Sokoban!

Add On Method to the Crate's behavior: To have the Crate react to push messagse, we have to learn about creating new methods for our agent behavior. Methods are containers where all of the rules go to perform actions. We have been using the While method so far in our program, but now we will add and use the On Method. The On Method tells the agent what to do when specific messages are received. You can tell the type of Method you are looking at by looking at the tab in the upper left corner of Method area.

Add a new Method to our Crate behavior: Open the crate behavior as we have done previously for the Sokoban Agent. In the behavior editor click the New Method button. This will create a new On Method for you to use in your program. When the new Method is created AgentSheets will automatically put default text in the message received box. We want this name to match the name we used for the message we made in the previous step indicating we wanted to push "UP". Delete the text for the On method and type "push_up" into the text box. The picture below is what your new method should look like:

Add new On Methods to our Crate behavior for "DOWN", "RIGHT", and "LEFT" messages: Now we need to create three more new methods to react to the other messages that the crate could receive: "push_down", "push_left", and "push_right". As you previously did, create new On methods and associate each with one of the three remaining messages that the crate could receive.

This is a good time to apply your rules to the Sokoban agent. Press the Apply button in the behavior editor window.

Explanation: We have now added On methods to the Crate so that it can react to the messages received by the Sokoban.

Play Test: Testing Crate Receiving Messages

Push "RUN" in the worksheet editor to start your game again after receiving an error from the crate. If you receive any of the error messages below when trying to push the crate, look at your Crate rules and retest. Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_down' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_up' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_right' Sorry, I am just a 'crate'. I do not know how to react to the message: 'push_left' If you attempting to push the crate no longer causes any error messages, SUPER JOB!

Programming Crates

We're still missing one extremely important behavior: the behavior that actually moves the crates when they are pushed!

Add Movement in the Crate's On Methods: To have the crate actually move, we need to modify the On methods in the Crate behavior that we made in the last step. Make sure the Crate behavior editing window is open and locate the "push_down" On method. First add a Move action to the Then portion of the rule. We want the Crate to move in the same direction as it is being pushed, so the Move direction should be "DOWN". Similarly, add movement actions to the other three On methods for the crate behavior.

Stopping crates from going through walls: With the current rules, the crate will go through a wall if we attempt to push it through one. This is not what we want to have happen in this game. It is easy to change the crate push behavior. Let us start with the "push_down" method. Place a "See" condition into the If portion of the rule we already created. Change the direction to "Down" and change the depiction to the Floor tile we made earlier. Now modify the other three On Methods that we made earlier to also have See conditions looking in the correct directions. Your "push_down" On method should look similar to the picture below:

Play Test: Test whether your Crate moves correctly when pushed.

Try to pushing the crate over the Floor and through Walls. If your crate cannot be pushed over tiles or it can be pushed through walls, examine your crate behaviors again, making sure the See conditions are looking in the correct directions and have the right depictions. Retest. If your crate cannot be pushed through Walls and moves over the Floor tiles, excellent work!

Sending a message back to the Sokoban to also move: When we push the crate, the crate moves one space, but the Sokoban stays where it was when it attempted to push the Crate. We want the Sokoban to also move one space in the same direction as the Crate was pushed. To do this we will have the Crate send a message back to the Sokoban telling it to move in the same direction. To do this we will once again use the Make action. Place Make actions in the four On Methods for the Crate. These new make actions must come before the Move actions (Do you know why?). The Make actions must be sent in the opposite direction as the Crate is being pushed; this is because the Sokoban is always behind the crate. The messages we want to pass back to the Sokoban are "move_up", "move_down", "move_left", and "move_right". Once again, here is a picture of the On "push_down" method for reference:

The Sokoban does not know how to react to the messages that it is receiving back from the crate, therefore you will see an error message from AgentSheets if we Run our game now!

Programming Sokoban to React to Messages from Crate

We are finally at the last step before being finished! Congratulations on making it this far.

Add Four On methods to Sokoban's Behavior: We need to add four new On methods to the Sokoban behavior, similar to how we added On Methods to the Crate behavior. Open the Sokoban behavior as we have done before. Now, click the "New Method" button four times to create four new On Methods. The messages that the On Methods should respond to are: "move_down", "move_up", "move_left", and "move_right". Place each of the messages into a different On Method.

Making the Sokoban move after pushing the crate: At this point your Sokoban is still not moving after it pushes a crate. Fixing this is really simple. If the Sokoban receives a "move_down" message, the Sokoban should move down. Add a Move action to the On "move_down" Method and have the direction for movement go "DOWN". Here is a picture of the updated Sokoban On "move_down" method:

Update the other three On methods similarly to when the "move_down" message is received.

Play Test: Test whether your Sokoban now moves when you push the crate.

Try to push the crate in all directions. If your Sokoban does not move when the crate is pushed examine your Sokoban On method behaviors and retest if you make any changes. If your Sokoban moves when the crate is pushed, excellent work!

Finishing Up

Now Let's Go back to the Worksheet -- Let's do one final play test to see if we programmed everything correctly. Here is a picture of what your level might look like:

Play Test: Game Checklist

Press Run and see if everything works correctly. Check Does the Sokoban move in all directions over the Floor? Can the Sokoban push crates in all directions? Does the Sokoban also move in the same direction as the crate was pushed? Do the Walls block the Crates and Sokoban correctly? If your answer to one of these is no, go back to the related section and see what you might have done wrong. Otherwise, if everything works correctly GREAT JOB! You have created part 1 of your own Sokoban game! You can now go back and make any changes you want to make (like redrawing an agent, adding other behaviors etc.), or you can go on to part 2 which involves adding destination Agents, counting the number of crates not over destinations, and determining when a level is complete!

External links

• Wikipedia Sokoban Article