Sokoban Tutorial 2

From Scalable Game Design wiki
Jump to navigation Jump to search
Sokoban style game described in the tutorial


NOTE: If you no longer have the files you made during the first part of the Sokoban tutorial, you can download these files to use:

Download Sokoban Part One Files

Our overall aim is to create the Sokoban game depicted to the right. In this part of the tutorial we will add a step counter and the logic to detect finishing a game level, but first reviewing what we already accomplished will be helpful. For the first part of the Tutorial we started creating Sokoban and we Created the following Agents and Behaviors:


  • Moves Up, Down, Left, and Right in response to keyboard input.
  • Can push Crates over Floor tiles if not blocked by a Wall.
  • Responds to movement messages from the crate


  • No Behaviors


  • No Behaviors


  • Can be pushed over Floor tiles by responding to messages from the Sokoban
Play Test: Playing the game

If it's been awhile since you played the game you created in the first tutorial, run the Program and play the game to get a feel for how you left it. Once you are satisfied that everything is running normally, it is time to add more agents to continue making the game!

What Do We Need To Add?

Compare the above picture to our current game; what do we need to add to our game?

The Above Picture has the following agents

  • Destination (where the crates need to be pushed)
  • Letters (labels for the step count)
  • Numbers (will display the number of steps the Sokoban has taken)
  • Game Master (will count the number of crates not over Destination Agents)

Let's summarize how we will incorporate these new agents into the level


  • Have no behaviors
  • The Crate and Sokoban can move over Destinations
  • If Crates cover all level Destinations the level is complete


  • Have no behaviors
  • Indicate where the step count is located


  • Increments by one every time the Sokoban takes a step
  • Creates new number if needed
  • Indicates to next Number when it needs to increment

Game Master

  • Manages the incrementing of the step count
  • Asks Crates to update their status
  • If all Destinations are covered, indicates that the level has been finished

Creating the Destination Agent

We will now create a Destination agent that can have other agents pushed onto it.

Destination agent

Create and draw the Destination Agent: Create a new agent called Destination, 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 destination.

Program Destination: Now we would normally add some behavior to our new agent, but in this case there is nothing we need to program! This means that the destination will not actually perform any actions in our program.

Currently our Sokoban cannot move over destinations, so let's fix that behavior now!

Moving over Destination agents

Currently our Sokoban can walk over floors without a problem, but cannot travel over destinations. We now need to allow the Sokoban to move over destinations as well. To do this, we will duplicate the already existing Sokoban movement behaviors and edit them to give use the new behavior. For reference, here is a picture explaining the See condition again:

See Condition Diagram

Duplicate the Sokoban movement behaviors: Open the Sokoban behavior edit window again as done before. In the Sokoban’s behavior editor select the bottom movement rule (by clicking in the Then area) and click the Duplicate button 4 times. Now modify these new rules so that they match the original movement rules (you will have to modify the Move direction and the See direction for three of the rules - why?).

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 Destination. When you’re done the Sokoban’s behavior editor should have the original four movement rules for moving over Floor agents and now four movement rules for moving over destinations too!

Complete Sokoban's movement behavior for all four directions while moving over destination tiles

Moving the crate over the Destination: We can push the crate over the Floor tiles, however it will not currently move onto Destination agents and we will never be able to finish our game! It is actually very easy to fix this behavior. Open the Crate behavior editor and find the On method for "push_down", click on the If or Then labels of our rule (this should highlight the entire rule). Now click the "duplicate" button, which will make an exact copy of the highlighted rule. Now in our new duplicate rule, we just need to change the See action depiction to the Destination agent. Here is a picture of the modified "push_down" method:

On Method for push_down message being received. Crate checks to see if a Tile agent is below or a Destination agent is below. If there is a Floor agent or Destination agent below the crate it sends a message back to the Sokoban telling it to move down and then the crate moves down as well.

Remember to update the On methods for the other three messages that a Crate could receive using the same instructions as above.

Play Test: Can the Sokoban and Crate move on and off Destinations?
  • Try to move the Sokoban onto and off of the Destination in every direction
  • Try to push a crate on and off the Destination in every direction
  • Do the Sokoban and Crate move on and off the Destination correctly? If not, check the Crate and Sokoban rules and retest.
  • If the movement over the Destination is fine for the Sokoban and Crate, good work!

Creating the Letter Agent

Letter Agent Depictions
Letter S Depiction
Letter T Depiction
Letter E Depiction
Letter P Depiction

Create the Letter Agent: The Letter agents will not have any behavior, but will act as a label indicating where the player can locate the Sokoban step count. Create a new agent and name it Letter.

Add Depictions to Letter Agent: We need four depictions for our Letter agent: "S", "T", "E", and "P". Please note that each letter is not a new agent; it is just a different version of our Letter agent. In the Gallery Window select the Letter agent. At the bottom of the Gallery Window click the "New Depiction" button and name it "Letter_S." Then, select the new depiction, and edit it to represent the letter "S". Now, repeat this process for the remaining three letters.

Tip: We actually do not need to modify the original Letter depiction since we will not use it in our game, however it can be helpful to modify it. If you edit the original Letter depiction and make the "Mask Color" color "White", then all new depictions will also have a "White" masking color! To do this, open the Depiction Editor and go to "Color -> Mask Color" and select "White" (it is possible to use other colors as the Mask Color as well).

Choosing a Mask Color

Explanation - What is a Mask Color?: The Mask Color will make that color transparent for the Agent Depiction and whatever Agents are below that Mask Color will be visible.

Tip: Making depictions that have meaningful names is a good programming practice! When we use the "Letter_S" depiction of the Letter agent we know what it should look like, however if we just use "Letter" we would not know which letter it is referring to.

Place the Letter agents on the Worksheet: Make the word "STEPS" with your Letter agents. You can use the picture at the top as a guide. Save the Worksheet when you are happy with the arrangement of the letters.

Good Job! Now let's make the Number agent.

Creating the Number Agent

Number Agent Depictions
Number 0 Depiction
Number 1 Depiction
Number 2 Depiction
Number 3 Depiction
Number 4 Depiction
Number 5 Depiction
Number 6 Depiction
Number 7 Depiction
Number 8 Depiction
Number 9 Depiction

Create the Number Agent: The Number agents will actually change their depictions as the Sokoban moves through the game level. First, let us create a new agent and name it Number.

Add Depictions to Number Agent: We need ten depictions for our Number agent: "0", "1", "2", "3", "4", "5", "6", "7", "8", and "9". Please note that each number is not a new agent; it is just a different version of our Number agent. In the Gallery Window select the Number agent. At the bottom of the Gallery Window click the "New Depiction" button and name it "Zero." Then, select the new depiction, and edit it to represent the letter "0". Now, repeat this process for the remaining nine numbers. Remember the tips from the Letter agent!

Place the Number agent on the Worksheet: Add one "Zero" Digit agent to the worksheet about five places to the right of the "STEPS" agents you made previously. You can use the picture at the top as a guide. Save the Worksheet when you are happy with the arrangement of the letters.

Good Job! Now it is time to program the behavior of the Number agent!

The Number Agent Behavior

Our goal is to have our numbers show how many steps our Sokoban has made while solving the game level. This feature will also require the use of our Game Master agent that we will make soon, but we can still define what the Numbers will do.

We are creating a counter, which can be a somewhat tedious process, but it can be useful and fun. For instance, you do not have to count in decimal (0, 1, 2, 3, etc), but could count in binary (0000, 0001, 0010, etc) or in some alien language that you make up!

Add "increment" Method to the Numbers behavior: As we have done previously, open the behavior editor for the Numbers agent. We now need to program how the Numbers will increment as the Sokoban moves in the level.

Once the Numbers behavior editor is open, we need to add a new Method as we have done before. In case you have forgotten how to add a new Method to our behaviors, click on the "New Method" button and it will be created. Replace the default Method name with "increment".

Add Rules to Numbers Agent "increment" Method: We now need to add rules to the Method we just created. We will actually have eleven rules, even though there are only ten numbers! Let's start with the first rule; if we see a "Zero" depiction, we need to change it to a "One" depiction. Make your rule look like the first rule in the following picture.

First three rules of increment Method for Number Agent

Use the other two rules from the picture as guides for how to make rules for the numbers 1 - 8. What should happen if the current number is a "Nine" and we need to increment? We will need two special rules for this case. Use the picture below for the two "Nine" rules.

"Nine" depiction rules of increment Method for Number Agent

**Warning: If your counter is not on empty space (i.e. on the floor, wall, etc.) you want to make sure that the last "if" is not "empty to the left" but rather "sees floor to the left" or whatever you have the counter on....

Explanation: If our Number is a "Nine", then we want it to change to a "Zero", however we also want our step count to increase correctly. There are two cases that can happen. First, there is not a number to the left of the "Nine", so we have to create a new Numbers Agent and set its Depiction to "One". The other case is that there is a Numbers Agent to the left of the "Nine", so we want to send a message to the Numbers Agent on the left telling it to change its depiction too!

We used the "See A" Action for one of the rules. The difference between the "See" and "See A" Actions is that "See A" looks for any Agent regardless of the Depiction, while the "See" Action looks for a specific Depiction of an Agent. We could program the same behavior using the "See" action as we did using the "See A" action, however it would require a separate rule for each Numbers depiction!

Fun Fact: We are not actually "incrementing" any numbers with our "increment" Method. We are updating Depictions to represent incrementing a number. We are simulating incrementing real numbers!

Good Job! At this point we cannot test if our Numbers "increment" behavior is going to work correctly, so we will create and program the Game Master Agent.

Creating the Game Master Agent

Game Master Depiction

The Game Master Agent will help manage important aspects of our game, such as incrementing the step count and also determining when the current game level has been finished. An interesting feature of the Game Master agent is that it does not need to be visible to the player, but it does need to be placed within our Worksheet at a specific location. To make it easier for us to see where we have placed this agent, it is a good idea to use some temporary or small depiction for it.

Create and draw the Game Master Agent: Create a new agent called "Game_Master", the same way you created the previous agents. Draw a picture you’d like to use to represent the Game Master.

Place the Game Master Agent in the Worksheet: It is very important that a single Game Master agent is placed to the Right of the Number agent that we previously placed on the worksheet. Use the picture below for reference!

Number & Game Master Position

Game Master Number Increment

Game Master Interaction with the Number Agent: Now we will add the functionality that allows the Game Master to tell the Numbers to increment. First open the Game Master behavior editor. Now we need to add a new On Method to the behavior and we will have it react to the message "update_steps". Use the picture below to place the correct Conditions and Actions into the rules for this method.

Game Master On "update_steps" Method Rule

Explanation: This Method has only one rule, which checks to see if there is any Number agent to its left and if there is it will send an "increment" message to the Number agent on the left. The Number On "increment" Method that we made earlier will react to this message and increment the values.

Getting the Step Count to Increment

We now have the Game Master reacting to the "update_steps" message and we have the Number reacting to "increment", but the numbers will still not increment when the Sokoban moves. To add this behavior we have to modify our Sokoban behaviors.

Every time the Sokoban moves it should send an "update_steps" message to the Game Master letting it know that a movement has occurred. The problem is that the Sokoban agent will not be adjacent to the Game Master agent, so we can not use the "Make" action to send a message. Instead we will use the "Broadcast" action that sends a message to all Agents of a specified type and it does not matter where the receiving Agent is in relation to the sender.

Diagram of Broadcast Action

Broadcasting Sokoban Steps: Let's add the "Broadcast" action to the Sokoban On "move_down" Method. Drag a "Broadcast" action over to the rule containing the "Move" action and set the agent to receive the message to the Game Master and also change the message to send to "update_steps". Use the picture below for help.

Sokoban "DOWN" movement with Broadcast added

Now, add the same Broadcast action to the On Methods for "move_up", "move_right", and "move_left".

Updating Other Sokoban Movements to Broadcast: The Sokoban needs to tell the Game Master that it has taken a step in two other cases: walking over Floor and Destinations. Add the same Broadcast action used previously to the eight rules for the other Sokoban movement. The picture below shows the updated rules for moving "DOWN" over the Floor and Destinations.

Sokoban "DOWN" movement with Broadcast added

Play Test: Step Counting

You have now programmed all of the behaviors that you need to record the number of steps the Sokoban takes while solving a level! Press the Run button to test your game.

  • When the Sokoban moves or pushes a Crate does the step count increase?
  • If you go over nine steps does the step count increase correctly?
  • If the answer is "No" to either of the above questions, check the behaviors for problems and retest.
  • If the step count is incrementing correctly (even if you had to change a few things and retest), you did a super job!

Programming Game Master to Detect Finishing Levels

It is time to learn about another important Computational Thinking Pattern: Polling.

Computational Thinking Pattern: Polling
CT Spiral small.jpg

Polling: If you have played the popular game Marco Polo, then you have used polling. When polling, the polling agent sends out a broadcast message asking other agents to report if they are in a certain state. The polling agent then checks what the other agents said and takes an action.

You can look at the complete Polling Description for more information.

To make Polling easier, we will use a new programming concept called a Global Variable. In AgentSheets Global Variables are also called Simulation Properties and these variable names always begin with "@". A Simulation Property (Global Variable) is a variable that can be seen and accessed by all Agents in the worksheets.

IMPORTANT: Variable Formats

Global vs Local Variables: It is important to be careful when working with Global Variables as they always require the @ before their names. If you omit the @ then the variable is treated like a local variable and is only accessible to the Agent itself.

The main point: Always remember the @ sign before Global Variable names!!!

We will use another new Action in our game, the Set action. The Set action allows us to set variables to values we want. There are two parts to the Set action, the first is where we specify the variable that we want to "Set" to a new value, and the second is the new value we want our variable to have.

Set Action Diagram

Updating Game Master Behaviors: We will now start adding behaviors to the While Method in our Game Master agent. Several things need to happen to enable Polling. First we need to set a Global Variable to zero. Let's call this variable "@Free_Crates" and we will use the Set action to set this variable to zero. Drag the Set action to the Then portion of the While rule and use "@Free_Crates" as the variable name. In the New Value section of the Set action type a zero. When finished this action should look like the following picture:

GM Set Action Complete

Now we will add a Broadcast action to this same rule. As you've done before, select the Broadcast action and add it to our rule. Select the Crate for the agents to receive the broadcast message and for the message to send use "report". Your finished Broadcast action should look like this:

GM Broadcast Action Complete

The last action we want to add to our current rule is a Make action that we used before. Add this action to our rule and for the message direction use the "dot". For the message to send use "check_crates". Your Make action should look like this:

GM Make Action Complete
IMPORTANT: Message Passing

The "Dot": You have just learned about another important programming concept with the Make action: using the "dot". The "dot" allows you to send messages back to the same agent!

We do not really need our While actions constantly running, so we will add a Once Every condition to our rule. The Once Every condition takes one value, which is the number of seconds to perform some actions. For our game we want the three actions we made to happen every 0.2 seconds, or five times per second. Drag the Once Every condition over to the If portion of our rule and change the number of seconds to "0.2". Our completed rule for our Game Master should look like this:

GM Final While Rules

At this point there is no reason to test our game, as we know that things will not work since we have not created the Report or Check Crates methods in our agents!

Finishing the Game Master - Check Crates Method

In the previous step we sent a message from the Game Master back to itself, but we still need to define the On Method that will handle this message just as we did when sending messages between the Sokoban and Crates.

Create a new On Method in the Game Master behaviors: As you have done before, create a new On Method in the Game Master behaviors by pushing the New Method button and change the message this On Method listens for by typing "check_crates" into the text box.

We will use the Is condition in the If portion of our method, which we have not used before. The Is condition tests a variable for some value and if the value is true, the Then portion of the rule is executed. There are several Condition Types that can be tested, such as equals (=), greater than (>), or less than (<).

Is Condition Diagram

Add the Is condition to our On Method: Locate the Is condition and add it to the If portion of our rule. Change the variable name we are looking for to our global variable "@Free_Crates". We will leave the Condition Type as the equals sign (=), as we want to test if "@Free_Crates" is equal to some value. The value we want to see if "@Free_Crates" equals is zero, so type a "0" into the Value box.

We are going to learn about new action now called Show Message. This action displays a message to a player in a pop-up window. Using Show Message will allow you to let the player know what is happening as they play. We are going to use this action to let the player know that they finished the level.

Show Message Action Diagram

Add Show Message action to our rule: Drag the Show Message action over to our rule and change the text to "You won the level!". This will let the player know that they successfully finished the level they are playing.

Add Reset Simulation Action to our rule: To finish our rule we will add the behavior of resetting the worksheet when the game level is finished. Find the Reset Simulation rule and drag it to the Then portion of our rule. After completing all of the steps above our On "check_crates" Method should now look like this:

Complete On "check_crates" Method

We have one more new Method to make before we can test our hard work!

Finishing the Crates - Report Method

We now will finish up our Crate behaviors to finish our game. In the last section we sent a "report" message to the Crates from the Game Master. Now we tell the Crate how to react to the "report" message.

Add new Method to Crate behaviors: If it is not already open, open the Crate behaviors as we have done before. Now click the "New Method" button to create the Method and use "report" as the message to react to.

We will use the Stacked condition that you may have previously used in the Frogger tutorials. The Stacked condition allows us to check what Agents are above or below another Agent.

Stacked Condition Diagram

Add Stacked condition to "report" Method: Drag the Stacked condition to our "report" Method. You want to make it look similar to the picture above. First, change where we want the Crate stacked to "immediately above", which says we want to know if our Crate agent is immediately above a specific Agent. In this case we want to know if the Crate is above the Floor, so change the "Agent to look for" to the depiction of your Floor Agent.

Reporting Stacked State: If our Crates are above the Floor, then we want to let the Game Master know by indicating that our crate is "Free". To do this we will add a Set action to our rule. Drag the Set action to our rule and change the variable we are setting to "@Free_Crates" and for the value to set our variable use "@Free_Crates + 1". Below is a picture of our completed "report" Method.

Final Crate On "report" Method

What happens if the Crate is not stacked above a Floor agent? Our Crate will not do anything when it receives the "report" message and "@Free_Crates" will remain at whatever value it had.

Finishing Up

Now Let's Go back to the Worksheet -- Let's do one final play test to see if we programmed everything correctly.


Play Test: Game Checklist

Press Run and see if everything works correctly. Check

  • When the Sokoban moves does the step count increment correctly?
  • When the Sokoban pushes the Crate does the step count increment correctly?
  • If you push all Crates over all Destinations does the level end?

If your answer to one of these is no, go back to the related section and see what you might have done wrong. Note: There should always be one Destination per Crate in the game levels.

Otherwise, if everything works correctly GREAT JOB! You have finished your own Sokoban game! You can now go back and make any changes you want to make (like redrawing an agent, redesigning your game level, adding other behaviors, etc.).

External Links