Ultima Ratio Regum 0.11 Update #30: Tutorial Design

Hello friends! This week I’m going to be covering a major addition for 0.11 – the implementation of a tutorial (and the replacement of the guidebook, too). This has been an exciting thing to develop because it really does signal this ongoing transformation from “cool detailed world without too much to actually do” into “game with actual objectives”, and has also been a really interesting design and coding challenge for me, simply by virtue of being unlike anything I’ve implemented before. Given the openness of the game I didn’t want the tutorial to just be an entirely fixed thing, but rather to reactively appear in small stages as the player looks at or does things that should logically trigger a tutorial prompt (e.g. the first time you look at X, get a tutorial prompt about X), yet at the same time there’s so much information to convey (even in 0.11) that there’s going to be quite a few. Striking this balance has been really interesting, and I’ll explore this in this entry, but the place I started was simply in deciding how the tutorial prompts should actually look.

I first considered having the tutorial popup be inverted from the normal URR style (i.e. a light background and dark text instead of light text on a dark background), I considered having it be the same colour as the “URR colour” (that sort of blue-lilac) or maybe similar to that but alternating between darker and lighter squares, or perhaps it should be rainbow coloured to really stand out (I blame the polychrome jokers in Balatro for that idea), but in the end I settled on gold, and as soon as I tried it, my brain said “yes”. I find this happens often in coding, where sometimes I just need to keep trying things over and over, and trusting that my brain will confirm when the right option has been found, even if things just don’t quite feel right yet (as an aside, I wish I did sometimes think to keep screenshots of failed attempts, as they’re actually pretty interesting to show off). The final piece, however, was to add the “?” in the upper-left corner of the tutorial box. I think this was a master stroke! Before then it just looked a little bit too much like other messages or other menus and things of that sort, but because nothing else in the game looks at all like that question mark, it quite nicely marks the tutorial out as a largely non-diegetic element and also makes it impossible for a player to miss the fact that a tutorial prompt has appeared, and hence they should probably read it before continuing any further. So, here are some really nice examples of some of the tutorial prompts (the first being particularly important!) that appear the first time you look at a particular type of item (the weapons / armour one will be disabled for 0.11, but I’m doing them all in one burst, so including it for now) in the game:

(In this next screenshot, you might notice mention of national relics – that’s not a 0.11 objective, but I think it only makes sense for nations to also have treasured items, much like religions, so we’ll come back to that one a bit later!)

So this is how each tutorial prompt looks – it’s gold, it highlights the thing it’s talking about, it has a little “?” in the upper-left corner to help distinguish it from anything else, and it has two options at the bottom – Enter to just continue, which removes the tutorial prompt and from there you just proceed as you otherwise would when doing whatever made the prompt appear, and X to cancel tutorials. The latter just brings up a tutorial message which looks like this…

…and from there you can head into the options menu, if you want to, to re-enable tutorials, on a completely new and much more polished options screen which also tells you which ones you’ve seen, and how many you so far haven’t (and very easy code included there so I can consistently add to the full set of tutorials without ever having to actually return to this code again):

And, as an aside, you can now shift to “bioregion” as the kind of visual for the top-left sidebar map, just like you can with terrain, territory, and height:

But back to the tutorials themselves. Those shown above are not the only contexts the player will be given a bit of tutorial direction in, since all of these are activated by viewing an item. Coding-wise this was pretty simple, as I just added a set that tracks what tutorials you’ve seen, and when you look at a category of item with a tutorial attached it just checks whether you’ve seen that tutorial or not, and if not then it shows it (and tracks it as shown), and if so, then it does nothing. Those were pretty simple, but other prompts became both more complex in terms of coding, and in terms of designing this kind of reactive tutorial system I wanted, where the player can potentially see tutorial prompts in many different sequences. For example, when the game starts, and they’re in the museum and then departing to see the wider world, I decided I wanted quite a number of tutorial guides coming in before they leave this starting location. The player is, in a sense, “captive” until they leave the great hall the museum rests on the upper floor of, and so that’s the time to give the player all the absolute essential tutorial items. After that, other tutorial items can just come up more naturally when the player first encounters what it is that they’re encountering for the first time. So I could therefore split the tutorial things into stuff which has to be triggered during the museum and then departure from the hall section of the game when you start, and then everything else can come later! This does mean two different kinds of logic for triggering the tutorial prompts – the first being the ones shown above, but the second being of a harder category.

So, to handle the second, I created a new set of information on each map grid, which notes what tiles have something special trigger when you step on them. Much later I can actually see this having a much wider use – e.g. a certain tile triggers a trap, a certain tile triggers an event, or a noise, or a change in the layout of the map, or whatever – but for now we’re just using them for tutorials. For most map grids this list is normally empty, so it’s < 1/1000th of a second to check the list normally, which isn’t going to do too much to reduce the game’s running speed :). But all of this, though, brought us to the hardest category of tutorial hint (from a coding point of view) – things that might be anywhere on screen rather than a fixed location, and so the tutorial prompt has to figure out how it’s meant to look. For example, when you’re in the museum, I wanted the game to circle the items on display when telling the player about the ‘l’ook function. Similarly, the first time you see water I want it to identify the water and tell you that you can swim and dive in it (which will be true soon), and first time you see a person, or an animal, it should also give you brief tutorial notes. The problem from a coding perspective, however, is that these might appear literally anywhere on the screen, and thus the game needs to be able to respond and logically present a tutorial pop-up in a sensible location, as well as correctly pointing to, or ringing, or pointing out, the thing that is actually being talked about here. All those above were relatively easy since one can only look at a weapon, for example, by, well, looking at it, so we know exactly what the screen will look like and thus how the gold borders should be positioned. Alternatively some can just appear in the middle of the screen, since they aren’t necessarily referring to anything specific, and those are obviously pretty easy as well. This final category is much harder, and took a bit of figuring out to get going.

The first of these, then, will appear when you’re on the museum floor but before you even get into the museum, after you’ve been set on your quest by the previous museum keeper (at least, this is what we’re going with for now!), and will appear if you haven’t already looked at your inventory by the point you’re in the middle of that corridor. If you have, then it won’t appear, but if you haven’t, then it’ll prompt you to look at the initial clues you’ve been given:

The hope being that the player would then, after dismissing the tutorial prompt, press “i” and have a look through their inventory, noting the initial clues, the fact they have some clothes, some currency, a journal, and probably a few other starting items as well, depending on what kind of civilization they start in (more on that in a later entry).  The second one to work on was then the actual the museum one, since I want the game to introduce the ‘l’ook function when you see the museum items, as a way of emphasising to the player that this is a key function, and taking a moment to “show off” some of the stuff you’ll be able to find in the world, and give a rapid sense of the size and detail of the world you might be walking into. So when you enter the museum, the game takes note of the shape of the museum (i.e. the classic square, circle, diamond, cross, octagon options) and draws a loop around them, and then finds a sensible place on the screen to put the tutorial prompt, and then connects the two. This was surprisingly tricky to develop and to ensure consistent correct visuals on, but I really like how this looks! Having developed this system it’s also a system I’ll be able to use for other tutorial prompts in the future, and also, potentially, other things. For instance, we might imagine a scenario in the future where one has really angered a religion, and when someone from that religion enters your line of sight for the first time, and draws their weapons, the game would note their arrival (not a tutorial prompt, but more of an event prompt). Anyway, for now though, we have a good system for highlighting the relevant museum section, and prompting the player to have a look at the items there:

Again, I really like this and I’m very happy with how it looks (and its ability to respond and shape itself around the game world, too, which is a minor point, but a pretty cool one). After this you’d then descend the staircase (also given a tutorial prompt, just to make sure everyone knows what it is, and how to use “>” and “<” to go up and down staircases in roguelikes) and enter the main floor of the great hall. You can wander around it, but once you get close to one of the exits into the outside world (and hence the ability to fast travel), this one comes up:

The goal here, then, is partly to convey some important controls, of course – especially now the guidebook has been removed, see below – but also to situate what the player has so far seen (their inventory, initial clues, their journal, the ability to look at stuff and potentially gain information from said looking) in a wider context of what your objectives are and what one should expect to happen after departing this starting location. I’m happy with this message – lightly inspired by an equivalent one from Return of the Obra Dinn – and I think it gets the point across well, hopefully striking a balance between “this is a challenge and you should expect to use your brain” and “there’s a huge amount to go and see and do, so go check it out!”.

Once you’re outside we then get into tutorial prompts which have many different options, some of which cancel each other out. For example, it’s important to tell the player how to fast travel and how to look at the world map, but the player might do either of these before leaving the great hall, even though one can’t fast travel until getting outside. As such, there are three possible options here. If the player tries to travel before getting outside, a tutorial prompt explains about travelling and looking at the world map. If the player just looks at the world map before getting outside, it gives essentially the reverse of that first message.  However, if you haven’t looked at the world map with either method for ten to fifteen turns after leaving the great hall – so after you’ve wandered just a few moments, and the game now counts your steps after leaving the university’s great hall for the first time – the game will give you the third possible tutorial prompt about travel, which tells you the controls for both travel on the world map and looking at the world map. What this means is that whichever happens first (player looks at world map, player tries to travel on world map, or player just wanders around outside, unsure of where to go), the game will tell you what you need to know about the world map and fast travel, but in a format specific to the particular way you get that information. I’m really happy with this system, actually, and I think it’s kind of cool. Then, regardless of whether you get what are called internally the “Travel”, “Travel 2” or “Travel 3” tutorial prompts, they all are then immediately followed by a sidebar prompt, which looks like this:

And that’s it! Those are the core tutorials.  What’s your objective, where’s the inventory (and hence by extension also “where’s the journal?”), how do clues work, how does looking at things work, what should you click if you need help, and how do you travel.  These are enough. Then beyond those, however, we have a few others in other places, such as this one in the religion / rewards / agenda screen…

…and the potential for more in the future. These include one that’ll appear when you first enter a cave or a mine for the first time, which’ll say something like “This is your first time entering a mine or a cave. There are vast underground realms beneath this world, although many are well-hidden. Much has long been lost and forgotten in such places”, or thereabouts. The various tutorial systems are now sufficiently well implemented that I wouldn’t anticipate any issues with just adding more in the future, for underground areas, and other secret plans, and the like. Also as part of this entry, as part of all this, I’m making a major change: the removal of the guidebook. I thought it over, and increasingly I think the tutorial system is far more accessible (i.e. it gives you the info you need when you need it), and the tutorial system doesn’t have any of the blather the guidebook has, and it doesn’t risk the player just reading a bunch of stuff before actually playing and getting overwhelmed. I also quite strongly think that removing the guidebook but keeping the tutorial system leaves a lot more possibility for interesting discoveries by the player rather than being spoiled, in a sense, about lots of the stuff deeper into the game. As such, the guidebook option on the main menu, and in the game, have both just been replaced by a list of controls, which has also been polished and updated (and will be updated each time there’s a major new release, but here’s just a working version for now)…

…and will be gestured to in-game by one of the tutorial messages, along with the encyclopedia. You’ll also note a bunch of control changes there, because I needed to implement eight-directional movement for players without a numpad, so anything in the “qwe asd zxc” part of the keyboard has to be moved over to another control now, such as “s” for speak becoming “v” for converse, and “e” for encyclopedia becoming “y”, and so forth.

And, actually finally… did you notice my mention of the word “journal” up above there? I know you did, dear reader, but this entry is already plenty long enough, so I’ll just go with this screenshot for now:

But as for what it contains, we’ll get back to that some other time :). I wonder what those tabs on the side mean, though??

What next?

Well, there we go! I’m really happy with how this all looks, and it’s so exciting to be at a moment where it’s actually finally appropriate to give the player directions on what to do. Although a very satisfying design challenge, and a very satisfying programming challenge, one of the best parts of this block of work has been this feeling that it signals a really transformative shift in what’s going on here. Big weird art projects don’t have tutorials, but games? Games do. It was really exciting putting this together, and realising that I’m now at the point where the next major release will actually need a tutorial, and that’s super thrilling. All long-term readers will know that one of the big psychological challenges of this project has always been its relatively lack of game-ness and the need for such a large and detailed world to build the game on, and hence the need to, in some sense, keep “waiting” until that game-ness comes into being and things more fully come to fruition. I won’t go into the details again here about that issue, since I’ve mentioned it many times in the last decade or so, but I did want to share that it has been deeply, deeply satisfying developing the tutorial system, and starting to get a proper sense of what the game will be like – how and where the player starts, the information given, the ability to craft a specific opening experience that should lay the kind of groundwork I want laid, and so on and so forth. I think these strike a really good balance between clarity and mystery, get all the important points across, and are infinitely more user-friendly than the horrendously bloated guidebook was in earlier versions.

So thanks, as ever, for reading! As ever, if you liked this post, please do think about sharing it around on some online place where people are interested in roguelikes or game development more generally, and I’d love to read any comments or thoughts in the comments section below. I’ll see you all again in just two weeks (!!) for an update on notes and clues, and books, and much else besides. See you then!