Making a Tutorial in under 3 minutes -WWDC23

Hello 👋. I am Yerik and I am taking part in the Swift Student Challenge.

Me and my App

If you’re not aware what the Swift Student Challange is, according to Apple:

“Show us your passion for coding by submitting an incredible app playground on the topic of your choice. Winners will receive exclusive WWDC23 outerwear, AirPods Pro, a customized pin set, and one year of membership in the Apple Developer Program. In addition, we’ll hold a separate random selection process just for winners who opt in for the opportunity to attend the special event at Apple Park.” — Apple

To give you a better context about my app and why I had to make a tutorial, allow me to share some background on what I did. If you want a video version, you can check my Devlog series:

My App Playground main goal is to help people learn about computational thinking, which is:
“We consider computational thinking to be the thought processes involved in formulating problems so their solutions can be represented as computational steps and algorithms.” — Alfred V. Aho, 2011

In order to achieve that, the App has puzzles in which the player has to “program” a ship to navigate through the obstacles and reach an objective. I won’t go into the details about the storytelling and why it’s a pirate ship since that is outside the scope of this article.

My main concern during development was: since the app is an educational tool/game, it must be easier to learn than the content it is trying to teach. I need my tutorial to be very easy to follow and once the player understands the basics, they’ll be able to venture in the more advanced levels. At the other hand, the Swift Student Challenge states that:
“[…] an App Playground that can be experienced within three minutes.” — Apple

We arrive then at the central topic of this article, how do you make a tutorial that teaches the player a complex topic in under 3 minutes?

I appologise if the title makes it sound like we’re building a tutorial in under 3 minutes, tutorials require a lot more thought and care than only 3 minutes.

The first step I took into making a tutorial was to design a starter level. In order to design it, you need to know what are the difficulties or obstacles in your game. Normally these obstacles are intended mechanics that you are already aware of.
In my App, the obstacles were:

• The instructions are relative to the ship’s current position and rotation
• The player has to keep the ship state (position and rotation) in their memories while “programming”

Both difficulties play into one another: The player has to keep in mind the ship state because the next instruction is relative to the current state.

The first level has to dial down all the difficulties. If you present the game hardest level for someone who has never played it before, they won’t have a fun and enjoyable time with it. Knowing the challenges my game presented, I knew that a good first level would:

1. Keep the ship in the same orientation as the player
2. Keep the number of instructions low

Both of these “guidelines” removed the difficulty from my game and allowed the player to focus in learning the interface.

Another important part of a first level is creating a safe environment for the player to learn. In my game, the only penalty in getting the instructions wrong is wasting time, so the first level has to be very quick to solve, diminishing the penalty. Even if the player gets it wrong, it’s a safe environment to experiment.

I came up with this design for the tutorial level

First prototype for the tutorial level

I placed the ship aligned at the bottom center of the board and the treasure chest is dead center, those places are likely where the players look over first. I also placed the obstacles in an Arrow-like shape but I can’t really tell if that made any difference in the tutorial.

At this point in time, I tested the App with 3 different players. 2 of them had a bit of previous knowledge about my game, one of them had no previous knowledge. What surprised me was that the results were almost identical regardless of that.

All players reported initial confusion when trying to solve the first puzzle. They claimed that they didn’t know what to do. I took some notes during their play session and I noticed that, althought they reported feeling confused, through exploration of the interface they were able to finish the first level.

With any iterative process, you gather feedback and then work to improve the weak points. So did I. With all my notes and feedback from the playtesters and mentors, I set out to make the interface a bit more intuitive.

My hypothesis is that there were the following causes to the confusion:

1. The App went from storytelling straight to the Treasure Map Editor (programming screen)
2. The Editor buttons weren’t in intuitive places
3. Screen components were blending together

My next step is to improve on these issues. Once again it’s important to remember the 3 minute limit, I can only add more steps to the tutorial as long as it’s still less than 3 minutes.

To tackle the first hypothesis, I added another text box. This box divided the screen in half so the player could only see the Editor half, reducing the amount of information they had to process at any time in the first level. Since the players understood the game through exploration of the interface, the text encouraged the player to try to press the buttons and see what happens.

While on the topic of buttons, I changed them. The buttons related to instructions were repositioned above the instruction list at the header and the button to run the level was moved to the bottom of the screen. This took advantage of the fact we read from top to bottom, this way the player will see the buttons on the screen at the order they will be used.

Finally for the screen components blending together, I did a color overhaul on the editor and color coded specific instructions. Green meant turn left, red meant going forward and blue meant turn right. Not only this color change helped players in the tutorial, they improved the overall editor use throughout the game.

Here is how the editor was looking after the first iteration:

The new text box

Color coding made a huge difference in the editor aesthetics

I tested with a few other players and these changes improved significantly how they performed. Players tried out the buttons and this led to faster understading of the core concept. But this round of testing showed a new problem that hadn’t surfaced yet. Players felt it was difficult to find the ship and the treasure on the board preview screen.

The way tackled this issue was adding a new text box to briefly hide the editor and allow the player to focus only on the board preview, and adding some visual elements to both the ship and the treasure chest. I added a shinny sparkle effect and while this helped, I also added a less subtle light in the first level. These effects had no real tie into the game and are probably the “weakest” solution, since they don’t blend in too well with the game theme, but they did get the job done. Another thing I added to improve visibility was a foam trail behind the ship.

The light guided the player's sight into the ship and the treasure

This last iteration was finished a few days before the deadline for the Swift Student Challenge submissions so I didn't had enough time to properly test it. In the only test I was able to run, the player didn't report any confusion and I didn't notice any issue with them understanding the game concepts.

In parallel, I was also developing the game's second level

In the first level I removed all difficulty, so in the second level I had to increment the challenge. This game is a very simple example, but this applies to all other games: stacking mechanics is the best way of teaching them. By stacking your game mechanics, you reinforce what the player has already learned and you introduce something new that ties into what the player already knows.

Keeping this in mind, the second level had to teach the player how to turn the ship around. The first level only required a single “Move Forward” instruction, so by adding a second level with at least a “Turn Left” required, I'd be certain that the player knows how to turn the ship once they get into the final level.

My first (and only) iteration of the second level was this:

The second level is very similar to the first

The first instruction is exactly the same as the last level. This is a way of stacking them, I'm building the turn mechanic on top of the already established move forward mechanic.

After the required "turn left" instruction, the player is also required to move the ship forward 2 steps. This is done intentionally, to show the player that moving forward (and turning) is relative to where the ship is currently pointing. Finally having 2 “move forward” instructions give different results, reinforces to the player that all instructions are dependent on the current ship state.

This level had no other iterations because it worked flawlessly with the first level. While the first level had to teach the player how to use the interface, this one only had to teach about a single instruction.

So, how did the players perform?

Throughout testing I found out that these tutorials were very effective. Players who reported an initial confusion were able to complete the third level, which required 9 instructions to complete (3 times more than the second level).

Player didn't report any confusion on either the second or the third level, and most of them were able to complete it first try. The few players who didn't complete either of them in the first try had enough knowledge of the game mechanics to quickly figure out what went wrong and fix their “programming”.

This also highlighted another point which is not inherently part of the tutorial but is equally important. The game should give feedback on what the player is doing wrong. In my game this feedback comes visually through the AR Board, the player can follow the ship and see what they did wrong. Depending on how they failed, the interface also highlights the instruction that crashed the ship, giving them a better lead on what went wrong.

Here is a shortened version of all that I did to design the tutorial:

1. Figure out what makes my game difficult
2. Create a first level that removes all the difficulty
3. Make this first level a safe environment (no punishment for getting it wrong)
4. Test it with players and take notes on how they perform
5. iteratively improve the level based on player behavior and how they react to the tutorial
6. Repeat for all the other tutorial levels, increasing the difficulty and stacking new mechanics with previously learned concepts

Finally, if you wish to see my WWDC23 Submission, you can check it out on youtube:

if you want to learn more about game tutorials, here are some great resources:

1. https://youtu.be/45csSEotJY8
2. https://youtu.be/MMggqenxuZc

Thank you for reading!