You can either watch this tutorial on Youtube below, or otherwise skip past it and read the text version (not all of the Puzzlescript tutorials are on Youtube yet but I plan to do that eventually).

This tutorial will teach you how to start programming in Puzzle Script for your own Sokoban games. It requires no prior programming knowledge, but assumes you completed the previous Puzzle Script tutorial on making your first game. The code itself is very simple, and this is a very gentle way to get into programming, before moving on to learning bigger engines like Unity, which is what I used to make Puzzledorf (however I’m considering Monogame for future games).

 The Code

Open the sample project here. Programming code is down the left side of the screen and is divided into sections: Objects, Legend, Sounds, etc. The Rules section is where you define how objects in your game interact. Scroll down to it. There should be one line of code as follows:

[ > Player | Crate ] -> [ >  Player | > Crate ]

What the above line of code means is, if the player is next to a crate and walking towards it, move the player and push the crate. To explain how this works, understand that Puzzle Script code follows the pattern of:

[ Condition ] -> [ Event ]

What it’s saying is:

[ If this condition is occurring ] -> then [ Do this ]

Puzzle Script checks the conditions on the left side of the arrow to see if they are true, such as, is a player object next to a crate object. Then if the condition is true, do something, ie, push the crate.

Example Conditions

Here is an example condition:

[ object1 | object2 ]

The above condition checks if object1 is next to object2. You check if two objects are next to each other by putting a straight | line between them, typed by pressing ‘shift + \’. Conditions are always enclosed in square [  ] brackets.

[ crate | crate ]

The above checks if two crates are next to each other.

[ crate | crate | crate ]

The above checks if three crates are next to each other.

[ crate target ]

The condition above checks if a crate is on top of a target, because there is no straight | line between the two objects. Objects can be on top of each other if they are in separate collision layers, which is discussed in later tutorials.

Keeping It Equal

Rules have to be balanced. Both the condition check and the event that follows need to be described the same way. I will show you what that means.

[ player | crate ] -> [ player |   ]

The above line of code destroys a crate if the player is next to one. You cannot have:

[ player | crate ] -> [ player ]

Because the condition on the left is checking if two objects are next to each other in two separate grid spaces, but the event only describes the single grid space that the player occupies. Puzzle Script needs to know what to do with the spaces it was checking. Really what the correct code for destroying a crate is saying is:

[ If player | is next to a crate ] -> then [ player does nothing | remove the crate ]
[ player | crate ] -> [ player |   ]

So even the blank spaces in your code can have meaning. The following is, however, allowed:

[ player target ] -> [ player ]

Because you are only talking about a single grid space in your condition and the event describes that same grid space.

How To Move Crates

Back to our original line of code.

[ >  Player | Crate ] -> [  >  Player | > Crate  ]

In other words:

[ If player moves towards crate | and is next to crate ] -> then [  move player | push crate  ]

The arrow > emphasises movement.

Sometimes you want to write comments to remind you what code does. Puzzle Script ignores comments – they are for our eyes only. To write a comment, put curved braces around a piece of text. Write a comment above the existing rule that describes what it does:

(The player pushes a crate)
[ >  Player | Crate ] -> [  >  Player | > Crate  ]

Now, underneath your crate pushing code, write this:

(The player pulls a crate)
[ <  Player | Crate ] -> [  <  Player | < Crate  ]

The reversed arrow means if the player moves away from a crate, the player pulls the crate. Press ‘Run’ to test. You should be able to pull and push crates. With programming, if you type even one letter wrong, the computer won’t understand, so fix any typos. When you make code changes, press ‘Run’ again to load the changes. If it doesn’t behave as expected, try pressing ‘Rebuild’ to wipe the programs memory and then press ‘Run’.

Sometimes you want to deactivate a line of code. Just turn it into a comment so it’s still there later. Now comment out the crate pushing code so that you can only pull crates, like this:

(The player pushes a crate)
([ >  Player | Crate ] -> [  >  Player | > Crate  ])
(The player pulls a crate)
[ <  Player | Crate ] -> [  <  Player | < Crate  ]

If that worked, comment out the crate pulling code and try the following:

[ <  Player | Crate ] -> [  <  Player | > Crate  ]

If the player moves away from a crate, the player and the crate will move in opposite directions. The arrows dictate which direction an object either is moving or will move. Now comment that out and try this:

[ >  Player | Crate ] -> [   Player | > Crate  ]

The crate moves, but the player stays still. Experiment with ^ and v (the letter v) to to see how objects move in response.

Errors

Let’s deliberately write a rule that’s wrong and see what happens. Type this:

[ <  Player | Crate ] -> [  <  Player  ]

Try running the program. You should see a message like this:

line 81 : In a rule, each pattern to match on the left must have a corresponding pattern on the right of equal length (number of cells).

Usually Puzzle Script is good at describing the error. Sometimes, however, Puzzle Script gets it wrong. In such cases, you have to read through your code and guess where the error is.

Experiment Some More

Try experimenting some more and writing rules of your own. Here are a few examples.

[ >  Player | ... | Crate ] -> [  >  Player | ... | > Crate  ]

In this example, the player will push the crate if they are anywhere on the same line of the level, and the player moves towards the crate.

[ >  Player | Crate ] -> [  Crate | Player  ]

The above will swap the player and the crate.

[ > Player | Crate ] -> [ Player | Target ]

In the above, if the player is next to a crate and moves towards it, the player will stop moving but the crate will become a target. The best part of puzzle script is how easy it is to come up with something new and experiment.

Conclusion

See the finished sample project here. The next tutorial discusses creating objects and doing simple pixel art for your Sokoban game so you can start to get more creative.

Next Tutorial >

If you liked this article, please check out Puzzledorf to show your support. If you enjoy playing, leaving a review helps the games visibility on Steam.