Sokoban Tutorial 1

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:

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-&gt;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-&gt;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-&gt;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!

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-&gt;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-&gt;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.

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.



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.



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!

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!

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.

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.

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:



Move Messages to the Sokoban
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.

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: